Skip to content

Commit 8935745

Browse files
faical-yannick-congoclaude
faical-yannick-congo
and
claude
committed
feat: complete Fluently platform — tests, CI gates, knowledge base, and interactive site
## Core fixes - Fix TypeScript monorepo build: correct paths in cli/mcp-server tsconfigs to point at scorer's compiled dist (not source), add rootDir to prevent nested dist/ output - Downgrade chalk@4 and ora@5 (ESM-only v5/v6 incompatible with CJS compiled output) - Add "type": "module" to root package.json to enable ESM scripts - Add exports field to scorer/package.json for subpath resolution at runtime - Fix KNOWLEDGE_DIR paths in all 3 test files (../../knowledge → ../../../knowledge) - Fix YAML indentation in coding-code-review-triage.yaml - Fix schema float comparison: === 1 → Math.abs(sum - 1) < 1e-9 for decimal weights - Fix validate-knowledge.js to import from dist/schema.js (not stale src/schema.js) - Fix score-pr-knowledge.js: entry.dimensions.description.description and result[0].dimensionScores.delegation (scoreTask returns an array) - Rename test-integration.js → .cjs (uses require(), incompatible with "type":"module") ## Test suite (30 tests, all passing) - packages/scorer/__tests__/engine.test.ts — 11 tests: scoreTask, loadKnowledgeEntries, schema validation (valid/invalid domain, score_hints sum, missing fields) - packages/cli/__tests__/commands.test.ts — 9 tests: score, compare, list, contribute commands - packages/mcp-server/__tests__/tools.test.ts — 10 tests: compare_problem_space, score_delegation, evaluate_discernment, check_diligence, get_4d_score tools ## CI — proper PR gate - Fix silent test failure: remove "| head -100" pipe that swallowed vitest's exit code - Add set -o pipefail + tee to capture output while preserving exit code - Add permissions: pull-requests: write for PR comment bot - On test failure: automatically post a detailed fix report comment to the PR with collapsible test output, numbered remediation steps, and a hard exit 1 gate - Build runs before validate-knowledge so dist/ artifacts exist at validation time - Add knowledge-validate.yml: validates + regenerates index.json on every knowledge PR - Add release.yml: publishes CLI + MCP server to npm on version tags ## Knowledge base — 16 entries across 7 domains - 4 original coding entries (bug-fix-prioritization, code-review-triage, refactoring-suggestions, test-case-generation) - 12 new entries from aifluencyframework.org with contributor + reference fields: education (course-design, lesson-planning, student-career-planning), general (email-writing, iterative-refinement-loop), healthcare (clinical-documentation), legal (ai-research-drafting), research (data-analysis, literature-review), writing (content-development, creative-ai-collaboration, marketing-email-campaign) - Add optional reference field to Zod schema - Generate knowledge/index.json with summary field for GitHub Pages rendering ## GitHub Pages site (site/) - index.html, knowledge.html, contribute.html: fix all "4D plays" → "Fluently 4D cycles", fix CLI name "4d" → "fluent", fix domain list, fix YAML template format - site/guide.html (new): user-centric visual guide with 4D workflow diagram, CLI command reference with example output, Before/During/After AI collaboration journey, 5-step contribution walkthrough with CI check explanation - site/knowledge.html: add 4D Match Finder chat — user enters Delegation + Description, client-side cosine similarity against index.json (raw.githubusercontent.com + API fallback), top-3 results with similarity bars; if no strong match (< 40%) a Register panel appears for Discernment + Diligence, pre-filling a GitHub issue - Add Guide link to nav and footer across all 4 site pages - Fix fetchKnowledgeBase() to extract .entries from index JSON (not the whole object) - Fix entry.description → entry.summary in knowledge card renderer ## Terminology + docs - CLAUDE.md, README.md, CONTRIBUTING.md: "4D plays/playbooks" → "Fluently 4D cycles", "4d" CLI → "fluent", fix domain list, fix schema block, fix dimensions format - _config.yml: Jekyll config for GitHub Pages serving from site/ directory - scripts/: validate-knowledge.js, generate-knowledge-index.js, generate-changelog.js, score-pr-knowledge.js — all working with ESM imports Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 1f91957 commit 8935745

