@stigmer/cli 3.0.8

package/src/output/style.ts

@@ -0,0 +1,57 @@
+// Minimal ANSI styling for human-facing output.
+//
+// Mirrors the Go CLI's reliance on fatih/color, which auto-disables when the
+// target stream is not a TTY and honors NO_COLOR. Keeping this tiny avoids a
+// dependency for what is a handful of escape codes.
+
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  faint: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+} as const;
+
+/** A styler whose methods either wrap text in ANSI codes or pass it through. */
+export interface Styler {
+  green(text: string): string;
+  yellow(text: string): string;
+  red(text: string): string;
+  cyan(text: string): string;
+  bold(text: string): string;
+  dim(text: string): string;
+}
+
+const PLAIN: Styler = {
+  green: (t) => t,
+  yellow: (t) => t,
+  red: (t) => t,
+  cyan: (t) => t,
+  bold: (t) => t,
+  dim: (t) => t,
+};
+
+const COLORED: Styler = {
+  green: (t) => `${ANSI.green}${ANSI.bold}${t}${ANSI.reset}`,
+  yellow: (t) => `${ANSI.yellow}${ANSI.bold}${t}${ANSI.reset}`,
+  red: (t) => `${ANSI.red}${ANSI.bold}${t}${ANSI.reset}`,
+  cyan: (t) => `${ANSI.cyan}${t}${ANSI.reset}`,
+  bold: (t) => `${ANSI.bold}${t}${ANSI.reset}`,
+  dim: (t) => `${ANSI.faint}${t}${ANSI.reset}`,
+};
+
+/** Pick a styler: colored only when explicitly enabled. */
+export function styler(colorize: boolean): Styler {
+  return colorize ? COLORED : PLAIN;
+}
+
+/**
+ * Whether color should be enabled for a stream. Disabled when NO_COLOR is set
+ * (any value) or the stream is not an interactive TTY.
+ */
+export function shouldColorize(stream: { isTTY?: boolean }): boolean {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "") return false;
+  return stream.isTTY === true;
+}

package/src/output/table.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { renderEmpty, renderTable } from "./table.js";
+
+describe("renderTable", () => {
+  it("returns empty string for no rows", () => {
+    expect(renderTable(["NAME", "KIND"], [])).toBe("");
+  });
+
+  it("renders aligned columns with a dash separator", () => {
+    const out = renderTable(
+      ["NAME", "KIND"],
+      [
+        ["my-agent", "agent"],
+        ["wf", "workflow"],
+      ],
+    );
+    const lines = out.trimEnd().split("\n");
+    expect(lines[0]).toBe("NAME       KIND");
+    expect(lines[1]).toBe("--------   --------");
+    expect(lines[2]).toBe("my-agent   agent");
+    expect(lines[3]).toBe("wf         workflow");
+  });
+
+  it("tolerates short rows by padding missing cells", () => {
+    const out = renderTable(["A", "B"], [["only"]]);
+    expect(out.trimEnd().split("\n")[2]).toBe("only");
+  });
+});
+
+describe("renderEmpty", () => {
+  it("reports an unfiltered empty state", () => {
+    expect(renderEmpty("agents")).toBe("\nNo agents found\n\n");
+  });
+  it("reports a query-filtered empty state", () => {
+    expect(renderEmpty("agents", "foo")).toBe("\nNo agents found matching 'foo'\n\n");
+  });
+});

package/src/output/table.ts

@@ -0,0 +1,52 @@
+// Shared table renderer for list/collection views. Mirrors the column model of
+// the Go CLI's pkg/display table (dynamic widths, dash separator, 3-space gap).
+//
+// Wave 1 implements the non-adaptive path: columns size to their widest cell.
+// Terminal-width adaptation and ANSI-aware measurement can be layered on later
+// without changing the call sites.
+
+const COLUMN_GAP = "   ";
+
+/** Render a table from headers and rows. Returns "" when there are no rows. */
+export function renderTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[],
+): string {
+  if (rows.length === 0) return "";
+
+  const widths = headers.map((header, column) => {
+    let width = header.length;
+    for (const row of rows) {
+      const cell = row[column] ?? "";
+      if (cell.length > width) width = cell.length;
+    }
+    return width;
+  });
+
+  const renderRow = (cells: readonly string[]): string =>
+    headers
+      .map((_, column) => padRight(cells[column] ?? "", widths[column]))
+      .join(COLUMN_GAP)
+      .replace(/ +$/, "");
+
+  const lines: string[] = [];
+  lines.push(renderRow(headers));
+  lines.push(widths.map((width) => "-".repeat(width)).join(COLUMN_GAP));
+  for (const row of rows) {
+    lines.push(renderRow(row));
+  }
+  return lines.join("\n") + "\n";
+}
+
+/** Standardized empty-state message for list commands. */
+export function renderEmpty(resourceName: string, query?: string): string {
+  const middle =
+    query !== undefined && query !== ""
+      ? `No ${resourceName} found matching '${query}'`
+      : `No ${resourceName} found`;
+  return `\n${middle}\n\n`;
+}
+
+function padRight(text: string, width: number): string {
+  return text + " ".repeat(Math.max(0, width - text.length));
+}

