syncpoint-ai 0.1.0

package/dist/cli/commands/dev.js

@@ -0,0 +1,379 @@
+/**
+ * CLI Dev commands — debugging / inspection utilities.
+ *
+ *   syncpoint dev status   — snapshot of all Gates, Claims, Agents, Operations
+ *   syncpoint dev tail     — live event stream from the internal event bus
+ *   syncpoint dev reset    — wipe all collaboration state back to initial
+ */
+import * as repo from "../../server/repositories/index.js";
+import { createEventBus, defaultContext, getDbPath, findIntermediateStateEntities, getEntityTransitionHistory, getCompensationDefinition } from "../../server/index.js";
+// ── 4.1  dev status ──────────────────────────────────
+function printStatus(opts) {
+    const agents = repo.listAgents();
+    const claims = repo.listResourceClaims();
+    const gates = repo.listSyncGates();
+    const operations = repo.listOperations();
+    const permits = repo.listWritePermits();
+    if (opts.json) {
+        console.log(JSON.stringify({ agents, claims, gates, operations, permits }, null, 2));
+        return;
+    }
+    // ── Agents ─────────────────────────────────
+    console.log(`\n=== Agents (${agents.length}) ===`);
+    if (agents.length === 0) {
+        console.log("  (none)");
+    }
+    else {
+        console.table(agents.map(a => ({
+            id: a.id.slice(0, 12),
+            name: a.name,
+            status: a.status,
+            task: a.currentTaskId?.slice(0, 12) ?? "-",
+        })));
+    }
+    // ── Resource Claims ────────────────────────
+    console.log(`\n=== Resource Claims (${claims.length}) ===`);
+    if (claims.length === 0) {
+        console.log("  (none)");
+    }
+    else {
+        console.table(claims.map(c => ({
+            id: c.id.slice(0, 12),
+            actor: c.actorId.slice(0, 12),
+            task: c.taskId.slice(0, 12),
+            mode: c.mode,
+            status: c.status,
+            resources: c.resources.map(r => r.locator).join(", "),
+        })));
+    }
+    // ── Sync Gates ─────────────────────────────
+    console.log(`\n=== Sync Gates (${gates.length}) ===`);
+    if (gates.length === 0) {
+        console.log("  (none)");
+    }
+    else {
+        console.table(gates.map(g => ({
+            id: g.id.slice(0, 12),
+            task: g.taskId.slice(0, 12),
+            status: g.status,
+            reason: g.reason,
+            required: g.requiredAgentIds.length,
+            acked: g.ackedAgentIds.length,
+        })));
+    }
+    // ── Operations ────────────────────────────
+    console.log(`\n=== Operations (${operations.length}) ===`);
+    if (operations.length === 0) {
+        console.log("  (none)");
+    }
+    else {
+        console.table(operations.map(o => ({
+            id: o.id.slice(0, 12),
+            type: o.type,
+            actor: o.actorId.slice(0, 12),
+            task: o.taskId.slice(0, 12),
+            status: o.status,
+            title: o.title.slice(0, 40),
+        })));
+    }
+    // ── Write Permits ──────────────────────────
+    console.log(`\n=== Write Permits (${permits.length}) ===`);
+    if (permits.length === 0) {
+        console.log("  (none)");
+    }
+    else {
+        console.table(permits.map(p => ({
+            id: p.id.slice(0, 12),
+            actor: p.actorId.slice(0, 12),
+            task: p.taskId.slice(0, 12),
+            status: p.status,
+            intent: p.intent,
+        })));
+    }
+    console.log(`\nDB: ${getDbPath()}`);
+}
+// ── 4.2  dev tail ─────────────────────────────────────
+function startTail(opts) {
+    const bus = createEventBus();
+    // Print recent events from DB first
+    const limit = parseInt(opts.n ?? "20", 10);
+    const raw = defaultContext.raw;
+    const recent = raw.prepare(`SELECT id, event_type, entity_type, entity_id, detail, created_at FROM event ORDER BY created_at DESC LIMIT ?`).all(limit);
+    if (recent.length > 0) {
+        if (opts.json) {
+            for (const row of recent.reverse()) {
+                console.log(JSON.stringify(row));
+            }
+        }
+        else {
+            console.log(`--- Last ${recent.length} events ---`);
+            for (const row of recent) {
+                console.log(`  [${row.created_at}] ${row.event_type} ${row.entity_type}:${row.entity_id.slice(0, 12)}${row.detail ? ` (${row.detail})` : ""}`);
+            }
+            console.log("--- live ---");
+        }
+    }
+    // Subscribe to live events
+    const handler = (data) => {
+        if (opts.json) {
+            console.log(JSON.stringify({ ...data, timestamp: new Date().toISOString() }));
+            return;
+        }
+        const ts = new Date().toISOString();
+        console.log(`[${ts}] ${data.eventType} ${data.entityType}:${data.entityId.slice(0, 12)}${data.detail ? ` (${data.detail})` : ""}`);
+    };
+    bus.on("event", handler);
+    console.log("Tailing events (Ctrl+C to stop)...");
+    process.on("SIGINT", () => {
+        bus.off("event", handler);
+        console.log("\nStopped tailing.");
+        process.exit(0);
+    });
+}
+// ── 4.3  dev reset ────────────────────────────────────
+function resetState(opts) {
+    if (!opts.confirm) {
+        console.log("This will DELETE all collaboration state (gates, claims, operations, permits, events, etc.).");
+        console.log("Run with --confirm to proceed.");
+        return;
+    }
+    const raw = defaultContext.raw;
+    // Delete in dependency order — child join tables first, then parent tables
+    const joinTables = [
+        "sync_gate_required_agent",
+        "sync_gate_ack",
+        "sync_gate_vote",
+        "sync_gate_resource",
+        "sync_gate_related_claim",
+        "resource_claim_resource",
+        "operation_resource",
+        "write_permit_resource",
+        "checkpoint_review_approver",
+        "negotiation_participant",
+        "context_snapshot_resource",
+    ];
+    const parentTables = [
+        "sync_gate",
+        "resource_claim",
+        "operation",
+        "write_permit",
+        "checkpoint_review",
+        "negotiation_session",
+        "context_snapshot",
+        "checkpoint",
+        "diary_entry",
+        "handoff",
+        "peer_contract",
+        "review_request",
+        "review_evidence",
+        "review_decision",
+        "change_request",
+        "approval_record",
+        "review_checklist_item",
+        "event",
+        "guard_session",
+    ];
+    const allTables = [...joinTables, ...parentTables];
+    let deleted = 0;
+    for (const table of allTables) {
+        try {
+            const result = raw.prepare(`DELETE FROM \`${table}\``).run();
+            deleted += result.changes;
+        }
+        catch {
+            // Table may not exist in this DB — skip
+        }
+    }
+    // Reset agent currentTaskId
+    try {
+        raw.exec(`UPDATE agent SET current_task_id = NULL WHERE current_task_id IS NOT NULL`);
+    }
+    catch { /* no agents table */ }
+    // Reset task ownerAgentId
+    try {
+        raw.exec(`UPDATE task SET owner_agent_id = NULL WHERE owner_agent_id IS NOT NULL`);
+    }
+    catch { /* no tasks table */ }
+    if (opts.json) {
+        console.log(JSON.stringify({ deleted, tables: allTables.length }));
+        return;
+    }
+    console.log(`Reset complete. Deleted ${deleted} rows across ${allTables.length} tables.`);
+    console.log("Agents and tasks remain; collaboration state cleared.");
+}
+// ── 4.4  dev integrity ──────────────────────────────────
+function checkIntegrity(opts) {
+    const result = defaultContext.checkIntegrity();
+    if (opts.json) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    if (result.ok) {
+        console.log(`✓ Database integrity: ${result.details}`);
+    }
+    else {
+        console.error(`✗ Database integrity FAILED: ${result.details}`);
+    }
+}
+// ── 4.5  dev recover ────────────────────────────────────
+const KNOWN_ENTITY_TYPES = ["resource_claim", "sync_gate", "operation", "write_permit", "checkpoint_review", "negotiation_session", "guard_session"];
+const TERMINAL_STATES = {
+    resource_claim: ["released", "expired", "revoked"],
+    sync_gate: ["resolved", "cancelled", "expired"],
+    operation: ["applied", "rejected", "cancelled"],
+    write_permit: ["applied", "expired", "revoked"],
+    checkpoint_review: ["resolved", "cancelled"],
+    negotiation_session: ["resolved", "cancelled", "expired"],
+    guard_session: ["revoked", "expired"],
+};
+function scanStuckEntities(opts) {
+    const types = opts.entityType ? [opts.entityType] : KNOWN_ENTITY_TYPES;
+    const stuck = [];
+    for (const entityType of types) {
+        const terminalStates = TERMINAL_STATES[entityType] ?? [];
+        if (terminalStates.length === 0)
+            continue;
+        try {
+            const intermediates = findIntermediateStateEntities(entityType, terminalStates);
+            for (const entity of intermediates) {
+                // Get last transition time and operation
+                const history = getEntityTransitionHistory(entityType, entity.entityId, 1);
+                const lastOp = history[0]?.operation;
+                const compensation = lastOp ? getCompensationDefinition(entityType, lastOp) : undefined;
+                stuck.push({
+                    entityType,
+                    entityId: entity.entityId,
+                    state: entity.state,
+                    lastOperation: lastOp,
+                    lastTransition: history[0]?.createdAt,
+                    suggestedRecovery: compensation?.compensateToState,
+                });
+            }
+        }
+        catch {
+            // Entity type may not have transitions logged yet — skip
+        }
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ stuck, count: stuck.length }));
+        return;
+    }
+    if (stuck.length === 0) {
+        console.log("No stuck entities found. All entities are in terminal states or have no transition log.");
+        return;
+    }
+    console.log(`Found ${stuck.length} stuck entities (in non-terminal states):`);
+    console.table(stuck.map(s => ({
+        type: s.entityType,
+        id: s.entityId.slice(0, 12),
+        state: s.state,
+        lastOp: s.lastOperation ?? "unknown",
+        suggestedRecovery: s.suggestedRecovery ?? "manual",
+    })));
+    console.log("\nSuggested recovery commands:");
+    for (const s of stuck) {
+        const targetState = s.suggestedRecovery ?? "manual";
+        if (targetState !== "manual") {
+            console.log(`  syncpoint dev recover --entity-type ${s.entityType} --entity-id ${s.entityId} --to-state ${targetState}`);
+        }
+    }
+}
+function forceRecover(opts) {
+    if (!opts.entityType || !opts.entityId || !opts.toState) {
+        console.error("--entity-type, --entity-id, and --to-state are required for forced recovery.");
+        console.error("Example: syncpoint dev recover --entity-type resource_claim --entity-id abc123 --to-state released");
+        process.exit(1);
+    }
+    const raw = defaultContext.raw;
+    const tableName = opts.entityType;
+    // Map entity_type to the actual table and state column
+    const stateColumnMap = {
+        resource_claim: "status",
+        sync_gate: "status",
+        operation: "status",
+        write_permit: "status",
+        checkpoint_review: "status",
+        negotiation_session: "status",
+        guard_session: "status",
+    };
+    const stateCol = stateColumnMap[opts.entityType];
+    if (!stateCol) {
+        console.error(`Unknown entity type: ${opts.entityType}`);
+        process.exit(1);
+    }
+    try {
+        const stmt = raw.prepare(`UPDATE \`${tableName}\` SET ${stateCol} = ? WHERE id = ?`);
+        const result = stmt.run(opts.toState, opts.entityId);
+        if (result.changes === 0) {
+            console.error(`No row updated. Entity ${opts.entityType}:${opts.entityId} not found.`);
+            process.exit(1);
+        }
+        // Log the recovery in state_transition_log
+        raw.prepare(`
+      INSERT INTO state_transition_log (id, entity_type, entity_id, from_state, to_state, operation, agent_id, payload_json, created_at)
+      VALUES (?, ?, ?, 'recovery', ?, 'force_recover', 'system', '{}', ?)
+    `).run(`recovery-${Date.now()}`, opts.entityType, opts.entityId, opts.toState, new Date().toISOString());
+        if (opts.json) {
+            console.log(JSON.stringify({ recovered: true, entityType: opts.entityType, entityId: opts.entityId, toState: opts.toState }));
+        }
+        else {
+            console.log(`Recovered ${opts.entityType}:${opts.entityId.slice(0, 12)} → ${opts.toState}`);
+        }
+    }
+    catch (err) {
+        console.error(`Recovery failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+export function registerDevCommands(program) {
+    const dev = program
+        .command("dev")
+        .description("Developer debugging and inspection commands");
+    dev
+        .command("status")
+        .description("Snapshot of all Gates, Claims, Agents, Operations, and Permits")
+        .option("--json", "Output JSON")
+        .action((opts) => {
+        printStatus(opts);
+    });
+    dev
+        .command("tail")
+        .description("Live event stream from the SyncPoint event bus")
+        .option("-n, --lines <n>", "Number of recent events to show first", "20")
+        .option("--json", "Output newline-delimited JSON")
+        .action((opts) => {
+        startTail(opts);
+    });
+    dev
+        .command("reset")
+        .description("Wipe all collaboration state back to initial (keeps agents and tasks)")
+        .option("--confirm", "Actually perform the reset (required)")
+        .option("--json", "Output JSON result")
+        .action((opts) => {
+        resetState(opts);
+    });
+    dev
+        .command("integrity")
+        .description("Check database integrity (PRAGMA integrity_check)")
+        .option("--json", "Output JSON")
+        .action((opts) => {
+        checkIntegrity(opts);
+    });
+    dev
+        .command("recover")
+        .description("Scan for stuck entities after a crash, or force-recover a specific entity")
+        .option("--entity-type <type>", "Filter scan to a specific entity type, or target for force recovery")
+        .option("--entity-id <id>", "Entity ID for force recovery")
+        .option("--to-state <state>", "Target state for force recovery")
+        .option("--json", "Output JSON")
+        .action((opts) => {
+        if (opts.entityId && opts.toState) {
+            forceRecover(opts);
+        }
+        else {
+            scanStuckEntities(opts);
+        }
+    });
+    // ── Register ──────────────────────────────────────────
+}
+//# sourceMappingURL=dev.js.map

package/dist/cli/commands/dev.js.map

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

package/dist/cli/commands/error-handler.d.ts

@@ -0,0 +1,32 @@
+/**
+ * User-friendly error handling for SyncPoint CLI.
+ *
+ * Translates raw errors into actionable, human-readable messages
+ * with suggestions for resolution.
+ */
+export interface FormattedError {
+    icon: string;
+    title: string;
+    message: string;
+    suggestion: string;
+    details?: string;
+    /** Link to relevant docs or GitHub issues. */
+    helpUrl?: string;
+}
+/**
+ * Format any error into a user-friendly structure.
+ */
+export declare function formatError(err: unknown): FormattedError;
+/**
+ * Print a formatted error to stderr and set the process exit code.
+ */
+export declare function printError(err: unknown, exitCode?: number): void;
+/**
+ * Wrap an async action with error handling.
+ * Catches any error, prints it nicely, and sets exit code.
+ *
+ * Usage:
+ *   .action((opts) => handleError(() => doWork(opts)))
+ */
+export declare function handleError(fn: () => void | Promise<void>): () => Promise<void>;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/cli/commands/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../_build/src/cli/commands/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAyJxD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,IAAI,CAc3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAQ/E"}

package/dist/cli/commands/error-handler.js

@@ -0,0 +1,185 @@
+/**
+ * User-friendly error handling for SyncPoint CLI.
+ *
+ * Translates raw errors into actionable, human-readable messages
+ * with suggestions for resolution.
+ */
+import { SyncPointError, ResourceConflictError, ResourceNotFoundError, ConstraintViolationError, UnauthorizedError, ForbiddenError, InvalidStateTransitionError, ValidationError, DatabaseError, OperationTimeoutError, InternalError, } from "../../kernel/index.js";
+const ISSUES_URL = "https://github.com/MIK-HEAL/SyncPoint/issues";
+/**
+ * Format any error into a user-friendly structure.
+ */
+export function formatError(err) {
+    // ── Known SyncPoint errors ──
+    if (err instanceof ResourceConflictError) {
+        return {
+            icon: "🔒",
+            title: "Resource Conflict",
+            message: err.message,
+            suggestion: "Try narrowing your claim scope (e.g. --scope function) or wait for the other agent to release.",
+            details: err.message,
+        };
+    }
+    if (err instanceof ResourceNotFoundError) {
+        return {
+            icon: "🔍",
+            title: "Resource Not Found",
+            message: err.message,
+            suggestion: "Check the resource locator. Use 'syncpoint status' to see active resources.",
+        };
+    }
+    if (err instanceof ConstraintViolationError) {
+        return {
+            icon: "🚫",
+            title: "Constraint Violation",
+            message: err.message,
+            suggestion: "Review constraints with 'syncpoint constraint list'. Consider requesting an exemption if this is intentional.",
+        };
+    }
+    if (err instanceof UnauthorizedError) {
+        return {
+            icon: "🔑",
+            title: "Unauthorized",
+            message: err.message,
+            suggestion: "Check your agent token. Run 'syncpoint connect --status' to verify your session.",
+        };
+    }
+    if (err instanceof ForbiddenError) {
+        return {
+            icon: "⛔",
+            title: "Forbidden",
+            message: err.message,
+            suggestion: "Your agent does not have permission for this action. Contact the session owner.",
+        };
+    }
+    if (err instanceof InvalidStateTransitionError) {
+        return {
+            icon: "⚠️",
+            title: "Invalid State Transition",
+            message: err.message,
+            suggestion: "Check the current status with 'syncpoint status'. The requested action is not valid from the current state.",
+        };
+    }
+    if (err instanceof ValidationError) {
+        return {
+            icon: "📝",
+            title: "Validation Error",
+            message: err.message,
+            suggestion: "Run the command with --help to see valid parameters.",
+        };
+    }
+    if (err instanceof DatabaseError) {
+        return {
+            icon: "💾",
+            title: "Database Error",
+            message: err.message,
+            suggestion: "Check that .syncpoint/syncpoint.db is accessible and not corrupted. Try 'syncpoint doctor'.",
+            helpUrl: ISSUES_URL,
+        };
+    }
+    if (err instanceof OperationTimeoutError) {
+        return {
+            icon: "⏰",
+            title: "Operation Timeout",
+            message: err.message,
+            suggestion: "The operation took too long. Check your network connection and retry.",
+        };
+    }
+    if (err instanceof InternalError) {
+        return {
+            icon: "🔥",
+            title: "Internal Error",
+            message: err.message,
+            suggestion: `This is unexpected. Please report it at ${ISSUES_URL}`,
+            helpUrl: ISSUES_URL,
+        };
+    }
+    if (err instanceof SyncPointError) {
+        return {
+            icon: "❌",
+            title: "SyncPoint Error",
+            message: err.message,
+            suggestion: "See above for details.",
+        };
+    }
+    // ── Generic / unknown errors ──
+    if (err instanceof Error) {
+        const msg = err.message;
+        // Detect common patterns
+        if (msg.includes("ECONNREFUSED") || msg.includes("connect")) {
+            return {
+                icon: "🔌",
+                title: "Connection Failed",
+                message: "Could not connect to the SyncPoint server.",
+                suggestion: "Is the server running? Start it with 'syncpoint server start'.",
+            };
+        }
+        if (msg.includes("ENOENT") || msg.includes("not found")) {
+            return {
+                icon: "📁",
+                title: "File Not Found",
+                message: msg,
+                suggestion: "Check that the file path is correct and the file exists.",
+            };
+        }
+        if (msg.includes("EACCES") || msg.includes("permission")) {
+            return {
+                icon: "🔐",
+                title: "Permission Denied",
+                message: msg,
+                suggestion: "Check file permissions or run with appropriate privileges.",
+            };
+        }
+        // Unknown error — encourage bug report
+        return {
+            icon: "❌",
+            title: "Unexpected Error",
+            message: err.message,
+            suggestion: `Please report this issue at ${ISSUES_URL} with the details below.`,
+            details: err.stack ?? err.message,
+            helpUrl: ISSUES_URL,
+        };
+    }
+    return {
+        icon: "❌",
+        title: "Error",
+        message: String(err),
+        suggestion: "An unknown error occurred.",
+    };
+}
+/**
+ * Print a formatted error to stderr and set the process exit code.
+ */
+export function printError(err, exitCode = 1) {
+    const formatted = formatError(err);
+    const lines = [`${formatted.icon} ${formatted.title}: ${formatted.message}`];
+    if (formatted.suggestion) {
+        lines.push(`   💡 ${formatted.suggestion}`);
+    }
+    if (formatted.details && formatted.title !== "Unexpected Error") {
+        lines.push(`   Details: ${formatted.details}`);
+    }
+    if (formatted.helpUrl) {
+        lines.push(`   🔗 ${formatted.helpUrl}`);
+    }
+    console.error(lines.join("\n"));
+    process.exitCode = exitCode;
+}
+/**
+ * Wrap an async action with error handling.
+ * Catches any error, prints it nicely, and sets exit code.
+ *
+ * Usage:
+ *   .action((opts) => handleError(() => doWork(opts)))
+ */
+export function handleError(fn) {
+    return async () => {
+        try {
+            await fn();
+        }
+        catch (err) {
+            printError(err);
+        }
+    };
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/cli/commands/error-handler.js.map

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

package/dist/cli/commands/facade.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI Facade — root-level short commands for v0.1.
+ *
+ * These wrap existing application services into user-friendly
+ * top-level commands:
+ *   syncpoint status
+ *   syncpoint claim <paths>
+ *   syncpoint resume
+ *   syncpoint checkpoint
+ *   syncpoint wake
+ */
+import { Command } from "commander";
+export declare function registerFacadeCommands(program: Command): void;
+//# sourceMappingURL=facade.d.ts.map

package/dist/cli/commands/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../../../_build/src/cli/commands/facade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAsF5C,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0c7D"}