@stigmer/cli 3.0.8

package/src/resources/picker/ink.tsx

@@ -0,0 +1,114 @@
+// In-process Ink renderer for the interactive resource pickers (`run` agent
+// browse, `resume` session browse). Mirrors stream/ink.tsx: render an Ink tree
+// in-process, reuse the CLI's already-authenticated client via
+// InkStigmerProvider, and NEVER call process.exit — resolve a value and let the
+// caller continue its flow.
+//
+// This module is only ever reached through a dynamic import() in the command
+// action (DD-001), so React/Ink load lazily — non-interactive commands never
+// pay for them. Within this already-lazy module, ordinary JSX/imports are fine.
+
+import React from "react";
+import { render } from "ink";
+import { AgentPicker, InkStigmerProvider, SessionPicker } from "@stigmer/ink";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { DeploymentMode, Stigmer } from "@stigmer/sdk";
+
+/** Options for {@link pickAgent}. */
+export interface PickAgentOptions {
+  /** The CLI's configured, refreshing-token client (backend.stigmer). */
+  readonly client: Stigmer;
+  /** Organization to search within. */
+  readonly org: string;
+  /** Seeds the search box with the unresolved text the user already typed. */
+  readonly initialQuery?: string;
+  /** Feature-gating mode; "cloud" unless the CLI targets a local backend. */
+  readonly deploymentMode?: DeploymentMode;
+}
+
+/**
+ * Render the agent picker and resolve with the chosen agent, or `undefined`
+ * when the user cancels (Esc / Ctrl+C). Never throws and never exits the
+ * process — the caller decides what to do with the selection.
+ */
+export async function pickAgent(opts: PickAgentOptions): Promise<SearchResult | undefined> {
+  return runPicker<SearchResult>(
+    (resolve) => (
+      <AgentPicker
+        org={opts.org}
+        initialQuery={opts.initialQuery}
+        onSelect={(agent) => resolve(agent)}
+        onCancel={() => resolve(undefined)}
+      />
+    ),
+    opts.client,
+    opts.deploymentMode,
+  );
+}
+
+/** Options for {@link pickSession}. */
+export interface PickSessionOptions {
+  /** The CLI's configured, refreshing-token client (backend.stigmer). */
+  readonly client: Stigmer;
+  /** Seeds the filter box with the text the user already typed. */
+  readonly initialQuery?: string;
+  /** Feature-gating mode; "cloud" unless the CLI targets a local backend. */
+  readonly deploymentMode?: DeploymentMode;
+}
+
+/**
+ * Render the session picker and resolve with the chosen session, or `undefined`
+ * when the user cancels (Esc / Ctrl+C).
+ */
+export async function pickSession(opts: PickSessionOptions): Promise<Session | undefined> {
+  return runPicker<Session>(
+    (resolve) => (
+      <SessionPicker
+        initialQuery={opts.initialQuery}
+        onSelect={(session) => resolve(session)}
+        onCancel={() => resolve(undefined)}
+      />
+    ),
+    opts.client,
+    opts.deploymentMode,
+  );
+}
+
+// Shared mount loop: render the picker element (which calls `resolve` on select
+// or cancel), unmount on the first resolution, and clean up signal handlers.
+// exitOnCtrlC is false so the picker component owns Ctrl+C (→ cancel) rather
+// than Ink killing the tree out from under us.
+function runPicker<T>(
+  renderPicker: (resolve: (value: T | undefined) => void) => React.ReactElement,
+  client: Stigmer,
+  deploymentMode: DeploymentMode | undefined,
+): Promise<T | undefined> {
+  return new Promise<T | undefined>((resolve) => {
+    let settled = false;
+    const finish = (value: T | undefined): void => {
+      if (settled) return;
+      settled = true;
+      instance.unmount();
+      resolve(value);
+    };
+
+    const instance = render(
+      <InkStigmerProvider client={client} deploymentMode={deploymentMode ?? "cloud"}>
+        {renderPicker(finish)}
+      </InkStigmerProvider>,
+      { exitOnCtrlC: false },
+    );
+
+    const onSignal = (): void => finish(undefined);
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+
+    void instance.waitUntilExit().finally(() => {
+      process.removeListener("SIGINT", onSignal);
+      process.removeListener("SIGTERM", onSignal);
+      // Covers an external unmount (e.g. terminal close) with no selection.
+      finish(undefined);
+    });
+  });
+}

