greprag 5.3.0 → 5.5.0

package/dist/commands/checkpoint-helpers.d.ts

@@ -0,0 +1,41 @@
+/** CLI plumbing for `greprag checkpoint`. Pulled out of the subcommand
+ *  dispatch file (checkpoint.ts) to keep both under the 500-line ceiling.
+ *
+ *  Owns: env / config loading, HTTP wrappers, project resolution, git
+ *  context capture, --since parsing, generic-title pre-check, age
+ *  formatting. Pure plumbing — no business logic.
+ */
+export declare function loadEnvFile(filePath: string): void;
+export declare function getConfig(): {
+    apiUrl: string;
+    apiKey: string;
+};
+export declare function abortNotConfigured(): never;
+export declare function apiPost<T>(url: string, apiKey: string, body: Record<string, unknown>): Promise<T>;
+export declare function apiGet<T>(url: string, apiKey: string): Promise<T>;
+export declare function apiPatch<T>(url: string, apiKey: string, body: Record<string, unknown>): Promise<T>;
+export declare function apiDelete<T>(url: string, apiKey: string): Promise<T>;
+export declare function getFlag(args: string[], flag: string): string | undefined;
+export interface ResolvedProject {
+    projectId: string;
+    projectName: string;
+}
+export declare function resolveProject(args: string[], apiUrl: string, apiKey: string): Promise<ResolvedProject>;
+export declare function readSessionEnv(): string | null;
+export declare function captureGitContext(cwd: string): {
+    branch: string | null;
+    gitRootSha: string | null;
+    workingDir: string;
+};
+/** Convert --since "<duration>" to an ISO windowStart. Accepts:
+ *    "30m" / "30min" → 30 minutes ago
+ *    "2h" / "2hr"    → 2 hours ago
+ *    "1d" / "1day"   → 1 day ago
+ *    bare ISO timestamp passes through unchanged
+ *  Returns null on parse failure. */
+export declare function parseSince(since: string | undefined): string | null;
+export declare function isLikelyGenericTitle(title: string, projectName: string): {
+    generic: boolean;
+    reason?: string;
+};
+export declare function relativeAge(createdAtIso: string, now: Date): string;

package/dist/commands/checkpoint-helpers.js

