refactor(cli): derive legacy sandbox dispatch from metadata

src/commands/sandbox/snapshot/create.ts

@@ -8,7 +8,7 @@ export default withCommandDisplay(Command, [
   {
     usage: "nemoclaw <name> snapshot create",
     description: "Create a snapshot of sandbox state",
-    flags: "[--name <label>]",
+    flags: "[--name <name>]",
     group: "Sandbox Management",
     scope: "sandbox",
     order: 7,

src/commands/sandbox/snapshot/restore.ts

@@ -8,7 +8,7 @@ export default withCommandDisplay(Command, [
   {
     usage: "nemoclaw <name> snapshot restore",
     description: "Restore state from a snapshot",
-    flags: "[v<N>|name|timestamp] [--to <dst>] (omit version for latest; auto-creates <dst> from this sandbox image if needed)",
+    flags: "[selector] [--to <dst>]",
     group: "Sandbox Management",
     scope: "sandbox",
     order: 9,

src/lib/cli/oclif-dispatch.test.ts

@@ -3,7 +3,7 @@
 
 import { describe, expect, it } from "vitest";
 
-import { resolveGlobalOclifDispatch, resolveSandboxOclifDispatch } from "./oclif-dispatch";
+import { resolveGlobalOclifDispatch, resolveLegacySandboxDispatch } from "./oclif-dispatch";
 
 describe("resolveGlobalOclifDispatch", () => {
   it("routes simple and nested global commands through oclif", () => {
@@ -43,62 +43,62 @@ describe("resolveGlobalOclifDispatch", () => {
   });
 });
 
-describe("resolveSandboxOclifDispatch", () => {
-  it("routes sandbox status through oclif", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "status", [])).toEqual({
+describe("resolveLegacySandboxDispatch", () => {
+  it("rewrites simple legacy sandbox actions to oclif command dispatches", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "status", [])).toEqual({
       kind: "oclif",
       commandId: "sandbox:status",
       args: ["alpha"],
     });
-  });
-
-  it("keeps sandbox status help public", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "status", ["--help"])).toMatchObject({
-      kind: "help",
-      usage: "status",
-    });
-  });
-
-  it("routes sandbox doctor through oclif", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "doctor", ["--json"])).toEqual({
+    expect(resolveLegacySandboxDispatch("alpha", "doctor", ["--json"])).toEqual({
       kind: "oclif",
       commandId: "sandbox:doctor",
       args: ["alpha", "--json"],
     });
   });
 
-  it("keeps sandbox doctor help public", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "doctor", ["--help"])).toMatchObject({
-      kind: "help",
-      usage: "doctor [--json]",
+  it("rewrites legacy hyphenated actions to oclif-native command ids", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "policy-add", ["--from-file"])).toEqual({
+      kind: "oclif",
+      commandId: "sandbox:policy:add",
+      args: ["alpha", "--from-file"],
+    });
+    expect(resolveLegacySandboxDispatch("alpha", "gateway-token", ["--quiet"])).toEqual({
+      kind: "oclif",
+      commandId: "sandbox:gateway:token",
+      args: ["alpha", "--quiet"],
     });
   });
 
-  it("keeps sandbox logs help public with supported filters", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "logs", ["--help"])).toMatchObject({
+  it("keeps legacy public help usage for sandbox-scoped commands", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "status", ["--help"])).toEqual({
+      kind: "help",
+      commandId: "sandbox:status",
+      publicUsage: "<name> status",
+    });
+    expect(resolveLegacySandboxDispatch("alpha", "logs", ["--help"])).toEqual({
       kind: "help",
-      usage: "logs [--follow] [--tail <lines>|-n <lines>] [--since <duration>]",
+      commandId: "sandbox:logs",
+      publicUsage: "<name> logs [--follow] [--tail <lines>|-n <lines>] [--since <duration>]",
     });
   });
 
-  it("routes sandbox recover through oclif", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "recover", [])).toEqual({
+  it("rewrites sandbox recover through metadata-derived dispatch", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "recover", [])).toEqual({
       kind: "oclif",
       commandId: "sandbox:recover",
       args: ["alpha"],
     });
-  });
-
-  it("returns help for sandbox recover", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "recover", ["--help"])).toMatchObject({
+    expect(resolveLegacySandboxDispatch("alpha", "recover", ["--help"])).toEqual({
       kind: "help",
-      usage: "recover",
+      commandId: "sandbox:recover",
+      publicUsage: "<name> recover",
     });
   });
 
