@stigmer/cli 3.0.8

package/src/resources/delete.ts

@@ -0,0 +1,239 @@
+// `delete` dispatch: resolve a resource by reference, describe it for a
+// confirmation prompt, then delete it. Mirrors the Go CLI's unified delete,
+// including its three special cases:
+//
+//   - execution  → maps to a *cancel* (agent executions only, by ID)
+//   - organization → not org-scoped; resolved via findMyOrganizations
+//   - api_key    → addressable by ID only (not slug)
+//
+// The deletion verbs are id-shaped mutations, so they ride the high-level
+// `client.stigmer.*` sub-clients — only `apply` needs raw controllers (see the
+// Wave 2 architecture note). Fetching reuses the `get` bindings rather than
+// re-implementing a second fetch path.
+//
+// Each kind produces a DeletePlan: a warning to show before confirming, the
+// confirmation prompt, and a `perform` thunk that runs the mutation and returns
+// the success/already-terminal result. The command layer owns the interaction
+// (render warning → confirm → perform → render result); this module owns *what*
+// to delete and *how* to describe it.
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { CliExitError, ExitCode, UsageError } from "../errors/index.js";
+import { CommandResult } from "../output/index.js";
+import { defaultRegistry, type TypeInfo, Verb } from "../registry/index.js";
+import { cancelAgentExecution, formatAgentPhase, isAgentExecutionId, isExecutionAlias } from "./execution.js";
+import { fetchResource } from "./get.js";
+import { getterFor } from "./get-bindings.js";
+import { parseReference } from "./reference.js";
+
+/** A staged delete: confirmation content plus the mutation to run on approval. */
+export interface DeletePlan {
+  /** Shown to the user (unless `--force`) before the destructive action. */
+  readonly warning: CommandResult;
+  /** The yes/no question, e.g. "Proceed with deletion? [y/N]". */
+  readonly confirmPrompt: string;
+  /** Runs the mutation and returns the result to render. */
+  perform(): Promise<CommandResult>;
+}
+
+// Every resource proto carries the same ApiResourceMetadata envelope; this is
+// the structural slice the delete UI needs. Reading it generically keeps the
+// dispatch kind-agnostic without a per-kind accessor.
+interface HasMetadata {
+  readonly metadata?: { readonly id?: string; readonly name?: string; readonly slug?: string; readonly org?: string };
+}
+
+type DeleteFn = (client: Stigmer, id: string) => Promise<HasMetadata>;
+
+// Kinds the unified delete handles directly, each bound to its SDK delete call.
+// Mirrors Go's routeDelete switch exactly: kinds that carry a Delete verb but no
+// entry here (identity_provider, oauth_app, environment, instances, session)
+// fall through to a "not implemented" usage error, as in Go's default branch.
+// McpServer is the outlier whose delete takes a DeleteResourceInput, not an ID.
+const DELETE_HANDLERS: ReadonlyMap<ApiResourceKind, DeleteFn> = new Map<ApiResourceKind, DeleteFn>([
+  [ApiResourceKind.agent, (c, id) => c.agent.delete(id)],
+  [ApiResourceKind.workflow, (c, id) => c.workflow.delete(id)],
+  [ApiResourceKind.mcp_server, (c, id) => c.mcpServer.delete({ resourceId: id })],
+  [ApiResourceKind.project, (c, id) => c.project.delete(id)],
+  [ApiResourceKind.skill, (c, id) => c.skill.delete(id)],
+  [ApiResourceKind.api_key, (c, id) => c.apiKey.delete(id)],
+]);
+
+/**
+ * Build the delete plan for a `<type> <reference>` pair. Routes the three
+ * special cases first, then the registry-driven standard path. Throws on
+ * unknown/unsupported types before any network call.
+ */
+export async function planDelete(
+  client: Stigmer,
+  typeArg: string,
+  reference: string,
+  org: string,
+): Promise<DeletePlan> {
+  if (isExecutionAlias(typeArg)) {
+    return planExecutionCancel(client, reference);
+  }
+
+  const info = defaultRegistry().getByAlias(typeArg);
+  if (info === undefined) {
+    throw new UsageError(
+      `unknown resource type: ${typeArg}\n\nAvailable types: agent, workflow, mcpserver, project, skill, execution, organization`,
+    );
+  }
+
+  if (info.kind === ApiResourceKind.organization) {
+    return planOrganizationDelete(client, reference);
+  }
+
+  if (!info.supportedVerbs.has(Verb.Delete)) {
+    throw new UsageError(`${info.displayName} does not support 'delete'`);
+  }
+
+  const deleteFn = DELETE_HANDLERS.get(info.kind);
+  if (deleteFn === undefined) {
+    throw new UsageError(`delete not implemented for ${info.displayName}`);
+  }
+
+  return planStandardDelete(client, info, reference, org, deleteFn);
+}
+
+async function planStandardDelete(
+  client: Stigmer,
+  info: TypeInfo,
+  reference: string,
+  org: string,
+  deleteFn: DeleteFn,
+): Promise<DeletePlan> {
+  // Safe by construction: every DELETE_HANDLERS key also has a get binding.
+  const getter = getterFor(info.kind);
+  if (getter === undefined) {
+    throw new UsageError(`delete not implemented for ${info.displayName}`);
+  }
+
+  const parsed = parseReference(reference, org, info.idPrefix);
+  // ResourceResult.message is the opaque proto Message; every resource carries
+  // the ApiResourceMetadata envelope, so read it through the structural view.
+  const resource = (await getter(client, parsed)).message as unknown as HasMetadata;
+  const id = metaOf(resource).id;
+
+  return {
+    warning: buildDeleteWarning(info, resource),
+    confirmPrompt: "Proceed with deletion? [y/N]",
+    perform: async () => buildDeleteSuccess(info, await deleteFn(client, id)),
+  };
+}
+
+async function planOrganizationDelete(client: Stigmer, reference: string): Promise<DeletePlan> {
+  // Organizations are not org-scoped: a bare token is a slug resolved against
+  // the caller's memberships (fetchResource handles the id-vs-slug split).
+  const parsed = parseReference(reference, "", "org");
+  const resource = (await fetchResource(client, ApiResourceKind.organization, parsed)).message as unknown as HasMetadata;
+  const meta = metaOf(resource);
+
+  const warning = CommandResult.warning("You are about to delete the following organization:");
+  warning.addSection("").field("ID", meta.id).field("Name", meta.name).field("Slug", meta.slug);
+  warning.hint("This will delete the organization and all its resources.");
+  warning.hint("This action cannot be undone.");
+
+  return {
+    warning,
+    confirmPrompt: "Proceed with deletion? [y/N]",
+    perform: async () => {
+      const deleted = metaOf(await client.organization.delete(meta.id));
+      const out = CommandResult.success("Organization deleted successfully");
+      out.addSection("Deleted Organization").field("ID", deleted.id).field("Name", deleted.name).field("Slug", deleted.slug);
+      return out;
+    },
+  };
+}
+
+function planExecutionCancel(client: Stigmer, reference: string): DeletePlan {
+  if (!isAgentExecutionId(reference)) {
+    throw new CliExitError(
+      `invalid execution ID: ${reference}\n\nExecutions must be referenced by ID (e.g., aex_01abc123)`,
+      ExitCode.Usage,
+    );
+  }
+
+  const warning = CommandResult.warning(`You are about to cancel execution: ${reference}`);
+  warning.hint("This will gracefully stop the running agent.");
+
+  return {
+    warning,
+    confirmPrompt: "Proceed with cancellation? [y/N]",
+    perform: async () => {
+      const { execution, wasAlreadyTerminal } = await cancelAgentExecution(client, reference);
+      const id = execution.metadata?.id ?? "";
+      const status = formatAgentPhase(execution.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED);
+
+      const out = wasAlreadyTerminal
+        ? CommandResult.warning("Execution was already in terminal state")
+        : CommandResult.success("Execution cancelled successfully");
+      out.addSection("Execution").field("ID", id).field("Status", status);
+      return out;
+    },
+  };
+}
+
+// --- Warning + success rendering (mirrors Go's per-type delete handlers) ---
+
+function buildDeleteWarning(info: TypeInfo, message: HasMetadata): CommandResult {
+  if (info.kind === ApiResourceKind.api_key) {
+    return buildApiKeyWarning(message);
+  }
+
+  const meta = metaOf(message);
+  const warning = CommandResult.warning(`You are about to delete the following ${info.displayName.toLowerCase()}:`);
+  const section = warning
+    .addSection("")
+    .field("ID", meta.id)
+    .field("Name", meta.name)
+    .field("Slug", meta.slug)
+    .field("Org", meta.org);
+
+  if (info.kind === ApiResourceKind.skill) {
+    const tag = (message as { spec?: { tag?: string } }).spec?.tag;
+    if (tag) section.field("Tag", tag);
+    warning.hint("This will delete the skill and all its versions.");
+  }
+
+  warning.hint("This action cannot be undone.");
+  return warning;
+}
+
+function buildApiKeyWarning(message: HasMetadata): CommandResult {
+  const meta = metaOf(message);
+  const warning = CommandResult.warning("You are about to delete the following API key:");
+  const section = warning.addSection("").field("ID", meta.id);
+  if (meta.name) section.field("Name", meta.name);
+  const fingerprint = (message as { spec?: { fingerprint?: string } }).spec?.fingerprint;
+  if (fingerprint) section.field("Fingerprint", `***${fingerprint}`);
+  warning.hint("This will permanently revoke the API key.");
+  warning.hint("This action cannot be undone.");
+  return warning;
+}
+
+function buildDeleteSuccess(info: TypeInfo, deleted: HasMetadata): CommandResult {
+  const meta = metaOf(deleted);
+  const out = CommandResult.success(`${info.displayName} deleted successfully`);
+  const section = out.addSection(`Deleted ${info.displayName}`).field("ID", meta.id);
+
+  if (info.kind === ApiResourceKind.api_key) {
+    if (meta.name) section.field("Name", meta.name);
+    return out;
+  }
+
+  section.field("Name", meta.name).field("Slug", meta.slug);
+  return out;
+}
+
+function metaOf(message: HasMetadata): { id: string; name: string; slug: string; org: string } {
+  return {
+    id: message.metadata?.id ?? "",
+    name: message.metadata?.name ?? "",
+    slug: message.metadata?.slug ?? "",
+    org: message.metadata?.org ?? "",
+  };
+}

