@stigmer/cli 3.0.8

package/src/resources/ignore/pattern.ts

@@ -0,0 +1,131 @@
+// Faithful port of go-git's plumbing/format/gitignore Pattern (ParsePattern +
+// Match). This is what gives `push` its exact gitignore semantics: domain
+// scoping, directory-only patterns, single-name vs glob matching, and the
+// `**` zero-to-many-directories wildcard.
+
+import { matchName } from "./match.js";
+
+export enum MatchResult {
+  NoMatch = 0,
+  Exclude = 1,
+  Include = 2,
+}
+
+const INCLUSION_PREFIX = "!";
+const ZERO_TO_MANY = "**";
+const DIR_SEP = "/";
+
+export interface Pattern {
+  /** Whether this is a negation (`!`) pattern — needed for source ordering. */
+  readonly inclusion: boolean;
+  match(path: readonly string[], isDir: boolean): MatchResult;
+}
+
+class GitignorePattern implements Pattern {
+  readonly inclusion: boolean;
+  private readonly domain: readonly string[];
+  private readonly parts: readonly string[];
+  private readonly dirOnly: boolean;
+  private readonly isGlob: boolean;
+
+  constructor(domain: readonly string[], parts: readonly string[], inclusion: boolean, dirOnly: boolean, isGlob: boolean) {
+    this.domain = domain;
+    this.parts = parts;
+    this.inclusion = inclusion;
+    this.dirOnly = dirOnly;
+    this.isGlob = isGlob;
+  }
+
+  match(path: readonly string[], isDir: boolean): MatchResult {
+    const matchResult = this.inclusion ? MatchResult.Include : MatchResult.Exclude;
+
+    if (path.length <= this.domain.length) return MatchResult.NoMatch;
+    for (let i = 0; i < this.domain.length; i++) {
+      if (path[i] !== this.domain[i]) return MatchResult.NoMatch;
+    }
+
+    const scoped = path.slice(this.domain.length);
+    const matched = this.isGlob ? this.globMatch(scoped, isDir) : this.simpleNameMatch(scoped, isDir);
+    return matched ? matchResult : MatchResult.NoMatch;
+  }
+
+  private simpleNameMatch(path: readonly string[], isDir: boolean): boolean {
+    for (let i = 0; i < path.length; i++) {
+      if (!matchName(this.parts[0], path[i])) continue;
+      if (this.dirOnly && !isDir && i === path.length - 1) return false;
+      return true;
+    }
+    return false;
+  }
+
+  private globMatch(path: readonly string[], isDir: boolean): boolean {
+    let matched = false;
+    let canTraverse = false;
+    let remaining = path;
+
+    for (let i = 0; i < this.parts.length; i++) {
+      const part = this.parts[i];
+      if (part === "") {
+        canTraverse = false;
+        continue;
+      }
+      if (part === ZERO_TO_MANY) {
+        if (i === this.parts.length - 1) break;
+        canTraverse = true;
+        continue;
+      }
+      if (part.includes(ZERO_TO_MANY)) return false;
+      if (remaining.length === 0) return false;
+
+      if (canTraverse) {
+        canTraverse = false;
+        for (;;) {
+          if (remaining.length === 0) {
+            matched = false;
+            break;
+          }
+          const e = remaining[0];
+          remaining = remaining.slice(1);
+          if (matchName(part, e)) {
+            matched = true;
+            break;
+          }
+        }
+      } else {
+        if (!matchName(part, remaining[0])) return false;
+        matched = true;
+        remaining = remaining.slice(1);
+      }
+    }
+
+    if (matched && this.dirOnly && !isDir && remaining.length === 0) {
+      matched = false;
+    }
+    return matched;
+  }
+}
+
+/** Parse a gitignore pattern string into a matchable Pattern (go-git parity). */
+export function parsePattern(raw: string, domain: readonly string[]): Pattern {
+  let p = raw;
+  let inclusion = false;
+
+  if (p.startsWith(INCLUSION_PREFIX)) {
+    inclusion = true;
+    p = p.slice(1);
+  }
+
+  if (!p.endsWith("\\ ")) {
+    p = p.replace(/ +$/, "");
+  }
+
+  let dirOnly = false;
+  if (p.endsWith(DIR_SEP)) {
+    dirOnly = true;
+    p = p.slice(0, -1);
+  }
+
+  const isGlob = p.includes(DIR_SEP);
+  const parts = p.split(DIR_SEP);
+  return new GitignorePattern(domain, parts, inclusion, dirOnly, isGlob);
+}

