@protoboxai/codeloop 0.3.0

package/dist/lib/spec.js

@@ -0,0 +1,102 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { cardKey, findCard, findCardOrNone, readCards } from './cards.js';
+import { annotateCard, RefusalError } from './engine.js';
+import { cardNumber } from './lane.js';
+import { withLock } from './lock.js';
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const LAYERS = ['api', 'sdk', 'ui', 'test', 'docs'];
+const MAX_ACCEPTANCE = 5;
+const TASK = /^- \[( |x)\] (T\d{3})( \[P\])?( \[(US\d+)\])? \[(api|sdk|ui|test|docs)\] (.+)$/;
+const ACCEPTANCE = /^- (US\d+)[ :.]/;
+export function slugify(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
+}
+/** `ref` is a card id or its number. A folder recorded on the card wins over a folder found by number. */
+export function resolveSpecDir(projectDir, ref) {
+    const card = findCardOrNone(readCards(projectDir).cards, ref);
+    if (card?.spec)
+        return card.spec;
+    const key = card ? cardKey(card) : cardNumber(ref);
+    if (existsSync(join(projectDir, 'specs', key)))
+        return `specs/${key}`;
+    const specs = join(projectDir, 'specs');
+    const found = existsSync(specs) ? readdirSync(specs).filter(d => d.startsWith(`${key}-`)) : [];
+    if (found.length === 1)
+        return `specs/${found[0]}`;
+    throw new RefusalError(found.length ? `specs/${key}-* matches ${found.length} folders; pass the card id` : `no spec folder for ${ref}; run \`codeloop spec new <card-id>\``);
+}
+export function newSpec(projectDir, cardId, role = 'agent') {
+    const card = findCard(readCards(projectDir).cards, cardId);
+    const dir = card.spec ?? `specs/${cardKey(card)}-${slugify(card.title)}`;
+    const created = [];
+    mkdirSync(join(projectDir, dir), { recursive: true });
+    for (const name of ['research.md', 'spec.md', 'plan.md', 'tasks.md']) {
+        const dest = join(projectDir, dir, name);
+        if (existsSync(dest))
+            continue;
+        const template = readFileSync(join(PACKAGE_ROOT, 'templates/spec', name), 'utf-8');
+        writeFileSync(dest, template.replaceAll('{{id}}', card.id).replaceAll('{{title}}', card.title));
+        created.push(`${dir}/${name}`);
+    }
+    if (card.spec !== dir)
+        annotateCard(projectDir, card.id, { spec: dir }, 'spec', { note: dir, role });
+    return { dir, created };
+}
+function read(projectDir, dir, name) {
+    const file = join(projectDir, dir, name);
+    if (!existsSync(file))
+        throw new RefusalError(`${dir}/${name} is missing`);
+    return readFileSync(file, 'utf-8');
+}
+export function readTasks(projectDir, dir) {
+    const tasks = [];
+    const malformed = [];
+    for (const line of read(projectDir, dir, 'tasks.md').split('\n')) {
+        if (!/^- \[[ x]\]/.test(line))
+            continue;
+        const m = TASK.exec(line);
+        if (m)
+            tasks.push({ done: m[1] === 'x', id: m[2], parallel: !!m[3], accept: m[5], layer: m[6], text: m[7] });
+        else
+            malformed.push(line);
+    }
+    return { tasks, malformed };
+}
+export function readAcceptance(projectDir, dir) {
+    return read(projectDir, dir, 'spec.md').split('\n').map(l => ACCEPTANCE.exec(l)?.[1]).filter((id) => !!id);
+}
+export function checkSpec(projectDir, dir) {
+    const acceptance = readAcceptance(projectDir, dir);
+    const { tasks, malformed } = readTasks(projectDir, dir);
+    const errors = [];
+    if (acceptance.length === 0)
+        errors.push(`${dir}/spec.md has no acceptance lines (\`- US1 Given ...\`)`);
+    if (acceptance.length > MAX_ACCEPTANCE)
+        errors.push(`${acceptance.length} acceptance lines, the limit is ${MAX_ACCEPTANCE}: split the card`);
+    for (const line of malformed)
+        errors.push(`untagged task (needs a T-number and one of [${LAYERS.join('|')}]): ${line}`);
+    for (const us of acceptance) {
+        if (!tasks.some(t => t.accept === us))
+            errors.push(`acceptance line ${us} has no task`);
+    }
+    for (const task of tasks) {
+        if (task.accept && !acceptance.includes(task.accept))
+            errors.push(`task ${task.id} cites ${task.accept}, which spec.md does not have`);
+    }
+    return errors;
+}
+export function tickTask(projectDir, dir, taskId) {
+    const file = join(projectDir, dir, 'tasks.md');
+    // Builders on different layers tick tasks in the same file at the same time.
+    withLock(file, () => {
+        const lines = read(projectDir, dir, 'tasks.md').split('\n');
+        const index = lines.findIndex(l => TASK.exec(l)?.[2] === taskId);
+        if (index < 0)
+            throw new RefusalError(`task ${taskId} not found in ${dir}/tasks.md`);
+        lines[index] = lines[index].replace('- [ ]', '- [x]');
+        writeFileSync(file, lines.join('\n'));
+    });
+}
+//# sourceMappingURL=spec.js.map

