chore: update docs/CLI.md, packages/cli/commands/scan.script.ts, packages/cli/commands/doctor.script.ts +5 more

Author: CartagoGit

docs/CLI.md

@@ -11,6 +11,22 @@ The CLI remains the functional reference; GUI labels map to these commands.
 | Push | `apisrc push --project-root <path> --workspace <id>` | Collection/environment actions; keys are never written to disk or diagnostics. |
 | Live | `apisrc watch --project-root <path>` | Watches source changes; auto-export is opt-in and off by default. |
 
+## Durable state diagnostics
+
+State persistence is shadow-only and opt-in. A normal scan continues to use
+the legacy in-memory result as its authority. Use `--shadow` to write the
+complete snapshot to the SQLite state database without activating it:
+
+```text
+apisrc scan --project-root <path> --shadow
+```
+
+Use `doctor --json` (or run `packages/cli/commands/doctor.script.ts` directly
+while the command is being exposed by the host) to inspect database version,
+migration status, active snapshot, last write, corruption and parity
+diagnostics. Secret values are never printed; the report only says that they
+were omitted. An absent or unavailable database does not change scan behavior.
+
 `sync` is a carrier over the existing generation handler. It does not scan or
 export through a second pipeline. GUI dry-run, retry, cancellation and native
 secure storage are host concerns around the same operation contract.

packages/cli/commands/doctor.script.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+import { existsSync } from "node:fs";
+import { STATE_DB_SCHEMA_VERSION } from "../../contracts/constants/core/state-store.constant.js";
+import { hasFlag, readFlag } from "../../core/helpers/argv.helper.js";
+import { resolveStateDatabasePath } from "../../core/state/sqlite/state-db-path.service.js";
+
+export interface IDoctorReport {
+  readonly databasePath: string;
+  readonly database: "available" | "missing" | "corrupt";
+  readonly dbVersion: number | null;
+  readonly migration: "current" | "unavailable";
+  readonly activeSnapshot: string | null;
+  readonly lastWrite: string | null;
+  readonly corruption: string | null;
+  readonly parity: "not-run" | "unavailable";
+  readonly secretsOmitted: true;
+}
+
+export interface IDoctorOutcome {
+  readonly code: number;
+  readonly output: string;
+  readonly report: IDoctorReport;
+}
+
+function missingReport(databasePath: string, reason: string): IDoctorReport {
+  return {
+    databasePath,
+    database: "missing",
+    dbVersion: null,
+    migration: "unavailable",
+    activeSnapshot: null,
+    lastWrite: null,
+    corruption: reason,
+    parity: "unavailable",
+    secretsOmitted: true,
+  };
+}
+
+export async function runDoctor(argv: string[] = process.argv.slice(2)): Promise<IDoctorOutcome> {
+  const databasePath = readFlag(argv, "--state-db") ?? resolveStateDatabasePath();
+  let report: IDoctorReport;
+  if (!existsSync(databasePath)) {
+    report = missingReport(databasePath, "State database does not exist");
+  } else {
+    try {
+      const { openStateDatabase } = await import("../../core/state/sqlite/sqlite-connection.adapter.js");
+      const connection = openStateDatabase(databasePath);
+      try {
+        const active = connection.database.query("SELECT active_snapshot_id FROM projects WHERE active_snapshot_id IS NOT NULL ORDER BY updated_at DESC LIMIT 1").get() as { active_snapshot_id?: string } | null;
+        const latest = connection.database.query("SELECT captured_at FROM snapshots WHERE status = 'complete' ORDER BY captured_at DESC LIMIT 1").get() as { captured_at?: string } | null;
+        report = {
+          databasePath,
+          database: "available",
+          dbVersion: connection.version,
+          migration: connection.version === STATE_DB_SCHEMA_VERSION ? "current" : "unavailable",
+          activeSnapshot: active?.active_snapshot_id ?? null,
+          lastWrite: latest?.captured_at ?? null,
+          corruption: null,
+          parity: "not-run",
+          secretsOmitted: true,
+        };
+      } finally {
+        connection.close();
+      }
+    } catch (error) {
+      report = missingReport(databasePath, error instanceof Error ? error.message : String(error));
+      report = { ...report, database: report.corruption?.includes("Corrupt") ? "corrupt" : "missing" };
+    }
+  }
+
+  const output = hasFlag(argv, "--json") ? JSON.stringify(report) : [
+    `Database: ${report.database}`,
+    `Path: ${report.databasePath}`,
+    `DB version: ${report.dbVersion ?? "unavailable"}`,
+    `Migration: ${report.migration}`,
+    `Active snapshot: ${report.activeSnapshot ?? "none"}`,
+    `Last write: ${report.lastWrite ?? "none"}`,
+    `Corruption: ${report.corruption ?? "none"}`,
+    `Parity: ${report.parity}`,
+    "Secrets: omitted",
+  ].join("\n");
+  return { code: report.database === "available" ? 0 : 1, output, report };
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  const outcome = await runDoctor(argv);
+  process.stdout.write(`${outcome.output}\n`);
+  return outcome.code;
+}
+
+if (import.meta.main) process.exit(await main());

