grounder 0.2.0 → 0.3.0

package/dist/commands/handoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/commands/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAgB3D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc;IAC7C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,qBAAqB,CAAC;QAC3B,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAuB;IACjE,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QACvC,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;YAC5D,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM;YACN,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/commands/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAgB3D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc;IAC7C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC/C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,qBAAqB,CAAC;QAC3B,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAuB;IACjE,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QACvC,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;YAC5D,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM;YACN,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,23 @@
+import { type AgentAdapter } from "../agents/index.js";
+export interface MigrateOptions {
+    force?: boolean;
+    hooks?: boolean;
+    dryRun?: boolean;
+    homeDir?: string;
+    /** Agent ids to migrate. Defaults to ledger keys, else auto-detect. */
+    agents?: string[];
+}
+/**
+ * Resolve which agents to migrate:
+ * 1. Explicit `--agent` ids (unknown ids still throw)
+ * 2. Else agents recorded in `~/.grounder/state.json` that this binary knows
+ * 3. Else auto-detect installed agents (legacy / pre-ledger)
+ *
+ * Ledger keys from a newer Grounder (agents this binary does not know) are
+ * skipped with a stderr warning — same forward-compat idea as schema hard-stops,
+ * but migrate can still refresh the agents it understands.
+ */
+export declare function resolveMigrateAgents(explicitIds: string[] | undefined, homeDir?: string): Promise<AgentAdapter[]>;
+export declare function runMigrate(argv: string[]): Promise<number>;
+export declare function runMigrateWithOptions(options?: MigrateOptions): Promise<number>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAA6B,MAAM,oBAAoB,CAAC;AAQlF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,EACjC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,EAAE,CAAC,CAmBzB;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAchE;AAED,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8DzF"}

package/dist/commands/migrate.js

@@ -0,0 +1,104 @@
+import { ALL_AGENTS, resolveAgents } from "../agents/index.js";
+import { readHomeConfig, withHomeDir } from "../connector/home.js";
+import { assertAgentSchemasSupported, readGrounderState, statePath } from "../connector/state.js";
+import { isUnsupportedSchemaError } from "../connector/unsupported-schema.js";
+import { helpExitCode } from "../help.js";
+import { flagBool, flagStrings, parseArgs } from "../util/parse-args.js";
+import { applyAgentInstalls } from "./apply-agent-installs.js";
+/**
+ * Resolve which agents to migrate:
+ * 1. Explicit `--agent` ids (unknown ids still throw)
+ * 2. Else agents recorded in `~/.grounder/state.json` that this binary knows
+ * 3. Else auto-detect installed agents (legacy / pre-ledger)
+ *
+ * Ledger keys from a newer Grounder (agents this binary does not know) are
+ * skipped with a stderr warning — same forward-compat idea as schema hard-stops,
+ * but migrate can still refresh the agents it understands.
+ */
+export async function resolveMigrateAgents(explicitIds, homeDir) {
+    if (explicitIds && explicitIds.length > 0) {
+        return resolveAgents(explicitIds);
+    }
+    const state = await readGrounderState(homeDir);
+    const recordedIds = state ? Object.keys(state.agents) : [];
+    if (recordedIds.length === 0) {
+        return resolveAgents();
+    }
+    const known = ALL_AGENTS.filter((a) => recordedIds.includes(a.id));
+    const unknown = recordedIds.filter((id) => !ALL_AGENTS.some((a) => a.id === id));
+    if (unknown.length > 0) {
+        process.stderr.write(`Skipping unknown agent(s) in install state: ${unknown.join(", ")}. Upgrade grounder to migrate them.\n`);
+    }
+    return known;
+}
+export async function runMigrate(argv) {
+    const helpCode = helpExitCode(argv, "migrate");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    const { flags, repeated } = parseArgs(argv);
+    const agents = flagStrings(repeated, "agent");
+    return runMigrateWithOptions({
+        force: flagBool(flags, "force", "f"),
+        hooks: flagBool(flags, "hooks"),
+        dryRun: flagBool(flags, "dry-run"),
+        agents: agents.length > 0 ? agents : undefined,
+    });
+}
+export async function runMigrateWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const homeDir = options.homeDir;
+        const force = options.force ?? false;
+        const hooks = options.hooks ?? false;
+        const dryRun = options.dryRun ?? false;
+        const home = await readHomeConfig();
+        if (!home) {
+            process.stderr.write("No home config found. Run `grounder vault init <path>` first.\n");
+            return 1;
+        }
+        const agents = await resolveMigrateAgents(options.agents, homeDir);
+        try {
+            const state = await readGrounderState(homeDir);
+            assertAgentSchemasSupported(state, agents);
+        }
+        catch (error) {
+            if (isUnsupportedSchemaError(error)) {
+                process.stderr.write(`${error.message}\n`);
+                return 1;
+            }
+            throw error;
+        }
+        process.stdout.write(`Vault root: ${home.vaultRoot}\n`);
+        if (dryRun) {
+            process.stdout.write("Dry run — no files will be written.\n");
+        }
+        process.stdout.write("Will refresh:\n");
+        if (agents.length === 0) {
+            process.stdout.write("  (no agents recorded or detected)\n");
+        }
+        else {
+            for (const agent of agents) {
+                for (const artifactPath of agent.expectedArtifacts(homeDir)) {
+                    process.stdout.write(`  ${agent.id.padEnd(8)} ${artifactPath}\n`);
+                }
+            }
+            process.stdout.write("  hooks    previously installed or --hooks (owned JSON always refreshed)\n");
+            process.stdout.write(`  state    ${statePath(homeDir)}\n`);
+        }
+        process.stdout.write("\n");
+        if (agents.length === 0) {
+            process.stdout.write("Nothing to migrate.\n");
+            return 0;
+        }
+        await applyAgentInstalls({
+            agents,
+            force,
+            hooks,
+            refreshInstalledHooks: true,
+            dryRun,
+            homeDir,
+        });
+        return 0;
+    });
+}
+//# sourceMappingURL=migrate.js.map

