ekohacks 0.4.0 → 0.5.0

package/dist/cli.js

@@ -9,8 +9,9 @@ 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, docsSync } 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';
@@ -18,6 +19,7 @@ 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);
@@ -31,7 +33,7 @@ const printChecks = (checks) => {
 };
 if (command === 'docs') {
     const subject = rest[0];
-    if (rest.length !== 1 || (subject !== 'check' && subject !== 'sync')) {
+    if (rest.length !== 1 || (subject !== 'check' && subject !== 'sync' && subject !== 'draft')) {
         console.error(USAGE);
         process.exit(2);
     }
@@ -67,6 +69,68 @@ if (command === 'docs') {
         }
         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.
@@ -155,15 +161,22 @@ const syncedBlock = (region, pkg, entries) => {
     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 sidebar is code the sync will not touch, so
-// the line a human has to add is spelled out rather than written.
+// 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 = specifier.split('/').at(-1) ?? specifier;
+    const name = pageNameFor(specifier);
     return {
         path: `docs/${name}.md`,
         content: [
             `# ${specifier}`,
             '',
+            DRAFT_OPEN,
+            '',
             '```ts',
             importLineFor(specifier),
             '',
@@ -174,6 +187,8 @@ const stubFor = (specifier) => {
             '',
             '- 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}' } -->`,
             '',
@@ -231,3 +246,117 @@ export const docsSync = ({ pkg, exports, files, }) => {
     }
     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.4.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
+    }
   }
 }