package/dist/lib/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/lib/spec.ts"],"names":[],"mappings":"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"}

package/dist/lib/stats.d.ts

@@ -0,0 +1,13 @@
+import { type Card } from './cards.js';
+import type { Lane } from './lane.js';
+export interface Stats {
+    cards: number;
+    done: number;
+    human_turns_per_card: number | null;
+    unattended_span_hours: number | null;
+    cycle_time_hours: number | null;
+    rework: number | null;
+    stuck_rate: number | null;
+    first_pass_rate_by_gate: Record<string, number>;
+}
+export declare function computeStats(cards: Card[], lanes: Lane[]): Stats;

package/dist/lib/stats.js

@@ -0,0 +1,43 @@
+import { DONE, PROPOSED } from './cards.js';
+const HOUR = 3_600_000;
+const ms = (iso) => new Date(iso).getTime();
+const ratio = (n, d) => (d ? n / d : null);
+// Longest stretch of a card's life with no human event: creation, each human event, last event.
+function unattended(card) {
+    const marks = [card.createdAt, ...card.events.filter(e => e.human).map(e => e.at), card.events.at(-1)?.at ?? card.createdAt].map(ms);
+    return Math.max(...marks.slice(1).map((t, i) => t - marks[i]), 0);
+}
+export function computeStats(cards, lanes) {
+    // Dropping a proposal is a choice about what to work on, not a judgement of work, so it is
+    // left out of the gate and rework numbers. It still counts as a human turn.
+    const judged = (e) => e.stage !== PROPOSED;
+    const events = cards.flatMap(c => c.events);
+    const done = cards.filter(c => c.stage === DONE);
+    // First pass at a gate: the first human decision at that stage was an approval.
+    const gates = {};
+    for (const card of cards) {
+        const lane = lanes.find(l => l.id === card.lane);
+        const decided = new Set();
+        for (const e of card.events) {
+            if ((e.action !== 'approve' && e.action !== 'reject') || !e.stage || !judged(e) || decided.has(e.stage))
+                continue;
+            decided.add(e.stage);
+            const key = `${card.lane}/${lane?.stages.find(s => s.id === e.stage)?.gate?.name ?? e.stage}`;
+            gates[key] ??= { first: 0, total: 0 };
+            gates[key].total++;
+            if (e.action === 'approve')
+                gates[key].first++;
+        }
+    }
+    return {
+        cards: cards.length,
+        done: done.length,
+        human_turns_per_card: ratio(events.filter(e => e.human).length, cards.length),
+        unattended_span_hours: cards.length ? Math.max(...cards.map(unattended)) / HOUR : null,
+        cycle_time_hours: done.length ? done.reduce((sum, c) => sum + ms(c.updatedAt) - ms(c.createdAt), 0) / done.length / HOUR : null,
+        rework: ratio(events.filter(e => e.action === 'reject' && judged(e)).length, events.filter(e => e.action === 'approve').length),
+        stuck_rate: ratio(cards.filter(c => c.events.some(e => e.action === 'stuck')).length, cards.length),
+        first_pass_rate_by_gate: Object.fromEntries(Object.entries(gates).map(([k, g]) => [k, g.first / g.total])),
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/lib/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/lib/stats.ts"],"names":[],"mappings":"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"}

package/dist/lib/verify.d.ts

@@ -0,0 +1,25 @@
+export interface LayerResult {
+    layer: string;
+    pass: boolean;
+    output: string;
+}
+export interface VerifyResult {
+    exitCode: number;
+    sha: string;
+    missing: string[];
+    cases: {
+        id: string;
+        accept: string;
+        pass: boolean;
+        layers: LayerResult[];
+    }[];
+    vacuous: string[];
+    mutate?: string;
+    /** Why nothing was run. */
+    problem?: string;
+}
+export declare function verify(projectDir: string, ref: string, opts?: {
+    mutate?: boolean;
+    env?: string;
+    record?: boolean;
+}): Promise<VerifyResult>;

package/dist/lib/verify.js

@@ -0,0 +1,135 @@
+import { spawnSync } from 'child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { cardKey, findCardOrNone, readCards, safeName } from './cards.js';
+import { loadConfig } from './config.js';
+import { annotateCard, RefusalError } from './engine.js';
+import { cardNumber } from './lane.js';
+import { checkEnv } from './shell.js';
+import { readAcceptance, resolveSpecDir } from './spec.js';
+const tail = (text) => text.trimEnd().split('\n').slice(-20).join('\n').slice(-2000);
+function git(cwd, args) {
+    const run = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+    return run.status === 0 ? run.stdout.trim() : '';
+}
+function loadUseCases(projectDir, nnn) {
+    const dir = join(projectDir, 'usecases', nnn);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter(f => f.endsWith('.yaml')).sort().map(f => {
+        const uc = parseYaml(readFileSync(join(dir, f), 'utf-8'));
+        // The id names the evidence file.
+        safeName(uc?.id, `use case id in usecases/${nnn}/${f}`);
+        return uc;
+    });
+}
+function runCli(uc, cwd, env, base = checkEnv()) {
+    const { run, expect } = uc.layers.cli;
+    const proc = spawnSync(run, { cwd, shell: true, encoding: 'utf-8', timeout: 600_000, env: { ...base, ...(env ? { CODELOOP_ENV: env } : {}) } });
+    const pass = proc.status === (expect?.exit ?? 0) && (!expect?.stdout || (proc.stdout ?? '').includes(expect.stdout));
+    return { layer: 'cli', pass, output: tail(`${proc.stdout ?? ''}${proc.stderr ?? ''}\nexit ${proc.status}`) };
+}
+async function runApi(uc, baseUrl) {
+    const { request, expect } = uc.layers.api;
+    const url = `${(uc.layers.api.base_url ?? baseUrl).replace(/\/$/, '')}${request.path}`;
+    try {
+        const res = await fetch(url, {
+            method: request.method ?? 'GET',
+            ...(request.body !== undefined ? { body: JSON.stringify(request.body), headers: { 'content-type': 'application/json' } } : {}),
+        });
+        return { layer: 'api', pass: res.status === expect.status, output: tail(`${request.method ?? 'GET'} ${url} → ${res.status} (expected ${expect.status})\n${await res.text()}`) };
+    }
+    catch (e) {
+        return { layer: 'api', pass: false, output: `${request.method ?? 'GET'} ${url} failed: ${e.message}` };
+    }
+}
+function baseUrlFor(projectDir, env) {
+    const config = loadConfig(projectDir);
+    return (env && config.deploy?.[env]?.base_url) || process.env.CODELOOP_BASE_URL || 'http://localhost:4040';
+}
+function setupCommand(projectDir, tree) {
+    const configured = loadConfig(projectDir).verify?.setup;
+    if (configured !== undefined)
+        return configured || '';
+    return existsSync(join(tree, 'package.json')) ? 'npm ci && npm run build --if-present' : '';
+}
+/**
+ * Re-runs the cli use cases on the commit before the card's first `Feature: <id>` commit. A use
+ * case that still passes there never depended on the feature, so it proves nothing. The worktree
+ * is installed and built first: a use case that fails there only because nothing was built would
+ * look non-vacuous without being so.
+ */
+function mutate(projectDir, cardId, cases) {
+    const first = git(projectDir, ['log', '--reverse', '--format=%H', `--grep=^Feature: ${cardId}$`]).split('\n')[0];
+    if (!first)
+        return { vacuous: [], cannotRun: true, message: `cannot run: no commit carries the trailer "Feature: ${cardId}", so there is no commit before the feature to compare against` };
+    const base = git(projectDir, ['rev-parse', `${first}^`]);
+    if (!base)
+        return { vacuous: [], cannotRun: true, message: `cannot run: the first Feature: ${cardId} commit has no parent` };
+    const tree = join(mkdtempSync(join(tmpdir(), 'codeloop-mutate-')), 'tree');
+    if (spawnSync('git', ['worktree', 'add', '--detach', tree, base], { cwd: projectDir, encoding: 'utf-8' }).status !== 0) {
+        throw new RefusalError(`could not create a worktree at ${base.slice(0, 7)}`);
+    }
+    try {
+        const setup = setupCommand(projectDir, tree);
+        if (setup) {
+            const run = spawnSync(setup, { cwd: tree, shell: true, encoding: 'utf-8', timeout: 900_000 });
+            if (run.status !== 0) {
+                return { vacuous: [], cannotRun: true, message: `environment differs: \`${setup}\` failed at ${base.slice(0, 7)}, so the use cases were not judged there\n${tail(`${run.stdout ?? ''}${run.stderr ?? ''}`)}` };
+            }
+        }
+        // When the project ships the `codeloop` binary itself, use cases must drive the old build, not
+        // the one running this command.
+        const bin = existsSync(join(tree, 'package.json')) ? JSON.parse(readFileSync(join(tree, 'package.json'), 'utf-8')).bin?.codeloop : undefined;
+        const env = bin && existsSync(join(tree, bin)) ? checkEnv(join(tree, bin)) : checkEnv();
+        const vacuous = cases.filter(uc => uc.layers.cli && runCli(uc, tree, undefined, env).pass).map(uc => uc.id);
+        return { vacuous, message: `re-ran ${cases.filter(uc => uc.layers.cli).length} cli use cases at ${base.slice(0, 7)}, before ${cardId}${setup ? ` (after \`${setup}\`)` : ''}` };
+    }
+    finally {
+        spawnSync('git', ['worktree', 'remove', '--force', tree], { cwd: projectDir });
+        rmSync(join(tree, '..'), { recursive: true, force: true });
+    }
+}
+export async function verify(projectDir, ref, opts = {}) {
+    const card = findCardOrNone(readCards(projectDir).cards, ref);
+    const nnn = card ? cardKey(card) : cardNumber(ref);
+    const acceptance = readAcceptance(projectDir, resolveSpecDir(projectDir, ref));
+    const cases = loadUseCases(projectDir, nnn);
+    const sha = git(projectDir, ['rev-parse', 'HEAD']);
+    const result = { exitCode: 0, sha, missing: acceptance.filter(us => !cases.some(uc => uc.accept === us)), cases: [], vacuous: [] };
+    // Nothing to check is not a pass: no acceptance lines or no use cases must stop the stage.
+    if (acceptance.length === 0)
+        return { ...result, exitCode: 2, problem: `the spec for ${ref} has no acceptance lines (\`- US1 Given ...\`), so there is nothing to verify` };
+    if (result.missing.length)
+        return { ...result, exitCode: 2 };
+    const baseUrl = baseUrlFor(projectDir, opts.env);
+    const out = join(projectDir, 'evidence', nnn);
+    mkdirSync(out, { recursive: true });
+    for (const uc of cases) {
+        const layers = [];
+        if (uc.layers.cli)
+            layers.push(runCli(uc, projectDir, opts.env));
+        if (uc.layers.api)
+            layers.push(await runApi(uc, baseUrl));
+        // A use case with nothing runnable (ui only, or empty) must not count as a pass.
+        const pass = layers.length > 0 && layers.every(l => l.pass);
+        result.cases.push({ id: uc.id, accept: uc.accept, pass, layers });
+        writeFileSync(join(out, `${uc.id}.json`), JSON.stringify({ id: uc.id, accept: uc.accept, failure_mode: uc.failure_mode, sha, env: opts.env ?? 'local', pass, layers }, null, 2) + '\n');
+    }
+    const passed = result.cases.every(c => c.pass);
+    const rows = result.cases.map(c => `| ${c.id} | ${c.accept} | ${c.layers.map(l => `${l.layer} ${l.pass ? 'pass' : 'FAIL'}`).join(', ') || 'no runnable layer'} |`);
+    writeFileSync(join(out, 'verify.md'), [`# Verify ${ref}`, '', `result: ${passed ? 'pass' : 'fail'}`, `sha: ${sha || 'none'}`, `env: ${opts.env ?? 'local'}`, '', '| Use case | Accepts | Layers |', '|---|---|---|', ...rows, ''].join('\n'));
+    if (card && opts.record !== false) {
+        annotateCard(projectDir, card.id, { evidence: `evidence/${nnn}/verify.md` }, 'verify', { note: `result: ${passed ? 'pass' : 'fail'} at ${sha.slice(0, 7) || 'no commit'}` });
+    }
+    if (!passed)
+        return { ...result, exitCode: 1 };
+    if (opts.mutate) {
+        const m = mutate(projectDir, card?.id ?? ref, cases);
+        return { ...result, vacuous: m.vacuous, mutate: m.message, exitCode: m.cannotRun ? 5 : m.vacuous.length ? 4 : 0 };
+    }
+    return result;
+}
+//# sourceMappingURL=verify.js.map

package/dist/lib/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/lib/verify.ts"],"names":[],"mappings":"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"}

package/dist/lib/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compare two semver-style version strings.
+ * Returns: -1 if a < b, 0 if equal, 1 if a > b
+ */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * Parse version from a codeloop-version comment in file content.
+ * Also supports legacy flywheel-version for backward compatibility.
+ */
+export declare function parseVersion(content: string): string | null;

package/dist/lib/version.js

@@ -0,0 +1,27 @@
+/**
+ * Compare two semver-style version strings.
+ * Returns: -1 if a < b, 0 if equal, 1 if a > b
+ */
+export function compareVersions(a, b) {
+    const partsA = a.split('.').map(Number);
+    const partsB = b.split('.').map(Number);
+    const len = Math.max(partsA.length, partsB.length);
+    for (let i = 0; i < len; i++) {
+        const numA = partsA[i] ?? 0;
+        const numB = partsB[i] ?? 0;
+        if (numA < numB)
+            return -1;
+        if (numA > numB)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Parse version from a codeloop-version comment in file content.
+ * Also supports legacy flywheel-version for backward compatibility.
+ */
+export function parseVersion(content) {
+    const match = content.match(/<!--\s*(?:codeloop|flywheel)-version:\s*([\d.]+)\s*-->/);
+    return match ? match[1] : null;
+}
+//# sourceMappingURL=version.js.map

package/dist/lib/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/lib/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAEnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,IAAI,GAAG,IAAI;YAAE,OAAO,CAAC,CAAC,CAAC;QAC3B,IAAI,IAAI,GAAG,IAAI;YAAE,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC"}

package/dist/lib/wiki.d.ts

@@ -0,0 +1,51 @@
+export declare const WIKI_DIR = ".codeloop/wiki";
+declare const KINDS: {
+    readonly gotcha: "gotchas";
+    readonly decision: "decisions";
+    readonly concept: "concepts";
+};
+export type Kind = keyof typeof KINDS;
+export interface Page {
+    path: string;
+    kind: Kind;
+    title: string;
+    scope: string[];
+    freq: number;
+    severity: 'warning' | 'critical';
+    cards: string[];
+    updated: string;
+    promoted?: boolean;
+    body: string;
+}
+export declare function listPages(projectDir: string): Page[];
+/** Pages that changed here and in the cloud: the local file and the cloud version written beside it, waiting for a merge. */
+export declare function cloudCopies(projectDir: string): {
+    path: string;
+    cloud: string;
+}[];
+export declare function thresholds(projectDir: string): {
+    critical: number;
+    promote: number;
+};
+/** A title that already exists is the same lesson met again: its frequency goes up instead of a second page. */
+export declare function capture(projectDir: string, input: {
+    title: string;
+    scope: string[];
+    body: string;
+    kind?: Kind;
+    card?: string;
+}, now?: Date): Page;
+export declare function inject(projectDir: string, files: string[]): Page[];
+/** Applies the frequency thresholds: critical at `critical_frequency`, copied into rules.md once at `promote_frequency`. */
+export declare function learn(projectDir: string): {
+    critical: string[];
+    promoted: string[];
+};
+export declare function lintWiki(projectDir: string, now?: Date): {
+    broken: string[];
+    stale: string[];
+    duplicates: string[];
+};
+/** Critical pages whose scope matches the files and that were not acknowledged by title. */
+export declare function blockingGotchas(projectDir: string, files: string[], acked: string[]): Page[];
+export {};

package/dist/lib/wiki.js

@@ -0,0 +1,164 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+import { stringify } from 'yaml';
+import { CLOUD_COPY, writeCloudWikiPage } from './cloud.js';
+import { loadConfig } from './config.js';
+import { RefusalError } from './engine.js';
+import { globMatches } from './glob.js';
+import { clock } from './clock.js';
+import { withLock } from './lock.js';
+import { parseFrontmatter } from './skills.js';
+import { slugify } from './spec.js';
+export const WIKI_DIR = '.codeloop/wiki';
+const KINDS = { gotcha: 'gotchas', decision: 'decisions', concept: 'concepts' };
+const STALE_DAYS = 90;
+export function listPages(projectDir) {
+    const pages = [];
+    for (const [kind, folder] of Object.entries(KINDS)) {
+        const dir = join(projectDir, WIKI_DIR, folder);
+        if (!existsSync(dir))
+            continue;
+        for (const file of readdirSync(dir).filter(f => f.endsWith('.md') && !f.endsWith(CLOUD_COPY)).sort()) {
+            const { data, body } = parseFrontmatter(readFileSync(join(dir, file), 'utf-8'));
+            pages.push({
+                path: `${WIKI_DIR}/${folder}/${file}`,
+                kind,
+                title: String(data.title ?? file.replace(/\.md$/, '')),
+                scope: data.scope ?? [],
+                freq: Number(data.freq ?? 1),
+                severity: data.severity === 'critical' ? 'critical' : 'warning',
+                cards: data.cards ?? [],
+                updated: String(data.updated ?? ''),
+                ...(data.promoted ? { promoted: true } : {}),
+                body: body.trim(),
+            });
+        }
+    }
+    return pages;
+}
+/** Pages that changed here and in the cloud: the local file and the cloud version written beside it, waiting for a merge. */
+export function cloudCopies(projectDir) {
+    return [...Object.values(KINDS), 'competitors'].flatMap(folder => {
+        const dir = join(projectDir, WIKI_DIR, folder);
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir).filter(f => f.endsWith(CLOUD_COPY)).sort().map(f => ({ path: `${WIKI_DIR}/${folder}/${f.slice(0, -CLOUD_COPY.length)}.md`, cloud: `${WIKI_DIR}/${folder}/${f}` }));
+    });
+}
+function writePage(projectDir, page) {
+    const { path, kind: _kind, body, ...frontmatter } = page;
+    mkdirSync(dirname(join(projectDir, path)), { recursive: true });
+    writeFileSync(join(projectDir, path), `---\n${stringify(frontmatter)}---\n\n${body}\n`);
+}
+function writeIndex(projectDir) {
+    const pages = listPages(projectDir);
+    const lines = ['# Wiki', '', 'Generated by `codeloop wiki capture`. Run `codeloop wiki inject --files <paths>` to get the pages that apply to a change.', ''];
+    for (const [kind, folder] of Object.entries(KINDS)) {
+        lines.push(`## ${folder[0].toUpperCase()}${folder.slice(1)}`, '');
+        const mine = pages.filter(p => p.kind === kind);
+        if (mine.length === 0)
+            lines.push('None yet.');
+        for (const p of mine)
+            lines.push(`- [${p.title}](${relative(WIKI_DIR, p.path)}): freq ${p.freq}, ${p.severity}, scope ${p.scope.join(', ') || 'none'}`);
+        lines.push('');
+    }
+    mkdirSync(join(projectDir, WIKI_DIR), { recursive: true });
+    writeFileSync(join(projectDir, WIKI_DIR, 'INDEX.md'), lines.join('\n'));
+}
+export function thresholds(projectDir) {
+    const config = loadConfig(projectDir);
+    return { critical: config.codeloop?.critical_frequency ?? 3, promote: config.codeloop?.promote_frequency ?? 10 };
+}
+/** A title that already exists is the same lesson met again: its frequency goes up instead of a second page. */
+export function capture(projectDir, input, now = clock()) {
+    const kind = input.kind ?? 'gotcha';
+    if (!KINDS[kind])
+        throw new RefusalError(`unknown kind "${kind}" (gotcha, decision or concept)`);
+    if (!slugify(input.title))
+        throw new RefusalError(`wiki title "${input.title}" has no letters or digits to name its file with`);
+    // A second capture of the same title reads the page, raises its frequency and writes it back.
+    return withLock(join(projectDir, WIKI_DIR, 'INDEX.md'), () => captureLocked(projectDir, input, kind, now));
+}
+function captureLocked(projectDir, input, kind, now) {
+    const today = now.toISOString().slice(0, 10);
+    const existing = listPages(projectDir).find(p => p.title.toLowerCase() === input.title.toLowerCase());
+    const page = existing
+        ? {
+            ...existing,
+            freq: existing.freq + 1,
+            scope: [...new Set([...existing.scope, ...input.scope])],
+            cards: [...new Set([...existing.cards, ...(input.card ? [input.card] : [])])],
+            updated: today,
+        }
+        : {
+            path: `${WIKI_DIR}/${KINDS[kind]}/${slugify(input.title)}.md`,
+            kind,
+            title: input.title,
+            scope: input.scope,
+            freq: 1,
+            severity: 'warning',
+            cards: input.card ? [input.card] : [],
+            updated: today,
+            body: input.body.trim(),
+        };
+    if (page.freq >= thresholds(projectDir).critical)
+        page.severity = 'critical';
+    writePage(projectDir, page);
+    writeIndex(projectDir);
+    writeCloudWikiPage(projectDir, page.path);
+    return page;
+}
+export function inject(projectDir, files) {
+    const paths = files.map(f => relative(projectDir, resolve(projectDir, f)));
+    return listPages(projectDir).filter(p => p.scope.some(glob => paths.some(path => globMatches(glob, path))));
+}
+/** Applies the frequency thresholds: critical at `critical_frequency`, copied into rules.md once at `promote_frequency`. */
+export function learn(projectDir) {
+    const { critical, promote } = thresholds(projectDir);
+    const result = { critical: [], promoted: [] };
+    for (const page of listPages(projectDir)) {
+        let changed = false;
+        if (page.freq >= critical && page.severity !== 'critical') {
+            page.severity = 'critical';
+            result.critical.push(page.title);
+            changed = true;
+        }
+        if (page.freq >= promote && !page.promoted) {
+            const rules = join(projectDir, '.codeloop/rules.md');
+            const current = existsSync(rules) ? readFileSync(rules, 'utf-8') : '# Rules\n';
+            writeFileSync(rules, `${current.trimEnd()}\n\n## ${page.title}\n\nPromoted from ${page.path} at freq ${page.freq}. Scope: ${page.scope.join(', ') || 'all'}.\n\n${page.body}\n`);
+            page.promoted = true;
+            result.promoted.push(page.title);
+            changed = true;
+        }
+        if (changed)
+            writePage(projectDir, page);
+    }
+    if (result.critical.length || result.promoted.length)
+        writeIndex(projectDir);
+    return result;
+}
+export function lintWiki(projectDir, now = clock()) {
+    const pages = listPages(projectDir);
+    const broken = [];
+    const files = [...pages.map(p => ({ path: p.path, text: p.body })), { path: `${WIKI_DIR}/INDEX.md`, text: existsSync(join(projectDir, WIKI_DIR, 'INDEX.md')) ? readFileSync(join(projectDir, WIKI_DIR, 'INDEX.md'), 'utf-8') : '' }];
+    for (const file of files) {
+        for (const m of file.text.matchAll(/\[[^\]]*\]\(([^)#\s]+)(?:#[^)]*)?\)/g)) {
+            if (/^[a-z]+:/i.test(m[1]))
+                continue;
+            if (!existsSync(resolve(projectDir, dirname(file.path), m[1])))
+                broken.push(`${file.path}: link to ${m[1]} does not resolve`);
+        }
+    }
+    const cutoff = new Date(now.getTime() - STALE_DAYS * 86_400_000).toISOString().slice(0, 10);
+    const stale = pages.filter(p => p.updated && p.updated < cutoff).map(p => `${p.path}: last updated ${p.updated}, over ${STALE_DAYS} days ago`);
+    const titles = pages.map(p => p.title.toLowerCase());
+    const duplicates = pages.filter((p, i) => titles.indexOf(p.title.toLowerCase()) !== i).map(p => `${p.path}: duplicate title "${p.title}"`);
+    return { broken, stale, duplicates };
+}
+/** Critical pages whose scope matches the files and that were not acknowledged by title. */
+export function blockingGotchas(projectDir, files, acked) {
+    const ack = new Set(acked.map(t => t.toLowerCase()));
+    return inject(projectDir, files).filter(p => p.severity === 'critical' && !ack.has(p.title.toLowerCase()));
+}
+//# sourceMappingURL=wiki.js.map