grounder 0.2.0 → 0.3.0

package/dist/connector/state.js

@@ -0,0 +1,189 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileExists } from "../util/fs.js";
+import { resolveHomeDir } from "./home.js";
+import { UnsupportedSchemaError } from "./unsupported-schema.js";
+export function statePath(homeDir) {
+    return path.join(resolveHomeDir(homeDir), ".grounder", "state.json");
+}
+/**
+ * Read `~/.grounder/state.json`. Missing file → `null` (legacy / pre-ledger
+ * install — callers should treat missing agent entries as schema 0).
+ */
+export async function readGrounderState(homeDir) {
+    const filePath = statePath(homeDir);
+    if (!(await fileExists(filePath))) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid grounder state at ${filePath}: ${detail}. Fix or remove it, then run: grounder migrate --force`);
+    }
+    if (typeof raw.grounderVersion !== "string" || raw.grounderVersion.length === 0) {
+        throw new Error(`Invalid grounder state at ${filePath}: missing grounderVersion. Fix or remove it, then run: grounder migrate --force`);
+    }
+    if (raw.agents === null || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+        throw new Error(`Invalid grounder state at ${filePath}: missing agents`);
+    }
+    const agents = {};
+    for (const [id, entry] of Object.entries(raw.agents)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(`Invalid grounder state at ${filePath}: bad agent entry "${id}"`);
+        }
+        const commandsSchema = entry.commandsSchema;
+        if (typeof commandsSchema !== "number" || !Number.isInteger(commandsSchema)) {
+            throw new Error(`Invalid grounder state at ${filePath}: agent "${id}" missing commandsSchema`);
+        }
+        const hooksSchema = entry.hooksSchema;
+        if (hooksSchema !== undefined &&
+            (typeof hooksSchema !== "number" || !Number.isInteger(hooksSchema))) {
+            throw new Error(`Invalid grounder state at ${filePath}: agent "${id}" has invalid hooksSchema`);
+        }
+        const filesRaw = entry.files;
+        const files = filesRaw && typeof filesRaw === "object" && !Array.isArray(filesRaw) ? { ...filesRaw } : {};
+        agents[id] = {
+            commandsSchema,
+            ...(hooksSchema !== undefined ? { hooksSchema } : {}),
+            files,
+        };
+    }
+    return { grounderVersion: raw.grounderVersion, agents };
+}
+export async function writeGrounderState(state, homeDir) {
+    const filePath = statePath(homeDir);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+/** Recorded commands schema for an agent, or `0` when missing (legacy). */
+export function recordedCommandsSchema(state, agentId) {
+    return state?.agents[agentId]?.commandsSchema ?? 0;
+}
+/** Hooks version stored for an agent, or `0` if missing (never stored / never installed). */
+export function recordedHooksSchema(state, agentId) {
+    return state?.agents[agentId]?.hooksSchema ?? 0;
+}
+/**
+ * Merge one agent's install info into `~/.grounder/state.json`. Creates the
+ * file when missing. Keeps other agents and merges any provided `files` over
+ * this agent's existing map.
+ */
+export async function recordAgentInstall(opts) {
+    const existing = await readGrounderState(opts.homeDir);
+    const prev = existing?.agents[opts.agentId];
+    const nextEntry = {
+        commandsSchema: opts.commandsSchema !== undefined ? opts.commandsSchema : (prev?.commandsSchema ?? 0),
+        files: {
+            ...(prev?.files ? { ...prev.files } : {}),
+            ...(opts.files ?? {}),
+        },
+    };
+    if (opts.hooksSchema !== undefined) {
+        nextEntry.hooksSchema = opts.hooksSchema;
+    }
+    else if (prev?.hooksSchema !== undefined) {
+        nextEntry.hooksSchema = prev.hooksSchema;
+    }
+    const next = {
+        grounderVersion: opts.grounderVersion,
+        agents: {
+            ...(existing?.agents ?? {}),
+            [opts.agentId]: nextEntry,
+        },
+    };
+    await writeGrounderState(next, opts.homeDir);
+    return next;
+}
+/**
+ * True when `state.json` says this machine's install is behind what this
+ * Grounder version expects. Used by peek/status — they only read `state.json`,
+ * they do not look at Cursor/Claude files on disk.
+ *
+ * If there is no state file, returns false (callers handle that separately).
+ * Only agents listed in state are checked.
+ *
+ * Session hooks: if an agent has no `hooksSchema` in state, that means hooks
+ * were never turned on for them. That is not "behind" — otherwise peek would
+ * keep telling people who never enabled hooks to run migrate. When hooks
+ * actually exist on disk, doctor uses {@link isHooksSchemaBehind} instead.
+ */
+export function isInstallSchemaStale(state, agents) {
+    if (!state) {
+        return false;
+    }
+    for (const agent of agents) {
+        const entry = state.agents[agent.id];
+        if (!entry) {
+            continue;
+        }
+        if (entry.commandsSchema < agent.commandsSchema) {
+            return true;
+        }
+        if (agent.hooksSchema !== undefined &&
+            entry.hooksSchema !== undefined &&
+            entry.hooksSchema < agent.hooksSchema) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * True when session-hook install info is behind what this Grounder expects.
+ * Call only after you already know Grounder hooks exist on disk (doctor).
+ *
+ * If state never stored a hooks version, treat that as version 0 so older
+ * hook installs still get a migrate hint. Peek/status must not use this —
+ * use {@link isInstallSchemaStale}, which leaves "hooks never enabled" alone.
+ */
+export function isHooksSchemaBehind(recorded, expected) {
+    if (expected === undefined) {
+        return false;
+    }
+    return (recorded ?? 0) < expected;
+}
+/**
+ * True when state says hooks are newer than this Grounder understands.
+ * No stored hooks version is not "newer".
+ */
+export function isHooksSchemaAhead(recorded, expected) {
+    if (expected === undefined || recorded === undefined) {
+        return false;
+    }
+    return recorded > expected;
+}
+/** Last-recorded content hash for a managed file, or `undefined` if unknown. */
+export function recordedFileHash(state, agentId, filePath) {
+    return state?.agents[agentId]?.files[filePath]?.hash;
+}
+/**
+ * Hard stop when `state.json` has install versions newer than this Grounder
+ * understands. Missing state or unknown agents are fine (older installs).
+ */
+export function assertAgentSchemasSupported(state, agents) {
+    if (!state) {
+        return;
+    }
+    for (const agent of agents) {
+        const recorded = state.agents[agent.id];
+        if (!recorded) {
+            continue;
+        }
+        if (recorded.commandsSchema > agent.commandsSchema) {
+            throw new UnsupportedSchemaError(`${agent.name} commands schema ${recorded.commandsSchema} is newer than this grounder supports (${agent.commandsSchema}). Upgrade grounder.`);
+        }
+        if (recorded.hooksSchema !== undefined &&
+            agent.hooksSchema !== undefined &&
+            recorded.hooksSchema > agent.hooksSchema) {
+            throw new UnsupportedSchemaError(`${agent.name} hooks schema ${recorded.hooksSchema} is newer than this grounder supports (${agent.hooksSchema}). Upgrade grounder.`);
+        }
+        for (const [filePath, file] of Object.entries(recorded.files)) {
+            if (typeof file?.schema === "number" && file.schema > agent.commandsSchema) {
+                throw new UnsupportedSchemaError(`${agent.name} file ${filePath} schema ${file.schema} is newer than this grounder supports (${agent.commandsSchema}). Upgrade grounder.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/connector/state.js.map

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

package/dist/connector/unsupported-schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * On-disk schema/version is newer than this binary understands (git-style hard
+ * stop). Distinct from corrupt data — fix is upgrade grounder, not reinit.
+ */
+export declare class UnsupportedSchemaError extends Error {
+    constructor(message: string);
+}
+export declare function isUnsupportedSchemaError(error: unknown): error is UnsupportedSchemaError;
+//# sourceMappingURL=unsupported-schema.d.ts.map

package/dist/connector/unsupported-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported-schema.d.ts","sourceRoot":"","sources":["../../src/connector/unsupported-schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAExF"}

package/dist/connector/unsupported-schema.js

@@ -0,0 +1,14 @@
+/**
+ * On-disk schema/version is newer than this binary understands (git-style hard
+ * stop). Distinct from corrupt data — fix is upgrade grounder, not reinit.
+ */
+export class UnsupportedSchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedSchemaError";
+    }
+}
+export function isUnsupportedSchemaError(error) {
+    return error instanceof UnsupportedSchemaError;
+}
+//# sourceMappingURL=unsupported-schema.js.map