49 files changed

Lines changed: 8305 additions & 660 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
paths:
7+
- 'packages/**'
8+
- 'knowledge/**'
9+
- '.github/workflows/ci.yml'
10+
- 'package.json'
11+
- 'tsconfig.base.json'
12+
13+
jobs:
14+
ci:
15+
runs-on: ubuntu-latest
16+
permissions:
17+
pull-requests: write
18+
strategy:
19+
matrix:
20+
node-version: [20, 22]
21+
22+
steps:
23+
- uses: actions/checkout@v4
24+
with:
25+
fetch-depth: 0
26+
27+
- name: Setup Node.js ${{ matrix.node-version }}
28+
uses: actions/setup-node@v4
29+
with:
30+
node-version: ${{ matrix.node-version }}
31+
cache: 'npm'
32+
33+
- name: Install dependencies
34+
run: npm ci
35+
36+
- name: Build
37+
run: npm run build
38+
39+
- name: Validate knowledge schema
40+
run: node scripts/validate-knowledge.js
41+
continue-on-error: false
42+
43+
- name: Run tests
44+
id: run_tests
45+
continue-on-error: true
46+
run: |
47+
set -o pipefail
48+
npm test -- --run 2>&1 | tee /tmp/test-output.txt
49+
50+
- name: Post test failure comment
51+
if: github.event_name == 'pull_request' && steps.run_tests.outcome == 'failure'
52+
uses: actions/github-script@v7
53+
with:
54+
script: |
55+
const fs = require('fs');
56+
let output = '';
57+
try {
58+
output = fs.readFileSync('/tmp/test-output.txt', 'utf8').slice(0, 4000);
59+
} catch (e) {
60+
output = '(could not read test output)';
61+
}
62+
const body = [
63+
'## ❌ Test Suite Failed — PR cannot be merged',
64+
'',
65+
'### What failed',
66+
'',
67+
'The test suite did not pass on Node.js `${{ matrix.node-version }}`. All tests must pass before this PR can be merged.',
68+
'',
69+
'<details>',
70+
'<summary>Test output (first 4000 characters)</summary>',
71+
'',
72+
'```',
73+
output,
74+
'```',
75+
'',
76+
'</details>',
77+
'',
78+
'### How to fix',
79+
'',
80+
'1. Pull the latest changes from this branch locally.',
81+
'2. Run `npm test -- --run` in the repository root to reproduce the failures.',
82+
'3. Fix the failing tests or the code that causes them to fail.',
83+
'4. Push your fixes — CI will re-run automatically.',
84+
'',
85+
'> **Note:** ALL tests must pass before this PR can be merged.',
86+
].join('\n');
87+
await github.rest.issues.createComment({
88+
issue_number: context.issue.number,
89+
owner: context.repo.owner,
90+
repo: context.repo.repo,
91+
body,
92+
});
93+
94+
- name: Fail build if tests failed
95+
if: steps.run_tests.outcome == 'failure'
96+
run: exit 1
97+
98+
- name: Score new knowledge entries
99+
if: github.event_name == 'pull_request'
100+
id: score_entries
101+
run: node scripts/score-pr-knowledge.js
102+
continue-on-error: true
103+
104+
- name: Comment PR with knowledge scores
105+
if: github.event_name == 'pull_request' && steps.score_entries.outputs.scores != ''
106+
uses: actions/github-script@v7
107+
with:
108+
script: |
109+
const scores = process.env.KNOWLEDGE_SCORES;
110+
if (scores) {
111+
await github.rest.issues.createComment({
112+
issue_number: context.issue.number,
113+
owner: context.repo.owner,
114+
repo: context.repo.repo,
115+
body: `## Fluently Knowledge Entry Fluency Scores\n\n${scores}`
116+
});
117+
}
118+
env:
119+
KNOWLEDGE_SCORES: ${{ steps.score_entries.outputs.scores }}

