@stigmer/react 0.0.68 → 0.0.69

package/src/demo/__tests__/demo-client.test.tsx

@@ -0,0 +1,213 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { StigmerProvider } from "../../provider";
+import { createDemoClient } from "../client";
+import { DemoTransport } from "../transport";
+import { rpcKey } from "../types";
+
+describe("createDemoClient", () => {
+  it("returns a client accepted by StigmerProvider", () => {
+    const client = createDemoClient({ fixtures: new Map() });
+
+    render(
+      <StigmerProvider client={client}>
+        <div data-testid="child">rendered</div>
+      </StigmerProvider>,
+    );
+
+    expect(screen.getByTestId("child").textContent).toBe("rendered");
+  });
+
+  it("provides all expected resource clients", () => {
+    const client = createDemoClient({ fixtures: new Map() });
+
+    expect(client.agent).toBeDefined();
+    expect(client.agentExecution).toBeDefined();
+    expect(client.agentInstance).toBeDefined();
+    expect(client.apiKey).toBeDefined();
+    expect(client.environment).toBeDefined();
+    expect(client.executionContext).toBeDefined();
+    expect(client.iamPolicy).toBeDefined();
+    expect(client.identityAccount).toBeDefined();
+    expect(client.identityProvider).toBeDefined();
+    expect(client.mcpServer).toBeDefined();
+    expect(client.organization).toBeDefined();
+    expect(client.project).toBeDefined();
+    expect(client.session).toBeDefined();
+    expect(client.skill).toBeDefined();
+    expect(client.workflow).toBeDefined();
+    expect(client.workflowExecution).toBeDefined();
+    expect(client.workflowInstance).toBeDefined();
+    expect(client.search).toBeDefined();
+    expect(client.github).toBeDefined();
+  });
+});
+
+describe("DemoTransport", () => {
+  it("calls unary fixture handler and returns its result", async () => {
+    const fixtureResponse = { id: "test-123", name: "mock-session" };
+    const fixtures = new Map([
+      [
+        "test.Service/get",
+        { unary: () => fixtureResponse },
+      ],
+    ]);
+
+    const transport = new DemoTransport(fixtures);
+    const result = await transport.unary(
+      { parent: { typeName: "test.Service" }, name: "get" },
+      undefined,
+      undefined,
+      undefined,
+      { id: "test-123" },
+    );
+
+    expect(result.stream).toBe(false);
+    expect(result.message).toBe(fixtureResponse);
+    expect(result.header).toBeInstanceOf(Headers);
+    expect(result.trailer).toBeInstanceOf(Headers);
+  });
+
+  it("passes request to unary fixture handler", async () => {
+    const request = { value: "session-42" };
+    let receivedRequest: unknown;
+
+    const fixtures = new Map([
+      [
+        "test.Service/get",
+        {
+          unary: (req: unknown) => {
+            receivedRequest = req;
+            return {};
+          },
+        },
+      ],
+    ]);
+
+    const transport = new DemoTransport(fixtures);
+    await transport.unary(
+      { parent: { typeName: "test.Service" }, name: "get" },
+      undefined,
+      undefined,
+      undefined,
+      request,
+    );
+
+    expect(receivedRequest).toBe(request);
+  });
+
+  it("calls stream fixture handler and yields results", async () => {
+    const items = [
+      { id: "1", status: "running" },
+      { id: "1", status: "completed" },
+    ];
+
+    const fixtures = new Map([
+      [
+        "test.Service/subscribe",
+        { stream: () => items },
+      ],
+    ]);
+
+    const transport = new DemoTransport(fixtures);
+
+    async function* singleMessage() {
+      yield { value: "exec-1" };
+    }
+
+    const result = await transport.stream(
+      { parent: { typeName: "test.Service" }, name: "subscribe" },
+      undefined,
+      undefined,
+      undefined,
+      singleMessage(),
+    );
+
+    expect(result.stream).toBe(true);
+
+    const collected: unknown[] = [];
+    for await (const msg of result.message) {
+      collected.push(msg);
+    }
+    expect(collected).toEqual(items);
+  });
+
+  it("throws descriptive error for missing unary fixture", async () => {
+    const transport = new DemoTransport(new Map());
+
+    await expect(
+      transport.unary(
+        {
+          parent: {
+            typeName:
+              "ai.stigmer.agentic.session.v1.SessionQueryController",
+          },
+          name: "get",
+        },
+        undefined,
+        undefined,
+        undefined,
+        {},
+      ),
+    ).rejects.toThrow("No demo fixture for SessionQueryController/get");
+  });
+
+  it("throws descriptive error for missing stream fixture", async () => {
+    const transport = new DemoTransport(new Map());
+
+    async function* empty() {
+      yield {};
+    }
+
+    await expect(
+      transport.stream(
+        {
+          parent: {
+            typeName:
+              "ai.stigmer.agentic.agentexecution.v1.AgentExecutionQueryController",
+          },
+          name: "subscribe",
+        },
+        undefined,
+        undefined,
+        undefined,
+        empty(),
+      ),
+    ).rejects.toThrow(
+      "No demo fixture for AgentExecutionQueryController/subscribe",
+    );
+  });
+
+  it("includes the full fixture key in the error message", async () => {
+    const transport = new DemoTransport(new Map());
+
+    await expect(
+      transport.unary(
+        {
+          parent: {
+            typeName:
+              "ai.stigmer.agentic.session.v1.SessionQueryController",
+          },
+          name: "get",
+        },
+        undefined,
+        undefined,
+        undefined,
+        {},
+      ),
+    ).rejects.toThrow(
+      'key "ai.stigmer.agentic.session.v1.SessionQueryController/get"',
+    );
+  });
+});
+
+describe("rpcKey", () => {
+  it("constructs a fixture key from service descriptor and method name", () => {
+    const service = {
+      typeName: "ai.stigmer.agentic.session.v1.SessionQueryController",
+    };
+    expect(rpcKey(service, "get")).toBe(
+      "ai.stigmer.agentic.session.v1.SessionQueryController/get",
+    );
+  });
+});