@@ -0,0 +1,250 @@
+"use strict";
+/** CLI plumbing for `greprag checkpoint`. Pulled out of the subcommand
+ *  dispatch file (checkpoint.ts) to keep both under the 500-line ceiling.
+ *
+ *  Owns: env / config loading, HTTP wrappers, project resolution, git
+ *  context capture, --since parsing, generic-title pre-check, age
+ *  formatting. Pure plumbing — no business logic.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEnvFile = loadEnvFile;
+exports.getConfig = getConfig;
+exports.abortNotConfigured = abortNotConfigured;
+exports.apiPost = apiPost;
+exports.apiGet = apiGet;
+exports.apiPatch = apiPatch;
+exports.apiDelete = apiDelete;
+exports.getFlag = getFlag;
+exports.resolveProject = resolveProject;
+exports.readSessionEnv = readSessionEnv;
+exports.captureGitContext = captureGitContext;
+exports.parseSince = parseSince;
+exports.isLikelyGenericTitle = isLikelyGenericTitle;
+exports.relativeAge = relativeAge;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const project_anchor_1 = require("../project-anchor");
+const API_URL_DEFAULT = 'https://api.greprag.com';
+// ---------- Env / config -----------------------------------------------------
+function loadEnvFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx < 1)
+                continue;
+            const key = trimmed.slice(0, eqIdx).trim();
+            let value = trimmed.slice(eqIdx + 1).trim();
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            if (!process.env[key])
+                process.env[key] = value;
+        }
+    }
+    catch { /* file missing — fine */ }
+}
+function getConfig() {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+    if (homeDir)
+        loadEnvFile(path.join(homeDir, '.greprag', '.env'));
+    if (!process.env.GREPRAG_API_KEY)
+        loadEnvFile(path.join(process.cwd(), '.env'));
+    return {
+        apiUrl: process.env.GREPRAG_API_URL || API_URL_DEFAULT,
+        apiKey: process.env.GREPRAG_API_KEY || '',
+    };
+}
+function abortNotConfigured() {
+    console.error('Not configured. Run: greprag init');
+    process.exit(1);
+}
+// ---------- HTTP -------------------------------------------------------------
+async function apiPost(url, apiKey, body) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let json;
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        json = { ok: false, error: 'invalid JSON', detail: text };
+    }
+    if (!res.ok) {
+        const err = new Error(`API ${res.status}: ${text}`);
+        err.status = res.status;
+        err.body = json;
+        throw err;
+    }
+    return json;
+}
+async function apiGet(url, apiKey) {
+    const res = await fetch(url, { headers: { 'Authorization': `Bearer ${apiKey}` } });
+    if (!res.ok)
+        throw new Error(`API ${res.status}: ${await res.text()}`);
+    return res.json();
+}
+async function apiPatch(url, apiKey, body) {
+    const res = await fetch(url, {
+        method: 'PATCH',
+        headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`API ${res.status}: ${await res.text()}`);
+    return res.json();
+}
+async function apiDelete(url, apiKey) {
+    const res = await fetch(url, {
+        method: 'DELETE',
+        headers: { 'Authorization': `Bearer ${apiKey}` },
+    });
+    if (!res.ok)
+        throw new Error(`API ${res.status}: ${await res.text()}`);
+    return res.json();
+}
+// ---------- Flags ------------------------------------------------------------
+function getFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1 || idx + 1 >= args.length)
+        return undefined;
+    return args[idx + 1];
+}
+async function resolveProject(args, apiUrl, apiKey) {
+    const projectArg = getFlag(args, '--project');
+    if (!projectArg) {
+        const anchor = (0, project_anchor_1.readAnchor)(process.cwd());
+        return { projectId: anchor.projectId, projectName: anchor.projectName };
+    }
+    const r = await apiGet(`${apiUrl}/v1/projects`, apiKey);
+    const needle = projectArg.trim().toLowerCase();
+    const match = (r.projects || []).find(p => p.project_name.toLowerCase() === needle);
+    if (!match) {
+        throw new Error(`project "${projectArg}" not found under this tenant. ` +
+            `Register it via 'greprag init' in that directory, then retry.`);
+    }
+    return { projectId: match.project_id, projectName: match.project_name };
+}
+function readSessionEnv() {
+    return process.env.CLAUDE_SESSION_ID || process.env.GREPRAG_SESSION_ID || null;
+}
+// ---------- Git context capture ---------------------------------------------
+function captureGitContext(cwd) {
+    let branch = null;
+    let gitRootSha = null;
+    try {
+        branch = (0, child_process_1.execSync)('git branch --show-current', {
+            cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim() || null;
+    }
+    catch { /* not a git repo */ }
+    try {
+        gitRootSha = (0, child_process_1.execSync)('git rev-list --max-parents=0 HEAD', {
+            cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim().split('\n')[0] || null;
+    }
+    catch { /* not a git repo */ }
+    return { branch, gitRootSha, workingDir: cwd };
+}
+// ---------- --since duration parser -----------------------------------------
+/** Convert --since "<duration>" to an ISO windowStart. Accepts:
+ *    "30m" / "30min" → 30 minutes ago
+ *    "2h" / "2hr"    → 2 hours ago
+ *    "1d" / "1day"   → 1 day ago
+ *    bare ISO timestamp passes through unchanged
+ *  Returns null on parse failure. */
+function parseSince(since) {
+    if (!since)
+        return null;
+    const trimmed = since.trim();
+    const asDate = new Date(trimmed);
+    if (!Number.isNaN(asDate.getTime()) && /\d{4}-\d{2}-\d{2}/.test(trimmed)) {
+        return asDate.toISOString();
+    }
+    const m = trimmed.match(/^(\d+(?:\.\d+)?)(m|min|h|hr|d|day)s?$/i);
+    if (!m)
+        return null;
+    const n = parseFloat(m[1]);
+    const unit = m[2].toLowerCase();
+    let ms;
+    if (unit === 'm' || unit === 'min')
+        ms = n * 60_000;
+    else if (unit === 'h' || unit === 'hr')
+        ms = n * 3_600_000;
+    else
+        ms = n * 86_400_000;
+    return new Date(Date.now() - ms).toISOString();
+}
+// ---------- Title pre-check (mirrors checkpoint-title.ts on server) ----------
+function isLikelyGenericTitle(title, projectName) {
+    const trimmed = title.trim();
+    if (!trimmed)
+        return { generic: true, reason: 'empty' };
+    const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
+    if (wordCount < 5)
+        return { generic: true, reason: `only ${wordCount} word(s)` };
+    if (projectName && trimmed.toLowerCase() === projectName.trim().toLowerCase()) {
+        return { generic: true, reason: 'just the project name' };
+    }
+    if (/^(notes?|stuff|things|misc|pausing|where i was|where i left off|checkpoint|save|wip|bookmark|todo|reminder)\.?\s*$/i.test(trimmed)) {
+        return { generic: true, reason: 'generic word' };
+    }
+    return { generic: false };
+}
+// ---------- Time formatting --------------------------------------------------
+function relativeAge(createdAtIso, now) {
+    const diffMs = now.getTime() - new Date(createdAtIso).getTime();
+    const diffMin = Math.floor(diffMs / 60_000);
+    if (diffMin < 1)
+        return 'just now';
+    if (diffMin < 60)
+        return `${diffMin}m ago`;
+    const diffHrs = Math.round(diffMs / 3_600_000);
+    if (diffHrs < 24)
+        return `${diffHrs}h ago`;
+    const diffDays = Math.round(diffMs / 86_400_000);
+    return diffDays === 1 ? 'yesterday' : `${diffDays}d ago`;
+}
+//# sourceMappingURL=checkpoint-helpers.js.map

package/dist/commands/checkpoint-helpers.js.map

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

package/dist/commands/checkpoint.d.ts

@@ -0,0 +1,16 @@
+/** greprag checkpoint — operator-triggered episodic bookmarks.
+ *
+ *  Subcommands:
+ *    save "<title>" [--note "<text>"] [--since "<duration>"]
+ *                   [--project <name>] [--source-session <id>] [--force]
+ *    list [--project <name>] [--all | --status open|closed]
+ *    show <nodeId> [--project <name>]
+ *    edit-note <nodeId> --append "<text>"   |   --replace "<text>"
+ *    close <nodeId> [--project <name>]
+ *    delete <nodeId> [--project <name>] [--yes]
+ *
+ *  Plumbing (config, HTTP, project resolution, git context, --since
+ *  parsing, title pre-check, time formatting) lives in
+ *  `./checkpoint-helpers.ts` so this file stays under the 500-line ceiling.
+ */
+export declare function runCheckpoint(args: string[]): Promise<void>;

package/dist/commands/checkpoint.js

@@ -0,0 +1,334 @@
+"use strict";
+/** greprag checkpoint — operator-triggered episodic bookmarks.
+ *
+ *  Subcommands:
+ *    save "<title>" [--note "<text>"] [--since "<duration>"]
+ *                   [--project <name>] [--source-session <id>] [--force]
+ *    list [--project <name>] [--all | --status open|closed]
+ *    show <nodeId> [--project <name>]
+ *    edit-note <nodeId> --append "<text>"   |   --replace "<text>"
+ *    close <nodeId> [--project <name>]
+ *    delete <nodeId> [--project <name>] [--yes]
+ *
+ *  Plumbing (config, HTTP, project resolution, git context, --since
+ *  parsing, title pre-check, time formatting) lives in
+ *  `./checkpoint-helpers.ts` so this file stays under the 500-line ceiling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCheckpoint = runCheckpoint;
+const checkpoint_helpers_1 = require("./checkpoint-helpers");
+const NODE_ID_RE = /^[0-9a-f]{8}$/i;
+// ---------- save ------------------------------------------------------------
+async function saveCmd(args) {
+    const cfg = (0, checkpoint_helpers_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, checkpoint_helpers_1.abortNotConfigured)();
+    const title = args[0];
+    if (!title || title.startsWith('--')) {
+        console.error('Usage: greprag checkpoint save "<title>" [--note "<text>"] [--since "<duration>"] [--project <name>] [--source-session <id>] [--force]');
+        process.exit(1);
+    }
+    const note = (0, checkpoint_helpers_1.getFlag)(args, '--note');
+    const since = (0, checkpoint_helpers_1.getFlag)(args, '--since');
+    const sourceSession = (0, checkpoint_helpers_1.getFlag)(args, '--source-session') || (0, checkpoint_helpers_1.readSessionEnv)();
+    const force = args.includes('--force');
+    const { projectId, projectName } = await (0, checkpoint_helpers_1.resolveProject)(args, cfg.apiUrl, cfg.apiKey);
+    if (!force) {
+        const check = (0, checkpoint_helpers_1.isLikelyGenericTitle)(title, projectName);
+        if (check.generic) {
+            console.error(`Title "${title}" looks generic (${check.reason}). Server will reject this.`);
+            console.error('Examples of accepted titles:');
+            console.error('  · PayBot backlinks codification — awaiting operator inputs');
+            console.error('  · Discord pairing reconciliation — paused mid-debug');
+            console.error('  · Episodic V2 prompt validation — 3 dailies left');
+            console.error('Try again with a specific title (or pass --force to attempt anyway).');
+            process.exit(1);
+        }
+    }
+    const sinceIso = (0, checkpoint_helpers_1.parseSince)(since);
+    if (since && !sinceIso) {
+        console.error(`--since "${since}" is not a valid duration. Use "30m", "2h", "1d", or ISO.`);
+        process.exit(1);
+    }
+    const gitCtx = (0, checkpoint_helpers_1.captureGitContext)(process.cwd());
+    const url = force
+        ? `${cfg.apiUrl}/v1/checkpoints/${projectId}?override_title_check=1`
+        : `${cfg.apiUrl}/v1/checkpoints/${projectId}`;
+    let result;
+    try {
+        result = await (0, checkpoint_helpers_1.apiPost)(url, cfg.apiKey, {
+            title,
+            sourceSessionId: sourceSession,
+            windowStart: sinceIso || undefined,
+            note: note ?? null,
+            branch: gitCtx.branch,
+            gitRootSha: gitCtx.gitRootSha,
+            workingDir: gitCtx.workingDir,
+            projectName,
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.status === 400 && e.body) {
+            console.error(`Error: ${e.body.detail || e.body.error}`);
+            if (e.body.examples) {
+                console.error('Examples of accepted titles:');
+                for (const ex of e.body.examples)
+                    console.error(`  · ${ex}`);
+            }
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (!result.ok || !result.nodeId) {
+        console.error(`Error: ${result.detail || result.error || 'unknown failure'}`);
+        process.exit(1);
+    }
+    const label = result.duplicate ? 'Reusing existing checkpoint' : 'Saved checkpoint';
+    console.log(`${label} [${result.nodeId}] in ${projectName}`);
+    console.log(`Title: ${result.title}`);
+    if (result.placeholder) {
+        console.log('');
+        console.log('Warning: no turns in window — synthesis was skipped.');
+        console.log('Recommend adding a --note via: greprag checkpoint edit-note ' + result.nodeId + ' --append "<text>"');
+    }
+    else {
+        console.log(`Claims: ${result.claimsCount ?? 0} · model: ${result.modelUsed || 'unknown'}`);
+    }
+}
+// ---------- list ------------------------------------------------------------
+async function listCmd(args) {
+    const cfg = (0, checkpoint_helpers_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, checkpoint_helpers_1.abortNotConfigured)();
+    const all = args.includes('--all');
+    const statusArg = (0, checkpoint_helpers_1.getFlag)(args, '--status');
+    const status = all ? 'all' : (statusArg === 'closed' ? 'closed' : statusArg === 'all' ? 'all' : 'open');
+    const { projectId, projectName } = await (0, checkpoint_helpers_1.resolveProject)(args, cfg.apiUrl, cfg.apiKey);
+    const result = await (0, checkpoint_helpers_1.apiGet)(`${cfg.apiUrl}/v1/checkpoints/${projectId}?status=${encodeURIComponent(status)}`, cfg.apiKey);
+    if (!result.ok || !result.checkpoints) {
+        throw new Error(result.error || 'list failed');
+    }
+    if (result.checkpoints.length === 0) {
+        const noun = status === 'closed' ? 'closed' : status === 'all' ? '' : 'open ';
+        console.log(`No ${noun}checkpoints in ${projectName}.`);
+        return;
+    }
+    const now = new Date();
+    const sortKey = (r) => (r.status === 'open' ? 0 : 1);
+    const rows = result.checkpoints.slice().sort((a, b) => sortKey(a) - sortKey(b) || (a.createdAt < b.createdAt ? 1 : -1));
+    console.log(`${rows.length} checkpoint${rows.length === 1 ? '' : 's'} in ${projectName}:`);
+    console.log('');
+    for (const r of rows) {
+        const date = r.createdAt.slice(0, 10);
+        const age = (0, checkpoint_helpers_1.relativeAge)(r.createdAt, now);
+        console.log(`  [${r.nodeId}] ${date} (${age})  ${r.title}  [${r.status}]`);
+    }
+}
+async function showCmd(args) {
+    const cfg = (0, checkpoint_helpers_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, checkpoint_helpers_1.abortNotConfigured)();
+    const nodeId = args[0];
+    if (!nodeId || nodeId.startsWith('--')) {
+        console.error('Usage: greprag checkpoint show <nodeId> [--project <name>]');
+        process.exit(1);
+    }
+    if (!NODE_ID_RE.test(nodeId)) {
+        console.error('nodeId must be 8 hex chars.');
+        process.exit(1);
+    }
+    const { projectId } = await (0, checkpoint_helpers_1.resolveProject)(args, cfg.apiUrl, cfg.apiKey);
+    const result = await (0, checkpoint_helpers_1.apiGet)(`${cfg.apiUrl}/v1/checkpoints/${projectId}/${nodeId}`, cfg.apiKey);
+    if (!result.ok || !result.checkpoint) {
+        console.error(`Error: ${result.error || 'not found'}`);
+        process.exit(1);
+    }
+    const cp = result.checkpoint;
+    const savedAt = cp.createdAt.slice(0, 16).replace('T', ' ') + ' UTC';
+    const sessionShort = (cp.sourceSessionId || '').slice(0, 8);
+    console.log(`${cp.title}       [${cp.status}]`);
+    const meta = [`Saved ${savedAt}`];
+    if (cp.branch)
+        meta.push(`branch ${cp.branch}`);
+    if (sessionShort)
+        meta.push(`session ${sessionShort}`);
+    console.log(meta.join(' · '));
+    if (cp.workingDir)
+        console.log(`Dir: ${cp.workingDir}`);
+    console.log('');
+    console.log(cp.summary || '(no summary)');
+    if (cp.nextLine) {
+        console.log('');
+        console.log(`NEXT: ${cp.nextLine}`);
+    }
+    const open = cp.claims.filter(c => c.tag === 'open');
+    if (open.length > 0) {
+        console.log('');
+        console.log('Open items (from claims):');
+        for (const c of open)
+            console.log(`  · ${c.text}`);
+    }
+    const other = cp.claims.filter(c => c.tag !== 'open');
+    if (other.length > 0) {
+        console.log('');
+        console.log('Decisions / Learned / Investigated:');
+        for (const c of other)
+            console.log(`  [${c.tag}:${c.source}] ${c.text}`);
+    }
+    if (cp.operatorNote) {
+        console.log('');
+        console.log('Operator note:');
+        console.log(cp.operatorNote);
+    }
+    if (cp.closedAt) {
+        console.log('');
+        console.log(`Closed: ${cp.closedAt.slice(0, 16).replace('T', ' ')} UTC`);
+    }
+}
+// ---------- edit-note -------------------------------------------------------
+async function editNoteCmd(args) {
+    const cfg = (0, checkpoint_helpers_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, checkpoint_helpers_1.abortNotConfigured)();
+    const nodeId = args[0];
+    if (!nodeId || nodeId.startsWith('--')) {
+        console.error('Usage: greprag checkpoint edit-note <nodeId> --append "<text>"   |   --replace "<text>"');
+        process.exit(1);
+    }
+    if (!NODE_ID_RE.test(nodeId)) {
+        console.error('nodeId must be 8 hex chars.');
+        process.exit(1);
+    }
+    const append = (0, checkpoint_helpers_1.getFlag)(args, '--append');
+    const replace = (0, checkpoint_helpers_1.getFlag)(args, '--replace');
+    if ((append == null) === (replace == null)) {
+        console.error('Pass exactly one of --append "<text>" or --replace "<text>".');
+        process.exit(1);
+    }
+    const action = append != null ? 'append' : 'replace';
+    const text = append != null ? append : replace;
+    const { projectId } = await (0, checkpoint_helpers_1.resolveProject)(args, cfg.apiUrl, cfg.apiKey);
+    const result = await (0, checkpoint_helpers_1.apiPatch)(`${cfg.apiUrl}/v1/checkpoints/${projectId}/${nodeId}`, cfg.apiKey, { action: 'edit-note', note: { action, text } });
+    if (!result.ok) {
+        console.error(`Error: ${result.error || 'edit-note failed'}`);
+        process.exit(1);
+    }
+    console.log(`Updated note on checkpoint [${nodeId}].`);
+    if (result.operatorNote) {
+        console.log('');
+        console.log('New note:');
+        console.log(result.operatorNote);
+    }
+}
+// ---------- close -----------------------------------------------------------
+async function closeCmd(args) {
+    const cfg = (0, checkpoint_helpers_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, checkpoint_helpers_1.abortNotConfigured)();
+    const nodeId = args[0];
+    if (!nodeId || nodeId.startsWith('--')) {
+        console.error('Usage: greprag checkpoint close <nodeId> [--project <name>]');
+        process.exit(1);
+    }
+    if (!NODE_ID_RE.test(nodeId)) {
+        console.error('nodeId must be 8 hex chars.');
+        process.exit(1);
+    }
+    const { projectId, projectName } = await (0, checkpoint_helpers_1.resolveProject)(args, cfg.apiUrl, cfg.apiKey);
+    const result = await (0, checkpoint_helpers_1.apiPatch)(`${cfg.apiUrl}/v1/checkpoints/${projectId}/${nodeId}`, cfg.apiKey, { action: 'close' });
+    if (!result.ok) {
+        console.error(`Error: ${result.error || 'close failed'}`);
+        process.exit(1);
+    }
+    if (result.alreadyClosed) {
+        console.log(`Checkpoint [${nodeId}] in ${projectName} was already closed.`);
+    }
+    else {
+        console.log(`Closed checkpoint [${nodeId}] in ${projectName}.`);
+    }
+}
+// ---------- delete ----------------------------------------------------------
+async function deleteCmd(args) {
+    const cfg = (0, checkpoint_helpers_1.getConfig)();
+    if (!cfg.apiKey)
+        (0, checkpoint_helpers_1.abortNotConfigured)();
+    const nodeId = args[0];
+    if (!nodeId || nodeId.startsWith('--')) {
+        console.error('Usage: greprag checkpoint delete <nodeId> [--project <name>] [--yes]');
+        process.exit(1);
+    }
+    if (!NODE_ID_RE.test(nodeId)) {
+        console.error('nodeId must be 8 hex chars.');
+        process.exit(1);
+    }
+    if (!args.includes('--yes') && !args.includes('-y')) {
+        console.error(`Refusing to delete without confirmation. Pass --yes to delete [${nodeId}].`);
+        console.error('Note: "close keeps history; delete is for typos." Consider `close` instead.');
+        process.exit(1);
+    }
+    const { projectId, projectName } = await (0, checkpoint_helpers_1.resolveProject)(args, cfg.apiUrl, cfg.apiKey);
+    const result = await (0, checkpoint_helpers_1.apiDelete)(`${cfg.apiUrl}/v1/checkpoints/${projectId}/${nodeId}`, cfg.apiKey);
+    if (!result.ok) {
+        console.error(`Error: ${result.error || 'delete failed'}`);
+        process.exit(1);
+    }
+    console.log(`Deleted checkpoint [${nodeId}] from ${projectName}.`);
+}
+// ---------- Dispatch --------------------------------------------------------
+const SUB_HELP = `
+greprag checkpoint — operator-triggered episodic bookmarks.
+
+A checkpoint is a "where I am + what was about to happen next" snapshot.
+The server synthesizes the session window into a summary + tagged claims
+(gemini-2.5-flash) and stores it as a checkpoint-shape node in the project's
+memory store. Lifecycle ops: list / show / edit-note / close / delete.
+
+Subcommands:
+  save "<title>" [--note "<text>"] [--since "<duration>"]
+                 [--project <name>] [--source-session <id>] [--force]
+        Save a checkpoint. Title must be 5+ words, specific (server hard-rejects
+        "PayBot stuff", "notes", project-name-only, all-caps, etc.). --since
+        accepts "30m" / "2h" / "1d" / ISO. --force bypasses heuristic title
+        checks (empty title still rejected).
+  list  [--project <name>] [--status open|closed|all] [--all]
+        Default: open only. --all = same as --status all.
+  show <nodeId> [--project <name>]
+        Print the synthesized summary, NEXT line, claims, operator note.
+  edit-note <nodeId> --append "<text>"   |   --replace "<text>"
+        Update the operator-note overlay (appended below the synthesis on show).
+  close <nodeId> [--project <name>]
+        Flip status to closed. Keeps history. Idempotent.
+  delete <nodeId> [--project <name>] [--yes]
+        Hard delete (close is usually the right move).
+
+Examples:
+  greprag checkpoint save "Episodic V2 prompt validation — 3 dailies left" --note "Re-run after weekly cron fires Sunday"
+  greprag checkpoint list
+  greprag checkpoint show a3f2c1d4
+  greprag checkpoint edit-note a3f2c1d4 --append "Operator reverted the prompt before sleeping."
+  greprag checkpoint close a3f2c1d4
+`.trim();
+async function runCheckpoint(args) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'save': return saveCmd(rest);
+        case 'list': return listCmd(rest);
+        case 'show': return showCmd(rest);
+        case 'edit-note': return editNoteCmd(rest);
+        case 'close': return closeCmd(rest);
+        case 'delete': return deleteCmd(rest);
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(SUB_HELP);
+            return;
+        default:
+            console.error(`Unknown subcommand: ${sub}\n`);
+            console.log(SUB_HELP);
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=checkpoint.js.map