Add named snapshot database targets

giodl73-repo · giodl73-repo · commit addd22047e2b · 2026-06-18T21:49:54.000-07:00
diff --git a/src/cli/program/register.snapshot.test.ts b/src/cli/program/register.snapshot.test.ts
@@ -82,6 +82,30 @@ describe("registerSnapshotCommand", () => {
     );
   });
 
+  it("runs snapshot create for a named global target", async () => {
+    await runCli(["snapshot", "create", "--target", "global", "--repository", "/tmp/snapshots"]);
+
+    expect(mocks.snapshotCreateCommand).toHaveBeenCalledWith(
+      {
+        target: "global",
+        repository: "/tmp/snapshots",
+      },
+      mocks.runtime,
+    );
+  });
+
+  it("runs snapshot create for a named agent target", async () => {
+    await runCli(["snapshot", "create", "--agent", "main", "--repository", "/tmp/snapshots"]);
+
+    expect(mocks.snapshotCreateCommand).toHaveBeenCalledWith(
+      {
+        agent: "main",
+        repository: "/tmp/snapshots",
+      },
+      mocks.runtime,
+    );
+  });
+
   it("runs snapshot list with forwarded options", async () => {
     await runCli(["snapshot", "list", "--repository", "/tmp/snapshots", "--json"]);
 
diff --git a/src/cli/program/register.snapshot.ts b/src/cli/program/register.snapshot.ts
@@ -26,7 +26,9 @@ export function registerSnapshotCommand(program: Command): void {
   snapshot
     .command("create")
     .description("Create a consistent SQLite snapshot in a local repository")
-    .requiredOption("--db <path>", "SQLite database path")
+    .option("--db <path>", "SQLite database path")
+    .option("--target <target>", "OpenClaw database target (global)")
+    .option("--agent <id>", "OpenClaw agent id for the per-agent database")
     .requiredOption("--repository <path>", "Snapshot repository directory")
     .option("--id <id>", "Logical database id recorded in the manifest")
     .option("--kind <kind>", "Logical database kind recorded in the manifest")
diff --git a/src/commands/snapshot.test.ts b/src/commands/snapshot.test.ts
@@ -12,13 +12,20 @@ import {
 } from "./snapshot.js";
 
 let workspaceDir: string;
+let previousOpenClawStateDir: string | undefined;
 
 describe("snapshot cli", () => {
   beforeEach(async () => {
+    previousOpenClawStateDir = process.env.OPENCLAW_STATE_DIR;
     workspaceDir = await fs.mkdtemp(path.join(tmpdir(), "snapshot-cli-"));
   });
 
   afterEach(async () => {
+    if (previousOpenClawStateDir === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = previousOpenClawStateDir;
+    }
     await fs.rm(workspaceDir, { recursive: true, force: true });
   });
 
@@ -107,10 +114,90 @@ describe("snapshot cli", () => {
     await expect(snapshotCreateCommand({ repository: workspaceDir }, runtime)).resolves.toBe(2);
 
     expect(runtime.logs).toEqual([]);
-    expect(runtime.errors).toEqual(["Missing required --db value."]);
+    expect(runtime.errors).toEqual([
+      "Missing snapshot source. Provide one of --db <path>, --target global, or --agent <id>.",
+    ]);
+  });
+
+  it("creates a snapshot from the named global OpenClaw database", async () => {
+    const runtime = createRuntimeCapture();
+    const stateDir = path.join(workspaceDir, "state-root");
+    const dbPath = path.join(stateDir, "state", "openclaw.sqlite");
+    const repositoryPath = path.join(workspaceDir, "snapshots");
+    process.env.OPENCLAW_STATE_DIR = stateDir;
+    await createSqliteDatabase(dbPath, "from-global");
+
+    await expect(
+      snapshotCreateCommand({ target: "global", repository: repositoryPath, json: true }, runtime),
+    ).resolves.toBe(0);
+
+    const createReport = JSON.parse(runtime.logs.shift() ?? "{}") as {
+      snapshotPath?: string;
+      manifest?: { database?: { id?: string; kind?: string } };
+    };
+    expect(createReport.snapshotPath).toBeTruthy();
+    expect(createReport.manifest?.database).toMatchObject({
+      id: "global",
+      kind: "global-control-plane",
+    });
+    expect(runtime.errors).toEqual([]);
+  });
+
+  it("creates a snapshot from the named per-agent OpenClaw database", async () => {
+    const runtime = createRuntimeCapture();
+    const stateDir = path.join(workspaceDir, "state-root");
+    const dbPath = path.join(stateDir, "agents", "ops-team", "agent", "openclaw-agent.sqlite");
+    const repositoryPath = path.join(workspaceDir, "snapshots");
+    process.env.OPENCLAW_STATE_DIR = stateDir;
+    await createSqliteDatabase(dbPath, "from-agent");
+
+    await expect(
+      snapshotCreateCommand({ agent: "Ops Team", repository: repositoryPath, json: true }, runtime),
+    ).resolves.toBe(0);
+
+    const createReport = JSON.parse(runtime.logs.shift() ?? "{}") as {
+      snapshotPath?: string;
+      manifest?: { database?: { id?: string; kind?: string } };
+    };
+    expect(createReport.snapshotPath).toBeTruthy();
+    expect(createReport.manifest?.database).toMatchObject({
+      id: "agent:ops-team",
+      kind: "agent-data-plane",
+    });
+    expect(runtime.errors).toEqual([]);
+  });
+
+  it("rejects ambiguous snapshot source selectors", async () => {
+    const runtime = createRuntimeCapture();
+
+    await expect(
+      snapshotCreateCommand(
+        { db: "/tmp/source.sqlite", target: "global", repository: workspaceDir },
+        runtime,
+      ),
+    ).resolves.toBe(2);
+
+    expect(runtime.logs).toEqual([]);
+    expect(runtime.errors).toEqual([
+      "Choose only one snapshot source: --db, --target, or --agent.",
+    ]);
   });
 });
 
+async function createSqliteDatabase(dbPath: string, value: string): Promise<void> {
+  await fs.mkdir(path.dirname(dbPath), { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  try {
+    db.exec(`
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE entries (value TEXT NOT NULL);
+    `);
+    db.prepare("INSERT INTO entries (value) VALUES (?)").run(value);
+  } finally {
+    db.close();
+  }
+}
+
 function createRuntimeCapture(): RuntimeEnv & {
   readonly logs: string[];
   readonly errors: string[];
diff --git a/src/commands/snapshot.ts b/src/commands/snapshot.ts
@@ -1,14 +1,19 @@
 // Core command handlers for SQLite snapshot artifacts.
+import { normalizeAgentId } from "../routing/session-key.js";
+import { type RuntimeEnv, writeRuntimeJson } from "../runtime.js";
 import { createLocalSqliteSnapshotProvider } from "../snapshot/local-repository.js";
 import type {
   SnapshotManifest,
   SnapshotSummary,
   SnapshotVerificationResult,
 } from "../snapshot/snapshot-provider.js";
-import { type RuntimeEnv, writeRuntimeJson } from "../runtime.js";
+import { resolveOpenClawAgentSqlitePath } from "../state/openclaw-agent-db.paths.js";
+import { resolveOpenClawStateSqlitePath } from "../state/openclaw-state-db.paths.js";
 
 export interface SnapshotCreateOptions {
   readonly db?: string;
+  readonly target?: string;
+  readonly agent?: string;
   readonly repository?: string;
   readonly id?: string;
   readonly kind?: string;
@@ -48,18 +53,24 @@ type SnapshotListReport = {
   readonly snapshots: readonly SnapshotSummary[];
 };
 
+type SnapshotCreateSource = {
+  readonly path: string;
+  readonly id?: string;
+  readonly kind?: string;
+};
+
 export async function snapshotCreateCommand(
   options: SnapshotCreateOptions,
   runtime: RuntimeEnv,
 ): Promise<number> {
   try {
     const repositoryPath = requireOption(options.repository, "--repository");
-    const dbPath = requireOption(options.db, "--db");
+    const source = resolveSnapshotCreateSource(options);
     const provider = createLocalSqliteSnapshotProvider({ repositoryPath });
     const result = await provider.create({
-      path: dbPath,
-      ...(options.id ? { id: options.id } : {}),
-      ...(options.kind ? { kind: options.kind } : {}),
+      path: source.path,
+      ...(source.id ? { id: source.id } : {}),
+      ...(source.kind ? { kind: source.kind } : {}),
     });
     writeCreateReport(
       { ok: true, snapshotPath: result.ref.path, manifest: result.manifest },
@@ -125,6 +136,46 @@ export async function snapshotListCommand(
   }
 }
 
+function resolveSnapshotCreateSource(options: SnapshotCreateOptions): SnapshotCreateSource {
+  const selectors = [
+    hasValue(options.db),
+    hasValue(options.target),
+    hasValue(options.agent),
+  ].filter(Boolean).length;
+  if (selectors === 0) {
+    throw new Error(
+      "Missing snapshot source. Provide one of --db <path>, --target global, or --agent <id>.",
+    );
+  }
+  if (selectors > 1) {
+    throw new Error("Choose only one snapshot source: --db, --target, or --agent.");
+  }
+  if (hasValue(options.db)) {
+    return {
+      path: requireValue(options.db, "--db"),
+      ...(options.id ? { id: options.id } : {}),
+      ...(options.kind ? { kind: options.kind } : {}),
+    };
+  }
+  if (hasValue(options.target)) {
+    const target = requireValue(options.target, "--target").toLowerCase();
+    if (target !== "global") {
+      throw new Error(`Unsupported snapshot target "${target}". Supported targets: global.`);
+    }
+    return {
+      path: resolveOpenClawStateSqlitePath(),
+      id: options.id ?? "global",
+      kind: options.kind ?? "global-control-plane",
+    };
+  }
+  const agentId = normalizeAgentId(requireValue(options.agent, "--agent"));
+  return {
+    path: resolveOpenClawAgentSqlitePath({ agentId }),
+    id: options.id ?? `agent:${agentId}`,
+    kind: options.kind ?? "agent-data-plane",
+  };
+}
+
 function writeCreateReport(
   report: SnapshotCreateReport,
   options: SnapshotJsonOptions,
@@ -193,6 +244,10 @@ function requireOption(value: string | undefined, flag: string): string {
   return requireValue(value, flag);
 }
 
+function hasValue(value: string | undefined): boolean {
+  return value !== undefined && value.trim() !== "";
+}
+
 function requireValue(value: string | undefined, label: string): string {
   if (value === undefined || value.trim() === "") {
     throw new Error(`Missing required ${label} value.`);