package/src/resources/list.ts

@@ -0,0 +1,97 @@
+// `list` dispatch: render a collection of resources for a kind.
+//
+// Most registry kinds are search-indexed and list through the unified
+// SearchService (matching the Go CLI's search-backed list). Organizations and
+// API keys are not search-indexed and use their dedicated find RPCs.
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import { SearchResultSchema } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../errors/index.js";
+import type { OutputFormat } from "../output/index.js";
+import { bool, type JsonObject, obj, renderCollection, str, type TableShape } from "./render.js";
+
+// Kinds the SearchService indexes; mirrors the Go CLI's search-backed list set.
+const SEARCH_KINDS = new Set<ApiResourceKind>([
+  ApiResourceKind.agent,
+  ApiResourceKind.workflow,
+  ApiResourceKind.mcp_server,
+  ApiResourceKind.project,
+  ApiResourceKind.skill,
+]);
+
+export async function listResources(
+  client: Stigmer,
+  kind: ApiResourceKind,
+  org: string,
+  limit: number,
+  format: OutputFormat,
+): Promise<string> {
+  if (kind === ApiResourceKind.organization) {
+    const result = await client.organization.findMyOrganizations();
+    return renderCollection(OrganizationSchema, result.entries, format, ORG_TABLE);
+  }
+  if (kind === ApiResourceKind.api_key) {
+    const result = await client.apiKey.findAll();
+    return renderCollection(ApiKeySchema, result.entries, format, APIKEY_TABLE);
+  }
+  if (!SEARCH_KINDS.has(kind)) {
+    throw new UsageError("list is not implemented for this resource type");
+  }
+  const result = await client.search.query({ kinds: [kind], org, page: { num: 1, size: limit } });
+  return renderCollection(SearchResultSchema, result.entries, format, SEARCH_TABLE);
+}
+
+// Shared with `search` — both render SearchService results identically.
+export const SEARCH_TABLE: TableShape = {
+  resourceName: "resources",
+  headers: ["NAME", "DESCRIPTION", "VISIBILITY", "CREATED"],
+  row: (json) => [
+    str(json, "qualified_slug"),
+    truncate(str(json, "description"), 50),
+    str(json, "visibility"),
+    date(str(json, "created_at")),
+  ],
+};
+
+const ORG_TABLE: TableShape = {
+  resourceName: "organizations",
+  headers: ["NAME", "SLUG", "ID"],
+  row: (json) => {
+    const metadata = obj(json, "metadata");
+    return [str(metadata, "name"), str(metadata, "slug"), str(metadata, "id")];
+  },
+};
+
+const APIKEY_TABLE: TableShape = {
+  resourceName: "API keys",
+  headers: ["ID", "NAME", "FINGERPRINT", "EXPIRES"],
+  row: (json) => {
+    const metadata = obj(json, "metadata");
+    const spec = obj(json, "spec");
+    const fingerprint = str(spec, "fingerprint");
+    return [
+      str(metadata, "id"),
+      str(metadata, "name") || "-",
+      fingerprint === "" ? "" : `***${fingerprint}`,
+      apiKeyExpiry(spec),
+    ];
+  },
+};
+
+function apiKeyExpiry(spec: JsonObject): string {
+  if (bool(spec, "never_expires")) return "Never";
+  const expiresAt = str(spec, "expires_at");
+  return expiresAt === "" ? "Never" : date(expiresAt);
+}
+
+function truncate(text: string, max: number): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
+}
+
+function date(timestamp: string): string {
+  return timestamp === "" ? "-" : timestamp.slice(0, 10);
+}

package/src/resources/mcp/runtime-env.test.ts