package/src/resources/picker/tty.test.ts

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { interactiveBrowseEnabled } from "./tty.js";
+
+const TTY = { isTTY: true };
+const PIPE = { isTTY: false };
+
+describe("interactiveBrowseEnabled", () => {
+  const originalTerm = process.env.TERM;
+  afterEach(() => {
+    process.env.TERM = originalTerm;
+  });
+
+  it("enables the picker for inline output on a full TTY", () => {
+    process.env.TERM = "xterm-256color";
+    expect(interactiveBrowseEnabled("inline", { stdin: TTY, stdout: TTY })).toBe(true);
+  });
+
+  it("disables the picker in JSON output mode", () => {
+    process.env.TERM = "xterm-256color";
+    expect(interactiveBrowseEnabled("json", { stdin: TTY, stdout: TTY })).toBe(false);
+  });
+
+  it("disables the picker when stdout is not a TTY (piped output)", () => {
+    process.env.TERM = "xterm-256color";
+    expect(interactiveBrowseEnabled("inline", { stdin: TTY, stdout: PIPE })).toBe(false);
+  });
+
+  it("disables the picker when stdin is not a TTY (piped input)", () => {
+    process.env.TERM = "xterm-256color";
+    expect(interactiveBrowseEnabled("inline", { stdin: PIPE, stdout: TTY })).toBe(false);
+  });
+
+  it("disables the picker on a dumb terminal", () => {
+    process.env.TERM = "dumb";
+    expect(interactiveBrowseEnabled("inline", { stdin: TTY, stdout: TTY })).toBe(false);
+  });
+});

package/src/resources/picker/tty.ts

@@ -0,0 +1,30 @@
+// Capability gate for the interactive resource pickers (`run` agent browse,
+// `resume` session browse). Deliberately free of any React/Ink imports so the
+// command can decide whether to take the interactive path *before* paying the
+// dynamic-import cost of picker/ink.tsx (DD-001 lazy boundary).
+
+import { isInkSupported } from "../stream/tty.js";
+
+/** Minimal view of the process streams the gate inspects (injectable for tests). */
+export interface PickerStreams {
+  readonly stdin?: { readonly isTTY?: boolean };
+  readonly stdout?: { readonly isTTY?: boolean };
+}
+
+/**
+ * Whether the interactive picker can run: human output mode on a fully
+ * interactive terminal — stdout must be renderable (TTY, not `TERM=dumb`) and
+ * stdin must be keyboard-capable (TTY for raw-mode input).
+ *
+ * JSON mode and non-interactive shells (pipes, CI) return false so callers fall
+ * back to actionable guidance with a stable, scriptable exit code.
+ */
+export function interactiveBrowseEnabled(
+  outputMode: "inline" | "json",
+  streams: PickerStreams = process,
+): boolean {
+  if (outputMode !== "inline") return false;
+  const stdout = streams.stdout ?? process.stdout;
+  const stdin = streams.stdin ?? process.stdin;
+  return isInkSupported(stdout) && stdin.isTTY === true;
+}

package/src/resources/push-download.integration.test.ts