package/src/resources/diff.integration.test.ts

@@ -0,0 +1,103 @@
+// In-process integration test for `diff` against a workflow's remote state.
+
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_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, describe, expect, it } from "vitest";
+import { renderProtoYaml } from "../output/index.js";
+import { diffDocument } from "./diff.js";
+
+const knownWorkflow = create(WorkflowSchema, {
+  apiVersion: "agentic.stigmer.ai/v1",
+  kind: "Workflow",
+  metadata: { name: "Deploy", slug: "deploy", org: "acme", id: "wfl_1" },
+  spec: { description: "deploys things" },
+});
+
+let backend: Http2Server;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(WorkflowQueryController, {
+      getByReference: (req) => {
+        if (req.slug !== "deploy") throw new ConnectError("workflow not found", Code.NotFound);
+        return knownWorkflow;
+      },
+    });
+  };
+  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("diffDocument (workflow)", () => {
+  const doc = { kind: "Workflow", metadata: { slug: "deploy" } } as const;
+
+  it("reports an unchanged document as 'same'", async () => {
+    const remoteYaml = renderProtoYaml(WorkflowSchema, knownWorkflow);
+    const result = await diffDocument(client, ApiResourceKind.workflow, remoteYaml, doc, "wf.yaml", "acme", 3);
+    expect(result.status).toBe("same");
+  });
+
+  it("reports a changed document with a unified diff", async () => {
+    const result = await diffDocument(
+      client,
+      ApiResourceKind.workflow,
+      "kind: Workflow\nspec:\n  description: something else\n",
+      doc,
+      "wf.yaml",
+      "acme",
+      3,
+    );
+    expect(result.status).toBe("changed");
+    if (result.status === "changed") {
+      expect(result.text).toContain("@@");
+      expect(result.text).toContain("remote/wf.yaml");
+    }
+  });
+
+  it("reports a not-yet-deployed workflow as 'new'", async () => {
+    const result = await diffDocument(
+      client,
+      ApiResourceKind.workflow,
+      "kind: Workflow\nmetadata:\n  slug: missing\n",
+      { kind: "Workflow", metadata: { slug: "missing" } },
+      "wf.yaml",
+      "acme",
+      3,
+    );
+    expect(result.status).toBe("new");
+  });
+
+  it("treats non-workflow kinds as 'new' (diff not implemented)", async () => {
+    const result = await diffDocument(
+      client,
+      ApiResourceKind.agent,
+      "kind: Agent\n",
+      { kind: "Agent", metadata: { slug: "x" } },
+      "a.yaml",
+      "acme",
+      3,
+    );
+    expect(result.status).toBe("new");
+  });
+});

