@fakto/core 0.0.1 → 0.0.2

package/README.md

@@ -69,6 +69,22 @@ npx fakto canvas             # the live map on http://localhost:4848 (--backgrou
 
 As a library: `import { loadRepo, checkRepo, staleList } from '@fakto/core'`.
 
+## Claude Code skills
+
+The package ships the two skills Claude uses in a Fakto repo (`fakto`: the change workflow;
+`fakto-canvas`: starts the live map) and the hooks that run the check after every edit and
+start the canvas at session start. Claude Code loads skills from the project, not from
+`node_modules`, so install them into the repo:
+
+```bash
+npx fakto skills           # write .claude/skills/* and merge the hooks into .claude/settings.json
+npx fakto skills --check   # exit 1 when they are missing, edited, or from another version
+```
+
+Put `"postinstall": "fakto skills"` in the repo's package.json so every `npm install` refreshes
+them; the session-start hook runs it too, and `fakto check` warns when they are not current.
+Commit them: they are readable on GitHub and work before the first install.
+
 ## Canvas
 
 A local web app that draws the whole graph, lets you edit or add a fact, and runs your

package/bin/fakto.mjs

@@ -11,6 +11,7 @@
  *   fakto touch <file | fact-id>…  stamp reviewed: today and the source hashes (after a human reviewed it)
  *   fakto sync [path | fact-id …]  bring facts and sections in line with the files they draw on (--all)
  *   fakto canvas         open the canvas on localhost (--port 4848; --background to detach, --stop)
