@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/core/utils/backup.js

@@ -0,0 +1,98 @@
+/**
+ * Timestamped backup-directory utility.
+ *
+ * Several apply-style flows need to materialise a timestamped backup
+ * directory before overwriting files in place:
+ *   • `src/knowledge/builder.ts` (applyPages) — .forge-knowledge/
+ *
+ * Shared shape:
+ *   1. Compute a timestamp slug from `new Date()`.
+ *   2. Resolve the path `baseDir/<slug>` — if it already exists, append
+ *      `-2`, `-3`, ... until an unused name is found.
+ *   3. `mkdir -p` the resolved path.
+ *   4. Return the path so the caller can copy whatever files it wants into
+ *      it (the actual copy logic stays at the call site because the two
+ *      consumers have different file-selection rules).
+ *
+ * Step 2 is optional via `conflictSuffix: 'never'` for call sites whose
+ * current behavior was "no collision handling, just mkdir -p" — preserves
+ * pre-refactor byte-identical output.
+ */
+import { promises as fs, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Default timestamp slug formatter: local-time `YYYYMMDD-HHMM`.
+ *
+ * Local (not UTC) by design — matches the post-revert decision in commit
+ * 640d271a so backup directory names line up with the developer's wall clock.
+ */
+export function defaultTimestampSlug(now = new Date()) {
+    const YYYY = now.getFullYear();
+    const MM = String(now.getMonth() + 1).padStart(2, '0');
+    const DD = String(now.getDate()).padStart(2, '0');
+    const HH = String(now.getHours()).padStart(2, '0');
+    const mm = String(now.getMinutes()).padStart(2, '0');
+    return `${YYYY}${MM}${DD}-${HH}${mm}`;
+}
+/**
+ * Resolve + create a timestamped backup directory under `baseDir`.
+ *
+ * The caller copies whatever files it wants into `result.path` afterwards.
+ * Returns the resolved path and final slug. Throws on `fs.mkdir` failure
+ * (does NOT swallow filesystem errors).
+ */
+export async function createTimestampedBackup(options) {
+    const formatter = options.tsFormatter ?? defaultTimestampSlug;
+    const conflict = options.conflictSuffix ?? 'suffix';
+    const baseSlug = formatter();
+    let slug = baseSlug;
+    let backupPath = path.join(options.baseDir, slug);
+    if (conflict === 'suffix') {
+        let suffix = 2;
+        // Probe sequentially: <slug>, <slug>-2, <slug>-3, ...
+        // (matches upgrade-engine.ts pre-refactor behavior exactly)
+        while (true) {
+            try {
+                await fs.access(backupPath);
+                // Directory exists — try next suffix
+                slug = `${baseSlug}-${suffix}`;
+                backupPath = path.join(options.baseDir, slug);
+                suffix++;
+            }
+            catch {
+                break; // doesn't exist, we can use it
+            }
+        }
+    }
+    if (options.mkdir !== false) {
+        await fs.mkdir(backupPath, { recursive: true });
+    }
+    return { path: backupPath, slug };
+}
+/**
+ * Synchronous counterpart of {@link createTimestampedBackup} for call sites
+ * that must remain non-async (e.g. `knowledge/builder.ts:applyPages`).
+ *
+ * Behavior is identical to the async version, just uses `existsSync` +
+ * `mkdirSync` instead of `fs.access` / `fs.mkdir`.
+ */
+export function createTimestampedBackupSync(options) {
+    const formatter = options.tsFormatter ?? defaultTimestampSlug;
+    const conflict = options.conflictSuffix ?? 'suffix';
+    const baseSlug = formatter();
+    let slug = baseSlug;
+    let backupPath = path.join(options.baseDir, slug);
+    if (conflict === 'suffix') {
+        let suffix = 2;
+        while (existsSync(backupPath)) {
+            slug = `${baseSlug}-${suffix}`;
+            backupPath = path.join(options.baseDir, slug);
+            suffix++;
+        }
+    }
+    if (options.mkdir !== false) {
+        mkdirSync(backupPath, { recursive: true });
+    }
+    return { path: backupPath, slug };
+}
+//# sourceMappingURL=backup.js.map

package/dist/core/utils/backup.js.map

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

package/dist/core/utils/binary-paths.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Binary / install-path resolution helpers.
+ *
+ * Use these when reading files that ship WITH the cf binary (bundled skill /
+ * agent .md files), NOT for files in the user's project cwd. The daemon is
+ * launched by launchd / systemd / a fresh shell where `process.cwd()` is `/`
+ * or `$HOME` — assumptions like `cwd()/src/skills/distilled/<id>.md` silently
+ * resolve to nothing and the UI shows blank/"missing" content.
+ *
+ * Decision: docs/design/2026-06-01/0850-decision-cwd-binary-path-audit.md
+ * Companion: see `src/core/diagnostics/checks.ts` `resolveProjectRoot` for
+ * the inverse case (cwd as USER PROJECT — handled by CF_PROJECT_ROOT env).
+ *
+ * Resolution priority (highest first) for bundled skill/agent files:
+ *   1. `~/.claude/skills/<id>.md` or `~/.claude/agents/<name>.md` — user
+ *      install location, cross-project, populated by daemon `skill-sync.ts`.
+ *   2. `<binaryRoot>/skills/distilled/<id>.md` — prod (dist/) or test (src/)
+ *      sibling of the running JS file, resolved via `import.meta.url`. This
+ *      is the canonical binary-bundled location.
+ *   3. `<binaryRoot>/../src/skills/distilled/<id>.md` — dev fallback in case
+ *      running an ESM dev build that lives one level above `src/`.
+ *   4. `process.cwd()/src/skills/distilled/<id>.md` — legacy CLI fallback,
+ *      kept so `cf` invoked from the repo root still resolves bundled files
+ *      even if step 2 fails (e.g. transient `import.meta.url` weirdness).
+ *
+ * Pattern reference: `src/daemon/skill-sync.ts:40` (uses the same
+ * `import.meta.url` resolution) and `src/web/routes/static.ts:9-14`
+ * (uses the same candidate-fallback chain).
+ */
+/**
+ * Directory containing the running binary file (this module).
+ *
+ * - Prod build: `dist/core/utils/binary-paths.js` → returns `dist/core/utils`
+ * - Dev / vitest: `src/core/utils/binary-paths.ts` → returns `src/core/utils`
+ *
+ * Callers typically walk up with `..` to reach the bundled skills/agents
+ * directories (siblings of `core/`).
+ */
+export declare function getBinaryRoot(): string;
+/** `~/.claude/skills/` — user-installed skills directory (cross-project). */
+export declare function getUserSkillsDir(): string;
+/** `~/.claude/agents/` — user-installed agents directory (cross-project). */
+export declare function getUserAgentsDir(): string;
+/**
+ * Return the ordered list of candidate paths the loader should try for a
+ * bundled distilled skill, highest-priority first. Exposed so callers can
+ * report the actual `path` field on the API response.
+ *
+ * NOTE: skill .md files in `~/.claude/skills/` may be stored either as
+ * `<id>.md` (legacy) or `distilled-<id>.md` (current sync layout), so we emit
+ * both variants for the user dir.
+ */
+export declare function getSkillCandidates(id: string): string[];
+/**
+ * Return the ordered list of candidate paths for an agent .md file. Agents
+ * are different from skills: project-specific agents live in
+ * `<projectCwd>/.claude/agents/<name>.md` and MUST keep working — so cwd is
+ * kept as a candidate (last) rather than removed.
+ */
+export declare function getAgentCandidates(name: string): string[];
+/**
+ * Resolve a bundled skill .md file to the first candidate that exists on
+ * disk, or `null` if none match.
+ */
+export declare function resolveSkillPath(id: string): string | null;
+/**
+ * Resolve an agent .md file to the first candidate that exists on disk, or
+ * `null` if none match.
+ */
+export declare function resolveAgentPath(name: string): string | null;
+/**
+ * Resolve the binary-bundled `skills/distilled/` *directory* (not a specific
+ * file) — used by writers like `skills-distill` that need to emit files into
+ * the distilled tree. Returns the first existing directory in the chain, or
+ * `null` if none exist.
+ *
+ * Priority:
+ *   1. `<binaryRoot>/../skills/distilled` (prod: dist/skills/distilled)
+ *   2. `<binaryRoot>/../../src/skills/distilled` (dev: src/skills/distilled)
+ *   3. `process.cwd()/src/skills/distilled` (legacy fallback)
+ *
+ * Why include cwd: distill is historically a dev-time operation; users
+ * running `cf skills distill` from the repo root should keep working.
+ */
+export declare function resolveDistilledOutputDir(): string | null;
+/**
+ * Return the full ordered candidate list for the distilled output directory.
+ * Exposed for tests and for callers that need to log which paths were tried
+ * (e.g. on a "missing" response).
+ */
+export declare function getDistilledOutputDirCandidates(): string[];
+/**
+ * Targets for writing a freshly-distilled skill .md so it is BOTH immediately
+ * usable at runtime AND persisted into the git source-of-truth (decision
+ * 4e592120). Two distinct concerns:
+ *
+ *   - `runtimeDir` — where the running binary READS distilled skills from. In
+ *     a prod/daemon build this is `dist/skills/distilled` (sibling of the
+ *     running JS via `import.meta.url`); in dev/vitest it is
+ *     `src/skills/distilled`. Writing here makes `cf skill invoke` / agent /
+ *     `SkillRegistry.reload()` see the new file with no rebuild. ALWAYS set.
+ *
+ *   - `srcDir` — the git-tracked canonical source `src/skills/distilled`. Only
+ *     present in a repo/dev deployment where `src/` exists alongside the
+ *     binary. Writing here persists the skill so a later `npm run build`
+ *     (which does `rm -rf dist` then `cp src→dist`) does NOT delete it. In a
+ *     packaged/npm-global install there is no `src/` — `srcDir` is `null` and
+ *     callers gracefully degrade to runtime-only writes.
+ *
+ * Resolution is binDir-relative (via `import.meta.url`), NOT `process.cwd()`:
+ * the daemon is launched by launchd with cwd=`/`, so a cwd-anchored src path
+ * would silently miss. The cwd candidate is kept ONLY as a last-resort runtime
+ * fallback (mirrors `getDistilledOutputDirCandidates`).
+ *
+ * Both directories are returned as ABSOLUTE intended paths; they are NOT
+ * required to already exist (the writer mkdir's them). `runtimeDir` resolves
+ * to the first EXISTING dist/src sibling when one exists, else the canonical
+ * dist-sibling path so the writer creates it.
+ */
+export declare function resolveDistilledWriteTargets(): {
+    runtimeDir: string;
+    srcDir: string | null;
+};
+//# sourceMappingURL=binary-paths.d.ts.map

package/dist/core/utils/binary-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-paths.d.ts","sourceRoot":"","sources":["../../../src/core/utils/binary-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAsBvD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAWzD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,GAAG,IAAI,CAWzD;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,IAAI,MAAM,EAAE,CAO1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,4BAA4B,IAAI;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAwBA"}

package/dist/core/utils/binary-paths.js

@@ -0,0 +1,218 @@
+/**
+ * Binary / install-path resolution helpers.
+ *
+ * Use these when reading files that ship WITH the cf binary (bundled skill /
+ * agent .md files), NOT for files in the user's project cwd. The daemon is
+ * launched by launchd / systemd / a fresh shell where `process.cwd()` is `/`
+ * or `$HOME` — assumptions like `cwd()/src/skills/distilled/<id>.md` silently
+ * resolve to nothing and the UI shows blank/"missing" content.
+ *
+ * Decision: docs/design/2026-06-01/0850-decision-cwd-binary-path-audit.md
+ * Companion: see `src/core/diagnostics/checks.ts` `resolveProjectRoot` for
+ * the inverse case (cwd as USER PROJECT — handled by CF_PROJECT_ROOT env).
+ *
+ * Resolution priority (highest first) for bundled skill/agent files:
+ *   1. `~/.claude/skills/<id>.md` or `~/.claude/agents/<name>.md` — user
+ *      install location, cross-project, populated by daemon `skill-sync.ts`.
+ *   2. `<binaryRoot>/skills/distilled/<id>.md` — prod (dist/) or test (src/)
+ *      sibling of the running JS file, resolved via `import.meta.url`. This
+ *      is the canonical binary-bundled location.
+ *   3. `<binaryRoot>/../src/skills/distilled/<id>.md` — dev fallback in case
+ *      running an ESM dev build that lives one level above `src/`.
+ *   4. `process.cwd()/src/skills/distilled/<id>.md` — legacy CLI fallback,
+ *      kept so `cf` invoked from the repo root still resolves bundled files
+ *      even if step 2 fails (e.g. transient `import.meta.url` weirdness).
+ *
+ * Pattern reference: `src/daemon/skill-sync.ts:40` (uses the same
+ * `import.meta.url` resolution) and `src/web/routes/static.ts:9-14`
+ * (uses the same candidate-fallback chain).
+ */
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+/**
+ * Directory containing the running binary file (this module).
+ *
+ * - Prod build: `dist/core/utils/binary-paths.js` → returns `dist/core/utils`
+ * - Dev / vitest: `src/core/utils/binary-paths.ts` → returns `src/core/utils`
+ *
+ * Callers typically walk up with `..` to reach the bundled skills/agents
+ * directories (siblings of `core/`).
+ */
+export function getBinaryRoot() {
+    return path.dirname(fileURLToPath(import.meta.url));
+}
+/** `~/.claude/skills/` — user-installed skills directory (cross-project). */
+export function getUserSkillsDir() {
+    return path.join(os.homedir(), '.claude', 'skills');
+}
+/** `~/.claude/agents/` — user-installed agents directory (cross-project). */
+export function getUserAgentsDir() {
+    return path.join(os.homedir(), '.claude', 'agents');
+}
+/**
+ * Return the ordered list of candidate paths the loader should try for a
+ * bundled distilled skill, highest-priority first. Exposed so callers can
+ * report the actual `path` field on the API response.
+ *
+ * NOTE: skill .md files in `~/.claude/skills/` may be stored either as
+ * `<id>.md` (legacy) or `distilled-<id>.md` (current sync layout), so we emit
+ * both variants for the user dir.
+ */
+export function getSkillCandidates(id) {
+    const binDir = getBinaryRoot();
+    const userDir = getUserSkillsDir();
+    const fileName = `${id}.md`;
+    return [
+        // 1. User install location (preferred — cross-project, daemon-managed)
+        path.join(userDir, fileName),
+        // Compat: the file may live under the distilled- prefix even if caller
+        // passed the bare id (or vice versa). Both are emitted so either layout
+        // resolves.
+        id.startsWith('distilled-')
+            ? path.join(userDir, `${id.slice('distilled-'.length)}.md`)
+            : path.join(userDir, `distilled-${id}.md`),
+        // 2. Binary-sibling (prod: dist/skills/distilled, dev: src/skills/distilled).
+        //    From `<binDir>=dist/core/utils` we walk up two levels to `dist/`, then
+        //    down into skills/distilled. Same in dev (`src/core/utils` → `src/`).
+        path.join(binDir, '..', '..', 'skills', 'distilled', fileName),
+        // 3. One-level-up dev fallback (some bundlers flatten the structure)
+        path.join(binDir, '..', '..', '..', 'src', 'skills', 'distilled', fileName),
+        // 4. Legacy cwd fallback (CLI invoked from the repo root)
+        path.join(process.cwd(), 'src', 'skills', 'distilled', fileName),
+    ];
+}
+/**
+ * Return the ordered list of candidate paths for an agent .md file. Agents
+ * are different from skills: project-specific agents live in
+ * `<projectCwd>/.claude/agents/<name>.md` and MUST keep working — so cwd is
+ * kept as a candidate (last) rather than removed.
+ */
+export function getAgentCandidates(name) {
+    const userDir = getUserAgentsDir();
+    const fileName = `${name}.md`;
+    return [
+        // 1. User-global agents
+        path.join(userDir, fileName),
+        // 2. Project-local agents (preserved — `process.cwd()/.claude/agents/`)
+        //    Important: kept so project-specific agents authored in a repo still
+        //    resolve when `cf` is invoked from that repo.
+        path.join(process.cwd(), '.claude', 'agents', fileName),
+    ];
+}
+/**
+ * Resolve a bundled skill .md file to the first candidate that exists on
+ * disk, or `null` if none match.
+ */
+export function resolveSkillPath(id) {
+    for (const candidate of getSkillCandidates(id)) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Resolve an agent .md file to the first candidate that exists on disk, or
+ * `null` if none match.
+ */
+export function resolveAgentPath(name) {
+    for (const candidate of getAgentCandidates(name)) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Resolve the binary-bundled `skills/distilled/` *directory* (not a specific
+ * file) — used by writers like `skills-distill` that need to emit files into
+ * the distilled tree. Returns the first existing directory in the chain, or
+ * `null` if none exist.
+ *
+ * Priority:
+ *   1. `<binaryRoot>/../skills/distilled` (prod: dist/skills/distilled)
+ *   2. `<binaryRoot>/../../src/skills/distilled` (dev: src/skills/distilled)
+ *   3. `process.cwd()/src/skills/distilled` (legacy fallback)
+ *
+ * Why include cwd: distill is historically a dev-time operation; users
+ * running `cf skills distill` from the repo root should keep working.
+ */
+export function resolveDistilledOutputDir() {
+    const binDir = getBinaryRoot();
+    const candidates = [
+        path.join(binDir, '..', '..', 'skills', 'distilled'),
+        path.join(binDir, '..', '..', '..', 'src', 'skills', 'distilled'),
+        path.join(process.cwd(), 'src', 'skills', 'distilled'),
+    ];
+    for (const dir of candidates) {
+        if (fs.existsSync(dir))
+            return dir;
+    }
+    return null;
+}
+/**
+ * Return the full ordered candidate list for the distilled output directory.
+ * Exposed for tests and for callers that need to log which paths were tried
+ * (e.g. on a "missing" response).
+ */
+export function getDistilledOutputDirCandidates() {
+    const binDir = getBinaryRoot();
+    return [
+        path.join(binDir, '..', '..', 'skills', 'distilled'),
+        path.join(binDir, '..', '..', '..', 'src', 'skills', 'distilled'),
+        path.join(process.cwd(), 'src', 'skills', 'distilled'),
+    ];
+}
+/**
+ * Targets for writing a freshly-distilled skill .md so it is BOTH immediately
+ * usable at runtime AND persisted into the git source-of-truth (decision
+ * 4e592120). Two distinct concerns:
+ *
+ *   - `runtimeDir` — where the running binary READS distilled skills from. In
+ *     a prod/daemon build this is `dist/skills/distilled` (sibling of the
+ *     running JS via `import.meta.url`); in dev/vitest it is
+ *     `src/skills/distilled`. Writing here makes `cf skill invoke` / agent /
+ *     `SkillRegistry.reload()` see the new file with no rebuild. ALWAYS set.
+ *
+ *   - `srcDir` — the git-tracked canonical source `src/skills/distilled`. Only
+ *     present in a repo/dev deployment where `src/` exists alongside the
+ *     binary. Writing here persists the skill so a later `npm run build`
+ *     (which does `rm -rf dist` then `cp src→dist`) does NOT delete it. In a
+ *     packaged/npm-global install there is no `src/` — `srcDir` is `null` and
+ *     callers gracefully degrade to runtime-only writes.
+ *
+ * Resolution is binDir-relative (via `import.meta.url`), NOT `process.cwd()`:
+ * the daemon is launched by launchd with cwd=`/`, so a cwd-anchored src path
+ * would silently miss. The cwd candidate is kept ONLY as a last-resort runtime
+ * fallback (mirrors `getDistilledOutputDirCandidates`).
+ *
+ * Both directories are returned as ABSOLUTE intended paths; they are NOT
+ * required to already exist (the writer mkdir's them). `runtimeDir` resolves
+ * to the first EXISTING dist/src sibling when one exists, else the canonical
+ * dist-sibling path so the writer creates it.
+ */
+export function resolveDistilledWriteTargets() {
+    const binDir = getBinaryRoot();
+    const distSibling = path.join(binDir, '..', '..', 'skills', 'distilled');
+    const srcSibling = path.join(binDir, '..', '..', '..', 'src', 'skills', 'distilled');
+    // runtimeDir: prefer an already-existing dist/src sibling (whichever the
+    // binary actually reads from). If neither exists yet, default to the
+    // canonical dist-sibling so the writer creates it where the runtime reads.
+    let runtimeDir;
+    if (fs.existsSync(distSibling)) {
+        runtimeDir = distSibling;
+    }
+    else if (fs.existsSync(srcSibling)) {
+        // dev/vitest: binary lives in src/, so the dist sibling does not exist;
+        // src IS the runtime read path here.
+        runtimeDir = srcSibling;
+    }
+    else {
+        runtimeDir = distSibling;
+    }
+    // srcDir: canonical git source-of-truth. Present only when src/ exists
+    // alongside the binary (repo/dev). null in packaged/npm-global installs.
+    const srcDir = fs.existsSync(srcSibling) ? srcSibling : null;
+    return { runtimeDir, srcDir };
+}
+//# sourceMappingURL=binary-paths.js.map

package/dist/core/utils/binary-paths.js.map

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

package/dist/core/utils/bypass-token.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bypass token file helpers (Phase 2c safety-net #2).
+ *
+ * The token lives at `~/.claude-forge/bypass.token` (mode 0600). When present
+ * and not expired, PreToolUseHandler treats it like an inline `forge:bypass=`
+ * marker — the next deny becomes a `bypass` row + allow=true.
+ *
+ * Format (JSON):
+ *   {
+ *     "token":      "<uuid>",
+ *     "expires_at": "ISO timestamp",
+ *     "reason":     "<free-form text>",
+ *     "issued_at":  "ISO timestamp"
+ *   }
+ *
+ * Read-side robustness:
+ *   • Parsing failure / missing fields / expired token → returns `null`.
+ *   • File-mode looser than 0600 → returns `null` AND logs a warning (the
+ *     daemon refuses to honor a world-readable token to avoid local privilege
+ *     escalation).
+ *
+ * Write-side robustness:
+ *   • Always writes mode 0600 explicitly.
+ *   • Atomic via `writeFileSync` + chmod fallback.
+ */
+export interface BypassTokenPayload {
+    token: string;
+    /** ISO 8601 UTC timestamp at which the token stops being honored. */
+    expires_at: string;
+    /** Human-readable reason; surfaced in tool_intercepts.bypass_token. */
+    reason: string;
+    /** ISO 8601 UTC timestamp when the file was written. */
+    issued_at: string;
+}
+/**
+ * Read & validate the bypass token. Returns `null` for any of:
+ *   • file missing
+ *   • file mode != 0600 (world / group readable)
+ *   • JSON parse error
+ *   • missing required fields
+ *   • expired
+ *
+ * Caller paths (PreToolUseHandler) should treat a `null` return as "no bypass".
+ */
+export declare function readBypassFile(path?: string): BypassTokenPayload | null;
+export interface WriteBypassFileOptions {
+    /** Defaults to FORGE_PATHS.bypassToken(). Override only in tests. */
+    path?: string;
+    /** Time-to-live in milliseconds (caller computes from `--ttl 5m` etc.). */
+    ttlMs: number;
+    /** Free-form reason text persisted in the payload. */
+    reason: string;
+    /** Defaults to crypto.randomUUID(). Override only in tests. */
+    token?: string;
+    /** Defaults to Date.now(). Override only in tests. */
+    nowMs?: number;
+}
+/**
+ * Write the token JSON with mode 0600. The parent directory is created if it
+ * does not already exist. Returns the path written so callers can echo it.
+ */
+export declare function writeBypassFile(opts: WriteBypassFileOptions): {
+    path: string;
+    payload: BypassTokenPayload;
+};
+/** Remove the token file if present. Idempotent. */
+export declare function revokeBypassFile(path?: string): boolean;
+/**
+ * Parse `--ttl <duration>` argument from CLI. Accepts:
+ *   • plain number → seconds
+ *   • `<n>s` / `<n>m` / `<n>h` suffix
+ * Returns milliseconds. Throws on invalid input.
+ */
+export declare function parseTtl(input: string): number;
+//# sourceMappingURL=bypass-token.d.ts.map

package/dist/core/utils/bypass-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bypass-token.d.ts","sourceRoot":"","sources":["../../../src/core/utils/bypass-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAgBH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAkC,GAAG,kBAAkB,GAAG,IAAI,CAwClG;AAED,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,kBAAkB,CAAC;CAC7B,CAmBA;AAED,oDAAoD;AACpD,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAAkC,GAAG,OAAO,CASlF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ9C"}