package/src/resources/diff.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { unifiedDiff } from "./diff.js";
+
+describe("unifiedDiff", () => {
+  it("emits the file headers", () => {
+    const out = unifiedDiff("a", "b", "remote/x.yaml", "local/x.yaml", 3);
+    expect(out.startsWith("--- remote/x.yaml\n+++ local/x.yaml\n")).toBe(true);
+  });
+
+  it("produces no hunk for identical input", () => {
+    const out = unifiedDiff("x\ny\nz", "x\ny\nz", "remote/x", "local/x", 3);
+    expect(out).not.toContain("@@");
+  });
+
+  it("renders a single-line change with trailing context", () => {
+    const out = unifiedDiff("a\nb\nc", "a\nB\nc", "remote/x", "local/x", 3);
+    expect(out).toContain("@@ -2,2 +2,2 @@");
+    expect(out).toContain("-b");
+    expect(out).toContain("+B");
+    expect(out).toContain(" c");
+  });
+
+  it("renders a pure addition", () => {
+    const out = unifiedDiff("a", "a\nb", "remote/x", "local/x", 3);
+    expect(out).toContain("@@ -2,0 +2,1 @@");
+    expect(out).toContain("+b");
+  });
+
+  it("renders a pure deletion", () => {
+    const out = unifiedDiff("a\nb", "a", "remote/x", "local/x", 3);
+    expect(out).toContain("-b");
+    expect(out).not.toContain("+b");
+  });
+});