@@ -0,0 +1,175 @@
+// In-process integration test for `push skill` and `download execution`.
+//
+// Stands up a Connect backend (skill push + execution query/artifact-URL) plus a
+// plain HTTP server standing in for object storage, then drives the resource
+// layer end to end: pushSkill zips a temp dir and uploads it (asserting the
+// server receives a valid ZIP), and downloadExecutionArtifacts streams a
+// presigned URL to disk (asserting partial-failure tolerance).
+
+import { createServer as createHttpServer, type Server as HttpServer } from "node:http";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { GetArtifactDownloadUrlResponseSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
+import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
+import type { Stigmer } from "@stigmer/sdk";
+import { unzipSync } from "fflate";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { downloadExecutionArtifacts } from "./download.js";
+import { pushSkill } from "./skill.js";
+
+const SKILL_MD = ["---", "name: my-skill", "---", "# My Skill"].join("\n");
+const ARTIFACT_BODY = "hello artifact contents";
+
+let backend: Http2Server;
+let storage: HttpServer;
+let storageUrl: string;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+let pushedArtifacts: Uint8Array[] = [];
+let pushedTags: string[] = [];
+
+beforeEach(() => {
+  pushedArtifacts = [];
+  pushedTags = [];
+});
+
+const execution = create(AgentExecutionSchema, {
+  metadata: { id: "aex_done" },
+  status: {
+    phase: ExecutionPhase.EXECUTION_COMPLETED,
+    artifacts: [
+      { name: "report.txt", storageKey: "store/report.txt", sizeBytes: 23n, downloadUrl: "" },
+      { name: "broken.txt", storageKey: "store/missing.txt", sizeBytes: 5n, downloadUrl: "" },
+    ],
+  },
+});
+
+beforeAll(async () => {
+  // Object-storage stand-in: serves the good key, 404s anything else.
+  storage = createHttpServer((req, res) => {
+    if (req.url === "/store/report.txt") {
+      res.writeHead(200, { "content-type": "text/plain" });
+      res.end(ARTIFACT_BODY);
+      return;
+    }
+    res.writeHead(404);
+    res.end("not found");
+  });
+  await new Promise<void>((resolve) => storage.listen(0, "127.0.0.1", resolve));
+  storageUrl = `http://127.0.0.1:${(storage.address() as AddressInfo).port}`;
+
+  const routes = (router: ConnectRouter) => {
+    router.service(SkillCommandController, {
+      push: (req) => {
+        pushedArtifacts.push(req.artifact);
+        pushedTags.push(req.tag);
+        return create(SkillSchema, {
+          metadata: { id: "skl_1", slug: "my-skill", version: { id: "v2", previousVersionId: "v1" } },
+          spec: { tag: req.tag },
+          status: { versionHash: "abcdef1234567890" },
+        });
+      },
+    });
+    router.service(AgentExecutionQueryController, {
+      get: (req) => {
+        if (req.value !== "aex_done") throw new ConnectError("not found", Code.NotFound);
+        return execution;
+      },
+      getArtifactDownloadUrl: (req) =>
+        create(GetArtifactDownloadUrlResponseSchema, { downloadUrl: `${storageUrl}/${req.storageKey}` }),
+    });
+  };
+
+  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()));
+  await new Promise<void>((resolve) => storage.close(() => resolve()));
+});
+
+describe("pushSkill", () => {
+  it("zips a directory and uploads a valid artifact", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "push-it-"));
+    try {
+      writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+      writeFileSync(join(dir, "tool.py"), "print('x')\n");
+      writeFileSync(join(dir, ".env"), "SECRET=1\n"); // must be excluded
+
+      const result = await pushSkill(client, dir, "acme", "v1.2.3", "first push", {
+        respectGitignore: true,
+        extraIgnore: [],
+        extraInclude: [],
+      });
+
+      expect(result.skillName).toBe("my-skill");
+      expect(result.slug).toBe("my-skill");
+      expect(result.tag).toBe("v1.2.3");
+      expect(result.versionChanged).toBe(true);
+      expect(result.isNewResource).toBe(false);
+      expect(pushedTags).toEqual(["v1.2.3"]);
+
+      const entries = Object.keys(unzipSync(pushedArtifacts[0])).sort();
+      expect(entries).toEqual(["SKILL.md", "tool.py"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("defaults an empty tag to 'latest'", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "push-it-"));
+    try {
+      writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+      await pushSkill(client, dir, "acme", "", "", { respectGitignore: true, extraIgnore: [], extraInclude: [] });
+      expect(pushedTags).toEqual(["latest"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("downloadExecutionArtifacts", () => {
+  it("downloads available artifacts and tolerates partial failures", async () => {
+    const out = mkdtempSync(join(tmpdir(), "dl-it-"));
+    try {
+      const outcome = await downloadExecutionArtifacts(client, "aex_done", { artifactName: "", outputDir: out });
+      expect(outcome.total).toBe(2);
+      expect(outcome.downloaded).toBe(1); // broken.txt 404s, report.txt succeeds
+      expect(outcome.noArtifacts).toBe(false);
+      expect(readFileSync(join(out, "report.txt"), "utf8")).toBe(ARTIFACT_BODY);
+    } finally {
+      rmSync(out, { recursive: true, force: true });
+    }
+  });
+
+  it("filters to a named artifact", async () => {
+    const out = mkdtempSync(join(tmpdir(), "dl-it-"));
+    try {
+      const outcome = await downloadExecutionArtifacts(client, "aex_done", { artifactName: "report.txt", outputDir: out });
+      expect(outcome.total).toBe(1);
+      expect(outcome.downloaded).toBe(1);
+    } finally {
+      rmSync(out, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/read-completion.integration.test.ts

@@ -0,0 +1,156 @@
+// In-process integration test for the Wave 2b read surface: search, execution
+// get/list, session list, and usage reports.
+//
+// Stands up a real Connect backend over h2c serving the controllers these paths
+// call, points an SDK node client at it, and drives the resource layer end to
+// end. Asserts the SDK wiring (request shapes, RPC routing) and the protojson
+// parity contract for json output.
+
+import { create, toJson } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { GetSessionUsageReportOutputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionQueryController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { SearchResultSchema } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/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, describe, expect, it } from "vitest";
+import { classify, ExitCode } from "../errors/index.js";
+import { getExecution, listAgentExecutions, renderExecutionList } from "./execution.js";
+import { renderResource } from "./render.js";
+import { searchResources } from "./search.js";
+import { listSessions, renderSessionList } from "./session.js";
+import { getSessionUsageReport, renderSessionUsage } from "./usage.js";
+
+const knownExec = create(AgentExecutionSchema, {
+  metadata: { id: "aex_1", org: "acme" },
+  spec: { agentId: "agt_1" },
+  status: { phase: ExecutionPhase.EXECUTION_COMPLETED, startedAt: "2026-03-01T10:00:00Z" },
+});
+
+const knownSession = create(SessionSchema, {
+  metadata: { id: "ses_1", org: "acme" },
+  spec: { agentInstanceId: "agi_1", subject: "Fix the build" },
+});
+
+const knownSearchResult = create(SearchResultSchema, {
+  kind: ApiResourceKind.workflow,
+  id: "wfl_1",
+  name: "Deploy",
+  slug: "deploy",
+  qualifiedSlug: "acme/deploy",
+  org: "acme",
+  description: "deploys things",
+});
+
+const knownUsage = create(GetSessionUsageReportOutputSchema, {
+  sessionId: "ses_1",
+  executionCount: 1,
+  modelBreakdown: [{ model: "claude-sonnet-4", inputTokens: 1000n, outputTokens: 100n, billableCostMicros: 500000n }],
+});
+
+let backend: Http2Server;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentExecutionQueryController, {
+      get: (req) => {
+        if (req.value !== "aex_1") throw new ConnectError("execution not found", Code.NotFound);
+        return knownExec;
+      },
+      list: () => ({ totalPages: 1, entries: [knownExec] }),
+      getSessionUsageReport: (req) => {
+        if (req.sessionId !== "ses_1") throw new ConnectError("session not found", Code.NotFound);
+        return knownUsage;
+      },
+    });
+    router.service(SessionQueryController, {
+      list: () => ({ totalPages: 1, entries: [knownSession] }),
+    });
+    router.service(SearchService, {
+      search: () => ({ entries: [knownSearchResult], totalCount: 1, totalPages: 1 }),
+    });
+  };
+  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("search integration", () => {
+  it("queries the SearchService and renders entries as protojson", async () => {
+    const outcome = await searchResources(client, ApiResourceKind.workflow, "deploy", {
+      org: "acme",
+      excludePublic: false,
+      page: 1,
+      pageSize: 20,
+    }, "json");
+    expect(JSON.parse(outcome.rendered)).toEqual([
+      toJson(SearchResultSchema, knownSearchResult, { useProtoFieldName: true }),
+    ]);
+    expect(outcome.totalPages).toBe(1);
+  });
+
+  it("renders a human table for search results", async () => {
+    const outcome = await searchResources(client, ApiResourceKind.workflow, "deploy", {
+      org: "acme",
+      excludePublic: false,
+      page: 1,
+      pageSize: 20,
+    }, "table");
+    expect(outcome.rendered).toContain("acme/deploy");
+  });
+});
+
+describe("execution integration", () => {
+  it("gets an agent execution by ID and renders backend protojson", async () => {
+    const { schema, message } = await getExecution(client, "aex_1");
+    expect(JSON.parse(renderResource(schema, message, "json"))).toEqual(
+      toJson(AgentExecutionSchema, knownExec, { useProtoFieldName: true }),
+    );
+  });
+
+  it("maps a NotFound execution to ExitCode.NotFound", async () => {
+    const err = await getExecution(client, "aex_missing").catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.NotFound);
+  });
+
+  it("lists agent executions as protojson envelope", async () => {
+    const result = await listAgentExecutions(client, 50);
+    const json = JSON.parse(renderExecutionList(result, "json", "agent"));
+    expect(json.entries[0].metadata.id).toBe("aex_1");
+  });
+});
+
+describe("session integration", () => {
+  it("lists sessions as a human table", async () => {
+    const result = await listSessions(client, 50);
+    expect(renderSessionList(result, "table")).toContain("ses_1");
+  });
+});
+
+describe("usage integration", () => {
+  it("fetches a session usage report and renders the table", async () => {
+    const report = await getSessionUsageReport(client, "ses_1");
+    expect(renderSessionUsage(report, "table")).toContain("Session: ses_1");
+  });
+});

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

@@ -0,0 +1,164 @@
+// In-process integration test for the read verbs (get/list).
+//
+// Stands up a real Connect backend over h2c serving the query controllers the
+// CLI calls, points an SDK node client at it, and drives the resource layer
+// (fetchResource / listResources) end to end. Asserts the rendered JSON matches
+// the backend's protojson (the parity contract) and that backend RPC errors map
+// to the right CLI exit code via classify().
+
+import { create, toJson } 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 { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+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 { ApiKeyQueryController } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/query_pb";
+import { SearchResultSchema } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/v1/query_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { OrganizationQueryController } from "@stigmer/protos/ai/stigmer/tenancy/organization/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, describe, expect, it } from "vitest";
+import { classify, ExitCode } from "../errors/index.js";
+import { fetchResource } from "./get.js";
+import { listResources } from "./list.js";
+import { renderResource } from "./render.js";
+
+const knownAgent = create(AgentSchema, {
+  apiVersion: "agentic.stigmer.ai/v1",
+  kind: "Agent",
+  metadata: { name: "Reviewer", slug: "reviewer", org: "acme", id: "agt_1" },
+  spec: { description: "reviews code" },
+});
+
+const knownOrg = create(OrganizationSchema, {
+  apiVersion: "tenancy.stigmer.ai/v1",
+  kind: "Organization",
+  metadata: { name: "Acme", slug: "acme", org: "acme", id: "org_1" },
+});
+
+const knownApiKey = create(ApiKeySchema, {
+  apiVersion: "iam.stigmer.ai/v1",
+  kind: "ApiKey",
+  metadata: { name: "ci", org: "acme", id: "key_1" },
+  spec: { fingerprint: "abcd", neverExpires: true },
+});
+
+const knownSearchResult = create(SearchResultSchema, {
+  kind: ApiResourceKind.agent,
+  id: "agt_1",
+  name: "Reviewer",
+  slug: "reviewer",
+  qualifiedSlug: "acme/reviewer",
+  org: "acme",
+  description: "reviews code",
+});
+
+let backend: Http2Server;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+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(SearchService, {
+      search: () => ({ entries: [knownSearchResult], totalCount: 1, totalPages: 1 }),
+    });
+    router.service(OrganizationQueryController, {
+      findMyOrganizations: () => ({ entries: [knownOrg] }),
+    });
+    router.service(ApiKeyQueryController, {
+      findAll: () => ({ entries: [knownApiKey] }),
+    });
+  };
+  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("get integration", () => {
+  it("fetches an agent by org/slug and renders backend protojson", async () => {
+    const { schema, message } = await fetchResource(client, ApiResourceKind.agent, {
+      kind: "ref",
+      org: "acme",
+      slug: "reviewer",
+    });
+    const rendered = JSON.parse(renderResource(schema, message, "json"));
+    expect(rendered).toEqual(toJson(AgentSchema, knownAgent, { useProtoFieldName: true }));
+  });
+
+  it("fetches an agent by ID", async () => {
+    const { message } = await fetchResource(client, ApiResourceKind.agent, { kind: "id", id: "agt_1" });
+    expect(JSON.parse(renderResource(AgentSchema, message, "json"))).toMatchObject({
+      metadata: { id: "agt_1" },
+    });
+  });
+
+  it("resolves an organization by slug through findMyOrganizations", async () => {
+    const { message } = await fetchResource(client, ApiResourceKind.organization, {
+      kind: "ref",
+      org: "acme",
+      slug: "acme",
+    });
+    expect(JSON.parse(renderResource(OrganizationSchema, message, "json"))).toMatchObject({
+      metadata: { slug: "acme" },
+    });
+  });
+
+  it("maps a NotFound backend error to ExitCode.NotFound", async () => {
+    const err = await fetchResource(client, ApiResourceKind.agent, { kind: "id", id: "missing" }).catch((e) => e);
+    const classified = classify(err);
+    expect(classified?.exitCode).toBe(ExitCode.NotFound);
+  });
+
+  it("rejects an unsupported kind with a usage error", async () => {
+    const err = await fetchResource(client, ApiResourceKind.environment, { kind: "id", id: "x" }).catch((e) => e);
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});
+
+describe("list integration", () => {
+  it("lists agents via the search service as JSON", async () => {
+    const out = await listResources(client, ApiResourceKind.agent, "acme", 50, "json");
+    expect(JSON.parse(out)).toEqual([toJson(SearchResultSchema, knownSearchResult, { useProtoFieldName: true })]);
+  });
+
+  it("lists organizations via findMyOrganizations as JSON", async () => {
+    const out = await listResources(client, ApiResourceKind.organization, "acme", 50, "json");
+    expect(JSON.parse(out)).toEqual([toJson(OrganizationSchema, knownOrg, { useProtoFieldName: true })]);
+  });
+
+  it("lists API keys via findAll as JSON", async () => {
+    const out = await listResources(client, ApiResourceKind.api_key, "acme", 50, "json");
+    expect(JSON.parse(out)).toEqual([toJson(ApiKeySchema, knownApiKey, { useProtoFieldName: true })]);
+  });
+
+  it("renders a human table for search-backed lists", async () => {
+    const out = await listResources(client, ApiResourceKind.agent, "acme", 50, "table");
+    expect(out).toContain("NAME");
+    expect(out).toContain("acme/reviewer");
+  });
+});