@@ -0,0 +1,68 @@
+// Unit tests for shared MCP runtime_env construction.
+
+import { create } from "@bufbuild/protobuf";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { UsageError } from "../../errors/index.js";
+import { buildRuntimeEnv, mergeProcessEnv, parseEnvOverrides } from "./runtime-env.js";
+
+function serverWithEnv(env: Record<string, { isSecret: boolean }>) {
+  return create(McpServerSchema, { metadata: { id: "mcp_1" }, spec: { env } });
+}
+
+describe("parseEnvOverrides", () => {
+  it("parses KEY=VALUE pairs, preserving '=' in the value", () => {
+    expect(parseEnvOverrides(["A=1", "B=x=y"])).toEqual({ A: "1", B: "x=y" });
+  });
+
+  it("throws a usage error on an entry without '='", () => {
+    expect(() => parseEnvOverrides(["BROKEN"])).toThrow(UsageError);
+  });
+
+  it("throws when the key is empty", () => {
+    expect(() => parseEnvOverrides(["=value"])).toThrow(UsageError);
+  });
+});
+
+describe("buildRuntimeEnv", () => {
+  const original = process.env;
+  beforeEach(() => {
+    process.env = { ...original, GITHUB_TOKEN: "from-os", PLANTON_API_KEY: "" };
+  });
+  afterEach(() => {
+    process.env = original;
+  });
+
+  it("pulls declared keys from the OS environment with their secret flag", () => {
+    const env = buildRuntimeEnv(serverWithEnv({ GITHUB_TOKEN: { isSecret: true } }));
+    expect(env.GITHUB_TOKEN.value).toBe("from-os");
+    expect(env.GITHUB_TOKEN.isSecret).toBe(true);
+  });
+
+  it("skips declared keys that are unset or empty in the environment", () => {
+    const env = buildRuntimeEnv(serverWithEnv({ PLANTON_API_KEY: { isSecret: true }, MISSING: { isSecret: false } }));
+    expect(env.PLANTON_API_KEY).toBeUndefined();
+    expect(env.MISSING).toBeUndefined();
+  });
+
+  it("lets --env overrides win over the OS environment", () => {
+    const env = buildRuntimeEnv(serverWithEnv({ GITHUB_TOKEN: { isSecret: true } }), ["GITHUB_TOKEN=override"]);
+    expect(env.GITHUB_TOKEN.value).toBe("override");
+    // is_secret is carried from the declaration.
+    expect(env.GITHUB_TOKEN.isSecret).toBe(true);
+  });
+
+  it("treats an override for an undeclared key as non-secret", () => {
+    const env = buildRuntimeEnv(serverWithEnv({}), ["EXTRA=1"]);
+    expect(env.EXTRA.value).toBe("1");
+    expect(env.EXTRA.isSecret).toBe(false);
+  });
+});
+
+describe("mergeProcessEnv", () => {
+  it("overlays overrides on top of process.env", () => {
+    const merged = mergeProcessEnv(["PATH=/custom", "NEW=1"]);
+    expect(merged.PATH).toBe("/custom");
+    expect(merged.NEW).toBe("1");
+  });
+});

package/src/resources/mcp/runtime-env.ts

@@ -0,0 +1,79 @@
+// Shared MCP runtime_env construction (single source of truth).
+//
+// The Connect RPC takes a runtime_env map of resolved credential values. Both
+// the post-apply auto-discovery path (resources/apply/discovery.ts) and the
+// `connect mcp-server` command build it the same way, so the logic lives here.
+// Mirrors Go's mcpserver.buildRuntimeEnv + parseEnvOverrides (connect.go).
+//
+// Resolution order (lowest → highest priority):
+//   1. OS environment variables, for keys the server declares in spec.env
+//   2. Explicit --env KEY=VALUE overrides (override wins on collision)
+//
+// is_secret is taken from the server's declaration when the key is declared;
+// an override for an undeclared key is treated as non-secret (matches Go).
+
+import { create } from "@bufbuild/protobuf";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { UsageError } from "../../errors/index.js";
+
+type ExecutionValue = ReturnType<typeof create<typeof ExecutionValueSchema>>;
+
+/**
+ * Parse `--env KEY=VALUE` strings into a map. Unlike Go (which silently drops
+ * malformed entries), we reject an entry without `=` so a typo surfaces as a
+ * clear usage error rather than a silently-ignored credential.
+ */
+export function parseEnvOverrides(overrides: readonly string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const entry of overrides) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0) {
+      throw new UsageError(`invalid --env value '${entry}': expected KEY=VALUE`);
+    }
+    result[entry.slice(0, eq)] = entry.slice(eq + 1);
+  }
+  return result;
+}
+
+/**
+ * Build the runtime_env map for the Connect RPC from the OS environment and the
+ * supplied --env overrides. Only keys with a non-empty value are emitted.
+ */
+export function buildRuntimeEnv(
+  server: McpServer,
+  envOverrides: readonly string[] = [],
+): Record<string, ExecutionValue> {
+  const declarations = server.spec?.env ?? {};
+  const overrides = parseEnvOverrides(envOverrides);
+  const runtime: Record<string, ExecutionValue> = {};
+
+  for (const [key, decl] of Object.entries(declarations)) {
+    const value = process.env[key];
+    if (value !== undefined && value !== "") {
+      runtime[key] = create(ExecutionValueSchema, { value, isSecret: decl.isSecret });
+    }
+  }
+
+  for (const [key, value] of Object.entries(overrides)) {
+    runtime[key] = create(ExecutionValueSchema, { value, isSecret: declarations[key]?.isSecret ?? false });
+  }
+
+  return runtime;
+}
+
+/**
+ * Merge `--env` overrides on top of the current process environment for a
+ * spawned stdio subprocess (override wins). Mirrors Go's mergeEnv. Returns a
+ * plain map suitable for the MCP SDK's StdioClientTransport `env` option.
+ */
+export function mergeProcessEnv(envOverrides: readonly string[]): Record<string, string> {
+  const merged: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) merged[key] = value;
+  }
+  for (const [key, value] of Object.entries(parseEnvOverrides(envOverrides))) {
+    merged[key] = value;
+  }
+  return merged;
+}