package/src/resources/diff.ts

@@ -0,0 +1,187 @@
+// `diff`: compare local YAML against the rendered remote resource state.
+//
+// The unified-diff engine is a faithful port of the in-repo LCS differ
+// (workflow/versions.go computeUnifiedDiff), adapted so the trailing-context
+// window honors the `--context` flag. Like the Go original it emits trailing
+// context only (no leading context), so hunk boundaries differ slightly from
+// go-difflib — an accepted trade-off for a dependency-free, proven algorithm.
+// Diff output is human-facing and not a DD-005 byte-parity target.
+//
+// Only workflows are diffable today (matching Go's fetchRemoteResource, which
+// implements workflow and treats every other kind — and any not-found — as a
+// brand-new resource).
+
+import type { JsonValue } from "@bufbuild/protobuf";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { renderProtoYaml } from "../output/index.js";
+
+export type DiffResult =
+  | { readonly status: "new" }
+  | { readonly status: "same" }
+  | { readonly status: "changed"; readonly text: string };
+
+/** Diff one document against its remote state, returning what changed. */
+export async function diffDocument(
+  client: Stigmer,
+  kind: ApiResourceKind,
+  localRaw: string,
+  document: JsonValue,
+  baseName: string,
+  org: string,
+  contextLines: number,
+): Promise<DiffResult> {
+  let remoteYaml: string;
+  try {
+    remoteYaml = await fetchRemoteYaml(client, kind, document, org);
+  } catch {
+    // Not deployed, or a kind we don't diff yet — Go shows both as "new".
+    return { status: "new" };
+  }
+
+  if (localRaw.trim() === remoteYaml.trim()) return { status: "same" };
+
+  const text = unifiedDiff(remoteYaml, localRaw, `remote/${baseName}`, `local/${baseName}`, contextLines);
+  if (!text.includes("@@")) return { status: "same" };
+  return { status: "changed", text };
+}
+
+async function fetchRemoteYaml(client: Stigmer, kind: ApiResourceKind, document: JsonValue, org: string): Promise<string> {
+  if (kind !== ApiResourceKind.workflow) {
+    throw new Error("diff is only implemented for workflows");
+  }
+  const metadata = (document as { metadata?: { slug?: string; name?: string } }).metadata ?? {};
+  const slug = metadata.slug ?? metadata.name ?? "";
+  if (slug === "") throw new Error("workflow has no slug or name for remote lookup");
+
+  const remote = await client.workflow.getByReference({ org, slug });
+  return renderProtoYaml(WorkflowSchema, remote);
+}
+
+// --- Unified diff engine (ported from workflow/versions.go) ---
+
+interface DiffHunk {
+  readonly startA: number;
+  readonly lenA: number;
+  readonly startB: number;
+  readonly lenB: number;
+  readonly lines: readonly string[];
+}
+
+/** Produce a unified diff of `a`→`b` with `context` trailing context lines. */
+export function unifiedDiff(a: string, b: string, labelA: string, labelB: string, context: number): string {
+  const linesA = a.split("\n");
+  const linesB = b.split("\n");
+
+  let out = `--- ${labelA}\n+++ ${labelB}\n`;
+  for (const hunk of buildHunks(linesA, linesB, context)) {
+    out += `@@ -${hunk.startA + 1},${hunk.lenA} +${hunk.startB + 1},${hunk.lenB} @@\n`;
+    for (const line of hunk.lines) out += `${line}\n`;
+  }
+  return out;
+}
+
+function buildHunks(linesA: string[], linesB: string[], context: number): DiffHunk[] {
+  const lcs = longestCommonSubsequence(linesA, linesB);
+  const hunks: DiffHunk[] = [];
+  let currentLines: string[] = [];
+  let idxA = 0;
+  let idxB = 0;
+  let idxLcs = 0;
+  let hunkStartA = 0;
+  let hunkStartB = 0;
+  let inHunk = false;
+
+  const flushHunk = (): void => {
+    if (inHunk && currentLines.length > 0) {
+      hunks.push({
+        startA: hunkStartA,
+        lenA: countPrefix(currentLines, "-") + countPrefix(currentLines, " "),
+        startB: hunkStartB,
+        lenB: countPrefix(currentLines, "+") + countPrefix(currentLines, " "),
+        lines: currentLines,
+      });
+      currentLines = [];
+      inHunk = false;
+    }
+  };
+
+  while (idxA < linesA.length || idxB < linesB.length) {
+    const isContext =
+      idxLcs < lcs.length &&
+      idxA < linesA.length &&
+      idxB < linesB.length &&
+      linesA[idxA] === lcs[idxLcs] &&
+      linesB[idxB] === lcs[idxLcs];
+
+    if (isContext) {
+      if (inHunk) currentLines.push(` ${linesA[idxA]}`);
+      idxA++;
+      idxB++;
+      idxLcs++;
+      if (inHunk && countTrailingContext(currentLines) >= context) flushHunk();
+    } else {
+      if (!inHunk) {
+        inHunk = true;
+        hunkStartA = idxA;
+        hunkStartB = idxB;
+        currentLines = [];
+      }
+      if (idxA < linesA.length && (idxLcs >= lcs.length || linesA[idxA] !== lcs[idxLcs])) {
+        currentLines.push(`-${linesA[idxA]}`);
+        idxA++;
+      } else if (idxB < linesB.length && (idxLcs >= lcs.length || linesB[idxB] !== lcs[idxLcs])) {
+        currentLines.push(`+${linesB[idxB]}`);
+        idxB++;
+      }
+    }
+  }
+
+  flushHunk();
+  return hunks;
+}
+
+function longestCommonSubsequence(a: string[], b: string[]): string[] {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0));
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1] + 1;
+      } else {
+        dp[i][j] = dp[i - 1][j] >= dp[i][j - 1] ? dp[i - 1][j] : dp[i][j - 1];
+      }
+    }
+  }
+
+  const result: string[] = [];
+  let i = m;
+  let j = n;
+  while (i > 0 && j > 0) {
+    if (a[i - 1] === b[j - 1]) {
+      result.push(a[i - 1]);
+      i--;
+      j--;
+    } else if (dp[i - 1][j] >= dp[i][j - 1]) {
+      i--;
+    } else {
+      j--;
+    }
+  }
+  return result.reverse();
+}
+
+function countPrefix(lines: readonly string[], prefix: string): number {
+  return lines.filter((line) => line.startsWith(prefix)).length;
+}
+
+function countTrailingContext(lines: readonly string[]): number {
+  let count = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].startsWith(" ")) break;
+    count++;
+  }
+  return count;
+}

