grounder 0.2.0 → 0.3.0

package/dist/help.js

@@ -0,0 +1,355 @@
+/** Help tiers and command metadata for the grounder CLI. */
+const GROUP_ORDER = ["Setup", "Write", "Paths", "Maintain", "Advanced"];
+const QUICKSTART = `Quickstart:
+  grounder vault init <path-to-your-vault>
+  grounder init
+  grounder note "my first note"
+  grounder handoff $'# Handoff\\n\\n## Next\\n1. …'
+  grounder handoff list
+  grounder plan $'# Goal\\n\\nShip it' --title phase-1
+  grounder plan list`;
+/**
+ * Single registry driving synopsis, full help, and per-command help so they
+ * cannot drift from each other (or from the dispatcher ids).
+ */
+export const COMMANDS = [
+    {
+        id: "vault",
+        group: "Setup",
+        summary: "Vault setup commands",
+        listUsage: "vault init <path>",
+        usage: "grounder vault init <path> [--yes] [--force] [--agent <id>] [--hooks]",
+        list: false,
+        flags: `Subcommands:
+  vault init   Initialize vault + home config (once per machine)`,
+    },
+    {
+        id: "vault init",
+        group: "Setup",
+        summary: "Initialize vault + home config (once per machine)",
+        listUsage: "vault init <path>",
+        usage: "grounder vault init <path> [--yes] [--force] [--agent <id>] [--hooks]",
+        flags: `Flags:
+  --yes          Skip confirmation prompts
+  --force        Overwrite existing home config / generated files
+  --agent <id>   Install for a specific agent (repeatable; default: auto-detect)
+                 Supported: cursor, claude
+  --hooks        Also install session-start teaser hooks`,
+    },
+    {
+        id: "init",
+        group: "Setup",
+        summary: "Connect the current repo to your vault",
+        listUsage: "init",
+        usage: "grounder init [--yes] [--force] [--id <id>] [--vault <path>]",
+        flags: `Flags:
+  --yes          Skip confirmation prompts
+  --force        Overwrite an existing link marker
+  --id <id>      Override detected project id
+  --vault <path> Override home vault root for this run`,
+    },
+    {
+        id: "note",
+        group: "Write",
+        summary: "Write a note to the vault",
+        listUsage: "note <text>",
+        usage: "grounder note <text> [--title <slug>]",
+        flags: `Flags:
+  --title <slug> Short slug in filename (default: slugified first line)`,
+    },
+    {
+        id: "handoff",
+        group: "Write",
+        summary: "Write a session handoff to vault logs/",
+        listUsage: "handoff <text>",
+        usage: "grounder handoff <text> [--title <slug>]",
+        flags: `Flags:
+  --title <slug> Short slug in filename (default: slugified first line)
+
+Subcommands:
+  handoff list   Print recent handoff paths (newest first)
+  handoff peek   One-line latest-handoff teaser (session hooks)`,
+    },
+    {
+        id: "handoff list",
+        group: "Write",
+        summary: "Print recent handoff paths (newest first)",
+        listUsage: "handoff list",
+        usage: "grounder handoff list [--limit <n>] [--head]",
+        flags: `Flags:
+  --limit <n>  Max paths to print (default: 5)
+  --head       Print only the newest usable path
+               (skips empty/unreadable files; same pick as handoff peek)`,
+    },
+    {
+        id: "plan",
+        group: "Write",
+        summary: "Write/update a named plan under vault plans/",
+        listUsage: "plan <text>",
+        usage: "grounder plan <text> (--title <name> [--force] | --path <file>)",
+        flags: `Flags:
+  --title <name> Required filename stem when creating/updating by name
+                 (trailing .md ok; sanitized, max 80 chars)
+  --path <file>  Update an existing plan by path (must resolve under this
+                 project's plans/; no title sanitization; always overwrites)
+  --force        With --title: overwrite an existing plan (preserves created)
+
+Subcommands:
+  plan list   Print recent plan paths (newest first)`,
+    },
+    {
+        id: "plan list",
+        group: "Write",
+        summary: "Print recent plan paths (newest first)",
+        listUsage: "plan list",
+        usage: "grounder plan list [--limit <n>]",
+        flags: `Flags:
+  --limit <n>  Max paths to print (default: 5)`,
+    },
+    {
+        id: "path notes",
+        group: "Paths",
+        summary: "Print resolved notes directory",
+        listUsage: "path notes",
+        usage: "grounder path notes",
+    },
+    {
+        id: "path logs",
+        group: "Paths",
+        summary: "Print resolved logs directory",
+        listUsage: "path logs",
+        usage: "grounder path logs",
+    },
+    {
+        id: "path plans",
+        group: "Paths",
+        summary: "Print resolved plans directory",
+        listUsage: "path plans",
+        usage: "grounder path plans",
+    },
+    {
+        id: "path",
+        group: "Paths",
+        summary: "Print a resolved vault directory for the linked project",
+        listUsage: "path <notes|logs|plans>",
+        usage: "grounder path <notes|logs|plans>",
+        list: false,
+        flags: `Subcommands:
+  path notes   Print resolved notes directory
+  path logs    Print resolved logs directory
+  path plans   Print resolved plans directory`,
+    },
+    {
+        id: "status",
+        group: "Maintain",
+        summary: "Snapshot of machine + project link + resolved paths",
+        listUsage: "status",
+        usage: "grounder status",
+    },
+    {
+        id: "doctor",
+        group: "Maintain",
+        summary: "Health checks with fix hints",
+        listUsage: "doctor",
+        usage: "grounder doctor [--global]",
+        flags: `Flags:
+  --global  Machine-only checks (skip project/link checks)`,
+    },
+    {
+        id: "migrate",
+        group: "Maintain",
+        summary: "Refresh agent install after upgrading grounder",
+        listUsage: "migrate",
+        usage: "grounder migrate [--force] [--dry-run] [--agent <id>] [--hooks]",
+        flags: `Flags:
+  --force      Overwrite command files you edited locally; also needed
+               once when upgrading from Grounder before 0.3
+  --dry-run    Preview without writing
+  --agent <id> Limit to a specific agent (repeatable)
+  --hooks      Also install hooks if not previously installed`,
+    },
+    {
+        id: "handoff peek",
+        group: "Advanced",
+        summary: "One-line latest-handoff teaser (used by session hooks)",
+        listUsage: "handoff peek",
+        usage: "grounder handoff peek [--json]",
+        flags: `Flags:
+  --json  Emit one JSON line for Cursor sessionStart
+          ({ additional_context } or {})`,
+    },
+    {
+        id: "help",
+        group: "Maintain",
+        summary: "Show help (full reference / per-command)",
+        listUsage: "help [<command>]",
+        usage: "grounder help [<command>]",
+        list: false,
+        flags: `With no args, prints the full reference (same as --help).
+With a command id, prints that command's usage and flags.
+
+Examples:
+  grounder help
+  grounder help note
+  grounder help handoff list
+  grounder help vault init`,
+    },
+];
+/**
+ * Command ids the CLI dispatches (including parent topics). Keep in sync with
+ * `cli.ts` / `helpExitCode(...)` call sites — the invariant test locks this.
+ */
+export const DISPATCHED_COMMAND_IDS = [
+    "vault",
+    "vault init",
+    "init",
+    "note",
+    "handoff",
+    "handoff list",
+    "handoff peek",
+    "plan",
+    "plan list",
+    "path",
+    "path notes",
+    "path logs",
+    "path plans",
+    "status",
+    "doctor",
+    "migrate",
+    "help",
+];
+const byId = new Map(COMMANDS.map((c) => [c.id, c]));
+/** True when argv contains an exact `-h` or `--help` token. */
+export function wantsHelp(argv) {
+    return argv.some((arg) => arg === "-h" || arg === "--help");
+}
+/**
+ * Resolve a help topic from argv segments after `help`, longest match first
+ * (e.g. `handoff list` before `handoff`).
+ */
+export function resolveCommandHelp(segments) {
+    if (segments.length === 0) {
+        return undefined;
+    }
+    for (let len = segments.length; len >= 1; len--) {
+        const id = segments.slice(0, len).join(" ");
+        const meta = byId.get(id);
+        if (meta) {
+            return meta;
+        }
+    }
+    return undefined;
+}
+export function printCommandHelp(meta) {
+    let out = `Usage: ${meta.usage}\n`;
+    if (meta.summary) {
+        out += `\n${meta.summary}\n`;
+    }
+    if (meta.flags) {
+        out += `\n${meta.flags}\n`;
+    }
+    process.stdout.write(out);
+}
+export function printCommandHelpById(id) {
+    const meta = byId.get(id);
+    if (!meta) {
+        throw new Error(`Unknown help id: ${id}`);
+    }
+    printCommandHelp(meta);
+}
+/** If argv asks for help, print per-command help and return 0; else null. */
+export function helpExitCode(argv, commandId) {
+    if (!wantsHelp(argv)) {
+        return null;
+    }
+    printCommandHelpById(commandId);
+    return 0;
+}
+function listedCommands() {
+    return COMMANDS.filter((c) => c.list !== false);
+}
+function formatGroupedLists() {
+    const listed = listedCommands();
+    const width = Math.max(...listed.map((c) => c.listUsage.length));
+    const blocks = [];
+    for (const group of GROUP_ORDER) {
+        const cmds = listed.filter((c) => c.group === group);
+        if (cmds.length === 0) {
+            continue;
+        }
+        const lines = cmds.map((c) => `  ${c.listUsage.padEnd(width)}  ${c.summary}`);
+        blocks.push(`${group}:\n${lines.join("\n")}`);
+    }
+    return blocks.join("\n\n");
+}
+function formatCommandDetail(c) {
+    const lines = [`${c.id}`, `  Usage: ${c.usage}`];
+    if (c.flags) {
+        for (const line of c.flags.split("\n")) {
+            lines.push(line.length > 0 ? `  ${line}` : "");
+        }
+    }
+    return lines.join("\n");
+}
+function formatFullCommandDetails() {
+    const listed = listedCommands().filter((c) => c.id !== "help");
+    const blocks = [];
+    for (const group of GROUP_ORDER) {
+        const cmds = listed.filter((c) => c.group === group);
+        if (cmds.length === 0) {
+            continue;
+        }
+        blocks.push(`${group}\n${cmds.map(formatCommandDetail).join("\n\n")}`);
+    }
+    return blocks.join("\n\n");
+}
+/** Bare `grounder` / `-h` — short grouped synopsis (no flag encyclopedia). */
+export function printSynopsis() {
+    process.stdout.write(`grounder — connect git projects to Obsidian dev vaults for AI agents
+
+${formatGroupedLists()}
+
+Global options:
+  -h             Short synopsis (this text)
+  --help         Full reference (all commands + flags)
+  -v, --version  Show version
+
+Run \`grounder help <command>\` for one command's flags.
+Run \`grounder --help\` for the full reference.
+
+${QUICKSTART}
+`);
+}
+/** `--help` / `grounder help` with no args — one-shot reference for humans/agents. */
+export function printFullHelp() {
+    process.stdout.write(`grounder — connect git projects to Obsidian dev vaults for AI agents
+
+${formatGroupedLists()}
+
+Global options:
+  -h             Short synopsis
+  --help         This full reference
+  -v, --version  Show version
+
+Commands:
+${formatFullCommandDetails()}
+
+${QUICKSTART}
+`);
+}
+/** `grounder help [topic…]` — full help or per-command. */
+export function runHelp(argv) {
+    if (argv.length === 0 || wantsHelp(argv)) {
+        printFullHelp();
+        return 0;
+    }
+    const meta = resolveCommandHelp(argv);
+    if (!meta) {
+        process.stderr.write(`Unknown help topic: ${argv.join(" ")}\n`);
+        process.stderr.write("Run `grounder --help` for a list of commands.\n");
+        return 1;
+    }
+    printCommandHelp(meta);
+    return 0;
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAoB5D,MAAM,WAAW,GAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAErF,MAAM,UAAU,GAAG;;;;;;;qBAOE,CAAC;AAEtB;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAA2B;IAC9C;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,sBAAsB;QAC/B,SAAS,EAAE,mBAAmB;QAC9B,KAAK,EAAE,uEAAuE;QAC9E,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;iEACsD;KAC9D;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,mDAAmD;QAC5D,SAAS,EAAE,mBAAmB;QAC9B,KAAK,EAAE,uEAAuE;QAC9E,KAAK,EAAE;;;;;yDAK8C;KACtD;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,wCAAwC;QACjD,SAAS,EAAE,MAAM;QACjB,KAAK,EAAE,8DAA8D;QACrE,KAAK,EAAE;;;;uDAI4C;KACpD;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,2BAA2B;QACpC,SAAS,EAAE,aAAa;QACxB,KAAK,EAAE,uCAAuC;QAC9C,KAAK,EAAE;wEAC6D;KACrE;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,wCAAwC;QACjD,SAAS,EAAE,gBAAgB;QAC3B,KAAK,EAAE,0CAA0C;QACjD,KAAK,EAAE;;;;;gEAKqD;KAC7D;IACD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,2CAA2C;QACpD,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,8CAA8C;QACrD,KAAK,EAAE;;;yEAG8D;KACtE;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,8CAA8C;QACvD,SAAS,EAAE,aAAa;QACxB,KAAK,EAAE,iEAAiE;QACxE,KAAK,EAAE;;;;;;;;qDAQ0C;KAClD;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,wCAAwC;QACjD,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,kCAAkC;QACzC,KAAK,EAAE;+CACoC;KAC5C;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,gCAAgC;QACzC,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,qBAAqB;KAC7B;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,+BAA+B;QACxC,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,oBAAoB;KAC5B;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,gCAAgC;QACzC,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,qBAAqB;KAC7B;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,yDAAyD;QAClE,SAAS,EAAE,yBAAyB;QACpC,KAAK,EAAE,kCAAkC;QACzC,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;;;8CAGmC;KAC3C;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,qDAAqD;QAC9D,SAAS,EAAE,QAAQ;QACnB,KAAK,EAAE,iBAAiB;KACzB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,8BAA8B;QACvC,SAAS,EAAE,QAAQ;QACnB,KAAK,EAAE,4BAA4B;QACnC,KAAK,EAAE;2DACgD;KACxD;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,gDAAgD;QACzD,SAAS,EAAE,SAAS;QACpB,KAAK,EAAE,iEAAiE;QACxE,KAAK,EAAE;;;;;8DAKmD;KAC3D;IACD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,wDAAwD;QACjE,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,gCAAgC;QACvC,KAAK,EAAE;;yCAE8B;KACtC;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,0CAA0C;QACnD,SAAS,EAAE,kBAAkB;QAC7B,KAAK,EAAE,2BAA2B;QAClC,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;;;;;;;2BAOgB;KACxB;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,OAAO;IACP,YAAY;IACZ,MAAM;IACN,MAAM;IACN,SAAS;IACT,cAAc;IACd,cAAc;IACd,MAAM;IACN,WAAW;IACX,MAAM;IACN,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,MAAM;CACE,CAAC;AAEX,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAErD,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,CAAC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAkB;IACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,KAAK,IAAI,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;QAChD,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,IAAI,GAAG,GAAG,UAAU,IAAI,CAAC,KAAK,IAAI,CAAC;IACnC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,GAAG,IAAI,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,GAAG,IAAI,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,gBAAgB,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,SAAiB;IAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,mBAAmB,CAAC,CAAc;IACzC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QACZ,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,wBAAwB;IAC/B,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;EAErB,kBAAkB,EAAE;;;;;;;;;;EAUpB,UAAU;CACX,CAAC,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;EAErB,kBAAkB,EAAE;;;;;;;;EAQpB,wBAAwB,EAAE;;EAE1B,UAAU;CACX,CAAC,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,OAAO,CAAC,IAAc;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,aAAa,EAAE,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACxE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/util/fs.d.ts

@@ -1,4 +1,10 @@
 export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * True when `filePath` is present and executable (`X_OK`).
+ * On Windows, `X_OK` effectively degrades toward existence — callers should
+ * not oversell POSIX execute-bit semantics there.
+ */
+export declare function isExecutable(filePath: string): Promise<boolean>;
 /**
  * Creates a new markdown file under `dir`; never overwrites.
  * Tries `basename.md`, then `basename_02.md`, `_03`, … with `wx` (O_EXCL)

package/dist/util/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAIA,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAgBjB"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAIA,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOrE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAgBjB"}

package/dist/util/fs.js

@@ -1,4 +1,4 @@
-import { access, writeFile } from "node:fs/promises";
+import { access, constants, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { collisionSuffix } from "./timestamp-slug.js";
 export async function fileExists(filePath) {
@@ -10,6 +10,20 @@ export async function fileExists(filePath) {
         return false;
     }
 }
+/**
+ * True when `filePath` is present and executable (`X_OK`).
+ * On Windows, `X_OK` effectively degrades toward existence — callers should
+ * not oversell POSIX execute-bit semantics there.
+ */
+export async function isExecutable(filePath) {
+    try {
+        await access(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Creates a new markdown file under `dir`; never overwrites.
  * Tries `basename.md`, then `basename_02.md`, `_03`, … with `wx` (O_EXCL)

package/dist/util/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAW,EACX,QAAgB,EAChB,OAAe;IAEf,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/util/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAW,EACX,QAAgB,EAChB,OAAe;IAEf,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACrE,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/util/hash.d.ts

@@ -0,0 +1,3 @@
+/** SHA-256 of UTF-8 content, prefixed `sha256:` for ledger storage. */
+export declare function hashContent(content: string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/util/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/util/hash.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/util/hash.js

@@ -0,0 +1,6 @@
+import { createHash } from "node:crypto";
+/** SHA-256 of UTF-8 content, prefixed `sha256:` for ledger storage. */
+export function hashContent(content) {
+    return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+//# sourceMappingURL=hash.js.map

package/dist/util/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/util/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAChF,CAAC"}

package/dist/util/path.d.ts

@@ -7,4 +7,14 @@ export declare function expandHome(input: string): string;
  * Expand a leading `~`, then resolve to an absolute path (relative to `cwd` if given).
  */
 export declare function resolveUserPath(input: string, cwd?: string): string;
+/**
+ * True when `child` is inside `parent` (or equal), using lexical `path.resolve` only
+ * (does not follow symlinks). Rejects `..` escape and cross-root relatives.
+ */
+export declare function isPathInside(parent: string, child: string): boolean;
+/**
+ * True when `child`'s real path is strictly inside `parent` (symlinks followed).
+ * Returns `null` if either path cannot be resolved (e.g. missing).
+ */
+export declare function isRealPathInside(parent: string, child: string): Promise<boolean | null>;
 //# sourceMappingURL=path.d.ts.map

package/dist/util/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAElF"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAElF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAanE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAQ7F"}

package/dist/util/path.js

@@ -1,3 +1,4 @@
+import { realpath } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 /**
@@ -19,4 +20,34 @@ export function expandHome(input) {
 export function resolveUserPath(input, cwd = process.cwd()) {
     return path.resolve(cwd, expandHome(input));
 }
+/**
+ * True when `child` is inside `parent` (or equal), using lexical `path.resolve` only
+ * (does not follow symlinks). Rejects `..` escape and cross-root relatives.
+ */
+export function isPathInside(parent, child) {
+    const root = path.resolve(parent);
+    const target = path.resolve(child);
+    if (root === target) {
+        return true;
+    }
+    const relative = path.relative(root, target);
+    return (relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+/**
+ * True when `child`'s real path is strictly inside `parent` (symlinks followed).
+ * Returns `null` if either path cannot be resolved (e.g. missing).
+ */
+export async function isRealPathInside(parent, child) {
+    try {
+        const root = await realpath(parent);
+        const target = await realpath(child);
+        return root !== target && isPathInside(root, target);
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=path.js.map

package/dist/util/path.js.map

@@ -1 +1 @@
-{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACxE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACxE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,KAAa;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,CACL,QAAQ,KAAK,EAAE;QACf,QAAQ,KAAK,IAAI;QACjB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc,EAAE,KAAa;IAClE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO,IAAI,KAAK,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/util/plan-name.d.ts

@@ -0,0 +1,10 @@
+/** Generous cap for plan filenames — real plan names often exceed note/handoff's 20-char slug. */
+export declare const MAX_PLAN_NAME_LENGTH = 80;
+/**
+ * Sanitize a `--title` value into a filename-safe plan name.
+ * Trims, strips a trailing `.md` (case-insensitive), applies {@link sanitizeProjectId}
+ * character rules, and caps at {@link MAX_PLAN_NAME_LENGTH}.
+ * Returns `""` when the result is empty / unusable.
+ */
+export declare function sanitizePlanName(rawTitle: string): string;
+//# sourceMappingURL=plan-name.d.ts.map

package/dist/util/plan-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-name.d.ts","sourceRoot":"","sources":["../../src/util/plan-name.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOzD"}

package/dist/util/plan-name.js

@@ -0,0 +1,18 @@
+import { sanitizeProjectId } from "./project-id.js";
+/** Generous cap for plan filenames — real plan names often exceed note/handoff's 20-char slug. */
+export const MAX_PLAN_NAME_LENGTH = 80;
+/**
+ * Sanitize a `--title` value into a filename-safe plan name.
+ * Trims, strips a trailing `.md` (case-insensitive), applies {@link sanitizeProjectId}
+ * character rules, and caps at {@link MAX_PLAN_NAME_LENGTH}.
+ * Returns `""` when the result is empty / unusable.
+ */
+export function sanitizePlanName(rawTitle) {
+    const trimmed = rawTitle.trim().replace(/\.md$/i, "");
+    const sanitized = sanitizeProjectId(trimmed);
+    if (!sanitized) {
+        return "";
+    }
+    return sanitized.slice(0, MAX_PLAN_NAME_LENGTH).replace(/-+$/g, "");
+}
+//# sourceMappingURL=plan-name.js.map

package/dist/util/plan-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-name.js","sourceRoot":"","sources":["../../src/util/plan-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,kGAAkG;AAClG,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/util/semver.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compare npm-style `major.minor.patch` prefixes.
+ * Returns negative / zero / positive like `strcmp`, or `null` if either side
+ * lacks a leading `x.y.z` (prerelease/build suffixes after the triple are ignored).
+ */
+export declare function compareSemver(a: string, b: string): number | null;
+/** How the running package version relates to the last-recorded ledger version. */
+export type PackageVersionRelation = "match" | "ahead" | "behind" | "differs";
+export declare function packageVersionRelation(running: string, recorded: string): PackageVersionRelation;
+//# sourceMappingURL=semver.d.ts.map

package/dist/util/semver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.d.ts","sourceRoot":"","sources":["../../src/util/semver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBjE;AAED,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAUhG"}

package/dist/util/semver.js

@@ -0,0 +1,40 @@
+/**
+ * Compare npm-style `major.minor.patch` prefixes.
+ * Returns negative / zero / positive like `strcmp`, or `null` if either side
+ * lacks a leading `x.y.z` (prerelease/build suffixes after the triple are ignored).
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        if (!match) {
+            return null;
+        }
+        return [Number(match[1]), Number(match[2]), Number(match[3])];
+    };
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right) {
+        return null;
+    }
+    for (let i = 0; i < 3; i++) {
+        if (left[i] < right[i]) {
+            return -1;
+        }
+        if (left[i] > right[i]) {
+            return 1;
+        }
+    }
+    return 0;
+}
+export function packageVersionRelation(running, recorded) {
+    if (running === recorded) {
+        return "match";
+    }
+    const cmp = compareSemver(running, recorded);
+    if (cmp === null || cmp === 0) {
+        // Unparseable, or same x.y.z with different suffix/string form.
+        return "differs";
+    }
+    return cmp > 0 ? "ahead" : "behind";
+}
+//# sourceMappingURL=semver.js.map

package/dist/util/semver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.js","sourceRoot":"","sources":["../../src/util/semver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAmC,EAAE;QAC3D,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,CAAC,CAAC;QACZ,CAAC;QACD,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAKD,MAAM,UAAU,sBAAsB,CAAC,OAAe,EAAE,QAAgB;IACtE,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QAC9B,gEAAgE;QAChE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;AACtC,CAAC"}

package/dist/vault/layout.d.ts

@@ -10,4 +10,6 @@ export declare function projectDir(vaultRoot: string, projectId: string): string
 export declare function notesDir(vaultRoot: string, projectId: string): string;
 /** `<vault>/10-Projects/{projectId}/logs` — session handoffs. */
 export declare function logsDir(vaultRoot: string, projectId: string): string;
+/** `<vault>/10-Projects/{projectId}/plans` — named, updatable plan docs. */
+export declare function plansDir(vaultRoot: string, projectId: string): string;
 //# sourceMappingURL=layout.d.ts.map

package/dist/vault/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,yCAAyC;AACzC,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,yCAAyC;AACzC,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/vault/layout.js

@@ -19,4 +19,8 @@ export function notesDir(vaultRoot, projectId) {
 export function logsDir(vaultRoot, projectId) {
     return path.join(vaultRoot, PROJECTS_DIR, projectId, "logs");
 }
+/** `<vault>/10-Projects/{projectId}/plans` — named, updatable plan docs. */
+export function plansDir(vaultRoot, projectId) {
+    return path.join(vaultRoot, PROJECTS_DIR, projectId, "plans");
+}
 //# sourceMappingURL=layout.js.map

package/dist/vault/layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,SAAiB;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,OAAO,CAAC,SAAiB,EAAE,SAAiB;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,SAAiB;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,OAAO,CAAC,SAAiB,EAAE,SAAiB;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC"}