@seanmars/tospec 0.19.0-beta.7 → 0.20.0

package/dist/utils/file-lock.js

@@ -0,0 +1,149 @@
+/**
+ * A cross-process advisory lock for read-compute-write sequences.
+ *
+ * `tospec archive` is one: it reads every target spec, merges in memory, then
+ * writes. Two overlapping archives both read the pre-merge text, so the second
+ * write erases the first one's requirement while both report success — measured
+ * at roughly one in five overlapping pairs.
+ *
+ * Advisory, not mandatory: it stops two of *our* merges from interleaving, not
+ * arbitrary writers.
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Two independent expiries. `timeoutMs` bounds how long *we* wait and is short,
+ * because waiting a minute on a few file reads means something is wrong, not
+ * busy. `staleMs` bounds how long a lock survives its holder and is long,
+ * because expiring it on an alive-but-slow holder hands the lock to a second
+ * writer — the exact failure being prevented.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_STALE_MS = 10 * 60_000;
+const RETRY_INTERVAL_MS = 100;
+/**
+ * How long an unreadable lock is left alone before it counts as abandoned.
+ *
+ * `open(…, 'wx')` creates the file before the record is written, so a held lock
+ * is briefly an *empty* file. Without this grace a waiter reads that emptiness
+ * as "no record", deletes the lock and takes it, and both processes hold it. The
+ * holder fills the file in microseconds, and a second is still short enough that
+ * a genuinely corrupt lock clears on the next run.
+ */
+const UNREADABLE_GRACE_MS = 1_000;
+export class LockTimeoutError extends Error {
+    holder;
+    constructor(message, holder) {
+        super(message);
+        this.holder = holder;
+        this.name = 'LockTimeoutError';
+    }
+}
+/** Whether a pid is a live process on this machine. */
+function isAlive(pid) {
+    try {
+        // Signal 0 probes without delivering anything; EPERM means it exists and
+        // belongs to someone else, so still alive.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+async function readRecord(lockPath) {
+    try {
+        return JSON.parse(await fs.readFile(lockPath, 'utf-8'));
+    }
+    catch {
+        // Unreadable, or read in the gap between the exclusive create and the
+        // record write, so the caller waits UNREADABLE_GRACE_MS before judging it.
+        return null;
+    }
+}
+/**
+ * True when the lock on disk should be taken over: older than `staleMs`, or its
+ * holder is gone. Pids are only meaningful locally, so a foreign host's lock is
+ * judged purely by age. An unreadable record is never stale on sight — the
+ * caller decides that, after UNREADABLE_GRACE_MS.
+ */
+function isStale(record, staleMs) {
+    if (!record)
+        return false;
+    const age = Date.now() - Date.parse(record.startedAt);
+    if (Number.isFinite(age) && age > staleMs)
+        return true;
+    if (record.host !== os.hostname())
+        return false;
+    return !isAlive(record.pid);
+}
+/**
+ * Runs `fn` while holding an exclusive lock at `lockPath`. Released in a
+ * `finally`, so a throwing `fn` leaves nothing behind; a killed process is
+ * covered by the staleness rules above.
+ */
+export async function withFileLock(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const record = {
+        pid: process.pid,
+        host: os.hostname(),
+        startedAt: new Date().toISOString(),
+        operation: options.operation ?? 'operation',
+    };
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + timeoutMs;
+    /** When the lock first read as unreadable, or null while it reads cleanly. */
+    let unreadableSince = null;
+    for (;;) {
+        try {
+            // 'wx' is the whole mechanism: create-or-EEXIST in one syscall, so two
+            // processes cannot both believe they created it.
+            const handle = await fs.open(lockPath, 'wx');
+            try {
+                await handle.writeFile(JSON.stringify(record), 'utf-8');
+            }
+            finally {
+                await handle.close();
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            const holder = await readRecord(lockPath);
+            // Only a lock that stays unreadable past the grace period is abandoned
+            // rather than mid-creation.
+            if (holder === null)
+                unreadableSince ??= Date.now();
+            else
+                unreadableSince = null;
+            const graceExpired = unreadableSince !== null && Date.now() - unreadableSince >= UNREADABLE_GRACE_MS;
+            if (isStale(holder, staleMs) || graceExpired) {
+                // Unlink and loop rather than write over it: the create-exclusive retry
+                // decides the winner when two waiters both judge it stale.
+                await fs.rm(lockPath, { force: true });
+                unreadableSince = null;
+                continue;
+            }
+            // Before the sleep, so a `timeoutMs` shorter than the grace period is
+            // still honoured.
+            if (Date.now() >= deadline) {
+                const held = holder
+                    ? `held by pid ${holder.pid} on ${holder.host} since ${holder.startedAt} (${holder.operation})`
+                    : 'held by an unidentified process';
+                throw new LockTimeoutError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the lock at ${lockPath}, ${held}. ` +
+                    'Another tospec process is probably still running; if none is, delete that file and retry.', holder);
+            }
+            await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL_MS));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await fs.rm(lockPath, { force: true });
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/utils/file-lock.js.map

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

package/dist/utils/file-system.d.ts

@@ -1,10 +1,7 @@
 /**
- * Most-recent mtime of any file under `dirPath` (recursive), falling back to
- * the directory's own mtime when it holds no files.
- *
- * Shared by `tospec list --sort recent` and the dashboard so both rank changes
- * by the same clock; they used to walk separately and could disagree.
- * ponytail: recursive walk; fine at repo scale (dozens of changes).
+ * Most-recent mtime of any file under `dirPath`, falling back to the directory's
+ * own mtime when it holds none. Shared by `tospec list --sort recent` and the
+ * dashboard so both rank changes by the same clock.
  */
 export declare function getLastModified(dirPath: string): Promise<Date>;
 /**
@@ -17,39 +14,22 @@ export declare function getLastModified(dirPath: string): Promise<Date>;
 export declare function extractNameFromPath(filePath: string): string;
 /**
  * Whether a failed read of a *targeted path* means it is not there, as opposed
- * to being there and unusable.
- *
- * `ENOENT` is the file itself; `ENOTDIR` is a parent component that is a file,
- * which makes the path unreachable for the same reason. Everything else —
- * `EACCES`, `EISDIR`, `EIO`, `EPERM` — describes a path that exists and could not
- * be read, and callers that treat those as absence state a conclusion the read
- * never reached.
- *
- * Use this when "there is nothing at this path yet" is a legitimate outcome for
- * a specific file. For enumerating a directory, use `isAbsentDirectoryError` —
- * the two differ on `ENOTDIR` and the difference is load-bearing.
+ * to being there and unusable. `ENOTDIR` counts because a parent component that
+ * is a file makes the path unreachable for the same reason;
+ * `EACCES`/`EISDIR`/`EIO` describe a path that exists. For enumerating a
+ * directory use `isAbsentDirectoryError`: the two differ on `ENOTDIR`.
  */
 export declare function isMissingPathError(error: unknown): boolean;
 /**
- * Whether a failed directory enumeration means the directory is not there.
- *
- * Deliberately narrower than `isMissingPathError`: `ENOTDIR` from a `readdir`
- * means something that is not a directory occupies the path, and answering
- * "empty" for that is how a broken layout comes to look like an absent one. For
- * a targeted read the same code means the parent is unreachable, which is
- * genuine absence — hence two predicates rather than one plus an exception.
+ * Narrower than `isMissingPathError`: `ENOTDIR` from a `readdir` means a
+ * non-directory occupies the path, and answering "empty" makes a broken layout
+ * look like an absent one.
  */
 export declare function isAbsentDirectoryError(error: unknown): boolean;
 export declare class FileSystemUtils {
-    /**
-     * Converts a path to use forward slashes (POSIX style).
-     * Essential for cross-platform compatibility with glob libraries like fast-glob.
-     */
+    /** fast-glob and friends only accept forward slashes. */
     static toPosixPath(p: string): string;
-    /**
-     * Returns a canonical absolute path when the target exists.
-     * Falls back to path.resolve() so callers can still produce a stable absolute path.
-     */
+    /** Falls back to path.resolve() when the target does not exist. */
     static canonicalizeExistingPath(targetPath: string): string;
     private static isWindowsBasePath;
     private static normalizeSegments;

package/dist/utils/file-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-system.d.ts","sourceRoot":"","sources":["../../src/utils/file-system.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBpE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED,qBAAa,eAAe;IAC1B;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpC;IAED;;;OAGG;IACH,MAAM,CAAC,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAW1D;IAED,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAIhC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAMhC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAe/D;IAED,OAAa,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3D;IAED,OAAa,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED,OAAa,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU9D;IAED,OAAa,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE;IAED,OAAa,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEvD;IAED,OAAa,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAqCrE;CACF"}
+{"version":3,"file":"file-system.d.ts","sourceRoot":"","sources":["../../src/utils/file-system.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBpE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY5D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED,qBAAa,eAAe;IAC1B,yDAAyD;IACzD,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpC;IAED,mEAAmE;IACnE,MAAM,CAAC,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAW1D;IAED,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAIhC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAMhC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAe/D;IAED,OAAa,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3D;IAED,OAAa,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED,OAAa,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU9D;IAED,OAAa,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE;IAED,OAAa,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEvD;IAED,OAAa,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiCrE;CACF"}

package/dist/utils/file-system.js

@@ -2,19 +2,16 @@ import * as nodeFs from 'fs';
 import path from 'path';
 const fs = nodeFs.promises;
 /**
- * Most-recent mtime of any file under `dirPath` (recursive), falling back to
- * the directory's own mtime when it holds no files.
- *
- * Shared by `tospec list --sort recent` and the dashboard so both rank changes
- * by the same clock; they used to walk separately and could disagree.
- * ponytail: recursive walk; fine at repo scale (dozens of changes).
+ * Most-recent mtime of any file under `dirPath`, falling back to the directory's
+ * own mtime when it holds none. Shared by `tospec list --sort recent` and the
+ * dashboard so both rank changes by the same clock.
  */
 export async function getLastModified(dirPath) {
     let latest = null;
     async function walk(dir) {
         const entries = await fs.readdir(dir, { withFileTypes: true });
         // Entries are independent and `latest` is an order-insensitive max, so the
-        // stats fan out instead of running one await at a time.
+        // stats fan out rather than running one await at a time.
         await Promise.all(entries.map(async (entry) => {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory()) {
@@ -49,49 +46,32 @@ export function extractNameFromPath(filePath) {
 }
 /**
  * Whether a failed read of a *targeted path* means it is not there, as opposed
- * to being there and unusable.
- *
- * `ENOENT` is the file itself; `ENOTDIR` is a parent component that is a file,
- * which makes the path unreachable for the same reason. Everything else —
- * `EACCES`, `EISDIR`, `EIO`, `EPERM` — describes a path that exists and could not
- * be read, and callers that treat those as absence state a conclusion the read
- * never reached.
- *
- * Use this when "there is nothing at this path yet" is a legitimate outcome for
- * a specific file. For enumerating a directory, use `isAbsentDirectoryError` —
- * the two differ on `ENOTDIR` and the difference is load-bearing.
+ * to being there and unusable. `ENOTDIR` counts because a parent component that
+ * is a file makes the path unreachable for the same reason;
+ * `EACCES`/`EISDIR`/`EIO` describe a path that exists. For enumerating a
+ * directory use `isAbsentDirectoryError`: the two differ on `ENOTDIR`.
  */
 export function isMissingPathError(error) {
     const code = error?.code;
     return code === 'ENOENT' || code === 'ENOTDIR';
 }
 /**
- * Whether a failed directory enumeration means the directory is not there.
- *
- * Deliberately narrower than `isMissingPathError`: `ENOTDIR` from a `readdir`
- * means something that is not a directory occupies the path, and answering
- * "empty" for that is how a broken layout comes to look like an absent one. For
- * a targeted read the same code means the parent is unreachable, which is
- * genuine absence — hence two predicates rather than one plus an exception.
+ * Narrower than `isMissingPathError`: `ENOTDIR` from a `readdir` means a
+ * non-directory occupies the path, and answering "empty" makes a broken layout
+ * look like an absent one.
  */
 export function isAbsentDirectoryError(error) {
     return error?.code === 'ENOENT';
 }
 export class FileSystemUtils {
-    /**
-     * Converts a path to use forward slashes (POSIX style).
-     * Essential for cross-platform compatibility with glob libraries like fast-glob.
-     */
+    /** fast-glob and friends only accept forward slashes. */
     static toPosixPath(p) {
         return p.replace(/\\/g, '/');
     }
-    /**
-     * Returns a canonical absolute path when the target exists.
-     * Falls back to path.resolve() so callers can still produce a stable absolute path.
-     */
+    /** Falls back to path.resolve() when the target does not exist. */
     static canonicalizeExistingPath(targetPath) {
         try {
-            // Prefer the native resolver so Windows short-path aliases are expanded.
+            // The native resolver expands Windows short-path aliases.
             return nodeFs.realpathSync.native(targetPath);
         }
         catch {
@@ -161,7 +141,6 @@ export class FileSystemUtils {
     }
     static async ensureWritePermissions(dirPath) {
         try {
-            // If directory doesn't exist, check parent directory permissions
             if (!await this.directoryExists(dirPath)) {
                 const parentDir = path.dirname(dirPath);
                 if (!await this.directoryExists(parentDir)) {
@@ -171,8 +150,7 @@ export class FileSystemUtils {
             }
             const testFile = path.join(dirPath, '.tospec-test-' + Date.now() + '-' + Math.random().toString(36).slice(2));
             await fs.writeFile(testFile, '');
-            // On Windows, file may be temporarily locked by antivirus or indexing services.
-            // Retry unlink with a small delay if it fails.
+            // On Windows the file may be briefly locked by antivirus or indexing.
             const maxRetries = 3;
             for (let attempt = 0; attempt < maxRetries; attempt++) {
                 try {
@@ -181,12 +159,10 @@ export class FileSystemUtils {
                 }
                 catch (unlinkError) {
                     if (attempt === maxRetries - 1) {
-                        // Last attempt failed, but we successfully wrote the file, so permissions are OK
-                        // Just log and continue - the temp file will be cleaned up eventually
+                        // The write succeeded, so permissions are fine; only cleanup failed.
                         console.debug(`Could not clean up test file ${testFile}: ${unlinkError.message}`);
                     }
                     else {
-                        // Wait briefly before retrying (Windows file lock release)
                         await new Promise((resolve) => setTimeout(resolve, 50));
                     }
                 }

package/dist/utils/file-system.js.map

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

package/dist/utils/frontmatter.d.ts

@@ -1,22 +1,18 @@
 /**
- * Splits `---`-delimited yaml frontmatter from the markdown body.
+ * The single reader for ticket/change frontmatter, so the dashboard,
+ * `tospec show` and archive agree on which ticket belongs to which change.
  *
- * The single reader for ticket/change frontmatter: the dashboard, `tospec show`
- * and archive must agree on which ticket belongs to which change, so the
- * delimiter scan lives in one place rather than once per caller.
- *
- * Malformed yaml *throws* — the dashboard reports it per ticket as a
- * `parseError` rather than silently showing a ticket with no metadata. Callers
- * that would rather degrade than fail should use `frontmatterString`.
+ * Malformed yaml *throws*, so the dashboard can report it per ticket as a
+ * `parseError` instead of showing a ticket with no metadata. Callers that would
+ * rather degrade than fail should use `frontmatterString`.
  */
 export declare function splitFrontmatter(content: string): {
     data: Record<string, unknown>;
     body: string;
 };
 /**
- * Reads a string field from a document's frontmatter, or null when the field is
- * absent, non-string, or the frontmatter does not parse. For display and
- * lookup paths, where a broken header should fall back rather than fail.
+ * Null when the field is absent, non-string, or the frontmatter does not parse —
+ * for display and lookup paths, where a broken header should degrade, not fail.
  */
 export declare function frontmatterString(content: string, field: string): string | null;
 //# sourceMappingURL=frontmatter.d.ts.map

package/dist/utils/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAUA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO/E"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAaA;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO/E"}

package/dist/utils/frontmatter.js

@@ -1,16 +1,17 @@
 import { parse as parseYaml } from 'yaml';
+import { stripBom } from '../core/parsers/requirement-text.js';
 /**
- * Splits `---`-delimited yaml frontmatter from the markdown body.
+ * The single reader for ticket/change frontmatter, so the dashboard,
+ * `tospec show` and archive agree on which ticket belongs to which change.
  *
- * The single reader for ticket/change frontmatter: the dashboard, `tospec show`
- * and archive must agree on which ticket belongs to which change, so the
- * delimiter scan lives in one place rather than once per caller.
- *
- * Malformed yaml *throws* — the dashboard reports it per ticket as a
- * `parseError` rather than silently showing a ticket with no metadata. Callers
- * that would rather degrade than fail should use `frontmatterString`.
+ * Malformed yaml *throws*, so the dashboard can report it per ticket as a
+ * `parseError` instead of showing a ticket with no metadata. Callers that would
+ * rather degrade than fail should use `frontmatterString`.
  */
 export function splitFrontmatter(content) {
+    // A leading BOM fails the `---` test below and hands back empty `data`, which
+    // reads as "this ticket has no frontmatter" with nothing reporting a problem.
+    content = stripBom(content);
     if (!content.startsWith('---'))
         return { data: {}, body: content };
     const end = content.indexOf('\n---', 3);
@@ -23,9 +24,8 @@ export function splitFrontmatter(content) {
     return { data, body };
 }
 /**
- * Reads a string field from a document's frontmatter, or null when the field is
- * absent, non-string, or the frontmatter does not parse. For display and
- * lookup paths, where a broken header should fall back rather than fail.
+ * Null when the field is absent, non-string, or the frontmatter does not parse —
+ * for display and lookup paths, where a broken header should degrade, not fail.
  */
 export function frontmatterString(content, field) {
     try {

package/dist/utils/frontmatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAI9C,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACnE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxC,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAEnD,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7F,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IACpE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,KAAa;IAC9D,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/utils/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAI9C,8EAA8E;IAC9E,8EAA8E;IAC9E,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACnE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACxC,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAEnD,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7F,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IACpE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,KAAa;IAC9D,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/utils/interactive.d.ts

@@ -1,17 +1,12 @@
 export type InteractiveOptions = {
-    /**
-     * Explicit "disable prompts" flag passed by internal callers.
-     */
+    /** Explicit "disable prompts" flag passed by internal callers. */
     noInteractive?: boolean;
-    /**
-     * Commander-style negated option: `--no-interactive` sets this to false.
-     */
+    /** Commander-style negated option: `--no-interactive` sets this to false. */
     interactive?: boolean;
 };
 /**
- * Resolves whether non-interactive mode is requested.
- * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
- * Use this helper instead of manually checking options.noInteractive to avoid bugs.
+ * The one reader of both spellings. Checking `options.noInteractive` by hand misses
+ * commander's `interactive: false`.
  */
 export declare function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean;
 export declare function isInteractive(value?: boolean | InteractiveOptions): boolean;

package/dist/utils/interactive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../../src/utils/interactive.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,kBAAkB,GAAG,OAAO,CAGlF;AAED,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,kBAAkB,GAAG,OAAO,CAM3E"}
+{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../../src/utils/interactive.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kEAAkE;IAClE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,kBAAkB,GAAG,OAAO,CAGlF;AAED,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,kBAAkB,GAAG,OAAO,CAK3E"}

package/dist/utils/interactive.js

@@ -1,7 +1,6 @@
 /**
- * Resolves whether non-interactive mode is requested.
- * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
- * Use this helper instead of manually checking options.noInteractive to avoid bugs.
+ * The one reader of both spellings. Checking `options.noInteractive` by hand misses
+ * commander's `interactive: false`.
  */
 export function resolveNoInteractive(value) {
     if (typeof value === 'boolean')
@@ -13,7 +12,6 @@ export function isInteractive(value) {
         return false;
     if (process.env.OPEN_SPEC_INTERACTIVE === '0')
         return false;
-    // Respect the standard CI environment variable (set by GitHub Actions, GitLab CI, Travis, etc.)
     if ('CI' in process.env)
         return false;
     return !!process.stdin.isTTY;

package/dist/utils/interactive.js.map

@@ -1 +1 @@
-{"version":3,"file":"interactive.js","sourceRoot":"","sources":["../../src/utils/interactive.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAoC;IACvE,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,KAAK,EAAE,aAAa,KAAK,IAAI,IAAI,KAAK,EAAE,WAAW,KAAK,KAAK,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAoC;IAChE,IAAI,oBAAoB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAC5D,gGAAgG;IAChG,IAAI,IAAI,IAAI,OAAO,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"interactive.js","sourceRoot":"","sources":["../../src/utils/interactive.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAoC;IACvE,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,KAAK,EAAE,aAAa,KAAK,IAAI,IAAI,KAAK,EAAE,WAAW,KAAK,KAAK,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAoC;IAChE,IAAI,oBAAoB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAC5D,IAAI,IAAI,IAAI,OAAO,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AAC/B,CAAC"}

package/dist/utils/item-discovery.d.ts

@@ -1,21 +1,26 @@
 /**
- * Finds a change's ticket in the global `tospec/tickets/` index by matching the
- * ticket frontmatter's `change:` field. Scans only the active folder
- * (non-recursive), so archived tickets under `tickets/archive/` are excluded.
- * Returns the absolute path, or undefined if none matches.
+ * Every ticket in the active `tospec/tickets/` index whose frontmatter `change:`
+ * names this change, oldest first (the filename is the `yyyyMMdd_HHmmss` stamp).
+ * Non-recursive, so `tickets/archive/` is excluded.
  *
- * ponytail: linear scan of tickets/; fine at repo scale (one ticket per change).
- * Add an index if a project ever accumulates thousands of active changes.
+ * Plural because the index can hold more than one: `rm -rf` on a change leaves
+ * its ticket behind, and recreating the name adds a second. Callers that can
+ * report the ambiguity should; `findTicketPath` picks for the rest.
+ */
+export declare function findTicketPaths(root: string, changeName: string): Promise<string[]>;
+/**
+ * The newest wins: a second ticket exists because the change was recreated, so
+ * the later stamp describes the change on disk. Taking the first `readdir` entry
+ * files the run under the abandoned attempt's ticket.
  */
 export declare function findTicketPath(root: string, changeName: string): Promise<string | undefined>;
 /**
- * Active change directory names under `changesDir`, sorted, excluding `archive`
- * and dot-directories. The one rule for "which changes exist": list, archive
- * and status each filtered slightly differently, so a stray `.tmp/` showed up
- * in some listings and not others.
+ * The one rule for "which changes exist". Filtered separately per command, a
+ * stray `.tmp/` shows up in some listings and not others.
  */
 export declare function listActiveChangeDirs(changesDir: string): Promise<string[]>;
 export declare function getActiveChangeIds(root?: string): Promise<string[]>;
+/** A capability directory counts as a spec only once it holds a `spec.md`. */
 export declare function getSpecIds(root?: string): Promise<string[]>;
 export declare function getArchivedChangeIds(root?: string): Promise<string[]>;
 //# sourceMappingURL=item-discovery.d.ts.map

package/dist/utils/item-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"item-discovery.d.ts","sourceRoot":"","sources":["../../src/utils/item-discovery.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmBlG;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUhF;AAED,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAExF;AAED,wBAAsB,UAAU,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBhF;AAED,wBAAsB,oBAAoB,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW1F"}
+{"version":3,"file":"item-discovery.d.ts","sourceRoot":"","sources":["../../src/utils/item-discovery.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBzF;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGlG;AAeD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGhF;AAED,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAExF;AAED,8EAA8E;AAC9E,wBAAsB,UAAU,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAchF;AAED,wBAAsB,oBAAoB,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE1F"}