ekohacks 0.3.0 → 0.5.0

package/README.md

@@ -10,6 +10,8 @@ The release command is built: the four stories in [`stories/`](stories/) are imp
 
 The second command is `ekohacks docs check`, specified in [`stories/6-docs-check.md`](stories/6-docs-check.md): a gate that fails when a package's docs drift from its shipped exports map, born from the EkoLite 0.4.0 release shipping a wrong public surface. Its acceptance test is the same command run inside EkoLite.
 
+`ekohacks docs sync` is the other half, specified in [`stories/8-docs-sync.md`](stories/8-docs-sync.md): it writes the edits the check can prove — the entry-point block, the prose counts — and scaffolds a stub page for an entry point the docs just gained, leaving the prose to a person. [`stories/9-docs-draft.md`](stories/9-docs-draft.md) specifies drafting that prose and opening a PR for a human to review; it is written down, not built.
+
 ## How this is built
 
 - A tested core policy behind nullable infrastructure, in the style of [James Shore's Testing Without Mocks](https://www.jamesshore.com/v2/projects/nullables): real wrappers around `git`, `gh` and `npm`, each with a `createNull()` that answers with configurable responses and records what was asked of it. No mocks, no spies.

package/dist/cli.js

@@ -2,31 +2,38 @@
 // The thin shell: read the repo's files, wire the real wrappers, print one line per
 // check and per step, exit 0 only when the command ran to its end. Everything worth
 // testing lives below.
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { GhWrapper } from './infrastructure/gh.js';
 import { GitWrapper } from './infrastructure/git.js';
 import { NpmWrapper } from './infrastructure/npm.js';
 import { ProcessRunner } from './infrastructure/process.js';
+import { ClaudeWrapper } from './infrastructure/claude.js';
 import { cut } from './logic/cut.js';
-import { docsCheck } from './logic/docs.js';
+import { docsCheck, docsDraft, docsSync, draftBranchConflict, draftPrompts, openDraftPr, } from './logic/docs.js';
 import { preflight } from './logic/preflight.js';
 import { release } from './logic/release.js';
 import { ship } from './logic/ship.js';
 const USAGE = [
     'usage: ekohacks release [preflight|cut|ship] <version> [--yes]',
     '       ekohacks docs check',
+    '       ekohacks docs sync [--dry-run]',
+    '       ekohacks docs draft [--yes]',
 ].join('\n');
+const FLAGS = ['--yes', '--dry-run'];
 const argv = process.argv.slice(2);
 const yes = argv.includes('--yes');
-const [command, ...rest] = argv.filter((arg) => arg !== '--yes');
+const dryRun = argv.includes('--dry-run');
+const [command, ...rest] = argv.filter((arg) => !FLAGS.includes(arg));
 const printChecks = (checks) => {
     for (const check of checks) {
         console.log(check.passed ? `  ok    ${check.name}` : `  FAIL  ${check.name}: ${check.reason}`);
     }
 };
 if (command === 'docs') {
-    if (rest.length !== 1 || rest[0] !== 'check') {
+    const subject = rest[0];
+    if (rest.length !== 1 || (subject !== 'check' && subject !== 'sync' && subject !== 'draft')) {
         console.error(USAGE);
         process.exit(2);
     }
@@ -46,6 +53,84 @@ if (command === 'docs') {
             }
         }
     }
+    if (subject === 'sync') {
+        const { edits } = docsSync({ pkg: manifest.name, exports: manifest.exports, files });
+        if (edits.length === 0) {
+            console.log('  the docs are already in step');
+            process.exit(0);
+        }
+        for (const edit of edits) {
+            const verb = existsSync(edit.path) ? 'updated' : 'created';
+            if (!dryRun) {
+                mkdirSync(dirname(edit.path), { recursive: true });
+                writeFileSync(edit.path, edit.content);
+            }
+            console.log(`  ${dryRun ? `would have ${verb}` : verb} ${edit.path}`);
+        }
+        process.exit(0);
+    }
+    if (subject === 'draft') {
+        if (process.env.ANTHROPIC_API_KEY === undefined || process.env.ANTHROPIC_API_KEY === '') {
+            console.error('stopped: docs draft needs ANTHROPIC_API_KEY');
+            process.exit(1);
+        }
+        const prompts = draftPrompts({ pkg: manifest.name, exports: manifest.exports, files });
+        if (prompts.length === 0) {
+            console.log('  nothing to draft: no page carries a draft block');
+            process.exit(0);
+        }
+        // The PR branch is checked before the model runs, not after: a repeat run stops here for
+        // free rather than spending on drafts it could never open. The same wrapper opens the PR.
+        const git = GitWrapper.create();
+        const conflict = await draftBranchConflict(git);
+        if (conflict !== undefined) {
+            console.error(`stopped: ${conflict}`);
+            process.exit(1);
+        }
+        const pages = `${prompts.length} page${prompts.length === 1 ? '' : 's'}`;
+        console.log(`  ${pages} to draft, one model call each:`);
+        for (const { specifier } of prompts) {
+            console.log(`    ${specifier}`);
+        }
+        if (!yes) {
+            const readline = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = await readline.question(`  draft ${pages}? (y/n) `);
+            readline.close();
+            if (answer.trim().toLowerCase() !== 'y') {
+                console.error('stopped: draft not approved');
+                process.exit(1);
+            }
+        }
+        let claude;
+        try {
+            claude = await ClaudeWrapper.create();
+        }
+        catch (error) {
+            console.error(`stopped: ${error.message}`);
+            process.exit(1);
+        }
+        const { edits } = await docsDraft({
+            pkg: manifest.name,
+            exports: manifest.exports,
+            files,
+            claude,
+        });
+        for (const edit of edits) {
+            writeFileSync(edit.path, edit.content);
+            console.log(`  drafted ${edit.path}`);
+        }
+        const pr = await openDraftPr({
+            specifiers: prompts.map((prompt) => prompt.specifier),
+            git,
+            gh: GhWrapper.create(),
+        });
+        if ('stopped' in pr) {
+            console.error(`stopped: ${pr.stopped}`);
+            process.exit(1);
+        }
+        console.log(`  opened pr #${pr.number}`);
+        process.exit(0);
+    }
     const report = await docsCheck({
         pkg: manifest.name,
         exports: manifest.exports,

package/dist/infrastructure/claude.js

@@ -0,0 +1,54 @@
+const MODEL = 'claude-opus-4-8';
+const MAX_TOKENS = 16000;
+// Wraps the one model call the drafting policy needs: a prompt in, the text out. Real and null
+// share every line above the bottom layer — create() reaches the SDK through a dynamic import
+// so the other commands never pay for a client nobody asked for, and stops with a named reason
+// when the optional peer dependency is absent; createNull() answers configured text in order,
+// imports nothing, and never opens a socket. Both record every prompt through complete(), the
+// way NpmWrapper records every bump, so a test can pin what the policy asked without a spy.
+export class ClaudeWrapper {
+    static async create({ apiKey = process.env.ANTHROPIC_API_KEY, } = {}) {
+        const sdk = await import('@anthropic-ai/sdk').catch(() => undefined);
+        if (sdk === undefined) {
+            throw new Error('docs draft needs @anthropic-ai/sdk — npm i -g @anthropic-ai/sdk');
+        }
+        const client = new sdk.default({ apiKey });
+        return new ClaudeWrapper(async (prompt) => {
+            const message = await client.messages.create({
+                model: MODEL,
+                max_tokens: MAX_TOKENS,
+                thinking: { type: 'adaptive' },
+                messages: [{ role: 'user', content: prompt }],
+            });
+            return message.content
+                .filter((block) => block.type === 'text')
+                .map((block) => block.text)
+                .join('');
+        });
+    }
+    static createNull({ responses = [] } = {}) {
+        let round = 0;
+        return new ClaudeWrapper((_prompt) => {
+            const index = Math.min(round, responses.length - 1);
+            round += 1;
+            return Promise.resolve(responses[index] ?? '');
+        });
+    }
+    runComplete;
+    promptTrackers = [];
+    constructor(runComplete) {
+        this.runComplete = runComplete;
+    }
+    trackPrompts() {
+        const tracker = [];
+        this.promptTrackers.push(tracker);
+        return { data: tracker };
+    }
+    async complete(prompt) {
+        const text = await this.runComplete(prompt);
+        for (const tracker of this.promptTrackers) {
+            tracker.push(prompt);
+        }
+        return text;
+    }
+}

package/dist/logic/docs.js

@@ -1,7 +1,13 @@
+import { ClaudeWrapper } from '../infrastructure/claude.js';
+import { GhWrapper } from '../infrastructure/gh.js';
+import { GitWrapper } from '../infrastructure/git.js';
 import { ProcessRunner } from '../infrastructure/process.js';
+const DRAFT_BRANCH = 'docs/draft';
 const DOCS_BUILD_COMMAND = 'npm run docs:build';
 const OPEN_MARKER = '<!-- ekohacks:entry-points -->';
 const CLOSE_MARKER = '<!-- /ekohacks:entry-points -->';
+const DRAFT_OPEN = '<!-- ekohacks:draft -->';
+const DRAFT_CLOSE = '<!-- /ekohacks:draft -->';
 // The public entry points an exports map declares, as the specifiers a consumer imports:
 // "." is the bare package name, "./react" is pkg/react. A package with no exports map —
 // or a conditions-only one, with no "." keys — has a single entry point: itself.
@@ -50,9 +56,12 @@ const COUNT_WORDS = {
     nine: 9,
     ten: 10,
 };
-const countClaimsIn = (content) => [
-    ...content.matchAll(/\b(\d+|zero|one|two|three|four|five|six|seven|eight|nine|ten)[\s-]+entry[\s-]+points?\b/gi),
-].map(([, claim = '']) => COUNT_WORDS[claim.toLowerCase()] ?? Number(claim));
+// One definition of what a claim looks like, read by the check and rewritten by the sync — two
+// copies of it would be their own drift. Built fresh at each use: a shared global regex carries
+// its lastIndex from call to call.
+const COUNT_CLAIM_SOURCE = String.raw `\b(\d+|zero|one|two|three|four|five|six|seven|eight|nine|ten)[\s-]+entry[\s-]+points?\b`;
+const countClaims = () => new RegExp(COUNT_CLAIM_SOURCE, 'gi');
+const countClaimsIn = (content) => [...content.matchAll(countClaims())].map(([, claim = '']) => COUNT_WORDS[claim.toLowerCase()] ?? Number(claim));
 // The drift detector as a policy: the exports map is the truth, the docs carry their
 // claims in a block the tool owns, and every mismatch is a named check with the reason
 // a human needs to fix it. The caller supplies file contents and the runner; the policy
@@ -108,3 +117,246 @@ export const docsCheck = async ({ pkg, exports, files, runner, }) => {
         : { name: 'docs build', passed: false, reason: `${DOCS_BUILD_COMMAND} failed` });
     return { checks };
 };
+// Walks the same markers blockRegions does, but rebuilds the document around each region so a
+// rewrite can be handed back in place. An unclosed block ends the walk with the rest of the
+// document untouched: the check already fails it by name, and a sync that guessed where the
+// block ended would be guessing with someone's prose.
+const mapBlocks = (content, rewrite) => {
+    let rest = content;
+    let out = '';
+    for (;;) {
+        const open = rest.indexOf(OPEN_MARKER);
+        if (open === -1) {
+            return out + rest;
+        }
+        const afterOpen = rest.slice(open + OPEN_MARKER.length);
+        const close = afterOpen.indexOf(CLOSE_MARKER);
+        if (close === -1) {
+            return out + rest;
+        }
+        out += rest.slice(0, open) + OPEN_MARKER + rewrite(afterOpen.slice(0, close)) + CLOSE_MARKER;
+        rest = afterOpen.slice(close + CLOSE_MARKER.length);
+    }
+};
+// A namespace import is the one form the exports map alone can justify: it needs the specifier
+// and nothing else. The local name is the last segment, camel-cased past any character an
+// identifier cannot carry.
+const importLineFor = (specifier) => {
+    const [first = specifier, ...rest] = (specifier.split('/').at(-1) ?? specifier).split(/[^a-zA-Z0-9]+/);
+    const local = [first, ...rest.map((part) => part.charAt(0).toUpperCase() + part.slice(1))].join('');
+    return `import * as ${local} from '${specifier}';`;
+};
+// Both edits to a block are line surgery on the specifiers it already lists: a line naming a
+// specifier the exports no longer declare goes, and a specifier no line names arrives after the
+// last one that survived. Lines naming another package are not the block's business — the check
+// ignores them, and so does this.
+const syncedBlock = (region, pkg, entries) => {
+    const kept = region
+        .split('\n')
+        .filter((line) => specifiersIn(line, pkg).every((specifier) => entries.includes(specifier)));
+    const documented = new Set(specifiersIn(kept.join('\n'), pkg));
+    const missing = entries.filter((entry) => !documented.has(entry));
+    const lastImport = kept.reduce((found, line, index) => (specifiersIn(line, pkg).length > 0 ? index : found), -1);
+    kept.splice(lastImport + 1, 0, ...missing.map(importLineFor));
+    return kept.join('\n');
+};
+// A page the tool can write without knowing anything it does not know: the import line it can
+// derive, and a TODO everywhere prose belongs. The example and "what works today" live inside a
+// draft block the drafting tool owns, the seam `docs draft` writes into; the heading above and
+// the sidebar TODO below stay outside it, so a draft never touches them. The sidebar is code the
+// sync will not touch, so the line a human has to add is spelled out rather than written.
+// The page a specifier documents, derived from the specifier alone: ekolite/config → config.
+// stubFor writes it and draftPrompts reads it back, so it lives in one place rather than two.
+const pageNameFor = (specifier) => specifier.split('/').at(-1) ?? specifier;
+const stubFor = (specifier) => {
+    const name = pageNameFor(specifier);
+    return {
+        path: `docs/${name}.md`,
+        content: [
+            `# ${specifier}`,
+            '',
+            DRAFT_OPEN,
+            '',
+            '```ts',
+            importLineFor(specifier),
+            '',
+            '// TODO: an example that runs.',
+            '```',
+            '',
+            '## What works today',
+            '',
+            '- TODO: what a reader can rely on today, not what is planned.',
+            '',
+            DRAFT_CLOSE,
+            '',
+            '<!-- TODO: add this page to the sidebar in docs/.vitepress/config.mts:',
+            `     { text: '${name}', link: '/${name}' } -->`,
+            '',
+        ].join('\n'),
+    };
+};
+const wordForCount = (count) => Object.entries(COUNT_WORDS).find(([, value]) => value === count)?.[0];
+// A claim is rewritten in the form it was written: a digit stays a digit, a word stays a word
+// carrying the case it had. Past ten the table has no word, so the claim becomes a digit — the
+// same number the check reads either way.
+const countAs = (written, count) => {
+    const word = wordForCount(count);
+    if (/^\d+$/.test(written) || word === undefined) {
+        return String(count);
+    }
+    return written.charAt(0) === written.charAt(0).toUpperCase()
+        ? word.charAt(0).toUpperCase() + word.slice(1)
+        : word;
+};
+const syncedCounts = (content, count) => content.replace(countClaims(), (claim) => {
+    const written = claim.split(/[\s-]/)[0] ?? '';
+    return countAs(written, count) + claim.slice(written.length);
+});
+// The mechanical half of the drift the check names: the same inputs, and instead of a report
+// the files whose content should change, each as a whole new body. The shell does the writing,
+// so the policy stays pure — and a file this would leave alone never reaches the caller, which
+// is what makes a second run against a repo already in step write nothing.
+export const docsSync = ({ pkg, exports, files, }) => {
+    const entries = entryPointsFrom(pkg, exports);
+    const scanned = files.filter((file) => !file.path.split('/').includes('.vitepress'));
+    const edits = [];
+    for (const file of scanned) {
+        const synced = mapBlocks(file.content, (region) => syncedBlock(region, pkg, entries));
+        const content = syncedCounts(synced, entries.length);
+        if (content !== file.content) {
+            edits.push({ path: file.path, content });
+        }
+    }
+    // What the docs declared before this run is the baseline a stub is new against. An unclosed
+    // block declares nothing readable and a repo with no block at all has no baseline, so neither
+    // gets scaffolded: both are failures the check already names, and guessing past them would
+    // stamp pages across a repo on the strength of a marker somebody forgot to close.
+    const readable = scanned
+        .map((file) => blockRegions(file.content))
+        .filter((block) => !block.unclosed && block.regions.length > 0);
+    const declared = new Set(readable.flatMap((block) => block.regions.flatMap((region) => specifiersIn(region, pkg))));
+    const existing = new Set(files.map((file) => file.path));
+    if (readable.length > 0) {
+        for (const entry of entries.filter((entry) => entry !== pkg && !declared.has(entry))) {
+            const stub = stubFor(entry);
+            if (!existing.has(stub.path)) {
+                edits.push(stub);
+            }
+        }
+    }
+    return { edits };
+};
+// The exports map value a specifier resolves to, so the prompt can show the entry point's real
+// shape. The key is the mirror of entryPointsFrom: pkg is ".", pkg/config is "./config".
+const exportsEntryFor = (pkg, exports, specifier) => {
+    if (typeof exports !== 'object' || exports === null) {
+        return undefined;
+    }
+    const key = specifier === pkg ? '.' : `./${specifier.slice(pkg.length + 1)}`;
+    return exports[key];
+};
+// One prompt per undrafted page — a page carrying a draft block whose entry point the exports
+// map still declares. The repo is the style guide: the prompt quotes two existing pages verbatim
+// rather than describing a voice, so the draft tracks the docs instead of a copy of them. Pure —
+// the caller runs the model and lands the result.
+export const draftPrompts = ({ pkg, exports, files, }) => {
+    const scanned = files.filter((file) => !file.path.split('/').includes('.vitepress'));
+    const voice = scanned
+        .filter((file) => !file.content.includes(DRAFT_OPEN))
+        .sort((a, b) => a.path.localeCompare(b.path))
+        .slice(0, 2)
+        .map((page) => `--- ${page.path} ---\n${page.content}`)
+        .join('\n\n');
+    const prompts = [];
+    for (const specifier of entryPointsFrom(pkg, exports)) {
+        if (specifier === pkg) {
+            continue;
+        }
+        const path = `docs/${pageNameFor(specifier)}.md`;
+        const page = scanned.find((file) => file.path === path);
+        if (page === undefined || !page.content.includes(DRAFT_OPEN)) {
+            continue;
+        }
+        const prompt = [
+            `You are writing the documentation page for the \`${specifier}\` entry point of \`${pkg}\`.`,
+            '',
+            "Its entry in the package's exports map:",
+            '',
+            JSON.stringify(exportsEntryFor(pkg, exports, specifier), null, 2),
+            '',
+            'The page as it stands, a scaffold with a draft block to fill:',
+            '',
+            page.content,
+            '',
+            'Write only what belongs inside the draft block: one import-and-use example that runs, and a',
+            'short "what works today" list. Do not invent API the exports map does not name. Match the',
+            'voice, structure and formatting of these existing pages exactly:',
+            '',
+            voice,
+        ].join('\n');
+        prompts.push({ specifier, path, prompt });
+    }
+    return prompts;
+};
+// The drafted prose replaces the contents of the draft block and nothing else — the heading
+// above it and the sidebar TODO below it are outside the markers, so they survive. A page with
+// no block is returned unchanged, which is how docsDraft leaves a human's prose alone.
+const applyDraft = (content, prose) => {
+    const open = content.indexOf(DRAFT_OPEN);
+    if (open === -1) {
+        return content;
+    }
+    const afterOpen = content.slice(open + DRAFT_OPEN.length);
+    const close = afterOpen.indexOf(DRAFT_CLOSE);
+    if (close === -1) {
+        return content;
+    }
+    const before = content.slice(0, open);
+    const after = afterOpen.slice(close + DRAFT_CLOSE.length);
+    return `${before}${DRAFT_OPEN}\n\n${prose.trim()}\n\n${DRAFT_CLOSE}${after}`;
+};
+// The drafting policy: one model call per undrafted page, the returned prose landed in that
+// page's block. Same shape as docsSync — the files whose content should change, each a whole
+// new body — so the shell writes a draft exactly as it writes a sync. The model's output is
+// whatever the wrapper answers; the policy only decides where it lands.
+export const docsDraft = async ({ pkg, exports, files, claude, }) => {
+    const edits = [];
+    for (const { path, prompt } of draftPrompts({ pkg, exports, files })) {
+        const page = files.find((file) => file.path === path);
+        if (page === undefined) {
+            continue;
+        }
+        const prose = await claude.complete(prompt);
+        edits.push({ path, content: applyDraft(page.content, prose) });
+    }
+    return { edits };
+};
+// The one place the draft branch and its collision message live. The shell asks this before it
+// spends on the model, so a repeat run stops for free instead of drafting into a branch it can
+// never open; openDraftPr asks it again at the last moment as the real safety.
+export const draftBranchConflict = async (git) => (await git.branchExists(DRAFT_BRANCH))
+    ? `branch ${DRAFT_BRANCH} already exists from an earlier draft`
+    : undefined;
+// Opens the PR for drafts the shell has already written to disk: branch, commit, push, open —
+// the same moves as cut, but it stops at the open. Where release cut pauses for a human to
+// merge, this never merges: machine-drafted prose is a suggestion, and the PR body says so, so
+// the worst a bad draft can do is wait in review. `git switch -c` keeps the working-tree edits,
+// so the branch is created after the write. Like cut, it refuses a branch an earlier draft left
+// behind rather than letting git throw on the collision.
+export const openDraftPr = async ({ specifiers, git, gh, }) => {
+    const conflict = await draftBranchConflict(git);
+    if (conflict !== undefined) {
+        return { stopped: conflict };
+    }
+    await git.createBranch(DRAFT_BRANCH);
+    await git.commitAll('docs: draft the scaffolded entry point pages');
+    await git.push();
+    const body = [
+        'Machine-drafted documentation for entry points that carried only a scaffold. The prose is',
+        'unreviewed — read every line before merging, and treat it as a starting point, not an answer.',
+        '',
+        'Drafted:',
+        ...specifiers.map((specifier) => `- \`${specifier}\``),
+    ].join('\n');
+    return gh.openPr({ title: 'docs: draft the scaffolded entry point pages', body });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ekohacks",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The EkoHacks CLI: our everyday operations, automated one small command at a time.",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     "test:package": "scripts/test-package.sh"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "0.115.0",
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@types/node": "^26.1.1",
@@ -40,5 +41,13 @@
   },
   "bin": {
     "ekohacks": "dist/cli.js"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.115.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
   }
 }