package/dist/connector/unsupported-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported-schema.js","sourceRoot":"","sources":["../../src/connector/unsupported-schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,KAAK,YAAY,sBAAsB,CAAC;AACjD,CAAC"}

package/dist/connector/vault.d.ts

@@ -9,4 +9,6 @@ export declare function resolveVaultRoot(home: HomeConfig, override?: string): s
 export declare function resolveNotesDir(home: HomeConfig, repo: RepoConfig, vaultOverride?: string): string;
 /** Project logs (handoff) directory under the effective vault root. */
 export declare function resolveLogsDir(home: HomeConfig, repo: RepoConfig, vaultOverride?: string): string;
+/** Project plans directory under the effective vault root. */
+export declare function resolvePlansDir(home: HomeConfig, repo: RepoConfig, vaultOverride?: string): string;
 //# sourceMappingURL=vault.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/connector/vault.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5E;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAGR;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjG"}
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/connector/vault.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5E;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAGR;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjG;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAGR"}

package/dist/connector/vault.js

@@ -1,6 +1,6 @@
 // Config-aware vault resolution: effective vault root and artifact paths from connector state.
 import { resolveUserPath } from "../util/path.js";
-import { logsDir, notesDir } from "../vault/layout.js";
+import { logsDir, notesDir, plansDir } from "../vault/layout.js";
 /**
  * Effective vault root, in order: explicit `override`, `GROUNDER_VAULT`, then home config.
  * Expands a leading `~` so vault paths like `~/Documents/…` resolve to the user home.
@@ -24,4 +24,9 @@ export function resolveLogsDir(home, repo, vaultOverride) {
     const vaultRoot = resolveVaultRoot(home, vaultOverride);
     return logsDir(vaultRoot, repo.projectId);
 }
+/** Project plans directory under the effective vault root. */
+export function resolvePlansDir(home, repo, vaultOverride) {
+    const vaultRoot = resolveVaultRoot(home, vaultOverride);
+    return plansDir(vaultRoot, repo.projectId);
+}
 //# sourceMappingURL=vault.js.map