‎.github/workflows/knowledge-validate.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Knowledge Base Validation
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
paths:
7+
- 'knowledge/**'
8+
push:
9+
branches: [main]
10+
paths:
11+
- 'knowledge/**'
12+
13+
jobs:
14+
validate-knowledge:
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: write
18+
pull-requests: write
19+
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- name: Setup Node.js
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: 20
27+
cache: 'npm'
28+
29+
- name: Install dependencies
30+
run: npm ci
31+
32+
- name: Validate knowledge schema
33+
run: node scripts/validate-knowledge.js
34+
35+
- name: Generate knowledge index
36+
run: node scripts/generate-knowledge-index.js
37+
38+
- name: Commit index.json if changed
39+
if: github.event_name == 'push' || github.event_name == 'pull_request'
40+
run: |
41+
git config user.name "github-actions[bot]"
42+
git config user.email "github-actions[bot]@users.noreply.github.com"
43+
44+
if git diff --quiet knowledge/index.json; then
45+
echo "No changes to index.json"
46+
else
47+
git add knowledge/index.json
48+
git commit -m "chore: update knowledge index"
49+
git push
50+
fi
51+
continue-on-error: true

‎.github/workflows/release.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches: [main]
6+
tags: ['v*.*.*']
7+
8+
jobs:
9+
release:
10+
if: startsWith(github.ref, 'refs/tags/v')
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
packages: write
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Setup Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: 20
23+
cache: 'npm'
24+
registry-url: 'https://registry.npmjs.org'
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Build all packages
30+
run: npm run build
31+
32+
- name: Publish CLI to npm
33+
run: npm publish --workspace=packages/cli
34+
env:
35+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
36+
37+
- name: Publish MCP Server to npm
38+
run: npm publish --workspace=packages/mcp-server
39+
env:
40+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
41+
42+
- name: Extract version from tag
43+
id: version
44+
run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
45+
46+
- name: Generate changelog
47+
id: changelog
48+
run: |
49+
{
50+
echo 'changelog<<EOF'
51+
node scripts/generate-changelog.js
52+
echo 'EOF'
53+
} >> $GITHUB_OUTPUT
54+
55+
- name: Create GitHub Release
56+
uses: actions/create-release@v1
57+
env:
58+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
59+
with:
60+
tag_name: ${{ steps.version.outputs.version }}
61+
release_name: Release ${{ steps.version.outputs.version }}
62+
body: ${{ steps.changelog.outputs.changelog }}
63+
draft: false
64+
prerelease: false

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,6 @@ node_modules/
22
dist/
33
.env
44
*.local
5+
_site/
6+
.jekyll-cache/
7+
.jekyll-metadata

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ PROJECT: fluently
22
PURPOSE: An open-source CLI + MCP server + knowledge base that operationalizes the AI Fluency 4D Framework (Delegation, Description, Discernment, Diligence) by Dakan & Feller / Anthropic. Licensed CC BY-NC-SA.
33

44
ARCHITECTURE:
5-
- /knowledge/ — YAML 4D plays, community-contributed, organized by dimension and domain
6-
- /packages/cli/ — Node.js CLI (`4d` command) using commander.js and Anthropic SDK
5+
- /knowledge/ — YAML Fluently 4D cycles, community-contributed, organized by dimension and domain
6+
- /packages/cli/ — Node.js CLI (`fluent` command) using commander.js and Anthropic SDK
77
- /packages/mcp-server/ — MCP server exposing knowledge as AI-callable tools
88
- /packages/scorer/ — Shared scoring engine used by both CLI and MCP server
99
- /site/ — GitHub Pages static site (Astro or plain HTML)

0 commit comments

Comments
 (0)