@creator-notes/cnotes 0.16.11

package/dist/lib/claude-session.js

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { BRAND } from "./brand.js";
+import { cnotesEnv } from "./env.js";
+/**
+ * Where `cnotes claude-hook` (a Claude Code SessionStart hook) persists the
+ * current session id. A single "latest" file — simple and correct for the
+ * common one-session-per-machine case. Concurrent Claude Code sessions on the
+ * same machine would clobber it; set CNOTES_AGENT_SESSION_ID to disambiguate.
+ */
+export const CLAUDE_SESSION_FILE = join(homedir(), BRAND.configDir, "claude-session.json");
+/**
+ * How long a hook-captured session stays trustworthy as "the agent driving
+ * this cnotes run". The SessionStart hook stamps `updatedAt` when the session is
+ * (re)opened, but there's no heartbeat — so this is age-since-opened, not
+ * since-last-activity. A generous window keeps long-running sessions valid
+ * while stopping a file left behind by a session that ended days ago from
+ * stamping a later, unrelated run.
+ */
+export const SESSION_FILE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+/**
+ * Decide whether a stored hook session is still a trustworthy stand-in for
+ * "the agent driving THIS cnotes run". Pure (takes `now` + `cwd` rather than
+ * reading them) so the rules stay easy to reason about:
+ *
+ *   - Must carry an `id` — the only thing we can actually resume.
+ *   - Not older than {@link SESSION_FILE_MAX_AGE_MS} — a stale file left after
+ *     a session ended must not stamp a later run as if that chat drove it.
+ *   - If the file recorded the session's `cwd`, the current directory must sit
+ *     inside that subtree — a cnotes run in a *different* project isn't this
+ *     session's work. (No recorded cwd → can't scope, so we don't reject on
+ *     that basis.)
+ *
+ * Erring toward rejection is the safe bias here: a false negative just drops
+ * the (optional) resume affordance, whereas a false positive mislabels the
+ * run's provenance and offers a resume to the wrong chat.
+ */
+export function isStoredSessionUsable(stored, ctx) {
+    if (!stored.id)
+        return false;
+    if (typeof stored.updatedAt === "number" &&
+        ctx.now - stored.updatedAt > SESSION_FILE_MAX_AGE_MS) {
+        return false;
+    }
+    if (stored.cwd && !isWithin(ctx.cwd, stored.cwd))
+        return false;
+    return true;
+}
+/** True when `child` is `parent` or nested beneath it. */
+function isWithin(child, parent) {
+    const rel = relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Resolve the agent conversation/session driving the current cnotes run, so
+ * `cnotes operations begin` can stamp it on the operation row (making the run
+ * traceable + resumable from the timeline). Resolution order, most explicit
+ * first:
+ *
+ *   1. CN_AGENT_SESSION_ID (+ optional CN_AGENT_SESSION_KIND) — explicit
+ *      override, wins everything. Lets any agent runtime opt in by hand.
+ *   2. The SessionStart-hook file written by `cnotes claude-hook`, when it's still
+ *      fresh + scoped to this directory (see {@link isStoredSessionUsable}).
+ *      This is the Claude Code TOP-LEVEL session id, captured once when the
+ *      session starts — the most correct value to resume (a subagent's own
+ *      bash would otherwise report the subagent's id via the env var below).
+ *   3. CLAUDE_CODE_SESSION_ID — Claude Code's per-process env var. Zero-config
+ *      but undocumented; best-effort fallback when no hook is installed. It's
+ *      the live process's own env, so no staleness check applies.
+ *
+ * Returns null when nothing is known (e.g. cnotes run outside any agent), in which
+ * case the run simply isn't session-stamped — no error.
+ */
+export function resolveAgentSession() {
+    const overrideId = cnotesEnv("AGENT_SESSION_ID")?.trim();
+    if (overrideId) {
+        return {
+            kind: cnotesEnv("AGENT_SESSION_KIND")?.trim() || "claude-code",
+            id: overrideId,
+        };
+    }
+    const fromFile = readSessionFile(Date.now(), process.cwd());
+    if (fromFile)
+        return fromFile;
+    const envId = process.env.CLAUDE_CODE_SESSION_ID?.trim();
+    if (envId)
+        return { kind: "claude-code", id: envId };
+    return null;
+}
+function readSessionFile(now, cwd) {
+    try {
+        const raw = readFileSync(CLAUDE_SESSION_FILE, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (isStoredSessionUsable(parsed, { now, cwd })) {
+            return { kind: parsed.kind || "claude-code", id: parsed.id };
+        }
+    }
+    catch {
+        // No hook file / unreadable / malformed → fall through to env.
+    }
+    return null;
+}
+//# sourceMappingURL=claude-session.js.map

package/dist/lib/claude-session.js.map

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

package/dist/lib/config.d.ts

@@ -0,0 +1,28 @@
+export interface ResolvedConfig {
+    serverUrl: string;
+    token: string;
+    workspaceId: string;
+    json: boolean;
+    quiet: boolean;
+    fields?: string[];
+}
+interface GlobalOpts {
+    server?: string;
+    workspace?: string;
+    json?: boolean;
+    quiet?: boolean;
+    fields?: string;
+}
+/**
+ * Resolve server URL, token, and workspace from env vars, flags, and config file.
+ * Priority: flags > env vars > config file.
+ */
+export declare function resolveConfig(opts: GlobalOpts): ResolvedConfig;
+/**
+ * Resolve config without requiring workspace (for auth/config/workspace commands).
+ */
+export declare function resolveBaseConfig(opts: GlobalOpts): Omit<ResolvedConfig, "workspaceId"> & {
+    workspaceId?: string;
+};
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,UAAU,UAAU;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAqC9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAmBlH"}

package/dist/lib/config.js

@@ -0,0 +1,66 @@
+import { loadConfig, getServerConfig } from "./auth-store.js";
+import { AuthError, ValidationError } from "./errors.js";
+import { cnotesEnv } from "./env.js";
+/**
+ * Parse a `--fields a,b,c` option into a trimmed list, or undefined when unset.
+ */
+function parseFields(fields) {
+    if (!fields)
+        return undefined;
+    const list = fields.split(",").map((f) => f.trim()).filter(Boolean);
+    return list.length > 0 ? list : undefined;
+}
+/**
+ * Resolve server URL, token, and workspace from env vars, flags, and config file.
+ * Priority: flags > env vars > config file.
+ */
+export function resolveConfig(opts) {
+    const config = loadConfig();
+    // Server URL
+    const serverUrl = opts.server || cnotesEnv("SERVER") || config.currentServer;
+    // Token
+    const envToken = cnotesEnv("TOKEN");
+    const configToken = getServerConfig(config, serverUrl)?.token;
+    const token = envToken || configToken;
+    if (!token) {
+        throw new AuthError();
+    }
+    // Workspace ID
+    const envWorkspace = cnotesEnv("WORKSPACE");
+    const configWorkspace = getServerConfig(config, serverUrl)?.workspaceId;
+    const workspaceId = opts.workspace || envWorkspace || configWorkspace;
+    if (!workspaceId) {
+        throw new ValidationError("No workspace selected. Run `cnotes workspace select` or pass --workspace <id>");
+    }
+    // Output format
+    const json = opts.json || cnotesEnv("JSON") === "1" || !process.stdout.isTTY;
+    return {
+        serverUrl,
+        token,
+        workspaceId,
+        json: json ?? false,
+        quiet: opts.quiet ?? false,
+        fields: parseFields(opts.fields),
+    };
+}
+/**
+ * Resolve config without requiring workspace (for auth/config/workspace commands).
+ */
+export function resolveBaseConfig(opts) {
+    const config = loadConfig();
+    const serverUrl = opts.server || cnotesEnv("SERVER") || config.currentServer;
+    const envToken = cnotesEnv("TOKEN");
+    const configToken = getServerConfig(config, serverUrl)?.token;
+    const token = envToken || configToken || "";
+    const configWorkspace = getServerConfig(config, serverUrl)?.workspaceId;
+    const json = opts.json || cnotesEnv("JSON") === "1" || !process.stdout.isTTY;
+    return {
+        serverUrl,
+        token,
+        workspaceId: opts.workspace || cnotesEnv("WORKSPACE") || configWorkspace,
+        json: json ?? false,
+        quiet: opts.quiet ?? false,
+        fields: parseFields(opts.fields),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/config.js.map

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

package/dist/lib/env.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read a cnotes environment variable, honoring the pre-rename `CN_` prefix as a
+ * fallback.
+ *
+ * The cn→cnotes rename moved the env contract from `CN_*` to `CNOTES_*`. New
+ * config (`.mcp.json`, the Claude Desktop / Codex install templates) writes the
+ * `CNOTES_*` form, but MCP configs written before the rename still carry `CN_*`
+ * — so we read `CNOTES_<suffix>` first and fall back to `CN_<suffix>` until the
+ * user re-runs `cnotes mcp setup-*` (which rewrites the config to the new form).
+ *
+ * Pass the suffix only, e.g. `cnotesEnv("SERVER")` for CNOTES_SERVER/CN_SERVER.
+ */
+export declare function cnotesEnv(suffix: string): string | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5D"}

package/dist/lib/env.js

@@ -0,0 +1,16 @@
+/**
+ * Read a cnotes environment variable, honoring the pre-rename `CN_` prefix as a
+ * fallback.
+ *
+ * The cn→cnotes rename moved the env contract from `CN_*` to `CNOTES_*`. New
+ * config (`.mcp.json`, the Claude Desktop / Codex install templates) writes the
+ * `CNOTES_*` form, but MCP configs written before the rename still carry `CN_*`
+ * — so we read `CNOTES_<suffix>` first and fall back to `CN_<suffix>` until the
+ * user re-runs `cnotes mcp setup-*` (which rewrites the config to the new form).
+ *
+ * Pass the suffix only, e.g. `cnotesEnv("SERVER")` for CNOTES_SERVER/CN_SERVER.
+ */
+export function cnotesEnv(suffix) {
+    return process.env[`CNOTES_${suffix}`] ?? process.env[`CN_${suffix}`];
+}
+//# sourceMappingURL=env.js.map

package/dist/lib/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,MAAM,EAAE,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/dist/lib/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Exit codes are part of the CLI's contract with agents. Branching on the
+ * exit code is cheaper and more reliable than parsing stderr prose.
+ *
+ *   0  ok
+ *   1  generic error
+ *   2  auth required
+ *   3  validation (bad input)
+ *   4  not found
+ *   5  conflict (already exists / state collision)
+ *   6  rate-limited
+ *   7  permission denied
+ */
+export declare const EXIT_CODES: {
+    readonly OK: 0;
+    readonly GENERIC: 1;
+    readonly AUTH: 2;
+    readonly VALIDATION: 3;
+    readonly NOT_FOUND: 4;
+    readonly CONFLICT: 5;
+    readonly RATE_LIMIT: 6;
+    readonly PERMISSION: 7;
+};
+export declare class CliError extends Error {
+    exitCode: number;
+    hint?: string;
+    constructor(message: string, exitCode?: number, hint?: string);
+}
+export declare class AuthError extends CliError {
+    constructor(message?: string, hint?: string);
+}
+export declare class ValidationError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class NotFoundError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class ApiError extends CliError {
+    status: number;
+    body: Record<string, unknown>;
+    constructor(status: number, body: Record<string, unknown>);
+}
+/**
+ * Handle errors from CLI commands uniformly.
+ */
+export declare function handleError(error: unknown, json: boolean): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU;;;;;;;;;CASb,CAAC;AAEX,qBAAa,QAAS,SAAQ,KAAK;IAKxB,QAAQ,EAAE,MAAM;IAJzB,IAAI,CAAC,EAAE,MAAM,CAAC;gBAGZ,OAAO,EAAE,MAAM,EACR,QAAQ,GAAE,MAA2B,EAC5C,IAAI,CAAC,EAAE,MAAM;CAMhB;AAED,qBAAa,SAAU,SAAQ,QAAQ;gBAEnC,OAAO,GAAE,MAAmC,EAC5C,IAAI,GAAE,MAAmD;CAK5D;AAED,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAI3C;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAI3C;AAED,qBAAa,QAAS,SAAQ,QAAQ;IAE3B,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAD7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAgBvC;AA4FD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,KAAK,CA8BhE"}

package/dist/lib/errors.js

@@ -0,0 +1,194 @@
+/**
+ * Exit codes are part of the CLI's contract with agents. Branching on the
+ * exit code is cheaper and more reliable than parsing stderr prose.
+ *
+ *   0  ok
+ *   1  generic error
+ *   2  auth required
+ *   3  validation (bad input)
+ *   4  not found
+ *   5  conflict (already exists / state collision)
+ *   6  rate-limited
+ *   7  permission denied
+ */
+export const EXIT_CODES = {
+    OK: 0,
+    GENERIC: 1,
+    AUTH: 2,
+    VALIDATION: 3,
+    NOT_FOUND: 4,
+    CONFLICT: 5,
+    RATE_LIMIT: 6,
+    PERMISSION: 7,
+};
+export class CliError extends Error {
+    exitCode;
+    hint;
+    constructor(message, exitCode = EXIT_CODES.GENERIC, hint) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+        if (hint)
+            this.hint = hint;
+    }
+}
+export class AuthError extends CliError {
+    constructor(message = "Authentication required.", hint = "Run `cnotes auth login` to authenticate.") {
+        super(message, EXIT_CODES.AUTH, hint);
+        this.name = "AuthError";
+    }
+}
+export class ValidationError extends CliError {
+    constructor(message, hint) {
+        super(message, EXIT_CODES.VALIDATION, hint);
+        this.name = "ValidationError";
+    }
+}
+export class NotFoundError extends CliError {
+    constructor(message, hint) {
+        super(message, EXIT_CODES.NOT_FOUND, hint);
+        this.name = "NotFoundError";
+    }
+}
+export class ApiError extends CliError {
+    status;
+    body;
+    constructor(status, body) {
+        const baseMsg = body.error || `API error: HTTP ${status}`;
+        const fieldLines = formatFieldErrors(body.details);
+        const msg = fieldLines.length > 0
+            ? `${baseMsg}\n${fieldLines.map((l) => `  - ${l}`).join("\n")}`
+            : baseMsg;
+        const exitCode = exitCodeForStatus(status);
+        const resource = typeof body.resource === "string" ? body.resource : undefined;
+        const hint = typeof body.hint === "string"
+            ? body.hint
+            : hintForStatus(status, baseMsg, resource);
+        super(msg, exitCode, hint);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+function exitCodeForStatus(status) {
+    if (status === 401)
+        return EXIT_CODES.AUTH;
+    if (status === 403)
+        return EXIT_CODES.PERMISSION;
+    if (status === 404)
+        return EXIT_CODES.NOT_FOUND;
+    if (status === 409)
+        return EXIT_CODES.CONFLICT;
+    if (status === 422)
+        return EXIT_CODES.VALIDATION;
+    if (status === 429)
+        return EXIT_CODES.RATE_LIMIT;
+    if (status >= 400 && status < 500)
+        return EXIT_CODES.VALIDATION;
+    return EXIT_CODES.GENERIC;
+}
+function hintForStatus(status, message, resource) {
+    if (status === 401)
+        return "Run `cnotes auth login` to authenticate.";
+    if (status === 403)
+        return "Check workspace membership with `cnotes workspace current`.";
+    if (status === 404) {
+        // Prefer a server-provided `resource` field; fall back to regex on the
+        // error message. Regex is best-effort because server messages vary.
+        const r = (resource ?? "").toLowerCase();
+        if (r === "workspace" || (!r && /workspace/i.test(message))) {
+            return "Run `cnotes workspace list` to see available workspaces.";
+        }
+        if (r === "note" || (!r && /note/i.test(message))) {
+            return "Run `cnotes notes list` to see valid display IDs.";
+        }
+        if (r === "canvas" || (!r && /canvas/i.test(message))) {
+            return "Run `cnotes canvas list` to see available canvases.";
+        }
+        return "Run `cnotes schema` to see valid resource identifiers.";
+    }
+    if (status === 429)
+        return "Slow down requests or retry with backoff.";
+    if (status === 409)
+        return "Re-fetch current state and retry; another writer may have modified the resource.";
+    return undefined;
+}
+function isBatchItem(v) {
+    return (!!v &&
+        typeof v === "object" &&
+        typeof v.index === "number" &&
+        typeof v.field === "string" &&
+        typeof v.message === "string");
+}
+/**
+ * Extract human-readable lines from a server `details` payload. Recognises:
+ *   - `{ items: [{ index, key?, field, message }, ...] }` — `cnotes notes create` per-item errors
+ *   - Zod `.flatten()` shape `{ fieldErrors, formErrors }` — generic validation
+ */
+function formatFieldErrors(details) {
+    if (!details || typeof details !== "object")
+        return [];
+    const d = details;
+    const lines = [];
+    if (Array.isArray(d.items)) {
+        for (const raw of d.items) {
+            if (!isBatchItem(raw))
+                continue;
+            const keyLabel = raw.key ? `(${raw.key})` : "(?)";
+            lines.push(`item ${raw.index} ${keyLabel}: ${raw.field}: ${raw.message}`);
+        }
+        if (lines.length > 0)
+            return lines;
+    }
+    if (d.fieldErrors) {
+        for (const [field, errs] of Object.entries(d.fieldErrors)) {
+            if (!errs || errs.length === 0)
+                continue;
+            for (const err of errs)
+                lines.push(`${field}: ${err}`);
+        }
+    }
+    if (lines.length === 0 && Array.isArray(d.formErrors)) {
+        for (const err of d.formErrors)
+            lines.push(err);
+    }
+    return lines;
+}
+/**
+ * Handle errors from CLI commands uniformly.
+ */
+export function handleError(error, json) {
+    if (error instanceof CliError) {
+        if (json) {
+            const payload = {
+                error: error.message,
+                code: error.name,
+                exitCode: error.exitCode,
+            };
+            if (error.hint)
+                payload.hint = error.hint;
+            if (error instanceof ApiError) {
+                payload.status = error.status;
+                if (error.body && typeof error.body === "object" && "details" in error.body) {
+                    payload.details = error.body.details;
+                }
+            }
+            console.error(JSON.stringify(payload));
+        }
+        else {
+            console.error(`Error: ${error.message}`);
+            if (error.hint)
+                console.error(`  hint: ${error.hint}`);
+        }
+        process.exit(error.exitCode);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (json) {
+        console.error(JSON.stringify({ error: message, code: "unknown_error", exitCode: EXIT_CODES.GENERIC }));
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    process.exit(EXIT_CODES.GENERIC);
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

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

package/dist/lib/fs-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function readFileSafe(path: string): string;
+//# sourceMappingURL=fs-utils.d.ts.map

package/dist/lib/fs-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-utils.d.ts","sourceRoot":"","sources":["../../src/lib/fs-utils.ts"],"names":[],"mappings":"AAGA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASjD"}

package/dist/lib/fs-utils.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+import { CliError, ValidationError } from "./errors.js";
+export function readFileSafe(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        const nodeErr = err;
+        if (nodeErr.code === "ENOENT")
+            throw new ValidationError(`File not found: ${path}`);
+        if (nodeErr.code === "EACCES")
+            throw new ValidationError(`Permission denied: ${path}`);
+        throw new CliError(`Failed to read file: ${path} — ${nodeErr.message}`);
+    }
+}
+//# sourceMappingURL=fs-utils.js.map

package/dist/lib/fs-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../../src/lib/fs-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAA4B,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,eAAe,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QACpF,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,eAAe,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;QACvF,MAAM,IAAI,QAAQ,CAAC,wBAAwB,IAAI,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/dist/lib/install-hook.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Install a Claude Code SessionStart hook that captures the session id.
+ *
+ * The hook runs `cnotes claude-hook` at session start, which writes the current
+ * session id to a file (see lib/claude-session.ts). `cnotes operations begin` then
+ * stamps it on the operation row, so an agent run on the timeline can be traced
+ * back to — and resumed from — the conversation that produced it.
+ *
+ * Target: the USER-GLOBAL ~/.claude/settings.json (so capture works in every
+ * repo, not just one). We preserve all existing settings + other hooks, back up
+ * the file before writing, and are idempotent (a second install is a no-op).
+ *
+ * Unlike the MCP installer, a parse failure here ABORTS rather than starting
+ * fresh: settings.json holds the user's entire Claude Code config, so silently
+ * overwriting it would be destructive.
+ */
+/** The user-global Claude Code settings file. */
+export declare const CLAUDE_SETTINGS_PATH: string;
+/** The command the hook runs when `cnotes` is on PATH (a global install). */
+export declare const SESSION_HOOK_COMMAND = "cnotes claude-hook";
+/**
+ * Fallback command for when `cnotes` won't be on PATH — e.g. the user ran
+ * `npx @creator-notes/cnotes init` without installing globally. Resolving the hook
+ * through npx keeps it working instead of failing `command not found` on every
+ * session start. Costs npx resolution latency per session, so we only use it
+ * when `cnotes` genuinely isn't available. `npx cnotes` does NOT resolve (the published
+ * package is @creator-notes/cnotes); detection tolerates this form for idempotency.
+ */
+export declare const SESSION_HOOK_COMMAND_NPX = "npx @creator-notes/cnotes claude-hook";
+export interface HookInstallResult {
+    configPath: string;
+    /** created → new file; installed → merged into existing; already-present →
+     *  a claude-hook SessionStart entry was already there (no write). */
+    status: "created" | "installed" | "already-present";
+    backedUp?: string;
+}
+interface HookEntry {
+    type?: string;
+    command?: string;
+}
+interface HookGroup {
+    matcher?: string;
+    hooks?: HookEntry[];
+}
+interface ClaudeSettings {
+    hooks?: Record<string, HookGroup[]>;
+    [key: string]: unknown;
+}
+/**
+ * A plain JSON object — the only shape a Claude Code settings.json can validly
+ * take. Arrays, `null`, and primitives parse as valid JSON but aren't a config
+ * we can safely merge into, so callers treat them like a parse failure rather
+ * than silently clobbering the file. Exported for direct unit testing.
+ */
+export declare function isPlainSettingsObject(value: unknown): value is ClaudeSettings;
+/**
+ * Identify our entry by the `claude-hook` command (tolerates both the `cnotes` and
+ * `npx …` forms). Exported for direct unit testing.
+ */
+export declare function groupHasSessionHook(group: HookGroup): boolean;
+/** True when any SessionStart group already carries our hook. Exported for tests. */
+export declare function settingsHaveSessionHook(settings: ClaudeSettings): boolean;
+/**
+ * Rewrite any SessionStart hook that targets our `claude-hook` subcommand but
+ * isn't the command we're installing — e.g. a pre-rename `cn claude-hook` entry
+ * left dead once the `cn` binary was dropped — to `command`, in place. Returns
+ * true if anything changed. Exported for direct unit testing.
+ */
+export declare function upgradeStaleSessionHooks(settings: ClaudeSettings, command: string): boolean;
+/**
+ * True when a `cnotes claude-hook` SessionStart entry already exists. Read-only —
+ * lets callers skip prompting on re-runs without mutating anything. Returns
+ * false (rather than throwing) when the file is missing or unreadable.
+ */
+export declare function isClaudeSessionHookInstalled(): boolean;
+/**
+ * Idempotently add the SessionStart hook to ~/.claude/settings.json.
+ * Preserves existing settings + hooks, backs up an existing file first.
+ *
+ * @throws if an existing settings.json is present but not valid JSON — we will
+ *   not overwrite the user's whole config; the caller should surface the manual
+ *   install instructions instead.
+ */
+export declare function installClaudeSessionHook(command?: string): HookInstallResult;
+export {};
+//# sourceMappingURL=install-hook.d.ts.map

package/dist/lib/install-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-hook.d.ts","sourceRoot":"","sources":["../../src/lib/install-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,QAAiD,CAAC;AAEnF,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,0CAA0C,CAAC;AAEhF,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB;yEACqE;IACrE,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,iBAAiB,CAAC;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,SAAS;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,UAAU,SAAS;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;CACrB;AACD,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAE7E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAO7D;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAGzE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,GACd,OAAO,CAqBT;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,OAAO,CAStD;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,MAA6B,GACrC,iBAAiB,CAsEnB"}