freeharness 0.4.1

package/node_modules/@freeharness/sdd/dist/src/shim/follow-up.js

@@ -0,0 +1,279 @@
+// `openspec follow-up add|list|claim` — a per-change record of items to pick up
+// later, kept as a plain `follow-ups.md` next to the change's other artifacts and
+// moved with it at archive.
+//
+// The record is data, never instructions: every reader here (readFollowUps,
+// list, the archive notice) treats an item's text as an opaque string. No
+// content is executed, evaluated or passed to a shell.
+//
+// The template lives at canonical/openspec/templates/follow-ups.md for a human
+// reading the repo; a change's follow-ups.md is not a schema artifact (schema
+// templates resolve through a project's installed schema directory, see
+// vendor/openspec/engine/instruction-loader.ts), so this shim has no template
+// copy path for it and embeds the same two header lines as a constant below.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { changesDirFor, printJson, resolveChangeId, taskLabel } from './shared.js';
+const TEMPLATE = '<!-- Follow-ups for this change: one line per item, in the order they were added. -->\n' +
+    '<!-- Unclaimed: - [ ] <text> (from <task>)   Claimed: - [x] <text> (from <task>) -> claimed by <change-id> -->\n';
+// Leading whitespace and a `*` bullet are accepted so a hand-written item counts here exactly
+// as it counts in the SessionStart pointer, which reads the same files.
+const ITEM_LINE = /^\s*[-*]\s*\[([ xX])\]\s*(.*)$/;
+const CLAIMED_SUFFIX = /^(.*?)\s*->\s*claimed by\s+(\S+)\s*$/;
+const FROM_SUFFIX = /^(.*?)\s*\(from\s+([^)]+)\)\s*$/;
+const CONTROL_CHAR = /[\x00-\x1f\x7f]/;
+/**
+ * Rejects a `text` that would split the appended line into two item lines (a
+ * line break) or carry an unprintable byte, and an empty `text`. The written
+ * line can never be parsed back as two items.
+ */
+function validateFollowUpText(text) {
+    if (text.length === 0)
+        throw new Error('follow-up text cannot be empty.');
+    if (CONTROL_CHAR.test(text)) {
+        throw new Error('follow-up text cannot contain a line break or control character.');
+    }
+}
+/**
+ * Rejects a `--from` value that is not exactly a task label as `taskLabel`
+ * (shared.ts) recognizes it: `taskLabel` extracts the leading `N.N[a]`-style
+ * id from a task description, so a `--from` value round-trips through it only
+ * when the whole value is such a label, with nothing before or after. Reusing
+ * that recognizer (rather than a private copy of its pattern) means the two
+ * never drift, and a line break or other control character never round-trips.
+ */
+function validateFrom(from) {
+    if (taskLabel({ description: from, line: 0 }) !== from) {
+        throw new Error(`--from '${from}' must be a task label (e.g. 6.3 or 6.3a).`);
+    }
+}
+function followUpsPath(changeDir) {
+    return path.join(changeDir, 'follow-ups.md');
+}
+/** The change directory for an id already resolved in-flight or archived. */
+function changeDirForResolution(projectRoot, id, resolution) {
+    const changesDir = changesDirFor(projectRoot);
+    return resolution === 'archived' ? path.join(changesDir, 'archive', id) : path.join(changesDir, id);
+}
+/** Archived change ids (directories under openspec/changes/archive/). */
+function listArchivedChangeIds(projectRoot) {
+    const dir = path.join(changesDirFor(projectRoot), 'archive');
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+            .map((e) => e.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** In-flight change ids (directories under openspec/changes/, excluding archive). */
+function listInFlightChangeIds(projectRoot) {
+    const dir = changesDirFor(projectRoot);
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name !== 'archive' && !e.name.startsWith('.'))
+            .map((e) => e.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+function parseBody(body) {
+    const match = body.match(FROM_SUFFIX);
+    if (!match)
+        return { text: body, from: null };
+    return { text: match[1], from: match[2] };
+}
+/**
+ * Reads every item line of a change's follow-ups.md, ignoring any other line
+ * (heading, blank, comment). Index is the 1-based position among item lines in
+ * file order. Absent file -> empty list.
+ */
+export function readFollowUps(dir) {
+    const file = followUpsPath(dir);
+    if (!fs.existsSync(file))
+        return [];
+    const lines = fs.readFileSync(file, 'utf-8').split('\n');
+    const items = [];
+    let index = 0;
+    for (const line of lines) {
+        const match = line.match(ITEM_LINE);
+        if (!match)
+            continue;
+        index += 1;
+        const checked = match[1].toLowerCase() === 'x';
+        let body = match[2];
+        let claimedBy = null;
+        if (checked) {
+            const claim = body.match(CLAIMED_SUFFIX);
+            if (claim) {
+                body = claim[1];
+                claimedBy = claim[2];
+            }
+        }
+        const { text, from } = parseBody(body);
+        items.push({ index, text, from, done: checked, claimedBy });
+    }
+    return items;
+}
+/**
+ * Appends an unclaimed item to a change's follow-ups.md, creating the file from
+ * the template when absent. Throws when the change resolves neither in flight
+ * nor archived.
+ */
+export function addFollowUp(projectRoot, changeId, text, from) {
+    validateFollowUpText(text);
+    if (from !== undefined)
+        validateFrom(from);
+    const resolution = resolveChangeId(projectRoot, changeId);
+    if (!resolution) {
+        throw new Error(`Change '${changeId}' not found (neither in flight nor archived).`);
+    }
+    const dir = changeDirForResolution(projectRoot, changeId, resolution);
+    const file = followUpsPath(dir);
+    if (!fs.existsSync(file)) {
+        fs.writeFileSync(file, TEMPLATE, 'utf-8');
+    }
+    const index = readFollowUps(dir).length + 1;
+    const suffix = from ? ` (from ${from})` : '';
+    const line = `- [ ] ${text}${suffix}`;
+    const current = fs.readFileSync(file, 'utf-8');
+    const separator = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+    fs.writeFileSync(file, `${current}${separator}${line}\n`, 'utf-8');
+    return { change: changeId, index };
+}
+/** Every open (unchecked) item of every in-flight and archived change. */
+export function listFollowUps(projectRoot) {
+    const changesDir = changesDirFor(projectRoot);
+    const results = [];
+    const collect = (ids, base) => {
+        for (const id of ids) {
+            for (const item of readFollowUps(path.join(base, id))) {
+                // A checked item is settled even when it names no claimant; `claim` refuses it for the
+                // same reason, so the two commands never disagree about what is still open.
+                if (item.done)
+                    continue;
+                results.push({ change: id, index: item.index, text: item.text, from: item.from, state: 'open' });
+            }
+        }
+    };
+    collect(listInFlightChangeIds(projectRoot), changesDir);
+    collect(listArchivedChangeIds(projectRoot), path.join(changesDir, 'archive'));
+    return results;
+}
+/**
+ * Rewrites an item as claimed. Refuses an index without an item, an item
+ * already claimed, or a `--by` id that resolves neither in flight nor
+ * archived; every other line of the file is left byte-identical.
+ */
+export function claimFollowUp(projectRoot, changeId, index, byId) {
+    const resolution = resolveChangeId(projectRoot, changeId);
+    if (!resolution) {
+        throw new Error(`Change '${changeId}' not found (neither in flight nor archived).`);
+    }
+    const dir = changeDirForResolution(projectRoot, changeId, resolution);
+    const file = followUpsPath(dir);
+    if (!fs.existsSync(file)) {
+        throw new Error(`No follow-ups recorded for '${changeId}'; index ${index} does not exist.`);
+    }
+    const original = fs.readFileSync(file, 'utf-8');
+    const lines = original.split('\n');
+    let seen = 0;
+    let targetLine = -1;
+    let targetMatch = null;
+    for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(ITEM_LINE);
+        if (!match)
+            continue;
+        seen += 1;
+        if (seen === index) {
+            targetLine = i;
+            targetMatch = match;
+            break;
+        }
+    }
+    if (targetLine === -1 || !targetMatch) {
+        throw new Error(`Follow-up ${changeId}#${index} does not exist.`);
+    }
+    const checked = targetMatch[1].toLowerCase() === 'x';
+    let body = targetMatch[2];
+    if (checked) {
+        const claim = body.match(CLAIMED_SUFFIX);
+        const claimedBy = claim ? claim[2] : 'unknown';
+        throw new Error(`Follow-up ${changeId}#${index} is already claimed by ${claimedBy}.`);
+    }
+    if (!resolveChangeId(projectRoot, byId)) {
+        throw new Error(`--by change '${byId}' not found (neither in flight nor archived).`);
+    }
+    lines[targetLine] = `- [x] ${body} -> claimed by ${byId}`;
+    fs.writeFileSync(file, lines.join('\n'), 'utf-8');
+    return { change: changeId, index, by: byId };
+}
+/** CLI wrapper for `openspec follow-up add <change-id> "<text>" [--from <task>]`. */
+export function followUpAddHandler(projectRoot, changeId, text, options) {
+    try {
+        if (!changeId)
+            throw new Error('Missing required argument <change-id>.');
+        if (!text)
+            throw new Error('Missing required argument "<text>".');
+        const result = addFollowUp(projectRoot, changeId, text, options.from);
+        if (options.json) {
+            printJson({ added: true, ...result });
+            return 0;
+        }
+        console.log(`added ${result.change}#${result.index}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+/** CLI wrapper for `openspec follow-up list [--json]`. */
+export function followUpListHandler(projectRoot, options) {
+    const items = listFollowUps(projectRoot);
+    if (options.json) {
+        printJson(items);
+        return 0;
+    }
+    if (items.length === 0) {
+        console.log('no open follow-ups');
+        return 0;
+    }
+    for (const item of items) {
+        const suffix = item.from ? ` (from ${item.from})` : '';
+        console.log(`${item.change}#${item.index} ${item.text}${suffix}`);
+    }
+    return 0;
+}
+/** CLI wrapper for `openspec follow-up claim <change-id> <index> --by <change-id>`. */
+export function followUpClaimHandler(projectRoot, changeId, indexArg, options) {
+    try {
+        if (!changeId)
+            throw new Error('Missing required argument <change-id>.');
+        const index = Number(indexArg);
+        if (!indexArg || !Number.isInteger(index) || index < 1) {
+            throw new Error('Missing or invalid <index>.');
+        }
+        if (!options.by)
+            throw new Error('Missing required option --by <change-id>.');
+        const result = claimFollowUp(projectRoot, changeId, index, options.by);
+        if (options.json) {
+            printJson({ claimed: true, ...result });
+            return 0;
+        }
+        console.log(`claimed ${result.change}#${result.index} by ${result.by}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

package/node_modules/@freeharness/sdd/dist/src/shim/instructions.d.ts

@@ -0,0 +1,67 @@
+import { type ArtifactInstructions } from '../../vendor/openspec/engine/index.js';
+export interface InstructionsOptions {
+    change?: string;
+    schema?: string;
+    json?: boolean;
+}
+declare const SPECIAL_TARGETS: Set<string>;
+export declare function instructionsHandler(projectRoot: string, artifactId: string | undefined, options: InstructionsOptions): number;
+export declare function printInstructionsText(instructions: ArtifactInstructions, isBlocked: boolean): void;
+interface ApplyInstructions {
+    changeName: string;
+    changeDir: string;
+    schemaName: string;
+    contextFiles: Record<string, string[]>;
+    progress: {
+        total: number;
+        complete: number;
+        remaining: number;
+    };
+    tasks: {
+        id: string;
+        description: string;
+        done: boolean;
+    }[];
+    state: 'blocked' | 'all_done' | 'ready';
+    missingArtifacts?: string[];
+    /**
+     * Every artifact still to build before apply's own gate is satisfied, in
+     * the schema's build order - the transitive closure of `apply.requires`.
+     * Computed independently of `state`: a `ready` change (apply.requires
+     * itself satisfied) can still be missing artifacts the required one
+     * transitively depends on, which `missingArtifacts` never names since it
+     * stops at the first hop apply blocks on. Present whenever non-empty.
+     */
+    missingPrerequisites?: string[];
+    /** Non-blocking problems with the change, reported alongside the instruction. */
+    warnings?: string[];
+    instruction: string;
+}
+/**
+ * Whether the "Not created yet, in build order" line would repeat information
+ * the "Missing artifacts" line already gave in full.
+ *
+ * Compared as sets, not lengths: two equal-length lists naming different ids
+ * (e.g. a schema whose transitive chain swaps one artifact for another at the
+ * same depth) are NOT the same information, and a length-only compare (the
+ * prior `missingPrerequisites.length <= missingArtifacts.length`) would
+ * silently drop the second list even though it names something new.
+ * Exported for direct unit coverage of the comparison rule.
+ */
+export declare function isChainAlreadyNamed(state: ApplyInstructions['state'], missingArtifacts: string[] | undefined, missingPrerequisites: string[] | undefined): boolean;
+/** Archive-inputs brief: context and advisory guidance, both optional. */
+export interface ArchiveInstructions {
+    changeName: string;
+    context?: string;
+    operationGuidance?: string[];
+}
+/**
+ * Builds the archive inputs: project context (`openspec/config.yaml` `context`), the
+ * project's `operations.archive.guidance`, then the schema's `archive.guidance`.
+ * @param projectRoot Project root.
+ * @param changeName Change id.
+ * @param explicitSchema `--schema` override.
+ * @returns The brief the archive skill prints.
+ */
+export declare function buildArchiveInstructions(projectRoot: string, changeName: string, explicitSchema?: string): ArchiveInstructions;
+export { SPECIAL_TARGETS };