-  it("routes sandbox config set through oclif with security flags intact", () => {
+  it("rewrites config set through metadata-derived dispatch", () => {
     expect(
-      resolveSandboxOclifDispatch("alpha", "config", [
+      resolveLegacySandboxDispatch("alpha", "config", [
         "set",
         "--key",
         "inference.endpoints",
@@ -120,47 +120,56 @@ describe("resolveSandboxOclifDispatch", () => {
     });
   });
 
-  it("routes policy-add missing-value errors through the strict oclif adapter", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "policy-add", ["--from-file"])).toEqual({
+  it("rewrites nested sandbox subcommands and defaults", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "channels", [])).toEqual({
       kind: "oclif",
-      commandId: "sandbox:policy:add",
-      args: ["alpha", "--from-file"],
+      commandId: "sandbox:channels:list",
+      args: ["alpha"],
+    });
+    expect(resolveLegacySandboxDispatch("alpha", "channels", ["add", "slack"])).toEqual({
+      kind: "oclif",
+      commandId: "sandbox:channels:add",
+      args: ["alpha", "slack"],
+    });
+    expect(resolveLegacySandboxDispatch("alpha", "snapshot", ["restore", "latest"])).toEqual({
+      kind: "oclif",
+      commandId: "sandbox:snapshot:restore",
+      args: ["alpha", "latest"],
     });
   });
 
-  it("routes skill help and unknown subcommands through oclif", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "skill", ["--help"])).toEqual({
+  it("keeps share parent help public", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "share", ["--help"])).toEqual({
+      kind: "help",
+      commandId: "sandbox:share",
+      publicUsage: "<name> share <mount|unmount|status>",
+    });
+  });
+
+  it("falls back to parent commands that intentionally own unknown subcommands and custom help", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "skill", ["install", "--help"])).toEqual({
       kind: "oclif",
       commandId: "sandbox:skill",
-      args: ["alpha", "--help"],
+      args: ["alpha", "install", "--help"],
     });
-    expect(resolveSandboxOclifDispatch("alpha", "skill", ["bogus"])).toEqual({
+    expect(resolveLegacySandboxDispatch("alpha", "skill", ["bogus"])).toEqual({
       kind: "oclif",
       commandId: "sandbox:skill",
       args: ["alpha", "bogus"],
     });
-  });
-
-  it("routes nested sandbox defaults, help, and usage errors", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "channels", [])).toEqual({
-      kind: "oclif",
-      commandId: "sandbox:channels:list",
-      args: ["alpha"],
-    });
-    expect(resolveSandboxOclifDispatch("alpha", "channels", ["add", "slack"])).toEqual({
+    expect(resolveLegacySandboxDispatch("alpha", "snapshot", ["bogus"])).toEqual({
       kind: "oclif",
-      commandId: "sandbox:channels:add",
-      args: ["alpha", "slack"],
+      commandId: "sandbox:snapshot",
+      args: ["alpha", "bogus"],
     });
-    expect(resolveSandboxOclifDispatch("alpha", "config", ["bogus"])).toEqual({
+  });
+
+  it("preserves legacy usage errors for config and shields groups", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "config", ["bogus"])).toEqual({
       kind: "usageError",
-      lines: [
-        "config <get|set>",
-        "get [--key dotpath] [--format json|yaml]",
-        "set --key <dotpath> --value <value> [--restart] [--config-accept-new-path]",
-      ],
+      lines: ["config get [--key dotpath] [--format json|yaml]"],
     });
-    expect(resolveSandboxOclifDispatch("alpha", "shields", ["bogus"])).toEqual({
+    expect(resolveLegacySandboxDispatch("alpha", "shields", ["bogus"])).toEqual({
       kind: "usageError",
       lines: [
         "shields <down|up|status>",
@@ -171,13 +180,13 @@ describe("resolveSandboxOclifDispatch", () => {
     });
   });
 
-  it("routes snapshot unknown subcommands and unknown actions", () => {
-    expect(resolveSandboxOclifDispatch("alpha", "snapshot", ["bogus"])).toEqual({
-      kind: "oclif",
-      commandId: "sandbox:snapshot",
-      args: ["alpha", "bogus"],
+  it("reports channel subcommand and action errors", () => {
+    expect(resolveLegacySandboxDispatch("alpha", "channels", ["bogus"])).toEqual({
+      kind: "unknownSubcommand",
+      command: "channels",
+      subcommand: "bogus",
     });
-    expect(resolveSandboxOclifDispatch("alpha", "bogus", [])).toEqual({
+    expect(resolveLegacySandboxDispatch("alpha", "bogus", [])).toEqual({
       kind: "unknownAction",
       action: "bogus",
     });