spec-ctx 0.4.1 → 0.5.0

package/dist/loop/fails.js

@@ -1,4 +1,4 @@
-// REQ-LOOP-002 fail files under .ctx/evidence/<change>/<task>.fail-<n>.json and the attempt window (024/D4, 024/D5).
+// REQ-LOOP-002 REQ-LOOP-017 REQ-LOOP-018 fail files under .ctx/evidence/<change>/<task>.fail-<n>.json and the attempt window (024/D4, 024/D5).
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { readQuestions } from "../handoff/questions.js";
@@ -8,6 +8,7 @@ import { runCommand } from "../runcmd.js";
 import { dumps } from "../util/json.js";
 import { cmpStr } from "../util/pystr.js";
 import { isoNow } from "../util/time.js";
+const CURRENT = ".ctx/current.json";
 /** Every fail file of a task, parsed, in `at` order. A damaged file is skipped. */
 export function readFails(root, task) {
     const rel = evidenceRel({ id: task });
@@ -31,19 +32,22 @@ export function readFails(root, task) {
     return out.sort((a, b) => cmpStr(a.file.at, b.file.at) || cmpStr(a.rel, b.rel));
 }
 /**
- * The start of the attempt window of a task: `current.json.started_at` when the file names the task, else the
- * start of time. A resolved question for the task moves the start to its `resolved_at`, so a resolve resets the count.
+ * REQ-LOOP-018 the start of the attempt window of a task: `current.json.started_at` when the file names the task, else
+ * null, and no fail file counts (056/D4). A resolved question for the task moves the start to its `resolved_at`, so a
+ * resolve resets the count. `fallback` gives the start of time instead of null, for a current.json that could not be written.
  */
-export function windowStart(root, task, questions) {
-    let start = "";
+export function windowStart(root, task, questions, fallback = false) {
+    let start = fallback ? "" : null;
     try {
-        const cur = JSON.parse(readFileSync(join(root, ".ctx/current.json"), "utf8"));
+        const cur = JSON.parse(readFileSync(join(root, CURRENT), "utf8"));
         if (cur.task === task && typeof cur.started_at === "string")
             start = cur.started_at;
     }
     catch {
         // no current task
     }
+    if (start === null)
+        return null;
     for (const q of questions ?? safeQuestions(root)) {
         if (q.task === task && q.status === "resolved" && typeof q.resolved_at === "string" && cmpStr(q.resolved_at, start) > 0)
             start = q.resolved_at;
@@ -58,9 +62,11 @@ function safeQuestions(root) {
         return [];
     }
 }
-/** The fail files of a task inside its window, in `at` order. */
-export function failsInWindow(root, task, questions) {
-    const start = windowStart(root, task, questions);
+/** REQ-LOOP-018 the fail files of a task inside its window, in `at` order. None without a window. */
+export function failsInWindow(root, task, questions, fallback = false) {
+    const start = windowStart(root, task, questions, fallback);
+    if (start === null)
+        return [];
     return readFails(root, task).filter((f) => cmpStr(f.file.at, start) >= 0);
 }
 /** The open question that names the task, if any. */
@@ -74,9 +80,53 @@ export function openQuestionFor(root, task, questions) {
 export function isCapQuestion(q, task) {
     return q.status === "open" && q.task === task && q.stage === "cap";
 }
+/**
+ * REQ-LOOP-018 a failed run with no current.json for the task opens its window first (056/D4). The file has only
+ * `started_at` and `task`: no `verify`, so a later Verify edit is not refused, and no `bundle_chars`, so stats keeps
+ * cycle time for runs that began with task start. Returns false when the write fails.
+ */
+export function openWindow(root, task) {
+    try {
+        const cur = JSON.parse(readFileSync(join(root, CURRENT), "utf8"));
+        if (cur.task === task && typeof cur.started_at === "string")
+            return true;
+    }
+    catch {
+        // absent or damaged: write a new one
+    }
+    try {
+        mkdirSync(join(root, ".ctx"), { recursive: true });
+        writeFileSync(join(root, CURRENT), dumps({ started_at: isoNow(), task }) + "\n");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** REQ-LOOP-017 the line that keeps fail files out of git, in `.ctx/evidence/.gitignore` (056/D1). */
+export const FAIL_IGNORE = "*.fail-*.json";
+/**
+ * REQ-LOOP-017 make sure `.ctx/evidence/.gitignore` has the fail file line. Create the file or append the line. Other
+ * lines keep their bytes and order. A write error changes nothing (056/D1).
+ */
+export function ensureFailIgnore(root) {
+    const p = join(root, ".ctx/evidence/.gitignore");
+    try {
+        const cur = existsSync(p) ? readFileSync(p, "utf8") : "";
+        if (cur.split(/\r?\n/).some((l) => l.trim() === FAIL_IGNORE))
+            return;
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, (cur === "" || cur.endsWith("\n") ? cur : cur + "\n") + FAIL_IGNORE + "\n");
+    }
+    catch {
+        // a read-only tree keeps its fail files tracked
+    }
+}
 /** Write the next fail file of a task. The attempt counts the window, the file number counts every fail file. */
 export function writeFail(root, task, verify, tail) {
-    const attempt = failsInWindow(root, task).length + 1;
+    // REQ-LOOP-018 when current.json cannot be written, count as before (056/D4)
+    const opened = openWindow(root, task);
+    const attempt = failsInWindow(root, task, undefined, !opened).length + 1;
     const rel = evidenceRel({ id: task });
     const base = rel.slice(0, -".json".length);
     let n = 1;
@@ -86,6 +136,7 @@ export function writeFail(root, task, verify, tail) {
     const file = { at: isoNow(), attempt, stderr_tail: tail, task, verify };
     mkdirSync(dirname(join(root, target)), { recursive: true });
     writeFileSync(join(root, target), dumps(file) + "\n");
+    ensureFailIgnore(root);
     return { rel: target, file };
 }
 /** REQ-LOOP-002 the question text at the cap. It quotes the failing line (033/D2). Strict mode. */

package/dist/main.js

@@ -1,6 +1,9 @@
 // REQ-CLI-001 REQ-CLI-002 REQ-CLI-003 command dispatch. Each command loads its modules inside its action.
+import { resolve } from "node:path";
 import { COMMANDS, GROUPS, parseArgs, UsageError } from "./cli/args.js";
 import { VERSION } from "./version.js";
+import { errInfo, note } from "./journal/note.js";
+import { runCommand } from "./runcmd.js";
 export async function main(argv, io) {
     // REQ-LINT-001 the linters keep the argument rules of the Python scripts, so they skip this parser
     // REQ-CLI-006 `specctx help <cmd>` prints the page of one command
@@ -29,6 +32,7 @@ export async function main(argv, io) {
     }
     catch (e) {
         if (e instanceof UsageError) {
+            note(io, { cmd: "?" });
             io.err(`specctx: ${e.message}\n`);
             return 2;
         }
@@ -49,18 +53,26 @@ export async function main(argv, io) {
         return 0;
     }
     if (GROUPS.includes(parsed.command)) {
+        note(io, { cmd: "?" });
         const subs = COMMANDS.filter((c) => c.startsWith(parsed.command + " ")).map((c) => c.split(" ")[1]);
         io.err(`specctx: ${parsed.command} needs a subcommand: ${subs.join(", ")}\n`);
         return 2;
     }
     if (!COMMANDS.includes(parsed.command)) {
+        note(io, { cmd: "?" });
         const { commandList } = await import("./cli/help.js");
         io.err(`specctx: unknown command: ${parsed.command}\n${commandList()}`);
         return 2;
     }
+    note(io, { cmd: parsed.command });
     try {
         const { run } = await import("./cli/commands.js");
-        return await run(parsed, io);
+        const code = await run(parsed, io);
+        // REQ-JRN-002 init has no OpenSpec root check. Its root is the one it wrote to.
+        if (code === 0 && parsed.command === "init") {
+            note(io, { root: resolve(io.cwd, parsed.flags.root ?? "."), signal: "init-ok" });
+        }
+        return code;
     }
     catch (e) {
         const { UsageExit } = await import("./cli/errors.js");
@@ -69,6 +81,9 @@ export async function main(argv, io) {
             return 2;
         }
         io.err(`specctx: internal error: ${e.stack ?? String(e)}\n`);
+        // REQ-JRN-006 one Strict line that points to the report command and the issues page
+        io.err(`Run ${runCommand(io.journal?.run ?? "specctx", "report")} and file the output at https://github.com/sonqh/spec-ctx/issues.\n`);
+        note(io, { err: errInfo(e) });
         return 3;
     }
 }

package/dist/tasks/evidence.js

@@ -39,9 +39,9 @@ export function writeEvidence(root, t, entries, verify, kind, note, cwd) {
     // REQ-STAT-002 copy the bundle size and the start time that task start wrote for this task
     try {
         const cur = JSON.parse(readFileSync(join(root, ".ctx/current.json"), "utf8"));
-        if (cur.task === t.id) {
-            if (typeof cur.bundle_chars === "number")
-                ev.bundle_chars = cur.bundle_chars;
+        // REQ-LOOP-018 started_at only with bundle_chars, so a window that a failed run opened gives no cycle time (056/D4)
+        if (cur.task === t.id && typeof cur.bundle_chars === "number") {
+            ev.bundle_chars = cur.bundle_chars;
             if (typeof cur.started_at === "string")
                 ev.started_at = cur.started_at;
         }

package/dist/util/redact.js

@@ -0,0 +1,57 @@
+// REQ-TASK-008 machine paths out of evidence (056/D5). Windows paths are out of scope: Verify runs through sh.
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+const WORD = /[A-Za-z0-9._-]/;
+function trimSlash(p) {
+    return p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
+}
+function realOf(root) {
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        return null;
+    }
+}
+/** The home directory: HOME at call time when set, else the OS answer. Bun caches homedir(), so HOME goes first. */
+function homeNow() {
+    return process.env.HOME || homedir();
+}
+/**
+ * REQ-TASK-008 replace the project root and its real path with `.`, and the home directory with `~`. The longest path
+ * goes first, and the root wins a tie. A match needs a start of text or a non word character before it and a non word
+ * character or the end after it. A root or home of `/` or the empty string is skipped. `real` defaults to the real path
+ * of `root`, so a test can pin the macOS `/tmp` case.
+ */
+export function redactPaths(text, root, home = homeNow(), real = realOf(root)) {
+    const pairs = [];
+    const add = (from, to) => {
+        if (from === null)
+            return;
+        const p = trimSlash(from);
+        if (p === "" || p === "/" || pairs.some(([f]) => f === p))
+            return;
+        pairs.push([p, to]);
+    };
+    add(root, ".");
+    add(real, ".");
+    add(home, "~");
+    if (!pairs.length || text === "")
+        return text;
+    // the longest path first, the root before the home on a tie (a stable sort keeps the push order)
+    pairs.sort((a, b) => b[0].length - a[0].length);
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const hit = pairs.find(([from]) => text.startsWith(from, i) && (i === 0 || !WORD.test(text[i - 1])) && (i + from.length === text.length || !WORD.test(text[i + from.length])));
+        if (hit) {
+            out += hit[1];
+            i += hit[0].length;
+        }
+        else {
+            out += text[i];
+            i++;
+        }
+    }
+    return out;
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 // REQ-CLI-001 version string. tests/cli/version.test.ts keeps it equal to package.json.
-export const VERSION = "0.4.1";
+export const VERSION = "0.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-ctx",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Deterministic context engine and task workflow for OpenSpec projects.",
   "type": "module",
   "license": "MIT",