package/src/demo/__tests__/fixtures.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect } from "vitest";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { fixtures, buildScenario, type FixtureSpec } from "../fixtures";
+import { rpcKey } from "../types";
+
+describe("fixtures", () => {
+  describe("session", () => {
+    it("get returns correct key and unary entry", () => {
+      const handler = () => ({ id: "test" });
+      const spec = fixtures.session.get(handler);
+
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.session.v1.SessionQueryController/get",
+      );
+      expect(spec.entry.unary).toBe(handler);
+      expect(spec.entry.stream).toBeUndefined();
+      expect(spec.searchResourceKind).toBeUndefined();
+    });
+
+    it("list returns correct key", () => {
+      const spec = fixtures.session.list(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.session.v1.SessionQueryController/list",
+      );
+    });
+
+    it("create returns correct key", () => {
+      const spec = fixtures.session.create(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.session.v1.SessionCommandController/create",
+      );
+    });
+
+    it("update returns correct key", () => {
+      const spec = fixtures.session.update(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.session.v1.SessionCommandController/update",
+      );
+    });
+  });
+
+  describe("agentExecution", () => {
+    it("subscribe returns a stream entry", () => {
+      const handler = () => [{ id: "1" }, { id: "2" }];
+      const spec = fixtures.agentExecution.subscribe(handler);
+
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.agentexecution.v1.AgentExecutionQueryController/subscribe",
+      );
+      expect(spec.entry.stream).toBe(handler);
+      expect(spec.entry.unary).toBeUndefined();
+    });
+
+    it("listBySession returns correct key", () => {
+      const spec = fixtures.agentExecution.listBySession(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.agentexecution.v1.AgentExecutionQueryController/listBySession",
+      );
+    });
+
+    it("create returns correct key", () => {
+      const spec = fixtures.agentExecution.create(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.agentexecution.v1.AgentExecutionCommandController/create",
+      );
+    });
+
+    it("getArtifactContent returns correct key", () => {
+      const spec = fixtures.agentExecution.getArtifactContent(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.agentexecution.v1.AgentExecutionQueryController/getArtifactContent",
+      );
+    });
+  });
+
+  describe("search-backed list helpers", () => {
+    const searchKey = "ai.stigmer.search.v1.SearchService/search";
+
+    it("agent.list sets searchResourceKind to agent", () => {
+      const spec = fixtures.agent.list(() => ({}));
+      expect(spec.key).toBe(searchKey);
+      expect(spec.searchResourceKind).toBe(ApiResourceKind.agent);
+    });
+
+    it("skill.list sets searchResourceKind to skill", () => {
+      const spec = fixtures.skill.list(() => ({}));
+      expect(spec.key).toBe(searchKey);
+      expect(spec.searchResourceKind).toBe(ApiResourceKind.skill);
+    });
+
+    it("mcpServer.list sets searchResourceKind to mcp_server", () => {
+      const spec = fixtures.mcpServer.list(() => ({}));
+      expect(spec.key).toBe(searchKey);
+      expect(spec.searchResourceKind).toBe(ApiResourceKind.mcp_server);
+    });
+  });
+
+  describe("other domains", () => {
+    it("agent.getByReference returns correct key", () => {
+      const spec = fixtures.agent.getByReference(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.agent.v1.AgentQueryController/getByReference",
+      );
+    });
+
+    it("skill.getByReference returns correct key", () => {
+      const spec = fixtures.skill.getByReference(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.skill.v1.SkillQueryController/getByReference",
+      );
+    });
+
+    it("environment.list returns correct key", () => {
+      const spec = fixtures.environment.list(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.environment.v1.EnvironmentQueryController/list",
+      );
+    });
+
+    it("agentInstance.create returns correct key", () => {
+      const spec = fixtures.agentInstance.create(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.agentic.agentinstance.v1.AgentInstanceCommandController/create",
+      );
+    });
+
+    it("apiKey.findAll returns correct key", () => {
+      const spec = fixtures.apiKey.findAll(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.iam.apikey.v1.ApiKeyQueryController/findAll",
+      );
+    });
+
+    it("github.getOAuthAuthorizeUrl returns correct key", () => {
+      const spec = fixtures.github.getOAuthAuthorizeUrl(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.platform.github.v1.GitHubService/getOAuthAuthorizeUrl",
+      );
+    });
+
+    it("organization.create returns correct key", () => {
+      const spec = fixtures.organization.create(() => ({}));
+      expect(spec.key).toBe(
+        "ai.stigmer.tenancy.organization.v1.OrganizationCommandController/create",
+      );
+    });
+  });
+});
+
+describe("buildScenario", () => {
+  it("creates a DemoScenario from direct fixture specs", () => {
+    const sessionData = { id: "ses-1" };
+    const scenario = buildScenario(
+      fixtures.session.get(() => sessionData),
+    );
+
+    expect(scenario.fixtures).toBeInstanceOf(Map);
+    const key = rpcKey(
+      { typeName: "ai.stigmer.agentic.session.v1.SessionQueryController" },
+      "get",
+    );
+    const entry = scenario.fixtures.get(key);
+    expect(entry?.unary?.({})).toBe(sessionData);
+  });
+
+  it("merges search-backed list fixtures into a dispatch handler", () => {
+    const agentData = { kind: "agent" };
+    const skillData = { kind: "skill" };
+
+    const scenario = buildScenario(
+      fixtures.agent.list(() => agentData),
+      fixtures.skill.list(() => skillData),
+    );
+
+    const searchKey = "ai.stigmer.search.v1.SearchService/search";
+    const entry = scenario.fixtures.get(searchKey);
+    expect(entry).toBeDefined();
+
+    expect(entry!.unary!({ kinds: [ApiResourceKind.agent] })).toBe(agentData);
+    expect(entry!.unary!({ kinds: [ApiResourceKind.skill] })).toBe(skillData);
+  });
+
+  it("throws for unregistered search resource kind", () => {
+    const scenario = buildScenario(
+      fixtures.agent.list(() => ({})),
+    );
+
+    const searchKey = "ai.stigmer.search.v1.SearchService/search";
+    const entry = scenario.fixtures.get(searchKey)!;
+
+    expect(() => entry.unary!({ kinds: [ApiResourceKind.skill] })).toThrow(
+      "No search fixture for resource kind skill",
+    );
+  });
+
+  it("combines direct and search specs", () => {
+    const scenario = buildScenario(
+      fixtures.session.get(() => ({ id: "ses-1" })),
+      fixtures.agent.list(() => ({ entries: [] })),
+    );
+
+    const sessionKey =
+      "ai.stigmer.agentic.session.v1.SessionQueryController/get";
+    const searchKey = "ai.stigmer.search.v1.SearchService/search";
+
+    expect(scenario.fixtures.has(sessionKey)).toBe(true);
+    expect(scenario.fixtures.has(searchKey)).toBe(true);
+  });
+
+  it("returns empty fixtures when called with no args", () => {
+    const scenario = buildScenario();
+    expect(scenario.fixtures.size).toBe(0);
+  });
+});