package/src/program.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { buildProgram } from "./program.js";
+import { VERSION } from "./version.js";
+
+describe("buildProgram", () => {
+  it("registers the foundational commands", () => {
+    const program = buildProgram();
+    const names = program.commands.map((command) => command.name()).sort();
+    expect(names).toContain("version");
+    expect(names).toContain("completion");
+  });
+
+  it("registers the Wave 2b read commands", () => {
+    const program = buildProgram();
+    const names = program.commands.map((command) => command.name());
+    expect(names).toEqual(expect.arrayContaining(["search", "usage", "diff"]));
+  });
+
+  it("registers the Wave 2d artifact commands", () => {
+    const program = buildProgram();
+    const names = program.commands.map((command) => command.name());
+    expect(names).toEqual(expect.arrayContaining(["push", "download"]));
+  });
+
+  it("registers the Wave 3c streaming commands", () => {
+    const program = buildProgram();
+    const names = program.commands.map((command) => command.name());
+    expect(names).toEqual(expect.arrayContaining(["run", "resume", "draft"]));
+  });
+
+  it("exposes the draft subcommands", () => {
+    const program = buildProgram();
+    const draft = program.commands.find((command) => command.name() === "draft");
+    const subs = draft?.commands.map((command) => command.name()).sort();
+    expect(subs).toEqual(["agent", "mcp-server", "skill"]);
+  });
+
+  it("marks draft subcommands' --message as required", () => {
+    const program = buildProgram();
+    const draft = program.commands.find((command) => command.name() === "draft");
+    const skill = draft?.commands.find((command) => command.name() === "skill");
+    const message = skill?.options.find((option) => option.long === "--message");
+    expect(message?.required).toBe(true);
+  });
+
+  it("exposes the usage subcommands", () => {
+    const program = buildProgram();
+    const usage = program.commands.find((command) => command.name() === "usage");
+    const subs = usage?.commands.map((command) => command.name()).sort();
+    expect(subs).toEqual(["agent", "org", "session"]);
+  });
+
+  it("exposes the global flags as persistent options", () => {
+    const program = buildProgram();
+    const longFlags = program.options.map((option) => option.long);
+    expect(longFlags).toEqual(
+      expect.arrayContaining(["--debug", "--standalone", "--org", "--api-key"]),
+    );
+  });
+
+  it("reports a semver-shaped version", () => {
+    expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});

package/src/program.ts

@@ -0,0 +1,100 @@
+// Builds the root commander program: global flags, the preAction hook that
+// captures them into process-global runtime state, and command registration.
+//
+// Command modules are registered through small `register*` functions so the
+// entry path stays light; heavier commands lazy-load their implementation via
+// dynamic import inside the action (DD-001), so `stigmer --help`/`version`/
+// `completion` never pay for importing the backend client or auth stack.
+
+import { Command } from "commander";
+import { registerApiKey } from "./commands/apikey/index.js";
+import { registerApply } from "./commands/apply.js";
+import { registerAuth } from "./commands/auth/index.js";
+import { registerCompletion } from "./commands/completion.js";
+import { registerConfig } from "./commands/config/index.js";
+import { registerConnect } from "./commands/connect.js";
+import { registerDelete } from "./commands/delete.js";
+import { registerDiff } from "./commands/diff.js";
+import { registerDown } from "./commands/down.js";
+import { registerDownload } from "./commands/download.js";
+import { registerDraft } from "./commands/draft.js";
+import { registerExecution } from "./commands/execution/index.js";
+import { registerGet } from "./commands/get.js";
+import { registerInternalDaemon } from "./commands/internal-daemon.js";
+import { registerList } from "./commands/list.js";
+import { registerLogs } from "./commands/logs.js";
+import { registerMcpServer } from "./commands/mcp-server.js";
+import { registerPush } from "./commands/push.js";
+import { registerReset } from "./commands/reset.js";
+import { registerResume } from "./commands/resume.js";
+import { registerRun } from "./commands/run.js";
+import { registerSearch } from "./commands/search.js";
+import { registerSeedpack } from "./commands/seedpack.js";
+import { registerSetup } from "./commands/setup.js";
+import { registerStatus } from "./commands/status.js";
+import { registerTag } from "./commands/tag.js";
+import { registerUp } from "./commands/up.js";
+import { registerUsage } from "./commands/usage.js";
+import { registerValidate } from "./commands/validate.js";
+import { registerVersion } from "./commands/version.js";
+import { setDebug, setStandalone } from "./runtime.js";
+import { VERSION } from "./version.js";
+
+export function buildProgram(): Command {
+  const program = new Command();
+
+  program
+    .name("stigmer")
+    .description("Stigmer command-line interface")
+    .version(VERSION, "--version", "print the CLI version")
+    .option("-d, --debug", "enable debug output")
+    .option("--standalone", "ignore the config file; use flags and environment only")
+    .option("--org <slug>", "organization slug override")
+    .option("--api-key <key>", "API key for authentication")
+    .enablePositionalOptions();
+
+  // Capture global flags into process-global state before any command runs.
+  // Bridging --api-key to the env mirrors the Go CLI's PersistentPreRun so the
+  // SDK auth interceptor and config layer pick it up uniformly.
+  program.hook("preAction", () => {
+    const globals = program.opts();
+    setDebug(Boolean(globals.debug));
+    setStandalone(Boolean(globals.standalone));
+    if (typeof globals.apiKey === "string" && globals.apiKey !== "") {
+      process.env.STIGMER_API_KEY = globals.apiKey;
+    }
+  });
+
+  registerVersion(program);
+  registerCompletion(program);
+  registerConfig(program);
+  registerAuth(program);
+  registerApiKey(program);
+  registerGet(program);
+  registerList(program);
+  registerSearch(program);
+  registerValidate(program);
+  registerDelete(program);
+  registerTag(program);
+  registerDiff(program);
+  registerUsage(program);
+  registerPush(program);
+  registerDownload(program);
+  registerApply(program);
+  registerRun(program);
+  registerResume(program);
+  registerDraft(program);
+  registerExecution(program);
+  registerConnect(program);
+  registerMcpServer(program);
+  registerUp(program);
+  registerDown(program);
+  registerStatus(program);
+  registerLogs(program);
+  registerSeedpack(program);
+  registerSetup(program);
+  registerReset(program);
+  registerInternalDaemon(program);
+
+  return program;
+}

package/src/registry/aliases.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { generateAliases, normalizeAlias, pluralize, toKebabCase, toSnakeCase } from "./aliases.js";
+
+function normalized(aliases: string[]): Set<string> {
+  return new Set(aliases.map(normalizeAlias));
+}
+
+describe("generateAliases", () => {
+  it("derives the full McpServer alias set", () => {
+    const found = normalized(generateAliases("McpServer", "MCP Server", "mcp"));
+    for (const exp of [
+      "mcpserver",
+      "mcp-server",
+      "mcp_server",
+      "mcp",
+      "mcpservers",
+      "mcp-servers",
+      "mcp_servers",
+      "mcps",
+    ]) {
+      expect(found).toContain(exp);
+    }
+  });
+
+  it("derives the Agent alias set", () => {
+    const found = normalized(generateAliases("Agent", "Agent", "agt"));
+    for (const exp of ["agent", "agt", "agents", "agts"]) {
+      expect(found).toContain(exp);
+    }
+  });
+
+  it("derives the Workflow alias set", () => {
+    const found = normalized(generateAliases("Workflow", "Workflow", "wfl"));
+    for (const exp of ["workflow", "wfl", "workflows", "wfls"]) {
+      expect(found).toContain(exp);
+    }
+  });
+
+  it("does not let a multi-word display name steal the parent's name", () => {
+    // "Agent Instance" must NOT register "agent" (that belongs to Agent).
+    const found = normalized(generateAliases("AgentInstance", "Agent Instance", "ain"));
+    expect(found).not.toContain("agent");
+    expect(found).toContain("agentinstance");
+    expect(found).toContain("agent-instance");
+    expect(found).toContain("ain");
+  });
+
+  it("produces no duplicate normalized aliases", () => {
+    const aliases = generateAliases("Agent", "Agent", "agent");
+    const lower = aliases.map(normalizeAlias);
+    expect(new Set(lower).size).toBe(lower.length);
+  });
+});
+
+describe("case conversion", () => {
+  it.each([
+    ["McpServer", "mcp-server"],
+    ["Agent", "agent"],
+    ["AgentInstance", "agent-instance"],
+    ["WorkflowExecution", "workflow-execution"],
+    ["", ""],
+  ])("toKebabCase(%s) = %s", (input, expected) => {
+    expect(toKebabCase(input)).toBe(expected);
+  });
+
+  it.each([
+    ["McpServer", "mcp_server"],
+    ["Agent", "agent"],
+    ["AgentInstance", "agent_instance"],
+    ["WorkflowExecution", "workflow_execution"],
+    ["", ""],
+  ])("toSnakeCase(%s) = %s", (input, expected) => {
+    expect(toSnakeCase(input)).toBe(expected);
+  });
+});
+
+describe("pluralize", () => {
+  it.each([
+    ["agent", "agents"],
+    ["workflow", "workflows"],
+    ["mcpserver", "mcpservers"],
+    ["agents", "agents"],
+    ["", ""],
+  ])("pluralize(%s) = %s", (input, expected) => {
+    expect(pluralize(input)).toBe(expected);
+  });
+});
+
+describe("normalizeAlias", () => {
+  it.each([
+    ["Agent", "agent"],
+    ["  agent  ", "agent"],
+    ["MCP-Server", "mcp-server"],
+    ["WORKFLOW", "workflow"],
+    ["", ""],
+  ])("normalizeAlias(%s) = %s", (input, expected) => {
+    expect(normalizeAlias(input)).toBe(expected);
+  });
+});

package/src/registry/aliases.ts

@@ -0,0 +1,93 @@
+// Algorithmic alias generation — a faithful port of the Go types.GenerateAliases
+// family. Aliases are *derived* from proto kind metadata (name/display_name/
+// id_prefix), never hardcoded, so a new resource kind picks up its full set of
+// accepted spellings automatically. Keeping the algorithm byte-for-byte
+// identical to Go guarantees both CLIs accept exactly the same inputs.
+
+/**
+ * Generate every accepted input form for a resource kind.
+ *
+ * From name "McpServer":      "mcpserver", "mcp-server", "mcp_server", "McpServer"
+ * From displayName "MCP Server": "mcp" / "MCP"
+ * From idPrefix "mcp":         "mcp"
+ * Plus the plural of every form above.
+ */
+export function generateAliases(name: string, displayName: string, idPrefix: string): string[] {
+  const seen = new Set<string>();
+  const aliases: string[] = [];
+
+  const add = (alias: string): void => {
+    if (alias === "") return;
+    const lower = alias.toLowerCase();
+    if (!seen.has(lower)) {
+      seen.add(lower);
+      aliases.push(alias);
+    }
+  };
+
+  // From name: "McpServer"
+  add(name.toLowerCase()); // "mcpserver"
+  add(toKebabCase(name)); // "mcp-server"
+  add(toSnakeCase(name)); // "mcp_server"
+  add(name); // "McpServer"
+
+  // From display_name: single-word names contribute lower/upper forms; for
+  // multi-word names only the first word is added, and only when it does not
+  // simply re-derive the name (this stops "Agent Instance" from stealing
+  // "agent" from "Agent", while still letting "MCP Server" register "mcp").
+  const words = displayName.split(/\s+/).filter((w) => w.length > 0);
+  if (words.length === 1) {
+    add(words[0].toLowerCase());
+    add(words[0].toUpperCase());
+  } else if (words.length > 1) {
+    const firstWord = words[0].toLowerCase();
+    const lowerName = name.toLowerCase();
+    if (!lowerName.startsWith(firstWord) || firstWord === lowerName) {
+      add(firstWord);
+      add(words[0].toUpperCase());
+    }
+  }
+
+  // From id_prefix: "mcp"
+  add(idPrefix);
+
+  // Plurals of every form gathered so far.
+  for (const alias of [...aliases]) {
+    add(pluralize(alias));
+  }
+
+  return aliases;
+}
+
+/** Convert PascalCase to kebab-case: "McpServer" -> "mcp-server". */
+export function toKebabCase(s: string): string {
+  return splitCase(s, "-");
+}
+
+/** Convert PascalCase to snake_case: "McpServer" -> "mcp_server". */
+export function toSnakeCase(s: string): string {
+  return splitCase(s, "_");
+}
+
+function splitCase(s: string, sep: string): string {
+  let result = "";
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (i > 0 && ch >= "A" && ch <= "Z") {
+      result += sep;
+    }
+    result += ch.toLowerCase();
+  }
+  return result;
+}
+
+/** Naive English pluralization; the singular is always accepted too. */
+export function pluralize(s: string): string {
+  if (s === "" || s.endsWith("s")) return s;
+  return `${s}s`;
+}
+
+/** Normalize user input for case-insensitive alias lookup. */
+export function normalizeAlias(input: string): string {
+  return input.trim().toLowerCase();
+}

package/src/registry/index.ts

@@ -0,0 +1,7 @@
+// Public surface of the type-registry module.
+
+export { generateAliases, normalizeAlias, pluralize, toKebabCase, toSnakeCase } from "./aliases.js";
+export { CLI_RELEVANT_KINDS, type KindMeta, KIND_META } from "./metadata.js";
+export { defaultRegistry, type Registry, supportsVerb, type TypeInfo } from "./registry.js";
+export { ALL_VERBS, isFileBasedVerb, isReferenceBasedVerb, Verb } from "./verbs.js";
+export { VERB_SUPPORT, verbsForKind } from "./verb-support.js";

package/src/registry/metadata.ts

@@ -0,0 +1,60 @@
+// Declarative mirror of api_resource_kind.proto `kind_meta` for CLI-relevant
+// kinds.
+//
+// Why a hand-maintained table instead of reading the proto extension at
+// runtime: protobuf-es does not surface custom enum-value options (the
+// `kind_meta` extension) through its runtime reflection the way Go's protobuf
+// reflection does. The SDK already established this pattern — see
+// `sdk/typescript/src/gen/resource-availability.ts`, a generated table derived
+// from the same `kind_meta`. T06's codegen pass can emit THIS file the same
+// way; until then the table is small, stable, and guarded by tests that pin the
+// derived aliases. Values below are copied verbatim from the proto.
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+export interface KindMeta {
+  /** Proto kind_meta.name — also the YAML `kind` value (e.g. "McpServer"). */
+  readonly name: string;
+  /** Proto kind_meta.display_name (e.g. "MCP Server"). */
+  readonly displayName: string;
+  /** Proto kind_meta.id_prefix (e.g. "mcp"). */
+  readonly idPrefix: string;
+}
+
+export const KIND_META: ReadonlyMap<ApiResourceKind, KindMeta> = new Map([
+  [ApiResourceKind.organization, { name: "Organization", displayName: "Organization", idPrefix: "org" }],
+  [ApiResourceKind.agent, { name: "Agent", displayName: "Agent", idPrefix: "agt" }],
+  [ApiResourceKind.workflow, { name: "Workflow", displayName: "Workflow", idPrefix: "wfl" }],
+  [ApiResourceKind.skill, { name: "Skill", displayName: "Skill", idPrefix: "skl" }],
+  [ApiResourceKind.mcp_server, { name: "McpServer", displayName: "MCP Server", idPrefix: "mcp" }],
+  [ApiResourceKind.project, { name: "Project", displayName: "Project", idPrefix: "prj" }],
+  [ApiResourceKind.api_key, { name: "ApiKey", displayName: "API Key", idPrefix: "key" }],
+  [ApiResourceKind.identity_provider, { name: "IdentityProvider", displayName: "Identity Provider", idPrefix: "idp" }],
+  [ApiResourceKind.oauth_app, { name: "OAuthApp", displayName: "OAuth App", idPrefix: "oapp" }],
+  [ApiResourceKind.environment, { name: "Environment", displayName: "Environment", idPrefix: "env" }],
+  [ApiResourceKind.agent_instance, { name: "AgentInstance", displayName: "Agent Instance", idPrefix: "ain" }],
+  [ApiResourceKind.workflow_instance, { name: "WorkflowInstance", displayName: "Workflow Instance", idPrefix: "win" }],
+  [ApiResourceKind.session, { name: "Session", displayName: "Session", idPrefix: "ses" }],
+  [ApiResourceKind.agent_execution, { name: "AgentExecution", displayName: "Agent Execution", idPrefix: "aex" }],
+]);
+
+// Kinds that are user-facing in the CLI and therefore registered as addressable
+// types. Mirrors Go's `cliRelevantKinds`. Note: agent_execution is intentionally
+// excluded — it is driven through its dedicated AgentExecutionQueryController
+// RPCs as a command special-case, not the generic verb dispatch, even though it
+// carries kind metadata above and a verb-support entry below.
+export const CLI_RELEVANT_KINDS: readonly ApiResourceKind[] = [
+  ApiResourceKind.organization,
+  ApiResourceKind.agent,
+  ApiResourceKind.workflow,
+  ApiResourceKind.skill,
+  ApiResourceKind.mcp_server,
+  ApiResourceKind.project,
+  ApiResourceKind.api_key,
+  ApiResourceKind.identity_provider,
+  ApiResourceKind.oauth_app,
+  ApiResourceKind.environment,
+  ApiResourceKind.agent_instance,
+  ApiResourceKind.workflow_instance,
+  ApiResourceKind.session,
+];

package/src/registry/registry.test.ts

@@ -0,0 +1,80 @@
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { describe, expect, it } from "vitest";
+import { defaultRegistry } from "./registry.js";
+import { Verb } from "./verbs.js";
+
+const registry = defaultRegistry();
+
+describe("registry — alias resolution", () => {
+  it.each([
+    ["mcp", ApiResourceKind.mcp_server],
+    ["mcp-server", ApiResourceKind.mcp_server],
+    ["mcp_server", ApiResourceKind.mcp_server],
+    ["McpServer", ApiResourceKind.mcp_server],
+    ["mcpservers", ApiResourceKind.mcp_server],
+    ["agent", ApiResourceKind.agent],
+    ["agents", ApiResourceKind.agent],
+    ["agt", ApiResourceKind.agent],
+    ["workflow", ApiResourceKind.workflow],
+    ["wfl", ApiResourceKind.workflow],
+    ["org", ApiResourceKind.organization],
+    ["oapp", ApiResourceKind.oauth_app],
+  ])("resolves %s -> kind", (alias, kind) => {
+    expect(registry.getByAlias(alias)?.kind).toBe(kind);
+  });
+
+  it("resolution is case-insensitive", () => {
+    expect(registry.getByAlias("MCP-SERVER")?.kind).toBe(ApiResourceKind.mcp_server);
+  });
+
+  it("returns undefined for an unknown alias", () => {
+    expect(registry.getByAlias("nope")).toBeUndefined();
+  });
+
+  it("does not register agent_execution as an addressable type", () => {
+    expect(registry.getByKind(ApiResourceKind.agent_execution)).toBeUndefined();
+  });
+});
+
+describe("registry — YAML kind resolution", () => {
+  it("resolves the exact YAML kind", () => {
+    expect(registry.getByYamlKind("McpServer")?.kind).toBe(ApiResourceKind.mcp_server);
+    expect(registry.getByYamlKind("Workflow")?.kind).toBe(ApiResourceKind.workflow);
+  });
+});
+
+describe("registry — verb support matrix", () => {
+  it("agent supports read + run + search verbs", () => {
+    for (const v of [Verb.Apply, Verb.Validate, Verb.Get, Verb.List, Verb.Delete, Verb.Run, Verb.Search]) {
+      expect(registry.supportsVerb(ApiResourceKind.agent, v)).toBe(true);
+    }
+    expect(registry.supportsVerb(ApiResourceKind.agent, Verb.Push)).toBe(false);
+  });
+
+  it("skill supports push but not apply", () => {
+    expect(registry.supportsVerb(ApiResourceKind.skill, Verb.Push)).toBe(true);
+    expect(registry.supportsVerb(ApiResourceKind.skill, Verb.Apply)).toBe(false);
+  });
+
+  it("workflow_instance has no list verb", () => {
+    expect(registry.supportsVerb(ApiResourceKind.workflow_instance, Verb.Get)).toBe(true);
+    expect(registry.supportsVerb(ApiResourceKind.workflow_instance, Verb.List)).toBe(false);
+  });
+
+  it("typesForVerb(get) includes the core read kinds", () => {
+    const kinds = new Set(registry.typesForVerb(Verb.Get).map((t) => t.kind));
+    expect(kinds).toContain(ApiResourceKind.agent);
+    expect(kinds).toContain(ApiResourceKind.workflow);
+    expect(kinds).toContain(ApiResourceKind.mcp_server);
+  });
+});
+
+describe("registry — completeness", () => {
+  it("registers every CLI-relevant kind with metadata", () => {
+    for (const info of registry.all()) {
+      expect(info.name).not.toBe("");
+      expect(info.singular).toBe(info.name.toLowerCase());
+      expect(info.aliases.length).toBeGreaterThan(0);
+    }
+  });
+});