package/src/resources/mutate-verbs.integration.test.ts

@@ -0,0 +1,233 @@
+// In-process integration test for the mutating verbs (delete / tag).
+//
+// Stands up a real Connect backend over h2c serving the query *and* command
+// controllers these verbs call, points an SDK node client at it, and drives the
+// resource layer (planDelete → perform, tagVersion) end to end. Asserts the
+// rendered result shape, the special-case routing (execution→cancel,
+// already-terminal), and that backend errors map to the right CLI exit code.
+
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
+import type { Stigmer } from "@stigmer/sdk";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { classify, ExitCode } from "../errors/index.js";
+import { planDelete } from "./delete.js";
+import { tagVersion } from "./tag.js";
+
+const knownAgent = create(AgentSchema, {
+  metadata: { name: "Reviewer", slug: "reviewer", org: "acme", id: "agt_1" },
+});
+
+const knownMcp = create(McpServerSchema, {
+  metadata: { name: "Filesystem", slug: "filesystem", org: "acme", id: "mcp_1" },
+});
+
+const knownWorkflow = create(WorkflowSchema, {
+  metadata: { name: "Deploy", slug: "deploy", org: "acme", id: "wfl_1" },
+});
+
+// Pending execution (cancellable) vs. an already-terminal one.
+const pendingExecution = create(AgentExecutionSchema, {
+  metadata: { id: "aex_run" },
+  status: { phase: ExecutionPhase.EXECUTION_PENDING },
+});
+const cancelledExecution = create(AgentExecutionSchema, {
+  metadata: { id: "aex_run" },
+  status: { phase: ExecutionPhase.EXECUTION_CANCELLED },
+});
+const completedExecution = create(AgentExecutionSchema, {
+  metadata: { id: "aex_done" },
+  status: { phase: ExecutionPhase.EXECUTION_COMPLETED },
+});
+
+let backend: Http2Server;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+// Spies for the command-side calls, reset per test.
+let cancelCalls: string[] = [];
+let tagCalls: { workflowId: string; versionHash: string; tag: string }[] = [];
+
+beforeEach(() => {
+  cancelCalls = [];
+  tagCalls = [];
+});
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentQueryController, {
+      get: (req) => {
+        if (req.value !== "agt_1") throw new ConnectError("agent not found", Code.NotFound);
+        return knownAgent;
+      },
+      getByReference: (req) => {
+        if (req.slug !== "reviewer") throw new ConnectError("agent not found", Code.NotFound);
+        return knownAgent;
+      },
+    });
+    router.service(AgentCommandController, {
+      delete: () => knownAgent,
+    });
+
+    router.service(McpServerQueryController, {
+      getByReference: () => knownMcp,
+    });
+    router.service(McpServerCommandController, {
+      delete: (req) => {
+        if (req.resourceId !== "mcp_1") throw new ConnectError("bad id", Code.InvalidArgument);
+        return knownMcp;
+      },
+    });
+
+    router.service(WorkflowQueryController, {
+      getByReference: (req) => {
+        if (req.slug !== "deploy") throw new ConnectError("workflow not found", Code.NotFound);
+        return knownWorkflow;
+      },
+    });
+    router.service(WorkflowCommandController, {
+      tagVersion: (req) => {
+        tagCalls.push({ workflowId: req.workflowId, versionHash: req.versionHash, tag: req.tag });
+        return knownWorkflow;
+      },
+    });
+
+    router.service(AgentExecutionQueryController, {
+      get: (req) => {
+        if (req.value === "aex_done") return completedExecution;
+        if (req.value === "aex_run") return pendingExecution;
+        throw new ConnectError("execution not found", Code.NotFound);
+      },
+    });
+    router.service(AgentExecutionCommandController, {
+      cancel: (req) => {
+        cancelCalls.push(req.id);
+        return cancelledExecution;
+      },
+    });
+  };
+
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+  client = createNodeClient({ baseUrl: normalizeEndpoint(`127.0.0.1:${port}`) });
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("delete (standard kinds)", () => {
+  it("describes then deletes an agent by ID", async () => {
+    const plan = await planDelete(client, "agent", "agt_1", "acme");
+
+    expect(plan.warning.status).toBe("warning");
+    expect(plan.warning.sections[0].fields).toEqual([
+      { key: "ID", value: "agt_1" },
+      { key: "Name", value: "Reviewer" },
+      { key: "Slug", value: "reviewer" },
+      { key: "Org", value: "acme" },
+    ]);
+
+    const result = await plan.perform();
+    expect(result.status).toBe("success");
+    expect(result.message).toBe("Agent deleted successfully");
+    expect(result.sections[0].title).toBe("Deleted Agent");
+    expect(result.sections[0].fields).toContainEqual({ key: "ID", value: "agt_1" });
+  });
+
+  it("resolves an agent by org/slug for the pre-Get", async () => {
+    const plan = await planDelete(client, "agent", "reviewer", "acme");
+    expect((await plan.perform()).status).toBe("success");
+  });
+
+  it("deletes an MCP server via the DeleteResourceInput shape", async () => {
+    const plan = await planDelete(client, "mcpserver", "filesystem", "acme");
+    const result = await plan.perform();
+    expect(result.status).toBe("success");
+    expect(result.message).toBe("MCP Server deleted successfully");
+  });
+
+  it("maps a NotFound on the pre-Get to ExitCode.NotFound", async () => {
+    const err = await planDelete(client, "agent", "missing", "acme").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.NotFound);
+  });
+
+  it("rejects an unknown type with a usage error", async () => {
+    const err = await planDelete(client, "bogus", "x", "acme").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+
+  it("rejects a kind that has no delete handler with a usage error", async () => {
+    const err = await planDelete(client, "session", "ses_1", "acme").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});
+
+describe("delete execution (cancel special case)", () => {
+  it("cancels a non-terminal execution", async () => {
+    const plan = await planDelete(client, "execution", "aex_run", "");
+    expect(plan.confirmPrompt).toContain("cancellation");
+
+    const result = await plan.perform();
+    expect(result.status).toBe("success");
+    expect(result.message).toBe("Execution cancelled successfully");
+    expect(result.sections[0].fields).toContainEqual({ key: "Status", value: "cancelled" });
+    expect(cancelCalls).toEqual(["aex_run"]);
+  });
+
+  it("reports an already-terminal execution without issuing a cancel", async () => {
+    const plan = await planDelete(client, "execution", "aex_done", "");
+    const result = await plan.perform();
+    expect(result.status).toBe("warning");
+    expect(result.message).toBe("Execution was already in terminal state");
+    expect(result.sections[0].fields).toContainEqual({ key: "Status", value: "completed" });
+    expect(cancelCalls).toEqual([]);
+  });
+
+  it("rejects a non-execution ID with a usage error", async () => {
+    const err = await planDelete(client, "execution", "agt_1", "").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});
+
+describe("tag (workflow versions)", () => {
+  it("tags a workflow version and truncates the hash in the message", async () => {
+    const result = await tagVersion(client, "workflow", "acme/deploy", "abcdef1234567890", "stable", "acme");
+    expect(result.status).toBe("success");
+    expect(result.message).toBe("Tagged version abcdef123456 as 'stable'");
+    expect(tagCalls).toEqual([{ workflowId: "wfl_1", versionHash: "abcdef1234567890", tag: "stable" }]);
+  });
+
+  it("uses the org context for a bare slug", async () => {
+    await tagVersion(client, "wf", "deploy", "abc", "v1", "acme");
+    expect(tagCalls[0]?.workflowId).toBe("wfl_1");
+  });
+
+  it("rejects unsupported resource types with a usage error", async () => {
+    const err = await tagVersion(client, "agent", "acme/x", "abc", "v1", "acme").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});