packages/cli/commands/scan.script.ts

@@ -29,11 +29,59 @@ import { defaultOrchestrator } from "../../frameworks/framework.registry.js";
 import { guessedRootNotice, resolveRoot } from "../../core/helpers/resolve-root.helper.js";
 import type { IProjectContext } from "../../contracts/interfaces/core/project-context.interface.js";
 import type { IScanOutcome } from "../../contracts/interfaces/cli/scan-outcome.interface.js";
+import { hasFlag } from "../../core/helpers/argv.helper.js";
+import { StableIdService } from "../../core/state/stable-id.service.js";
+import { ShadowStateWriterService, type IShadowWriteDiagnostic } from "../../core/state/shadow-state-writer.service.js";
+
+export interface IScanOptions {
+  readonly shadow?: boolean;
+  readonly stateDatabasePath?: string;
+}
+
+async function writeShadowSnapshot(root: string, framework: string, routes: ReadonlyArray<{ method: string; uri: string }>, path?: string): Promise<IShadowWriteDiagnostic> {
+  const [{ SnapshotTransactionService }, { SqliteProjectRepository }, { SqliteSnapshotRepository }, { openStateDatabase }] = await Promise.all([
+    import("../../core/state/snapshot-transaction.service.js"),
+    import("../../core/state/sqlite/sqlite-project.repository.js"),
+    import("../../core/state/sqlite/sqlite-snapshot.repository.js"),
+    import("../../core/state/sqlite/sqlite-connection.adapter.js"),
+  ]);
+  const ids = new StableIdService();
+  const capturedAt = new Date().toISOString();
+  const projectId = ids.project(root);
+  const snapshot = {
+    projectId,
+    snapshotId: ids.snapshot(`${root}\0${capturedAt}`),
+    status: "building" as const,
+    revision: Date.now(),
+    capturedAt,
+    diagnostics: [],
+    metadata: { framework, routeCount: routes.length },
+    services: [{
+      serviceId: ids.service(`${root}\0${framework}`),
+      name: framework,
+      operations: routes.map((route) => ({
+        operationId: ids.operation(`${framework}\0${route.method}\0${route.uri}`),
+        method: route.method,
+        path: route.uri,
+      })),
+    }],
+  };
+  const connection = openStateDatabase(path);
+  try {
+    const snapshots = new SqliteSnapshotRepository(connection.database as never);
+    const projects = new SqliteProjectRepository(connection.database as never);
+    const transactions = new SnapshotTransactionService(connection.database as never, snapshots);
+    return new ShadowStateWriterService(transactions, projects).write(snapshot, root, true);
+  } finally {
+    connection.close();
+  }
+}
 
 /** Scans the project and returns what was found, printing it along the way. */
 export async function runScan(
   argv: string[] = process.argv.slice(2),
   context?: IProjectContext,
+  options: IScanOptions = {},
 ): Promise<IScanOutcome> {
   const root = context?.projectRoot ?? resolveRoot({ argv }).root;
 
@@ -85,6 +133,16 @@ export async function runScan(
     console.log(`  ${r.method.padEnd(6)} ${r.uri}${tags}${desc}`);
   }
 
+  if (options.shadow ?? hasFlag(argv, "--shadow")) {
+    try {
+      const shadow = await writeShadowSnapshot(root, match.framework, routes, options.stateDatabasePath);
+      if (!shadow.ok) console.error(`⚠ Shadow state write failed: ${shadow.error}`);
+      else console.log("✔ Shadow state snapshot persisted (legacy remains authoritative)");
+    } catch (error) {
+      console.error(`⚠ Shadow state unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
   return {
     code: 0,
     root,

packages/core/state/shadow-state-writer.service.ts

@@ -0,0 +1,50 @@
+import type { IProjectSnapshot } from "../../contracts/interfaces/core/project-state.interface.js";
+import type { ProjectId } from "../../contracts/interfaces/core/stable-ids.interface.js";
+import { SnapshotTransactionService } from "./snapshot-transaction.service.js";
+
+export interface IShadowWriteDiagnostic {
+  readonly ok: boolean;
+  readonly enabled: boolean;
+  readonly persisted: boolean;
+  readonly activated: false;
+  readonly snapshotId: string;
+  readonly error?: string;
+}
+
+export interface IShadowProjectRepository {
+  ensure(projectId: ProjectId, rootPath: string, now: string): void;
+}
+
+export class ShadowStateWriterService {
+  public constructor(
+    private readonly transactions: SnapshotTransactionService,
+    private readonly projects: IShadowProjectRepository,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  public write(
+    snapshot: IProjectSnapshot,
+    rootPath: string,
+    enabled: boolean,
+  ): IShadowWriteDiagnostic {
+    const base = {
+      enabled,
+      activated: false as const,
+      snapshotId: snapshot.snapshotId.value,
+    };
+    if (!enabled) return { ...base, ok: true, persisted: false };
+
+    try {
+      this.projects.ensure(snapshot.projectId, rootPath, this.now());
+      const complete = this.transactions.write(snapshot);
+      return { ...base, ok: true, persisted: complete.status === "complete" };
+    } catch (error) {
+      return {
+        ...base,
+        ok: false,
+        persisted: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+}

packages/core/state/state-parity.service.ts

@@ -0,0 +1,72 @@
+import type { IProjectSnapshot } from "../../contracts/interfaces/core/project-state.interface.js";
+import type { SnapshotId } from "../../contracts/interfaces/core/stable-ids.interface.js";
+import { canonicalSnapshotDigest } from "./canonical-snapshot.serializer.js";
+
+export type StateParityStatus = "match" | "mismatch" | "unavailable";
+
+export interface IStateParityDiagnostic {
+  readonly status: StateParityStatus;
+  readonly projectId: string;
+  readonly snapshotId: string;
+  readonly memoryDigest: string;
+  readonly sqliteDigest: string | null;
+  readonly message: string;
+}
+
+export interface IParitySnapshotRepository {
+  get(snapshotId: SnapshotId): IProjectSnapshot | null;
+}
+
+export class StateParityService {
+  public constructor(private readonly snapshots: IParitySnapshotRepository) {}
+
+  public compare(memory: IProjectSnapshot): IStateParityDiagnostic {
+    const memoryDigest = canonicalSnapshotDigest(memory);
+    let stored: IProjectSnapshot | null;
+    try {
+      stored = this.snapshots.get(memory.snapshotId);
+    } catch (error) {
+      return {
+        status: "unavailable",
+        projectId: memory.projectId.value,
+        snapshotId: memory.snapshotId.value,
+        memoryDigest,
+        sqliteDigest: null,
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+    if (stored === null) {
+      return {
+        status: "unavailable",
+        projectId: memory.projectId.value,
+        snapshotId: memory.snapshotId.value,
+        memoryDigest,
+        sqliteDigest: null,
+        message: "Snapshot is not available in SQLite",
+      };
+    }
+    const sqliteDigest = canonicalSnapshotDigest(stored);
+    return {
+      status: memoryDigest === sqliteDigest ? "match" : "mismatch",
+      projectId: memory.projectId.value,
+      snapshotId: memory.snapshotId.value,
+      memoryDigest,
+      sqliteDigest,
+      message: memoryDigest === sqliteDigest ? "Memory and SQLite snapshots match" : "Memory and SQLite snapshots differ",
+    };
+  }
+
+  public compareActive(memory: IProjectSnapshot, activeSnapshotId: SnapshotId | null): IStateParityDiagnostic {
+    if (activeSnapshotId === null || activeSnapshotId.value !== memory.snapshotId.value) {
+      return {
+        status: "mismatch",
+        projectId: memory.projectId.value,
+        snapshotId: memory.snapshotId.value,
+        memoryDigest: canonicalSnapshotDigest(memory),
+        sqliteDigest: null,
+        message: "SQLite active snapshot differs from the in-memory snapshot",
+      };
+    }
+    return this.compare(memory);
+  }
+}

tests/core/state/shadow-state-writer.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import type { IProjectSnapshot } from "../../../packages/contracts/interfaces/core/project-state.interface.js";
+import { ShadowStateWriterService } from "../../../packages/core/state/shadow-state-writer.service.js";
+
+const snapshot = (): IProjectSnapshot => ({
+  projectId: { kind: "project", value: "project-1" },
+  snapshotId: { kind: "snapshot", value: "snapshot-1" },
+  status: "building",
+  revision: 1,
+  capturedAt: "2026-09-09T00:00:00.000Z",
+  services: [],
+  diagnostics: [],
+});
+
+describe("shadow state writer", () => {
+  it("does nothing when shadow persistence is disabled", () => {
+    const result = new ShadowStateWriterService(null as never, null as never).write(snapshot(), "/tmp/project", false);
+    expect(result).toEqual({ enabled: false, persisted: false, activated: false, ok: true, snapshotId: "snapshot-1" });
+  });
+
+  it("persists complete state without activation", () => {
+    const writes: string[] = [];
+    const result = new ShadowStateWriterService(
+      { write: (value: IProjectSnapshot) => ({ ...value, status: "complete" as const }) } as never,
+      { ensure: () => writes.push("ensure") },
+    ).write(snapshot(), "/tmp/project", true);
+    expect(result.ok).toBe(true);
+    expect(result.persisted).toBe(true);
+    expect(result.activated).toBe(false);
+    expect(writes).toEqual(["ensure"]);
+  });
+});

tests/core/state/state-parity.spec.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import type { IProjectSnapshot } from "../../../packages/contracts/interfaces/core/project-state.interface.js";
+import { StateParityService } from "../../../packages/core/state/state-parity.service.js";
+
+const snapshot = (path = "/users"): IProjectSnapshot => ({
+  projectId: { kind: "project", value: "project-1" },
+  snapshotId: { kind: "snapshot", value: "snapshot-1" },
+  status: "complete",
+  revision: 1,
+  capturedAt: "2026-09-09T00:00:00.000Z",
+  services: [{ serviceId: { kind: "service", value: "service-1" }, name: "api", operations: [{ operationId: { kind: "operation", value: "operation-1" }, method: "GET", path }] }],
+  diagnostics: [],
+});
+
+describe("state parity", () => {
+  it("reports equal canonical memory and SQLite digests", () => {
+    expect(new StateParityService({ get: () => snapshot() }).compare(snapshot()).status).toBe("match");
+  });
+
+  it("reports a structured mismatch and unavailable database", () => {
+    expect(new StateParityService({ get: () => snapshot("/other") }).compare(snapshot()).status).toBe("mismatch");
+    expect(new StateParityService({ get: () => null }).compare(snapshot()).status).toBe("unavailable");
+  });
+});