package/src/demo/__tests__/samples.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from "vitest";
+import { ExecutionPhase, MessageType, ToolCallStatus, ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { samples } from "../samples";
+
+describe("samples", () => {
+  describe("session", () => {
+    it("creates a session with defaults", () => {
+      const s = samples.session();
+      expect(s.apiVersion).toBe("agentic.stigmer.ai/v1");
+      expect(s.kind).toBe("Session");
+      expect(s.metadata?.name).toBe("demo-session");
+      expect(s.metadata?.org).toBe("demo");
+      expect(s.spec?.subject).toBe("Demo conversation");
+    });
+
+    it("applies overrides", () => {
+      const s = samples.session({ name: "my-chat", subject: "Custom topic", org: "acme" });
+      expect(s.metadata?.name).toBe("my-chat");
+      expect(s.metadata?.org).toBe("acme");
+      expect(s.spec?.subject).toBe("Custom topic");
+    });
+  });
+
+  describe("agent", () => {
+    it("creates an agent with defaults", () => {
+      const a = samples.agent();
+      expect(a.kind).toBe("Agent");
+      expect(a.metadata?.name).toBe("Demo Agent");
+      expect(a.spec?.description).toContain("sample agent");
+    });
+
+    it("derives slug from name override", () => {
+      const a = samples.agent({ name: "My Custom Agent" });
+      expect(a.metadata?.slug).toBe("my-custom-agent");
+    });
+  });
+
+  describe("agentExecution", () => {
+    it("creates a completed execution with default messages", () => {
+      const ex = samples.agentExecution();
+      expect(ex.kind).toBe("AgentExecution");
+      expect(ex.status?.phase).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+      expect(ex.status?.messages.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it("uses provided phase and messages", () => {
+      const msgs = [
+        samples.humanMessage("test input"),
+        samples.aiMessage("test response"),
+      ];
+      const ex = samples.agentExecution({
+        phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+        messages: msgs,
+      });
+      expect(ex.status?.phase).toBe(ExecutionPhase.EXECUTION_IN_PROGRESS);
+      expect(ex.status?.messages).toHaveLength(2);
+      expect(ex.status?.messages[0].content).toBe("test input");
+    });
+  });
+
+  describe("skill", () => {
+    it("creates a skill with SKILL.md content", () => {
+      const sk = samples.skill();
+      expect(sk.kind).toBe("Skill");
+      expect(sk.spec?.skillMd).toContain("# Demo Skill");
+    });
+
+    it("applies custom skillMd", () => {
+      const sk = samples.skill({ skillMd: "# My Skill\nCustom content" });
+      expect(sk.spec?.skillMd).toContain("# My Skill");
+    });
+  });
+
+  describe("mcpServer", () => {
+    it("creates an MCP server with defaults", () => {
+      const m = samples.mcpServer();
+      expect(m.kind).toBe("McpServer");
+      expect(m.metadata?.name).toBe("Demo MCP Server");
+    });
+  });
+
+  describe("environment", () => {
+    it("creates an environment with defaults", () => {
+      const e = samples.environment();
+      expect(e.kind).toBe("Environment");
+      expect(e.metadata?.name).toBe("demo-env");
+    });
+  });
+
+  describe("agentInstance", () => {
+    it("creates an agent instance referencing demo agent", () => {
+      const ai = samples.agentInstance();
+      expect(ai.kind).toBe("AgentInstance");
+      expect(ai.spec?.agentId).toContain("agt-");
+    });
+  });
+
+  describe("message primitives", () => {
+    it("humanMessage has correct type", () => {
+      const msg = samples.humanMessage("Hello");
+      expect(msg.type).toBe(MessageType.MESSAGE_HUMAN);
+      expect(msg.content).toBe("Hello");
+      expect(msg.timestamp).toBeTruthy();
+    });
+
+    it("aiMessage has correct type and optional tool calls", () => {
+      const tc = samples.toolCall("web-search", "results here");
+      const msg = samples.aiMessage("Here are the results", [tc]);
+      expect(msg.type).toBe(MessageType.MESSAGE_AI);
+      expect(msg.toolCalls).toHaveLength(1);
+      expect(msg.toolCalls[0].name).toBe("web-search");
+    });
+
+    it("toolCall is completed with a result", () => {
+      const tc = samples.toolCall("lookup-order", '{"orderId": "123"}');
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+      expect(tc.name).toBe("lookup-order");
+      expect(tc.result).toBe('{"orderId": "123"}');
+    });
+
+    it("artifact defaults to FILE kind", () => {
+      const a = samples.artifact("report.md");
+      expect(a.name).toBe("report.md");
+      expect(a.kind).toBe(ExecutionArtifactKind.FILE);
+      expect(a.storageKey).toContain("demo-artifact-");
+    });
+  });
+
+  describe("list responses", () => {
+    it("sessionList wraps sessions", () => {
+      const list = samples.sessionList();
+      expect(list.entries).toHaveLength(1);
+      expect(list.totalPages).toBe(1);
+    });
+
+    it("sessionList accepts custom entries", () => {
+      const sessions = [
+        samples.session({ name: "s1" }),
+        samples.session({ name: "s2" }),
+      ];
+      const list = samples.sessionList(sessions);
+      expect(list.entries).toHaveLength(2);
+    });
+
+    it("agentExecutionList wraps executions", () => {
+      const list = samples.agentExecutionList();
+      expect(list.entries).toHaveLength(1);
+      expect(list.totalPages).toBe(1);
+    });
+
+    it("searchResponse wraps search results", () => {
+      const resp = samples.searchResponse();
+      expect(resp.entries).toHaveLength(1);
+      expect(resp.totalCount).toBe(1);
+      expect(resp.totalPages).toBe(1);
+    });
+
+    it("searchResult accepts overrides", () => {
+      const r = samples.searchResult({
+        kind: ApiResourceKind.skill,
+        name: "My Skill",
+        slug: "my-skill",
+        org: "acme",
+      });
+      expect(r.kind).toBe(ApiResourceKind.skill);
+      expect(r.name).toBe("My Skill");
+      expect(r.qualifiedSlug).toBe("acme/my-skill");
+    });
+  });
+});

package/src/demo/client.ts

@@ -0,0 +1,78 @@
+import type { Transport } from "@connectrpc/connect";
+import type { Stigmer } from "@stigmer/sdk";
+import {
+  AgentClient,
+  AgentExecutionClient,
+  AgentInstanceClient,
+  ApiKeyClient,
+  EnvironmentClient,
+  ExecutionContextClient,
+  GitHubClient,
+  IamPolicyClient,
+  IdentityAccountClient,
+  IdentityProviderClient,
+  McpServerClient,
+  OrganizationClient,
+  ProjectClient,
+  SearchClient,
+  SessionClient,
+  SkillClient,
+  WorkflowClient,
+  WorkflowExecutionClient,
+  WorkflowInstanceClient,
+} from "@stigmer/sdk";
+import { DemoTransport } from "./transport";
+import type { DemoScenario } from "./types";
+
+/**
+ * Create a `Stigmer`-compatible client backed by in-memory fixture data.
+ *
+ * The returned object is structurally identical to a real {@link Stigmer}
+ * instance — all 17 resource clients plus `search` and `github` — but
+ * every RPC resolves through a {@link DemoTransport} instead of a network
+ * connection. Pass it to `<StigmerProvider client={...}>` and all
+ * descendant hooks and components work without a live backend.
+ *
+ * RPCs that have no registered fixture throw a descriptive error
+ * identifying the missing key. Register fixtures in the
+ * {@link DemoScenario} to cover the RPCs your components need.
+ *
+ * @example
+ * ```tsx
+ * import { StigmerProvider } from "@stigmer/react";
+ * import { createDemoClient } from "@stigmer/react/demo";
+ *
+ * const client = createDemoClient({ fixtures: myScenarioFixtures });
+ *
+ * <StigmerProvider client={client}>
+ *   <App />
+ * </StigmerProvider>
+ * ```
+ */
+export function createDemoClient(scenario: DemoScenario): Stigmer {
+  const transport = new DemoTransport(
+    scenario.fixtures,
+  ) as unknown as Transport;
+
+  return {
+    agent: new AgentClient(transport),
+    agentExecution: new AgentExecutionClient(transport),
+    agentInstance: new AgentInstanceClient(transport),
+    apiKey: new ApiKeyClient(transport),
+    environment: new EnvironmentClient(transport),
+    executionContext: new ExecutionContextClient(transport),
+    iamPolicy: new IamPolicyClient(transport),
+    identityAccount: new IdentityAccountClient(transport),
+    identityProvider: new IdentityProviderClient(transport),
+    mcpServer: new McpServerClient(transport),
+    organization: new OrganizationClient(transport),
+    project: new ProjectClient(transport),
+    session: new SessionClient(transport),
+    skill: new SkillClient(transport),
+    workflow: new WorkflowClient(transport),
+    workflowExecution: new WorkflowExecutionClient(transport),
+    workflowInstance: new WorkflowInstanceClient(transport),
+    search: new SearchClient(transport),
+    github: new GitHubClient(transport),
+  } as Stigmer;
+}