@cluesmith/codev 3.3.4 → 3.3.6

package/dist/agent-farm/servers/decisions/file.js

@@ -0,0 +1,146 @@
+// The decisions file on disk (Spec 1819): where it is, whether it may be touched,
+// and how a ruling replaces it.
+//
+// The path comes from `dashboard.decisionsFile` (workspace-relative), never from a
+// request. Every read and write canonicalizes it — symlinks followed — and refuses a
+// target outside the canonical workspace root. Writes go through one serializer per
+// canonical path and replace the file by renaming a fully written, fsynced temporary
+// file over it, so a crash leaves the old file or the new one, never a truncated one.
+import crypto from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../../../lib/config.js';
+import { KeyedSerializer } from '../write-queue.js';
+export const DEFAULT_DECISIONS_FILE = 'codev/state/pending-decisions.md';
+/** How long the state flag may reuse a workspace's configured path. */
+export const CONFIGURED_PATH_MEMO_MS = 5_000;
+const configuredPathMemo = new Map();
+/** At most one write per canonical decisions file runs at a time. */
+export const decisionsWriteQueue = new KeyedSerializer();
+function readConfiguredPath(workspacePath) {
+    try {
+        const value = loadConfig(workspacePath).dashboard?.decisionsFile;
+        if (value === undefined)
+            return { ok: true, path: DEFAULT_DECISIONS_FILE };
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new Error(`dashboard.decisionsFile must be a non-empty string, got ${JSON.stringify(value)}`);
+        }
+        if (path.isAbsolute(value)) {
+            throw new Error(`dashboard.decisionsFile must be relative to the workspace root, got ${JSON.stringify(value)}`);
+        }
+        return { ok: true, path: value };
+    }
+    catch (err) {
+        return { ok: false, error: err };
+    }
+}
+/**
+ * The workspace's configured decisions path (relative to its root). `fresh` reads the
+ * config now — the routes always do; otherwise a result up to
+ * {@link CONFIGURED_PATH_MEMO_MS} old is reused, because the state flag is polled every
+ * second by every open dashboard. The memo holds only the configured path (or the
+ * config error), never the decisions file's content. Throws the config error.
+ */
+export function configuredDecisionsPath(workspacePath, { fresh }) {
+    const memo = configuredPathMemo.get(workspacePath);
+    let outcome;
+    if (!fresh && memo && Date.now() - memo.at < CONFIGURED_PATH_MEMO_MS) {
+        outcome = memo.outcome;
+    }
+    else {
+        outcome = readConfiguredPath(workspacePath);
+        configuredPathMemo.set(workspacePath, { at: Date.now(), outcome });
+    }
+    if (!outcome.ok)
+        throw outcome.error;
+    return outcome.path;
+}
+/** Canonicalize a path that may not exist: realpath its nearest existing ancestor. */
+async function canonicalize(target) {
+    const missing = [];
+    let existing = target;
+    for (;;) {
+        try {
+            return path.join(await fsp.realpath(existing), ...missing);
+        }
+        catch (err) {
+            const parent = path.dirname(existing);
+            if (err.code !== 'ENOENT' || parent === existing)
+                throw err;
+            missing.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+}
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/**
+ * Resolve the configured path against the workspace root. Both are canonicalized
+ * (symlinks followed; a missing target through its nearest existing ancestor), and a
+ * canonical target outside the canonical root is reported as `inside: false`.
+ */
+export async function resolveDecisionsPath(workspacePath, configuredPath) {
+    const root = await fsp.realpath(workspacePath);
+    const target = path.resolve(root, configuredPath);
+    const displayPath = path.relative(root, target).split(path.sep).join('/');
+    const canonicalPath = await canonicalize(target);
+    if (!isInside(root, canonicalPath))
+        return { inside: false, displayPath, canonicalPath };
+    const stat = await fsp.stat(canonicalPath).catch((err) => {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    });
+    return { inside: true, canonicalPath, displayPath, exists: stat?.isFile() ?? false };
+}
+/** The last presence-check error logged per workspace, so a poll logs it once, not every second. */
+const loggedPresenceError = new Map();
+/**
+ * Whether the Decisions tab should show: the configured file exists inside the
+ * workspace. Uses the memoized configured path. A config error is logged and reads as
+ * false — it must never fail the state response; the decisions routes report it in full.
+ */
+export async function decisionsFilePresent(workspacePath, log) {
+    try {
+        const resolved = await resolveDecisionsPath(workspacePath, configuredDecisionsPath(workspacePath, { fresh: false }));
+        loggedPresenceError.delete(workspacePath);
+        return resolved.inside && resolved.exists;
+    }
+    catch (err) {
+        const message = err.message;
+        if (loggedPresenceError.get(workspacePath) !== message) {
+            loggedPresenceError.set(workspacePath, message);
+            log('WARN', `Decisions tab hidden for ${workspacePath}: ${message}`);
+        }
+        return false;
+    }
+}
+/**
+ * Replace `target` with `text`: write a temporary file in the same directory with the
+ * target's permissions, fsync it, and rename it over the target. The temporary file is
+ * removed if any step fails, leaving the target untouched. `target` must be the
+ * canonical path, so a symlink pointing at it is left in place.
+ */
+export async function writeFileAtomic(target, text) {
+    const mode = (await fsp.stat(target)).mode & 0o7777;
+    const temp = path.join(path.dirname(target), `.${path.basename(target)}.${crypto.randomUUID()}.tmp`);
+    try {
+        const handle = await fsp.open(temp, 'wx', mode);
+        try {
+            await handle.writeFile(text, 'utf8');
+            await handle.chmod(mode);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fsp.rename(temp, target);
+    }
+    catch (err) {
+        await fsp.rm(temp, { force: true });
+        throw err;
+    }
+}
+//# sourceMappingURL=file.js.map

package/dist/agent-farm/servers/decisions/file.js.map

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

package/dist/agent-farm/servers/decisions/grammar.d.ts

@@ -0,0 +1,36 @@
+export type LineEnding = '' | '\n' | '\r\n';
+export interface SourceLine {
+    /** 0-based line number. */
+    index: number;
+    /** Offset of the line's first character. */
+    start: number;
+    /** Offset just past the line's last content character (before the line ending). */
+    end: number;
+    /** The line's terminator ('' only for a final line without a newline). */
+    eol: LineEnding;
+    /** Line content without its terminator. */
+    text: string;
+    /** True for content inside a fence and for the fence delimiter lines themselves. */
+    fenced: boolean;
+    /** True for a fence delimiter line (opening or closing). */
+    fenceDelimiter: boolean;
+    /** ATX heading level (1–6) for an unfenced heading line, else 0. */
+    headingLevel: number;
+    /** Heading text (closing `#` sequence and surrounding whitespace removed). */
+    headingText: string;
+    /** True for an unfenced `**Your word:**` line. */
+    yourWord: boolean;
+}
+/** The `**Your word:**` label, as written in the file. */
+export declare const YOUR_WORD_LABEL = "**Your word:**";
+/** Whether `text`, taken as a standalone line, is a fence delimiter. */
+export declare function isFenceLine(text: string): boolean;
+/** Whether `text`, taken as an unfenced line, is an ATX heading. */
+export declare function isHeadingLine(text: string): boolean;
+/** Whether `text`, taken as an unfenced line, is a `**Your word:**` line. */
+export declare function isYourWordLine(text: string): boolean;
+/** Split `text` into classified lines with their original offsets and terminators. */
+export declare function classifyLines(text: string): SourceLine[];
+/** The line ending for inserted text: the file's first terminator (LF when it has none). */
+export declare function detectLineEnding(lines: SourceLine[]): '\n' | '\r\n';
+//# sourceMappingURL=grammar.d.ts.map

package/dist/agent-farm/servers/decisions/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/decisions/grammar.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,UAAU,GAAG,EAAE,GAAG,IAAI,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,UAAU,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,MAAM,EAAE,OAAO,CAAC;IAChB,4DAA4D;IAC5D,cAAc,EAAE,OAAO,CAAC;IACxB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAMD,0DAA0D;AAC1D,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAQhD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAiExD;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,GAAG,MAAM,CAGnE"}

package/dist/agent-farm/servers/decisions/grammar.js

@@ -0,0 +1,109 @@
+// Structural grammar for the decisions file (Spec 1819).
+//
+// One line classifier shared by the parser and the splice, so that what the tab
+// shows and what a write validates can never disagree about structure. It is a
+// subset of CommonMark:
+//   - fence lines: up to three leading spaces, then 3+ backticks or tildes. A fence
+//     opened by a run of N characters closes at the next line of the same character
+//     with at least N characters and nothing but whitespace after it. An unclosed
+//     fence runs to end of file.
+//   - heading lines: unfenced, up to three leading spaces, 1–6 `#`, then a space or
+//     end of line (ATX only; setext underlines are not structural).
+//   - Your-word lines: unfenced, up to three leading spaces, then `**Your word:**`.
+//
+// Offsets are string (UTF-16) offsets into the original text, so a splice can
+// insert at an exact position and preserve every other character.
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const HEADING_RE = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?[ \t]*$/;
+const YOUR_WORD_RE = /^ {0,3}\*\*Your word:\*\*/;
+/** The `**Your word:**` label, as written in the file. */
+export const YOUR_WORD_LABEL = '**Your word:**';
+/** Strip an ATX heading's optional closing sequence (` ##`), per CommonMark. */
+function stripClosingHashes(text) {
+    if (/^#+$/.test(text))
+        return '';
+    return text.replace(/[ \t]+#+$/, '').trim();
+}
+/** Whether `text`, taken as a standalone line, is a fence delimiter. */
+export function isFenceLine(text) {
+    return FENCE_RE.test(text);
+}
+/** Whether `text`, taken as an unfenced line, is an ATX heading. */
+export function isHeadingLine(text) {
+    return HEADING_RE.test(text);
+}
+/** Whether `text`, taken as an unfenced line, is a `**Your word:**` line. */
+export function isYourWordLine(text) {
+    return YOUR_WORD_RE.test(text);
+}
+/** Split `text` into classified lines with their original offsets and terminators. */
+export function classifyLines(text) {
+    const lines = [];
+    let openFence = null;
+    let pos = 0;
+    let index = 0;
+    while (pos < text.length) {
+        const nl = text.indexOf('\n', pos);
+        let end;
+        let eol;
+        let next;
+        if (nl === -1) {
+            end = text.length;
+            eol = '';
+            next = text.length;
+        }
+        else if (nl > pos && text[nl - 1] === '\r') {
+            end = nl - 1;
+            eol = '\r\n';
+            next = nl + 1;
+        }
+        else {
+            end = nl;
+            eol = '\n';
+            next = nl + 1;
+        }
+        const lineText = text.slice(pos, end);
+        let fenced = false;
+        let fenceDelimiter = false;
+        let headingLevel = 0;
+        let headingText = '';
+        let yourWord = false;
+        const fenceMatch = FENCE_RE.exec(lineText);
+        if (openFence) {
+            fenced = true;
+            if (fenceMatch &&
+                fenceMatch[1][0] === openFence.char &&
+                fenceMatch[1].length >= openFence.length &&
+                fenceMatch[2].trim() === '') {
+                fenceDelimiter = true;
+                openFence = null;
+            }
+        }
+        else if (fenceMatch && !(fenceMatch[1][0] === '`' && fenceMatch[2].includes('`'))) {
+            // A backtick fence's info string may not contain a backtick (CommonMark).
+            fenced = true;
+            fenceDelimiter = true;
+            openFence = { char: fenceMatch[1][0], length: fenceMatch[1].length };
+        }
+        else {
+            const headingMatch = HEADING_RE.exec(lineText);
+            if (headingMatch) {
+                headingLevel = headingMatch[1].length;
+                headingText = stripClosingHashes(headingMatch[2] ?? '');
+            }
+            else if (YOUR_WORD_RE.test(lineText)) {
+                yourWord = true;
+            }
+        }
+        lines.push({ index, start: pos, end, eol, text: lineText, fenced, fenceDelimiter, headingLevel, headingText, yourWord });
+        pos = next;
+        index++;
+    }
+    return lines;
+}
+/** The line ending for inserted text: the file's first terminator (LF when it has none). */
+export function detectLineEnding(lines) {
+    const first = lines.find(l => l.eol !== '');
+    return first?.eol === '\r\n' ? '\r\n' : '\n';
+}
+//# sourceMappingURL=grammar.js.map

package/dist/agent-farm/servers/decisions/grammar.js.map

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

package/dist/agent-farm/servers/decisions/notice.d.ts

@@ -0,0 +1,11 @@
+import type { RulingRequest } from './splice.js';
+/** Tell the hub architect `message`. May throw; the route logs the failure. */
+export type RulingNotifier = (message: string) => Promise<void>;
+/**
+ * The notice for a ruling the splice accepted: `RULED <id>: <word>`, or
+ * `QUESTION <id>:` when no word was chosen, with the trimmed comment on the lines after it.
+ * The comment is trimmed and split exactly as `spliceRuling` does, so the notice carries
+ * the lines that were written to the file.
+ */
+export declare function rulingNotice(ruling: RulingRequest): string;
+//# sourceMappingURL=notice.d.ts.map

package/dist/agent-farm/servers/decisions/notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/decisions/notice.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAI1D"}

package/dist/agent-farm/servers/decisions/notice.js

@@ -0,0 +1,18 @@
+// The hub architect's notice of a Decisions-tab ruling (#1828).
+//
+// Once a ruling is written, Tower tells the workspace's hub architect through the
+// mailbox, so the hub need not watch the file for it. The file stays the source of
+// truth: the notice is best-effort, and a ruling typed into the file by hand still
+// reaches the hub only when it scans the file.
+/**
+ * The notice for a ruling the splice accepted: `RULED <id>: <word>`, or
+ * `QUESTION <id>:` when no word was chosen, with the trimmed comment on the lines after it.
+ * The comment is trimmed and split exactly as `spliceRuling` does, so the notice carries
+ * the lines that were written to the file.
+ */
+export function rulingNotice(ruling) {
+    const head = ruling.word ? `RULED ${ruling.id}: ${ruling.word}` : `QUESTION ${ruling.id}:`;
+    const comment = (ruling.comment ?? '').trim().split(/\r\n|\r|\n/).join('\n');
+    return comment ? `${head}\n${comment}` : head;
+}
+//# sourceMappingURL=notice.js.map

package/dist/agent-farm/servers/decisions/notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice.js","sourceRoot":"","sources":["../../../../src/agent-farm/servers/decisions/notice.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,kFAAkF;AAClF,mFAAmF;AACnF,mFAAmF;AACnF,+CAA+C;AAO/C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,YAAY,MAAM,CAAC,EAAE,GAAG,CAAC;IAC3F,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC"}

package/dist/agent-farm/servers/decisions/parse.d.ts

@@ -0,0 +1,36 @@
+import type { DecisionItem, DecisionOption, DecisionsDocument, DecisionsFileProblem } from '@cluesmith/codev-types';
+import { type SourceLine } from './grammar.js';
+export interface ParsedItem extends DecisionItem {
+    /** Line index of the item's `###` heading. */
+    headingLine: number;
+    /** Line index just past the item's last line. */
+    endLine: number;
+    /** Offset of the heading line's first character. */
+    start: number;
+    /** Offset just past the item's last character (its final line ending included). */
+    end: number;
+    /** Line indices of the item's `**Your word:**` lines. */
+    yourWordLines: number[];
+}
+export interface ParsedDecisions {
+    lines: SourceLine[];
+    /** Line ending for inserted text: the file's own. */
+    eol: '\n' | '\r\n';
+    items: ParsedItem[];
+    ruledMarkdown: string;
+    problems: DecisionsFileProblem[];
+    version: string;
+}
+/**
+ * Options from a `**Your word:**` line. An option starts at a backticked span at the
+ * start of the text after the label, or at a backticked span immediately preceded by
+ * ` / `. Its description is the text after its `=`, if any, up to the next ` / ` that
+ * is followed by a backtick, or end of line. Any other ` / ` is part of the
+ * description. Text that is not an option, or not after an `=`, is not read.
+ */
+export declare function parseOptions(yourWordLineText: string): DecisionOption[];
+/** Parse the decisions file's text into its read model. */
+export declare function parseDecisions(text: string): ParsedDecisions;
+/** Project the parse onto the wire document served to the dashboard. */
+export declare function toDecisionsDocument(parsed: ParsedDecisions, path: string): DecisionsDocument;
+//# sourceMappingURL=parse.d.ts.map

package/dist/agent-farm/servers/decisions/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/decisions/parse.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACV,YAAY,EAEZ,cAAc,EAGd,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAoD,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGjG,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,qDAAqD;IACrD,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IACnB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AA4DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,EAAE,CAuBvE;AAmGD,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAiD5D;AA+DD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAmB5F"}