package/dist/commands/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAW/D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,WAAiC,EACjC,OAAgB;IAEhB,IAAI,WAAW,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,aAAa,CAAC,WAAW,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+CAA+C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,uCAAuC,CACzG,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc;IAC7C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC/C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,qBAAqB,CAAC;QAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC;QACpC,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAC/B,MAAM,EAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;QAClC,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;KAC/C,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,UAA0B,EAAE;IACtE,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;QACrC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;QAEvC,MAAM,IAAI,GAAG,MAAM,cAAc,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iEAAiE,CAAC,CAAC;YACxF,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAEnE,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;YAC/C,2BAA2B,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,wBAAwB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;gBAC3C,OAAO,CAAC,CAAC;YACX,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;QACxD,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACxC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,KAAK,MAAM,YAAY,IAAI,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC5D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,YAAY,IAAI,CAAC,CAAC;gBACpE,CAAC;YACH,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4EAA4E,CAC7E,CAAC;YACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE3B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;YAC9C,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,kBAAkB,CAAC;YACvB,MAAM;YACN,KAAK;YACL,KAAK;YACL,qBAAqB,EAAE,IAAI;YAC3B,MAAM;YACN,OAAO;SACR,CAAC,CAAC;QAEH,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/note.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAa7D;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB9E"}
+{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB7D;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB9E"}

package/dist/commands/note.js

@@ -1,9 +1,14 @@
 import { withHomeDir } from "../connector/home.js";
 import { resolveNotesDir } from "../connector/vault.js";
+import { helpExitCode } from "../help.js";
 import { flagString, parseArgs } from "../util/parse-args.js";
 import { writeNote } from "../vault/write-note.js";
 import { requireLinkedProject } from "./require-linked.js";
 export async function runNote(argv) {
+    const helpCode = helpExitCode(argv, "note");
+    if (helpCode !== null) {
+        return helpCode;
+    }
     const { positional, flags } = parseArgs(argv);
     const text = positional.join(" ").trim();
     if (!text) {

package/dist/commands/note.js.map

@@ -1 +1 @@
-{"version":3,"file":"note.js","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAU3D,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAc;IAC1C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,kBAAkB,CAAC;QACxB,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAoB;IAC3D,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE;YAC1D,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"note.js","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAU3D,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAc;IAC1C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,kBAAkB,CAAC;QACxB,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAoB;IAC3D,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE;YAC1D,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/package-version-notice.d.ts

@@ -0,0 +1,18 @@
+import { type PackageVersionRelation } from "../util/semver.js";
+export interface PackageVersionNotice {
+    relation: Exclude<PackageVersionRelation, "match">;
+    /** Doctor check message (plain language; versions in parentheses). */
+    message: string;
+    /** Suggested fix action. */
+    fix: string;
+    /** One-line stderr banner (includes trailing newlines). */
+    banner: string;
+    /** `grounder status` value after the Package: label. */
+    status: string;
+}
+/**
+ * Plain-language notice when the running Grounder and the version recorded for
+ * this machine's configuration disagree.
+ */
+export declare function packageVersionNotice(running: string, recorded: string): PackageVersionNotice | null;
+//# sourceMappingURL=package-version-notice.d.ts.map

package/dist/commands/package-version-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version-notice.d.ts","sourceRoot":"","sources":["../../src/commands/package-version-notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,sBAAsB,EAA0B,MAAM,mBAAmB,CAAC;AAKxF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;IACnD,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,oBAAoB,GAAG,IAAI,CAiC7B"}

package/dist/commands/package-version-notice.js

@@ -0,0 +1,39 @@
+import { packageVersionRelation } from "../util/semver.js";
+const MIGRATE = "grounder migrate";
+const UPGRADE = "install a newer Grounder";
+/**
+ * Plain-language notice when the running Grounder and the version recorded for
+ * this machine's configuration disagree.
+ */
+export function packageVersionNotice(running, recorded) {
+    const relation = packageVersionRelation(running, recorded);
+    if (relation === "match") {
+        return null;
+    }
+    if (relation === "ahead") {
+        return {
+            relation,
+            message: `Grounder ${running} is installed, but your configuration is still from ${recorded}`,
+            fix: MIGRATE,
+            banner: `Grounder was updated (${running}). Run \`${MIGRATE}\` to update your configuration.\n\n`,
+            status: `configuration outdated — run: ${MIGRATE}`,
+        };
+    }
+    if (relation === "behind") {
+        return {
+            relation,
+            message: `this Grounder (${running}) is older than your configuration (${recorded})`,
+            fix: UPGRADE,
+            banner: `This Grounder (${running}) is older than your configuration (${recorded}). Install a newer Grounder.\n\n`,
+            status: `older than configuration — ${UPGRADE}`,
+        };
+    }
+    return {
+        relation: "differs",
+        message: `Grounder version (${running}) doesn't match your configuration (${recorded})`,
+        fix: MIGRATE,
+        banner: `Grounder version doesn't match your configuration. Run \`${MIGRATE}\`.\n\n`,
+        status: `doesn't match configuration — run: ${MIGRATE}`,
+    };
+}
+//# sourceMappingURL=package-version-notice.js.map

package/dist/commands/package-version-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version-notice.js","sourceRoot":"","sources":["../../src/commands/package-version-notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAExF,MAAM,OAAO,GAAG,kBAAkB,CAAC;AACnC,MAAM,OAAO,GAAG,0BAA0B,CAAC;AAc3C;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,QAAgB;IAEhB,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3D,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO;YACL,QAAQ;YACR,OAAO,EAAE,YAAY,OAAO,uDAAuD,QAAQ,EAAE;YAC7F,GAAG,EAAE,OAAO;YACZ,MAAM,EAAE,yBAAyB,OAAO,YAAY,OAAO,sCAAsC;YACjG,MAAM,EAAE,iCAAiC,OAAO,EAAE;SACnD,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO;YACL,QAAQ;YACR,OAAO,EAAE,kBAAkB,OAAO,uCAAuC,QAAQ,GAAG;YACpF,GAAG,EAAE,OAAO;YACZ,MAAM,EAAE,kBAAkB,OAAO,uCAAuC,QAAQ,kCAAkC;YAClH,MAAM,EAAE,8BAA8B,OAAO,EAAE;SAChD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,SAAS;QACnB,OAAO,EAAE,qBAAqB,OAAO,uCAAuC,QAAQ,GAAG;QACvF,GAAG,EAAE,OAAO;QACZ,MAAM,EAAE,4DAA4D,OAAO,SAAS;QACpF,MAAM,EAAE,sCAAsC,OAAO,EAAE;KACxD,CAAC;AACJ,CAAC"}

package/dist/commands/path/logs.d.ts

@@ -2,6 +2,6 @@ export interface PathLogsOptions {
     cwd?: string;
     homeDir?: string;
 }
-export declare function runPathLogs(_argv: string[]): Promise<number>;
+export declare function runPathLogs(argv: string[]): Promise<number>;
 export declare function runPathLogsWithOptions(options?: PathLogsOptions): Promise<number>;
 //# sourceMappingURL=logs.d.ts.map

package/dist/commands/path/logs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../../src/commands/path/logs.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAElE;AAED,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAU3F"}
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../../src/commands/path/logs.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOjE;AAED,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAU3F"}

package/dist/commands/path/logs.js

@@ -1,7 +1,12 @@
 import { withHomeDir } from "../../connector/home.js";
 import { resolveLogsDir } from "../../connector/vault.js";
+import { helpExitCode } from "../../help.js";
 import { requireLinkedProject } from "../require-linked.js";
-export async function runPathLogs(_argv) {
+export async function runPathLogs(argv) {
+    const helpCode = helpExitCode(argv, "path logs");
+    if (helpCode !== null) {
+        return helpCode;
+    }
     return runPathLogsWithOptions({});
 }
 export async function runPathLogsWithOptions(options = {}) {

package/dist/commands/path/logs.js.map

@@ -1 +1 @@
-{"version":3,"file":"logs.js","sourceRoot":"","sources":["../../../src/commands/path/logs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAO5D,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAe;IAC/C,OAAO,sBAAsB,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,UAA2B,EAAE;IACxE,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"logs.js","sourceRoot":"","sources":["../../../src/commands/path/logs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAO5D,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAc;IAC9C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACjD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,sBAAsB,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,UAA2B,EAAE;IACxE,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/path/notes.d.ts

@@ -2,6 +2,6 @@ export interface PathNotesOptions {
     cwd?: string;
     homeDir?: string;
 }
-export declare function runPathNotes(_argv: string[]): Promise<number>;
+export declare function runPathNotes(argv: string[]): Promise<number>;
 export declare function runPathNotesWithOptions(options?: PathNotesOptions): Promise<number>;
 //# sourceMappingURL=notes.d.ts.map

package/dist/commands/path/notes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../../src/commands/path/notes.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAED,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAU7F"}
+{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../../src/commands/path/notes.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOlE;AAED,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAU7F"}

package/dist/commands/path/notes.js

@@ -1,7 +1,12 @@
 import { withHomeDir } from "../../connector/home.js";
 import { resolveNotesDir } from "../../connector/vault.js";
+import { helpExitCode } from "../../help.js";
 import { requireLinkedProject } from "../require-linked.js";
-export async function runPathNotes(_argv) {
+export async function runPathNotes(argv) {
+    const helpCode = helpExitCode(argv, "path notes");
+    if (helpCode !== null) {
+        return helpCode;
+    }
     return runPathNotesWithOptions({});
 }
 export async function runPathNotesWithOptions(options = {}) {

package/dist/commands/path/notes.js.map

@@ -1 +1 @@
-{"version":3,"file":"notes.js","sourceRoot":"","sources":["../../../src/commands/path/notes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAO5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAe;IAChD,OAAO,uBAAuB,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,UAA4B,EAAE;IAC1E,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"notes.js","sourceRoot":"","sources":["../../../src/commands/path/notes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAO5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAc;IAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAClD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,uBAAuB,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,UAA4B,EAAE;IAC1E,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/path/plans.d.ts

@@ -0,0 +1,7 @@
+export interface PathPlansOptions {
+    cwd?: string;
+    homeDir?: string;
+}
+export declare function runPathPlans(argv: string[]): Promise<number>;
+export declare function runPathPlansWithOptions(options?: PathPlansOptions): Promise<number>;
+//# sourceMappingURL=plans.d.ts.map

package/dist/commands/path/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../../../src/commands/path/plans.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOlE;AAED,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAU7F"}

package/dist/commands/path/plans.js

@@ -0,0 +1,22 @@
+import { withHomeDir } from "../../connector/home.js";
+import { resolvePlansDir } from "../../connector/vault.js";
+import { helpExitCode } from "../../help.js";
+import { requireLinkedProject } from "../require-linked.js";
+export async function runPathPlans(argv) {
+    const helpCode = helpExitCode(argv, "path plans");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    return runPathPlansWithOptions({});
+}
+export async function runPathPlansWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const linked = await requireLinkedProject(options.cwd ?? process.cwd());
+        if (!linked) {
+            return 1;
+        }
+        process.stdout.write(`${resolvePlansDir(linked.home, linked.repo)}\n`);
+        return 0;
+    });
+}
+//# sourceMappingURL=plans.js.map

package/dist/commands/path/plans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.js","sourceRoot":"","sources":["../../../src/commands/path/plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAO5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAc;IAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAClD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,uBAAuB,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,UAA4B,EAAE;IAC1E,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/plan/list.d.ts

@@ -0,0 +1,23 @@
+/** Options for {@link runPlanListWithOptions} (CLI parsing and tests). */
+export interface PlanListOptions {
+    /** Directory used to find the linked repo (default: `process.cwd()`). */
+    cwd?: string;
+    /** Max paths to print, newest first (default: 5). */
+    limit?: number;
+    /** Override home dir / `GROUNDER_HOME` (tests). */
+    homeDir?: string;
+}
+/**
+ * CLI entry for `grounder plan list [--limit <n>]`.
+ * `--limit` must be a positive integer when provided.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export declare function runPlanList(argv: string[]): Promise<number>;
+/**
+ * Resolves the linked project, lists recent plan paths under `plans/` (newest first).
+ * Prints one absolute path per line; empty when no plans. Same vault/link
+ * prerequisites as `grounder plan`.
+ * @returns Exit code (`0` on success, `1` when vault/link is missing).
+ */
+export declare function runPlanListWithOptions(options?: PlanListOptions): Promise<number>;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/plan/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/plan/list.ts"],"names":[],"mappings":"AASA,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCjE;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB3F"}

package/dist/commands/plan/list.js

@@ -0,0 +1,69 @@
+import { withHomeDir } from "../../connector/home.js";
+import { resolvePlansDir } from "../../connector/vault.js";
+import { helpExitCode } from "../../help.js";
+import { parseArgs } from "../../util/parse-args.js";
+import { listPlans } from "../../vault/list-plans.js";
+import { requireLinkedProject } from "../require-linked.js";
+const DEFAULT_LIMIT = 5;
+const USAGE = "Usage: grounder plan list [--limit <n>]\n";
+function usageError() {
+    process.stderr.write(USAGE);
+    return 1;
+}
+/**
+ * CLI entry for `grounder plan list [--limit <n>]`.
+ * `--limit` must be a positive integer when provided.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export async function runPlanList(argv) {
+    const helpCode = helpExitCode(argv, "plan list");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    const { positional, flags } = parseArgs(argv);
+    if (positional.length > 0) {
+        return usageError();
+    }
+    for (const key of flags.keys()) {
+        if (key !== "limit") {
+            return usageError();
+        }
+    }
+    const limitRaw = flags.get("limit");
+    let limit = DEFAULT_LIMIT;
+    if (limitRaw !== undefined) {
+        if (typeof limitRaw !== "string") {
+            return usageError();
+        }
+        const trimmed = limitRaw.trim();
+        const parsed = Number.parseInt(trimmed, 10);
+        if (!/^\d+$/.test(trimmed) || Number.isNaN(parsed) || parsed < 1) {
+            return usageError();
+        }
+        limit = parsed;
+    }
+    return runPlanListWithOptions({ limit });
+}
+/**
+ * Resolves the linked project, lists recent plan paths under `plans/` (newest first).
+ * Prints one absolute path per line; empty when no plans. Same vault/link
+ * prerequisites as `grounder plan`.
+ * @returns Exit code (`0` on success, `1` when vault/link is missing).
+ */
+export async function runPlanListWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const linked = await requireLinkedProject(options.cwd ?? process.cwd());
+        if (!linked) {
+            return 1;
+        }
+        const plansDir = resolvePlansDir(linked.home, linked.repo);
+        const paths = await listPlans(plansDir, {
+            limit: options.limit ?? DEFAULT_LIMIT,
+        });
+        for (const filePath of paths) {
+            process.stdout.write(`${filePath}\n`);
+        }
+        return 0;
+    });
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/plan/list.js.map

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

package/dist/commands/plan.d.ts

@@ -0,0 +1,34 @@
+/** Options for {@link runPlanWithOptions} (CLI parsing and tests). */
+export interface PlanOptions {
+    /** Directory used to find the linked repo (default: `process.cwd()`). */
+    cwd?: string;
+    /** Markdown body stored under the project `plans/` folder. */
+    text: string;
+    /** Required filename stem (`--title`); sanitized via {@link sanitizePlanName}. */
+    title?: string;
+    /**
+     * Absolute or relative path to an existing plan file (`--path`).
+     * Mutually exclusive with `--title`. Updates in place (no sanitization).
+     */
+    planPath?: string;
+    /** When true, overwrite an existing plan (preserving original `created`). */
+    force?: boolean;
+    /** Override home dir / `GROUNDER_HOME` (tests). */
+    homeDir?: string;
+    /** Fixed clock for deterministic `created` / `updated` (tests). */
+    now?: Date;
+}
+/**
+ * CLI entry for `grounder plan <text> (--title <name> [--force] | --path <file>)`.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export declare function runPlan(argv: string[]): Promise<number>;
+/**
+ * Resolves the linked project, writes/updates a named plan under `plans/`.
+ * Prints `Wrote <path>` on create, `Updated <path>` on overwrite.
+ * Without `--force`, an existing title-addressed plan prints a conflict hint and exits 1.
+ * With `--path`, updates an existing file in place (must resolve under this project's `plans/`).
+ * @returns Exit code (`0` on success, `1` on usage/conflict/link errors).
+ */
+export declare function runPlanWithOptions(options: PlanOptions): Promise<number>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/commands/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"AAeA,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB7D;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C9E"}

package/dist/commands/plan.js

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { withHomeDir } from "../connector/home.js";
+import { resolvePlansDir } from "../connector/vault.js";
+import { helpExitCode } from "../help.js";
+import { fileExists } from "../util/fs.js";
+import { flagBool, flagString, parseArgs } from "../util/parse-args.js";
+import { isPathInside, isRealPathInside, resolveUserPath } from "../util/path.js";
+import { sanitizePlanName } from "../util/plan-name.js";
+import { updatePlanAtPath, writePlan } from "../vault/write-plan.js";
+import { requireLinkedProject } from "./require-linked.js";
+const USAGE = "Usage: grounder plan <text> --title <name> [--force]\n" +
+    "   or: grounder plan <text> --path <file>";
+/**
+ * CLI entry for `grounder plan <text> (--title <name> [--force] | --path <file>)`.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export async function runPlan(argv) {
+    const helpCode = helpExitCode(argv, "plan");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    const { positional, flags } = parseArgs(argv);
+    const text = positional.join(" ").trim();
+    if (!text) {
+        process.stderr.write(`${USAGE}\n`);
+        return 1;
+    }
+    return runPlanWithOptions({
+        text,
+        title: flagString(flags, "title"),
+        planPath: flagString(flags, "path"),
+        force: flagBool(flags, "force"),
+    });
+}
+/**
+ * Resolves the linked project, writes/updates a named plan under `plans/`.
+ * Prints `Wrote <path>` on create, `Updated <path>` on overwrite.
+ * Without `--force`, an existing title-addressed plan prints a conflict hint and exits 1.
+ * With `--path`, updates an existing file in place (must resolve under this project's `plans/`).
+ * @returns Exit code (`0` on success, `1` on usage/conflict/link errors).
+ */
+export async function runPlanWithOptions(options) {
+    const hasTitle = options.title !== undefined;
+    const hasPath = options.planPath !== undefined;
+    if (hasTitle && hasPath) {
+        process.stderr.write("Use either --title or --path, not both.\n");
+        return 1;
+    }
+    if (!hasTitle && !hasPath) {
+        process.stderr.write(`${USAGE}\n`);
+        return 1;
+    }
+    if (hasPath && options.force) {
+        process.stderr.write("--force is not used with --path (path updates always overwrite).\n");
+        return 1;
+    }
+    const sanitizedTitle = hasTitle ? sanitizePlanName(options.title ?? "") : undefined;
+    if (hasTitle && !sanitizedTitle) {
+        process.stderr.write(`${USAGE}\n`);
+        return 1;
+    }
+    return withHomeDir(options.homeDir, async () => {
+        const linked = await requireLinkedProject(options.cwd ?? process.cwd());
+        if (!linked) {
+            return 1;
+        }
+        const plansDir = resolvePlansDir(linked.home, linked.repo);
+        if (hasPath) {
+            return updateByPath(plansDir, linked.repo.projectId, options);
+        }
+        if (!sanitizedTitle) {
+            process.stderr.write(`${USAGE}\n`);
+            return 1;
+        }
+        return writeByTitle(plansDir, linked.repo.projectId, sanitizedTitle, options);
+    });
+}
+async function writeByTitle(plansDir, projectId, name, options) {
+    const result = await writePlan(plansDir, name, options.text, {
+        projectId,
+        force: options.force,
+        now: options.now,
+    });
+    if (result.status === "exists") {
+        process.stderr.write(`Plan already exists: ${result.path}\nUse --force to overwrite.\n`);
+        return 1;
+    }
+    const verb = result.status === "overwritten" ? "Updated" : "Wrote";
+    process.stdout.write(`${verb} ${result.path}\n`);
+    return 0;
+}
+async function updateByPath(plansDir, projectId, options) {
+    const raw = options.planPath ?? "";
+    const cwd = options.cwd ?? process.cwd();
+    const filePath = resolveUserPath(raw, cwd);
+    if (!filePath.toLowerCase().endsWith(".md")) {
+        process.stderr.write(`Plan path must be a .md file under plans/: ${filePath}\n`);
+        return 1;
+    }
+    if (!isPathInside(plansDir, filePath) || path.resolve(filePath) === path.resolve(plansDir)) {
+        process.stderr.write(`Plan path must resolve inside this project's plans directory:\n  ${plansDir}\nGot: ${filePath}\n`);
+        return 1;
+    }
+    if (!(await fileExists(filePath))) {
+        process.stderr.write(`Plan not found: ${filePath}\n`);
+        return 1;
+    }
+    // Check follows symlinks; write would too — refuse links that land outside plans/.
+    const realInside = await isRealPathInside(plansDir, filePath);
+    if (realInside !== true) {
+        process.stderr.write(`Plan path must resolve inside this project's plans directory:\n  ${plansDir}\nGot: ${filePath}\n`);
+        return 1;
+    }
+    const result = await updatePlanAtPath(filePath, options.text, {
+        projectId,
+        now: options.now,
+    });
+    process.stdout.write(`Updated ${result.path}\n`);
+    return 0;
+}
+//# sourceMappingURL=plan.js.map