package/dist/connector/vault.js.map

@@ -1 +1 @@
-{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../src/connector/vault.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAIvD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,QAAiB;IAClE,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;QAC/B,OAAO,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAC7B,IAAgB,EAChB,IAAgB,EAChB,aAAsB;IAEtB,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACxD,OAAO,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AAC7C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,IAAgB,EAAE,IAAgB,EAAE,aAAsB;IACvF,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACxD,OAAO,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../src/connector/vault.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAIjE;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,QAAiB;IAClE,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;QAC/B,OAAO,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAC7B,IAAgB,EAChB,IAAgB,EAChB,aAAsB;IAEtB,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACxD,OAAO,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AAC7C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,IAAgB,EAAE,IAAgB,EAAE,aAAsB;IACvF,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACxD,OAAO,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAC7B,IAAgB,EAChB,IAAgB,EAChB,aAAsB;IAEtB,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACxD,OAAO,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;AAC7C,CAAC"}

package/dist/help.d.ts

@@ -0,0 +1,45 @@
+/** Help tiers and command metadata for the grounder CLI. */
+export type HelpGroup = "Setup" | "Write" | "Paths" | "Maintain" | "Advanced";
+export interface CommandMeta {
+    /** Canonical id (`note`, `handoff list`, `vault init`, …). */
+    id: string;
+    group: HelpGroup;
+    /** One-line summary for synopsis / full command lists. */
+    summary: string;
+    /** Usage line shown in per-command help (no `Usage:` prefix). */
+    usage: string;
+    /** Synopsis / full-list left column (no `grounder ` prefix). */
+    listUsage: string;
+    /** Flag / detail block for per-command help. */
+    flags?: string;
+    /** Include in synopsis and full command lists (default true). */
+    list?: boolean;
+}
+/**
+ * Single registry driving synopsis, full help, and per-command help so they
+ * cannot drift from each other (or from the dispatcher ids).
+ */
+export declare const COMMANDS: readonly CommandMeta[];
+/**
+ * Command ids the CLI dispatches (including parent topics). Keep in sync with
+ * `cli.ts` / `helpExitCode(...)` call sites — the invariant test locks this.
+ */
+export declare const DISPATCHED_COMMAND_IDS: readonly ["vault", "vault init", "init", "note", "handoff", "handoff list", "handoff peek", "plan", "plan list", "path", "path notes", "path logs", "path plans", "status", "doctor", "migrate", "help"];
+/** True when argv contains an exact `-h` or `--help` token. */
+export declare function wantsHelp(argv: string[]): boolean;
+/**
+ * Resolve a help topic from argv segments after `help`, longest match first
+ * (e.g. `handoff list` before `handoff`).
+ */
+export declare function resolveCommandHelp(segments: string[]): CommandMeta | undefined;
+export declare function printCommandHelp(meta: CommandMeta): void;
+export declare function printCommandHelpById(id: string): void;
+/** If argv asks for help, print per-command help and return 0; else null. */
+export declare function helpExitCode(argv: string[], commandId: string): number | null;
+/** Bare `grounder` / `-h` — short grouped synopsis (no flag encyclopedia). */
+export declare function printSynopsis(): void;
+/** `--help` / `grounder help` with no args — one-shot reference for humans/agents. */
+export declare function printFullHelp(): void;
+/** `grounder help [topic…]` — full help or per-command. */
+export declare function runHelp(argv: string[]): number;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9E,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,SAAS,CAAC;IACjB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAaD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,WAAW,EAsL1C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,0MAkBzB,CAAC;AAIX,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAEjD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,SAAS,CAY9E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CASxD;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAMrD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM7E;AAgDD,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,IAAI,CAepC;AAED,sFAAsF;AACtF,wBAAgB,aAAa,IAAI,IAAI,CAepC;AAED,2DAA2D;AAC3D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAe9C"}