package/src/resources/documents.test.ts

@@ -0,0 +1,67 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { UsageError } from "../errors/index.js";
+import { loadDocuments, resolveYamlFiles } from "./documents.js";
+
+let dir: string;
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "stigmer-docs-"));
+  writeFileSync(join(dir, "single.yaml"), "kind: Agent\nmetadata:\n  slug: a\n");
+  writeFileSync(join(dir, "multi.yaml"), "kind: Agent\nmetadata:\n  slug: a\n---\nkind: Workflow\nmetadata:\n  slug: w\n");
+  writeFileSync(join(dir, "nokind.yaml"), "metadata:\n  slug: a\n");
+  writeFileSync(join(dir, "broken.yaml"), "kind: Agent\nfoo: [1, 2\n");
+  writeFileSync(join(dir, "notyaml.txt"), "ignored");
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("resolveYamlFiles", () => {
+  it("returns a single file directly", () => {
+    expect(resolveYamlFiles(join(dir, "single.yaml"))).toEqual([join(dir, "single.yaml")]);
+  });
+
+  it("walks a directory for .yaml/.yml only", () => {
+    const files = resolveYamlFiles(dir);
+    expect(files).toContain(join(dir, "single.yaml"));
+    expect(files).toContain(join(dir, "multi.yaml"));
+    expect(files.some((f) => f.endsWith(".txt"))).toBe(false);
+  });
+
+  it("rejects a non-existent path with a usage error", () => {
+    expect(() => resolveYamlFiles(join(dir, "missing.yaml"))).toThrow(UsageError);
+  });
+});
+
+describe("loadDocuments", () => {
+  it("loads a single document with the whole file as raw", () => {
+    const docs = loadDocuments(join(dir, "single.yaml"));
+    expect(docs).toHaveLength(1);
+    expect(docs[0].kind).toBe("Agent");
+    expect(docs[0].raw).toContain("kind: Agent");
+  });
+
+  it("splits multi-document files with per-document raw text", () => {
+    const docs = loadDocuments(join(dir, "multi.yaml"));
+    expect(docs.map((d) => d.kind)).toEqual(["Agent", "Workflow"]);
+    expect(docs[0].raw).toContain("slug: a");
+    expect(docs[0].raw).not.toContain("Workflow");
+    expect(docs[1].raw).toContain("Workflow");
+  });
+
+  it("rejects a document missing its kind", () => {
+    expect(() => loadDocuments(join(dir, "nokind.yaml"))).toThrow(UsageError);
+  });
+
+  it("rejects malformed YAML in strict mode", () => {
+    expect(() => loadDocuments(join(dir, "broken.yaml"), { strict: true })).toThrow(UsageError);
+  });
+
+  it("tolerates malformed YAML in lenient mode (Wave-1 parity)", () => {
+    expect(() => loadDocuments(join(dir, "broken.yaml"))).not.toThrow();
+  });
+});