+ *   fakto skills         install or refresh the Claude Code skills and hooks in .claude/ (--check, --quiet)
  *
  * Conventions (full spec in this package's README):
  *   facts     <facts>/*.yaml, flat records: - id / value / statement / status / updated
@@ -26,7 +27,7 @@
  *
  * All logic lives in ../lib; this file only formats and dispatches.
  */
-import { findRoot, loadRepo, staleList, checkRepo, graphJson, touch as touchFiles, renderOutputs, renderStatus, syncPlan, syncExamples, feedsIndex, previousSelection, lineDiff } from '../lib/core.mjs';
+import { installSkills, skillsStatus, findRoot, loadRepo, staleList, checkRepo, graphJson, touch as touchFiles, renderOutputs, renderStatus, syncPlan, syncExamples, feedsIndex, previousSelection, lineDiff } from '../lib/core.mjs';
 
 const ROOT = findRoot(process.cwd());
 const cmd = process.argv[2];
@@ -164,6 +165,27 @@ function render(repo, only) {
   if (done.some((r) => !r.ok)) process.exit(1);
 }
 
+/**
+ * fakto skills [--check | --quiet]
+ * Installs this package's Claude Code skills into .claude/skills (stamped with the version) and
+ * merges its hooks and permissions into .claude/settings.json. Runs on postinstall and at session
+ * start. --check exits 1 when anything is missing or out of date; --quiet prints only changes.
+ */
+function skills() {
+  if (args.includes('--check')) {
+    const s = skillsStatus(ROOT);
+    for (const k of s.skills) console.log(`${k.status === 'ok' ? grn('ok      ') : red(k.status.padEnd(8))} .claude/skills/${k.name}${k.installed ? dim(`  (installed ${k.installed}, package ${s.version})`) : ''}`);
+    console.log(`${s.settings === 'ok' ? grn('ok      ') : red(s.settings.padEnd(8))} .claude/settings.json`);
+    if (!s.ok) { console.log(`\nRun ${'npx fakto skills'} to install the skills for ${s.version}.`); process.exit(1); }
+    return;
+  }
+  const { changed, version } = installSkills(ROOT);
+  const quiet = args.includes('--quiet');
+  if (!changed.length) { if (!quiet) console.log(grn(`Fakto skills are up to date (${version}).`)); return; }
+  if (quiet) console.log(`The Fakto skills were just updated to ${version} (${changed.join(', ')}). Read .claude/skills/fakto/SKILL.md and .claude/skills/fakto-canvas/SKILL.md again before you use them.`);
+  else for (const c of changed) console.log(`${c}: updated to ${version}`);
+}
+
 /** What answers on a port: { root } for a fakto canvas, 'other' for anything else, null when free. */
 async function probe(port) {
   try {
@@ -234,7 +256,7 @@ async function canvas() {
   await start({ root: ROOT, port });
 }
 
-const repo = cmd && cmd !== 'canvas' ? loadRepo(ROOT) : null;
+const repo = cmd && cmd !== 'canvas' && cmd !== 'skills' ? loadRepo(ROOT) : null;
 switch (cmd) {
   case 'graph': graph(repo); break;
   case 'check': check(repo); break;
@@ -243,8 +265,9 @@ switch (cmd) {
   case 'touch': touch(repo, args); break;
   case 'render': render(repo, args); break;
   case 'sync': sync(repo, args); break;
+  case 'skills': skills(); break;
   case 'canvas': await canvas(); break;
   default:
-    console.log('usage: fakto graph | check | stale | show <fact-id | file> | touch <file | fact-id>… | render [path…] | sync [path | fact-id …] | canvas');
+    console.log('usage: fakto graph | check | stale | show <fact-id | file> | touch <file | fact-id>… | render [path…] | sync [path | fact-id …] | skills | canvas');
     process.exit(cmd ? 1 : 0);
 }

package/lib/core.mjs

@@ -18,8 +18,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { renderStatus } from './render.mjs';
+import { skillsStatus } from './skills.mjs';
 import { parseSourceAnchors, factSourceStatus, drawStatus, exampleStatus, syncPlan, sourceCycles, restampFile, restampedSource, parseRef } from './sources.mjs';
 
+export { installSkills, skillsStatus, PACKAGE } from './skills.mjs';
 export { renderStatus, renderOutputs, parseSlides, stripAnchors, sourceHash, RENDERERS } from './render.mjs';
 export { parseRef, refString, resolveRef, blobHash, factSourceStatus, drawStatus, exampleStatus, syncPlan, sourceCycles, syncExamples, previousSelection, lineDiff, FROM_RE, EXAMPLE_RE } from './sources.mjs';
 
@@ -162,7 +164,7 @@ export function anchorOk(repo, artifact, anchor) {
  * Every problem, in the order the CLI prints them.
  * level: error | warning | info. kind: orphan | no-stamp | unknown | unknown-support | retired | draft | drift | stale |
  *   render-stale | render-missing | render-config | source-changed | source-missing | example-drift | source-cycle |
- *   region-unused.
+ *   region-unused | skills.
  * `message` is the CLI's text (without colour); line-level problems also carry
  * path, line, text, fact for the canvas.
  */
@@ -221,6 +223,12 @@ export function checkRepo(repo) {
     for (const a of repo.artifacts) for (const x of [...a.draws, ...a.examples]) if (x.ref.selector) used.add(`${x.ref.path}#${x.ref.selector}`);
     for (const a of repo.artifacts) for (const r of a.regions) if (!used.has(`${a.file}#${r.name}`)) out.push({ level: 'info', kind: 'region-unused', path: a.file, line: r.line, message: `${a.file}:${r.line}: region "${r.name}" is marked but nothing draws on it` });
   }
+  // The Claude Code skills and hooks this package ships must be installed, and current.
+  const sk = skillsStatus(repo.root);
+  if (!sk.ok) {
+    const bad = [...sk.skills.filter((s) => s.status !== 'ok').map((s) => `${s.name} ${s.status}${s.installed ? ` (${s.installed})` : ''}`), ...(sk.settings === 'ok' ? [] : [`settings ${sk.settings}`])];
+    out.push({ level: 'warning', kind: 'skills', path: '.claude', message: `.claude: the Fakto skills for Claude Code are not current for ${sk.version} (${bad.join(', ')}) — run npx fakto skills` });
+  }
   for (const r of renderStatus(repo)) {
     if (r.status === 'stale') out.push({ level: 'warning', kind: 'render-stale', path: r.to, message: `${r.to}: out of date with ${r.from} — run fakto render` });
     if (r.status === 'missing') out.push({ level: 'warning', kind: 'render-missing', path: r.to, message: `${r.to}: not rendered yet from ${r.from} — run fakto render` });

package/lib/skills.mjs

@@ -0,0 +1,95 @@
+/**
+ * The Claude Code side of a Fakto repo ships in this package, so it can never drift from the
+ * CLI it calls: the skills in ../skills and the hooks and permissions below.
+ *
+ *   installSkills(root)  write .claude/skills/<name>/ (stamped with this package's version) and
+ *                        merge the hooks and permissions into .claude/settings.json
+ *   skillsStatus(root)   what `fakto skills --check` and `fakto check` report
+ *
+ * Claude Code loads skills from the project's .claude/skills, never from node_modules, so a
+ * repo runs `fakto skills` on postinstall and the session-start hook runs it again.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SOURCE = path.join(PKG, 'skills');
+export const PACKAGE = JSON.parse(fs.readFileSync(path.join(PKG, 'package.json'), 'utf8'));
+const STAMP_RE = /<!-- Installed by `fakto skills` from (\S+)@(\d+\.\d+\.\d+[^\s.]*)\./;
+const stamp = () => `\n<!-- Installed by \`fakto skills\` from ${PACKAGE.name}@${PACKAGE.version}. Do not edit: \`fakto skills\` overwrites this file; change the package's skills instead. -->\n`;
+
+export const SESSION_HOOK = [
+  '[ -f fakto.config.json ] && [ -z "$FAKTO_CANVAS_RUN" ] && {',
+  'if [ -x node_modules/.bin/fakto ]; then node_modules/.bin/fakto skills --quiet;',
+  "echo 'This is a Fakto repo. Before anything else, use the fakto-canvas skill: start the canvas (npx fakto canvas --background) and tell the user where it runs.';",
+  "else echo 'This is a Fakto repo whose dependencies are not installed yet. Before anything else run npm install: it installs Fakto and refreshes its Claude skills in .claude/skills. Then use the fakto-canvas skill to start the canvas and tell the user where it runs.';",
+  'fi; } || true',
+].join(' ');
+export const CHECK_HOOK = 'npx --no fakto check 2>&1 | tail -n 8';
+export const PERMISSIONS = ['Bash(npx fakto:*)', 'Bash(npm run:*)', 'Bash(npm install)'];
+
+const ours = (entry) => (entry.hooks || []).some((h) => typeof h.command === 'string' && /\bfakto\b/.test(h.command));
+const WANT_HOOKS = {
+  SessionStart: { hooks: [{ type: 'command', command: SESSION_HOOK }] },
+  PostToolUse: { matcher: 'Edit|Write|MultiEdit', hooks: [{ type: 'command', command: CHECK_HOOK }] },
+};
+
+/** The settings with Fakto's hooks and permissions in place; everything else is kept as it was. */
+function mergedSettings(current) {
+  const s = JSON.parse(JSON.stringify(current || {}));
+  s.permissions = s.permissions || {};
+  s.permissions.allow = [...new Set([...(s.permissions.allow || []), ...PERMISSIONS])];
+  s.hooks = s.hooks || {};
+  for (const [event, entry] of Object.entries(WANT_HOOKS)) {
+    s.hooks[event] = [...(s.hooks[event] || []).filter((e) => !ours(e)), entry];
+  }
+  return s;
+}
+
+const skillNames = () => fs.readdirSync(SOURCE, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+const wanted = (name) => fs.readFileSync(path.join(SOURCE, name, 'SKILL.md'), 'utf8').replace(/\n*$/, '\n') + stamp();
+const settingsPath = (root) => path.join(root, '.claude', 'settings.json');
+const readJson = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
+
+/** { ok, version, skills: [{ name, status: ok | missing | outdated | modified, installed? }], settings: ok | missing | outdated } */
+export function skillsStatus(root) {
+  const skills = skillNames().map((name) => {
+    const p = path.join(root, '.claude', 'skills', name, 'SKILL.md');
+    if (!fs.existsSync(p)) return { name, status: 'missing' };
+    const have = fs.readFileSync(p, 'utf8');
+    const m = have.match(STAMP_RE);
+    if (have === wanted(name)) return { name, status: 'ok' };
+    if (m && m[2] !== PACKAGE.version) return { name, status: 'outdated', installed: m[2] };
+    return { name, status: 'modified' };   // same version (or no stamp at all) but different text: edited by hand
+  });
+  const cur = readJson(settingsPath(root));
+  const settings = !cur ? 'missing' : JSON.stringify(mergedSettings(cur)) === JSON.stringify(cur) ? 'ok' : 'outdated';
+  return { ok: skills.every((s) => s.status === 'ok') && settings === 'ok', version: PACKAGE.version, skills, settings };
+}
+
+/** Write what is not ok. Returns { changed: [paths], version }. */
+export function installSkills(root) {
+  const changed = [];
+  for (const name of skillNames()) {
+    const dir = path.join(root, '.claude', 'skills', name);
+    const p = path.join(dir, 'SKILL.md');
+    const want = wanted(name);
+    // a symlink (an older setup) is replaced by a real file, so the repo works on its own
+    try { if (fs.lstatSync(dir).isSymbolicLink()) fs.rmSync(dir); } catch { /* not there yet */ }
+    if (fs.existsSync(p) && fs.readFileSync(p, 'utf8') === want) continue;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, want);
+    changed.push(path.relative(root, p));
+  }
+  const sp = settingsPath(root);
+  const cur = readJson(sp);
+  if (fs.existsSync(sp) && !cur) throw new Error(`${path.relative(root, sp)} is not valid JSON; fix it, then run fakto skills again`);
+  const next = mergedSettings(cur);
+  if (!cur || JSON.stringify(next) !== JSON.stringify(cur)) {
+    fs.mkdirSync(path.dirname(sp), { recursive: true });
+    fs.writeFileSync(sp, JSON.stringify(next, null, 2) + '\n');
+    changed.push(path.relative(root, sp));
+  }
+  return { changed, version: PACKAGE.version };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fakto/core",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "license": "UNLICENSED",
   "description": "Keep every file that states a fact in line with the fact: the CLI, the library and the canvas in one package.",
   "type": "module",
@@ -17,6 +17,8 @@
     "lib/core.mjs",
     "lib/render.mjs",
     "lib/sources.mjs",
+    "lib/skills.mjs",
+    "skills",
     "canvas/server",
     "canvas/dist",
     "canvas/README.md",

package/skills/fakto/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: fakto
+description: >
+  Keep every artifact (docs, code, website, decks, box copy) in sync with the facts
+  it depends on. Use whenever a fact changes ("the price is now X", "we have 9 levels
+  now", "retire feature Y"), whenever `fakto check` or `fakto stale` reports something,
+  when adding a new fact or a new artifact, or when the user says "propagate",
+  "update everything that mentions X", or "what depends on X". Also when a source file
+  changed ("I changed the code, sync the docs", `fakto check` says "behind its source",
+  `fakto sync`). Facts live in the facts directory named in fakto.config.json; artifacts
+  carry `fact:<id>` anchors, and may draw on other files with `from:` / `example:`.
+---
+
+# fakto — keep dependents in sync
+
+Facts are the source of truth. Artifacts cite them with an inline anchor
+`fact:<id>` on the line that states the fact. The CLI finds what depends on
+what; this skill does the part that needs judgment: rewriting the dependents.
+
+Run the CLI as `npx fakto <cmd>` (the repo installs the `fakto` package).
+The conventions are in the package README (`node_modules/@fakto/core/README.md`).
+If `fakto.config.json` names `houseRules`, read that file before writing any
+artifact and follow it: it is the company's voice and wording rules.
+
+## Which case are you in?
+
+### A. A fact changed (the common case)
+
+1. Edit the fact record only: `value`, `statement`, and bump `updated` to today.
+   Never touch an artifact first.
+2. Run `npx fakto stale`. It lists every artifact whose `reviewed` date is older than
+   the fact's `updated` date, with the exact lines (anchors) that cite it.
+3. For each stale artifact, draft the minimal edit that makes the anchored line
+   true again. Rules:
+   - Change the sentence, keep the voice of that artifact (a manual is not a deck).
+   - Keep the anchor comment on the line. The drift check needs the new `value`
+     to appear on that line.
+   - Code: change the constant, not the comment. Derived values (enums, ranges,
+     schemas) move with it.
+   - `lifecycle: snapshot` artifacts are frozen. Never edit them; they are history.
+   - A changelog is living: add a dated entry on top, never rewrite old entries.
+     When an old entry's fact changes, turn its anchor into an as-of citation
+     (`fact:id@<that entry's date>`) so the line keeps its link and stops being
+     checked for the current value. Same for any "was X, now Y" aside.
+   - If an edit needs a decision (new copy angle, a number that no longer fits the
+     story), stop and ask; do not invent.
+4. Present the edit list (file, line, before → after) and apply it. If the user
+   asked for autonomous propagation, apply without asking.
+5. Stamp the reviewed artifacts: `npx fakto touch <file>…`. If `fakto.config.json`
+   declares `renders`, run `npx fakto render` next: generated outputs (a slide deck
+   built from a Markdown deck) are rebuilt from their source, never edited by hand.
+6. Run `npx fakto check`. It must print `0 errors` with no stale warnings. Fix anything
+   it reports before you call the job done.
+
+### B. Retiring a fact
+
+1. Set `status: retired` on the record, bump `updated`, add a `note:` saying why.
+2. Run `npx fakto check`. Every living artifact that cites it is now an error.
+3. Remove or rewrite each citing line. Where the artifact should record that the
+   thing existed (a changelog, a history section), keep the anchor as an as-of
+   citation (`fact:id@date`) or put `RETIRED` on the line.
+4. `npx fakto touch` the edited files, `npx fakto check` must be green.
+
+### C. Adding a new fact
+
+1. One record per fact, kebab-case id with a topic prefix, `status: live` only
+   when the value is confirmed; otherwise `draft`.
+2. `value` is the shortest string every artifact line must contain. Pick it so
+   it matches prose and code alike (`"7"`, `"$4.99"`, `"client.send("`).
+3. Anchor the artifacts that already state it. Run `npx fakto graph` to confirm it has
+   dependents; a fact with none is either new copy to write or not a fact.
+
+### D. Tagging a new artifact
+
+1. Add `reviewed: YYYY-MM-DD` to the file head (frontmatter or a comment).
+2. Anchor every line that states a fact: `<!-- fact:id -->`, `// fact:id`,
+   `# fact:id`, whatever comment syntax the file uses.
+3. A published, dated thing (a post, a press release, an old deck) gets
+   `lifecycle: snapshot` and is never edited again.
+4. `npx fakto check` must be green.
+
+### E. Narratives (facts without a `value`)
+
+A narrative is a story every channel tells in its own words ("a platform, not an
+appliance"). Its record has a `statement` and no `value`, and usually `supports: [ids]`,
+the facts it rests on. The check cannot compare wording, so you are the check:
+
+1. When a narrative's statement changes, `fakto stale` lists every section anchored to
+   it. Rewrite each so it tells the new story in that file's voice: a website headline,
+   a slide, a sentence in a deck. Do not paste the statement verbatim unless the file
+   is meant to quote it.
+2. Consistency pass: whenever you rewrite a file that cites a narrative (for any
+   reason), read the anchored section and confirm it still tells that narrative. If it
+   no longer does, rewrite it or report it; never leave a section that contradicts its
+   story.
+3. Numbers inside a narrative section are still facts: anchor them separately.
+4. `supports` must list existing fact ids; the check fails otherwise.
+
+### F. A source file changed (sync)
+
+Some facts and sections follow a file instead of the other way round: a fact with
+`source:`, a section with `<!-- from:path#selector -->`, a fence after
+`<!-- example:path#selector -->`. When that file changes:
+
+1. Run `npx fakto sync`. It copies every fenced example from its source (never edit those
+   by hand) and lists the facts and sections that need judgment, with the diff since their
+   last sync where git has the old version.
+2. **Facts.** For each listed fact, read the source (the anchored line, or the selection).
+   Change `value` and `statement` only if the meaning changed, and bump `updated` when you
+   do. For a source with a selector, then run `npx fakto touch <fact-id>` to restamp it,
+   also when nothing changed. A derived fact is never edited for any other reason.
+3. **Sections.** For each listed section, reread it against the source. Rewrite it only
+   where it no longer describes the source, in that file's own voice, keeping its anchors.
+   Then `npx fakto touch <file>`: it stamps `reviewed` and moves the `from:` hashes.
+4. **Propagate.** If step 2 changed a fact, follow case A from step 2 (`npx fakto stale`,
+   rewrite, touch, render).
+5. `npx fakto check` must be green. A rewrite can change a file another section draws on;
+   if `fakto check` still reports something behind its source, go again (at most three
+   passes, then report what is left).
+
+## Invariants
+
+- No number, name or claim in an artifact without a fact record and an anchor.
+- Forward links only: artifacts point at facts. The reverse direction is derived
+  by `npx fakto graph`, never stored.
+- The `updated` date on a fact moves on every value change. That date is the
+  whole propagation mechanism; forget it and nothing goes stale.
+- Snapshots are never edited. Living artifacts are never left stale.
+- Render outputs are build output: edit the source, then `npx fakto render`.
+- A derived fact (one with `source:`) follows its file: change the file, never the record.
+- Fenced examples are copies: `npx fakto sync` writes them, nobody else.

package/skills/fakto-canvas/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: fakto-canvas
+description: >
+  Start the Fakto canvas, the live map of this repo's facts and the files that state them,
+  and tell the user where it runs. Use it first, at the start of every session in a repo
+  that has a fakto.config.json, before any other work. Also use it whenever the user wants
+  to see the map, the canvas, or the changes as they happen, or says "start", "run it",
+  "open the canvas" or "show me".
+---
+
+# fakto-canvas — start the live map and say where it is
+
+The canvas is a local web page that draws every fact and every file that cites it, and
+updates live as files change. The user watches it while you work in the terminal, so
+start it before anything else.
+
+1. Run `npx fakto canvas --background`. It starts the canvas detached (or finds the one already
+   running for this repo) and returns within a few seconds with one line:
+   - `fakto canvas: http://localhost:<port>  (started in the background …)`: it started.
+   - `fakto canvas: http://localhost:<port>  (already running for …)`: one was already up.
+   - `The canvas is not installed` or `Cannot find package`: the dependencies are missing.
+     Run `npm install`, then try again.
+   Never run plain `npx fakto canvas` yourself: it stays in the foreground and blocks you.
+2. If it timed out, read the log file it names and tell the user what it says.
+3. Run `npx fakto check` and keep its last line (the error and warning count).
+4. Tell the user, in two short lines, with the real URL and counts:
+   > The Fakto canvas is running at http://localhost:4848. Open it to watch facts and files
+   > update as we work.
+   > Right now: 31 facts, 15 files, check green (or: what the check reports).
+
+   Get the counts from `npx fakto graph --json` if you need them (`facts.length`,
+   `artifacts.length`).
+
+## While it runs
+
+- Every edit you make shows up on the canvas within a second; mention it when the user should
+  look ("watch the marketing column").
+- The canvas has its own buttons (Save on a fact, Sync, Sync all). They run the user's Claude
+  Code CLI in this repo; their results land in the same files you see.
+- Leave it running when the session ends. If the user asks to stop it: `npx fakto canvas --stop`.