@stigmer/cli 3.0.8

package/src/resources/apply/synth/capstone.integration.test.ts

@@ -0,0 +1,134 @@
+// Capstone end-to-end test — the test the Go feature could never have.
+//
+// A real TypeScript entry point that imports `@stigmer/sdk/synth` is executed by
+// the REAL synthesize() (which spawns `npx tsx`), writing genuine `.pb` files;
+// those are then read and reconciled against an in-process backend. This is the
+// single test that exercises BOTH halves of the feature across the subprocess
+// boundary — producer (SDK) and consumer (CLI) — proving they actually connect.
+//
+// The fixture is created inside this package so the spawned `tsx` resolves
+// `@stigmer/sdk/synth` through the workspace node_modules via upward traversal
+// (a tmp dir under the OS temp root could not resolve the workspace packages).
+// Flakiness mitigations: a generous timeout (first `tsx` run transpiles the SDK)
+// and `prepare` disabled (the fixture borrows the workspace node_modules rather
+// than installing its own).
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { type ConnectRouter, createClient } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_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 { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { Project } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/api_pb";
+import { ProjectCommandController } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/command_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { createNodeClient, createNodeTransport, normalizeEndpoint } from "@stigmer/sdk/node";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { detectTrack } from "../declarative.js";
+import type { ControllerFn } from "../handlers.js";
+import { applyProjectTrack } from "./project-track.js";
+
+let backend: Http2Server;
+let stigmer: Stigmer;
+let controllerFn: ControllerFn;
+const openSessions = new Set<ServerHttp2Session>();
+let appliedProject: Project | undefined;
+
+// A real entry point exercising the public producer API end to end.
+const ENTRY_SOURCE = `import { defineProject } from "@stigmer/sdk/synth";
+
+const project = defineProject((ctx) => {
+  ctx.skill.fromDir("my-skill");
+  ctx.agent({ name: "Reviewer", slug: "reviewer", org: "acme", instructions: "review code" });
+});
+
+await project.synth();
+`;
+
+function makeFixture(dir: string): void {
+  writeFileSync(
+    join(dir, "stigmer.yaml"),
+    ["kind: Project", "metadata:", "  name: Demo", "  slug: demo", "spec:", "  entry_point: index.ts", ""].join("\n"),
+  );
+  writeFileSync(join(dir, "index.ts"), ENTRY_SOURCE);
+  mkdirSync(join(dir, "my-skill"));
+  writeFileSync(join(dir, "my-skill", "SKILL.md"), ["---", "name: my-skill", "---", "# My Skill"].join("\n"));
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentCommandController, { apply: (req) => req });
+    router.service(SkillCommandController, {
+      push: (req) =>
+        create(SkillSchema, {
+          metadata: { id: "skl_1", slug: "my-skill", version: { id: "v1" } },
+          spec: { tag: req.tag },
+          status: { versionHash: "abc123" },
+        }),
+    });
+    router.service(ProjectCommandController, {
+      apply: (req) => {
+        appliedProject = req;
+        return req;
+      },
+    });
+  };
+
+  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;
+  const baseUrl = normalizeEndpoint(`127.0.0.1:${port}`);
+  stigmer = createNodeClient({ baseUrl });
+  const transport = createNodeTransport({ baseUrl });
+  controllerFn = (service) => createClient(service, transport);
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("capstone: real SDK synthesis → CLI reconcile", () => {
+  it(
+    "runs a real @stigmer/sdk/synth entry point through tsx and reconciles it",
+    async () => {
+      // Created inside the package so the spawned tsx resolves @stigmer/sdk.
+      const dir = mkdtempSync(join(process.cwd(), "capstone-"));
+      try {
+        makeFixture(dir);
+        const detect = detectTrack(dir);
+        expect(detect.track).toBe("project");
+
+        const result = await applyProjectTrack(detect, {
+          controller: controllerFn,
+          stigmer,
+          org: "acme",
+          info: () => {},
+          warn: () => {},
+          // Real spawn (default); only skip the node_modules readiness check —
+          // the fixture borrows the workspace install via upward traversal.
+          synthesizeDeps: { prepare: () => {} },
+        });
+
+        expect(result.status).toBe("success");
+        const members = appliedProject?.spec?.members ?? [];
+        const skill = members.find((m) => m.kind === ApiResourceKind.skill);
+        const agent = members.find((m) => m.kind === ApiResourceKind.agent);
+        expect(skill).toMatchObject({ org: "acme", slug: "my-skill" });
+        expect(agent).toMatchObject({ org: "acme", slug: "reviewer" });
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+    120_000,
+  );
+});

package/src/resources/apply/synth/project-track.integration.test.ts

@@ -0,0 +1,194 @@
+// In-process integration test for the synthesis (project) track.
+//
+// Stands up a Connect backend (agent + skill + project controllers) and drives
+// applyProjectTrack end to end against a temp project directory whose
+// entry_point is "synthesized" by an injected spawn that writes `.pb` fixtures
+// into STIGMER_OUT_DIR (the same contract the real SDK writer produces). This
+// proves the consumer half — synthesize → read → shared reconciler — without a
+// real subprocess; the capstone test exercises the real `tsx` run.
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { create, toBinary } from "@bufbuild/protobuf";
+import { type ConnectRouter, createClient } 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 { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
+import { LocalDirSchema, SkillSynthSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/synth_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { Project } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/api_pb";
+import { ProjectCommandController } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/command_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { createNodeClient, createNodeTransport, normalizeEndpoint } from "@stigmer/sdk/node";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { detectTrack } from "../declarative.js";
+import type { ControllerFn } from "../handlers.js";
+import type { SpawnFn } from "./synthesize.js";
+import { applyProjectTrack, previewProjectTrack } from "./project-track.js";
+
+let backend: Http2Server;
+let stigmer: Stigmer;
+let controllerFn: ControllerFn;
+const openSessions = new Set<ServerHttp2Session>();
+
+let appliedProject: Project | undefined;
+
+beforeEach(() => {
+  appliedProject = undefined;
+});
+
+// A stigmer.yaml with entry_point makes detectTrack pick the project track; the
+// my-skill dir is the target of the synthesized local SkillSynth.
+function makeProject(dir: string): void {
+  writeFileSync(
+    join(dir, "stigmer.yaml"),
+    [
+      "kind: Project",
+      "metadata:",
+      "  name: Demo",
+      "  slug: demo",
+      "spec:",
+      "  entry_point: index.ts",
+      "",
+    ].join("\n"),
+  );
+  writeFileSync(join(dir, "index.ts"), "// synthesized by the injected spawn in this test\n");
+  mkdirSync(join(dir, "my-skill"));
+  writeFileSync(join(dir, "my-skill", "SKILL.md"), ["---", "name: my-skill", "---", "# My Skill"].join("\n"));
+}
+
+// Injected spawn standing in for `npx tsx index.ts`: writes the .pb files the
+// SDK writer would produce into STIGMER_OUT_DIR.
+const fakeSpawn: SpawnFn = async (_command, _args, options) => {
+  const outDir = options.env.STIGMER_OUT_DIR ?? "";
+  writeFileSync(
+    join(outDir, "agent-0.pb"),
+    toBinary(
+      AgentSchema,
+      create(AgentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: { name: "Reviewer", slug: "reviewer" },
+        spec: { description: "r" },
+      }),
+    ),
+  );
+  writeFileSync(
+    join(outDir, "skill-0.pb"),
+    toBinary(
+      SkillSynthSchema,
+      create(SkillSynthSchema, {
+        source: { case: "local", value: create(LocalDirSchema, { path: "my-skill" }) },
+        tag: "latest",
+      }),
+    ),
+  );
+  return { exitCode: 0, stdout: "", stderr: "" };
+};
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentCommandController, { apply: (req) => req });
+    router.service(SkillCommandController, {
+      push: (req) =>
+        create(SkillSchema, {
+          metadata: { id: "skl_1", slug: "my-skill", version: { id: "v1" } },
+          spec: { tag: req.tag },
+          status: { versionHash: "abc123" },
+        }),
+    });
+    router.service(ProjectCommandController, {
+      apply: (req) => {
+        appliedProject = req;
+        return req;
+      },
+    });
+  };
+
+  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;
+  const baseUrl = normalizeEndpoint(`127.0.0.1:${port}`);
+  stigmer = createNodeClient({ baseUrl });
+  const transport = createNodeTransport({ baseUrl });
+  controllerFn = (service) => createClient(service, transport);
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("applyProjectTrack", () => {
+  it("synthesizes, reads, and reconciles project membership", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "synth-it-"));
+    try {
+      makeProject(dir);
+      const detect = detectTrack(dir);
+      expect(detect.track).toBe("project");
+
+      const result = await applyProjectTrack(detect, {
+        controller: controllerFn,
+        stigmer,
+        org: "acme",
+        info: () => {},
+        warn: () => {},
+        synthesizeDeps: { spawn: fakeSpawn, prepare: () => {} },
+      });
+
+      expect(result.status).toBe("success");
+
+      expect(appliedProject).toBeDefined();
+      const members = appliedProject?.spec?.members ?? [];
+      expect(members).toHaveLength(2);
+
+      const skill = members.find((m) => m.kind === ApiResourceKind.skill);
+      const agent = members.find((m) => m.kind === ApiResourceKind.agent);
+      expect(skill).toMatchObject({ org: "acme", slug: "my-skill" });
+      expect(agent).toMatchObject({ org: "acme", slug: "reviewer" });
+
+      expect(appliedProject?.metadata?.org).toBe("acme");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("dry-run previews the configuration without synthesizing or applying", () => {
+    const dir = mkdtempSync(join(tmpdir(), "synth-dry-"));
+    try {
+      makeProject(dir);
+      const detect = detectTrack(dir);
+
+      const result = previewProjectTrack(detect);
+
+      expect(result.status).toBe("success");
+      expect(appliedProject).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("dry-run warns when the entry point file is missing", () => {
+    const dir = mkdtempSync(join(tmpdir(), "synth-dry-missing-"));
+    try {
+      makeProject(dir);
+      rmSync(join(dir, "index.ts"));
+      const detect = detectTrack(dir);
+
+      const result = previewProjectTrack(detect);
+      const text = JSON.stringify(result);
+      expect(text).toContain("Entry point file not found");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/apply/synth/project-track.ts

@@ -0,0 +1,126 @@
+// Synthesis (project) track: the consumer adapter for `apply entry_point`.
+//
+// Its job mirrors the declarative adapter's — turn a source into resources +
+// skill sources — but the source here is the SDK program rather than YAML
+// files: infer the runtime, run synthesis (subprocess → `.pb`), decode the
+// output, normalize it into the shared shapes, then hand off to the ONE shared
+// reconciler (DD-009 §6). There is no parallel project-apply path.
+//
+// Resources are emitted in dependency-apply order (mcp_server → agent →
+// workflow), matching the declarative track's APPLY_ORDER so parents land before
+// dependents — a deliberate, more-correct ordering than the Go synth path
+// (which applied agents first).
+
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { UsageError } from "../../../errors/index.js";
+import { CommandResult } from "../../../output/index.js";
+import {
+  type DeclarativeDeps,
+  type DetectResult,
+  type ReconcileResource,
+  reconcileProjectMembers,
+  type SkillSource,
+} from "../declarative.js";
+import { APPLY_HANDLERS, type ApplyHandler } from "../handlers.js";
+import type { SynthesisResult } from "./reader.js";
+import { readSynthesisOutput } from "./reader.js";
+import { inferRuntime } from "./runtime.js";
+import type { SynthesizeDeps } from "./synthesize.js";
+import { synthesize } from "./synthesize.js";
+
+/** Deps for the project track: the reconciler deps plus injectable synthesis. */
+export interface ProjectTrackDeps extends DeclarativeDeps {
+  /** Injectable synthesis collaborators (real subprocess by default). */
+  readonly synthesizeDeps?: SynthesizeDeps;
+}
+
+/**
+ * Apply an SDK project: synthesize the entry point, read the `.pb` output, and
+ * reconcile membership through the shared reconciler. Returns the summary
+ * CommandResult for the caller to render.
+ */
+export async function applyProjectTrack(detect: DetectResult, deps: ProjectTrackDeps): Promise<CommandResult> {
+  const { project, configDir } = detect;
+  if (project === undefined || configDir === undefined) {
+    throw new UsageError("project synthesis requires a stigmer.yaml project with an entry_point");
+  }
+  const entryPoint = project.spec?.entryPoint ?? "";
+  if (entryPoint === "") throw new UsageError("project has no entry_point");
+
+  const runtime = inferRuntime(entryPoint);
+  deps.info(`SDK mode: ${entryPoint} (runtime: ${runtime})`);
+
+  const { outputDir } = await synthesize(
+    { projectDir: configDir, entryPoint, runtime, orgId: deps.org },
+    deps.synthesizeDeps,
+  );
+  const synth = readSynthesisOutput(outputDir);
+  deps.info(
+    `Synthesis complete: ${synth.agents.length} agent(s), ${synth.workflows.length} workflow(s), ` +
+      `${synth.mcpServers.length} MCP server(s), ${synth.skillSynths.length} skill(s)`,
+  );
+
+  const resources = toReconcileResources(synth);
+  const skillSources = toSkillSources(synth, configDir);
+
+  return reconcileProjectMembers(project, resources, skillSources, deps);
+}
+
+/**
+ * Dry-run preview: validate the project configuration statically (no synthesis,
+ * no backend), warning if the entry point file is missing. Port of Go's
+ * executeSDKDryRun.
+ */
+export function previewProjectTrack(detect: DetectResult): CommandResult {
+  const { project, configDir } = detect;
+  if (project === undefined || configDir === undefined) {
+    throw new UsageError("project synthesis requires a stigmer.yaml project with an entry_point");
+  }
+  const entryPoint = project.spec?.entryPoint ?? "";
+  const runtime = inferRuntime(entryPoint);
+
+  const result = CommandResult.success("Dry run: SDK project configuration is valid");
+  const section = result.addSection("Project");
+  if (project.metadata?.name) section.field("Name", project.metadata.name);
+  section.field("Entry Point", entryPoint);
+  section.field("Runtime", runtime);
+
+  if (!existsSync(join(configDir, entryPoint))) {
+    result.addSection("Warning").item(`Entry point file not found: ${entryPoint}`);
+  }
+  result.hint("Remove --dry-run to execute synthesis and apply resources");
+  return result;
+}
+
+// Normalize decoded protos into ReconcileResources in dependency-apply order.
+function toReconcileResources(synth: SynthesisResult): ReconcileResource[] {
+  const resources: ReconcileResource[] = [];
+  for (const message of synth.mcpServers) resources.push({ handler: handlerFor(ApiResourceKind.mcp_server), message });
+  for (const message of synth.agents) resources.push({ handler: handlerFor(ApiResourceKind.agent), message });
+  for (const message of synth.workflows) resources.push({ handler: handlerFor(ApiResourceKind.workflow), message });
+  return resources;
+}
+
+// Normalize SkillSynths into SkillSources; local paths resolve relative to the
+// project dir (matching Go's pushSkillSynth).
+function toSkillSources(synth: SynthesisResult, configDir: string): SkillSource[] {
+  return synth.skillSynths.map((skill) => {
+    if (skill.source.case === "local") {
+      const path = skill.source.value.path;
+      return { kind: "local", dir: isAbsolute(path) ? path : join(configDir, path), tag: skill.tag };
+    }
+    if (skill.source.case === "git") {
+      const git = skill.source.value;
+      return { kind: "git", url: git.url, ref: git.ref, subdir: git.subdir, tag: skill.tag };
+    }
+    throw new UsageError("skill synthesis has no source configured (neither local nor git)");
+  });
+}
+
+function handlerFor(kind: ApiResourceKind): ApplyHandler {
+  const handler = APPLY_HANDLERS.get(kind);
+  if (handler === undefined) throw new UsageError(`apply not implemented for ${ApiResourceKind[kind]}`);
+  return handler;
+}

package/src/resources/apply/synth/reader.test.ts

@@ -0,0 +1,90 @@
+// Reader fixtures: encode protos with toBinary into a tmp dir, then assert the
+// reader globs/sorts/decodes them, tolerates a missing dir and a missing
+// dependencies.json, and errors when no resources are present.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { create, toBinary } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { LocalDirSchema, SkillSynthSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/synth_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readSynthesisOutput } from "./reader.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "synth-reader-"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function writeAgent(name: string, slug: string, file: string): void {
+  const agent = create(AgentSchema, { apiVersion: "agentic.stigmer.ai/v1", kind: "Agent", metadata: { name, slug } });
+  writeFileSync(join(dir, file), toBinary(AgentSchema, agent));
+}
+
+describe("readSynthesisOutput", () => {
+  it("decodes every kind and groups by kind", () => {
+    writeAgent("Support", "support", "agent-0.pb");
+    writeFileSync(
+      join(dir, "workflow-0.pb"),
+      toBinary(WorkflowSchema, create(WorkflowSchema, { metadata: { name: "Onboard", slug: "onboard" } })),
+    );
+    writeFileSync(
+      join(dir, "mcpserver-0.pb"),
+      toBinary(McpServerSchema, create(McpServerSchema, { metadata: { name: "FS", slug: "fs" } })),
+    );
+    writeFileSync(
+      join(dir, "skill-0.pb"),
+      toBinary(
+        SkillSynthSchema,
+        create(SkillSynthSchema, { source: { case: "local", value: create(LocalDirSchema, { path: "./calc" }) } }),
+      ),
+    );
+
+    const result = readSynthesisOutput(dir);
+
+    expect(result.agents).toHaveLength(1);
+    expect(result.agents[0].metadata?.slug).toBe("support");
+    expect(result.workflows[0].metadata?.slug).toBe("onboard");
+    expect(result.mcpServers[0].metadata?.slug).toBe("fs");
+    expect(result.skillSynths[0].source.case).toBe("local");
+  });
+
+  it("globs and lexically sorts files of the same kind", () => {
+    writeAgent("A0", "a0", "agent-0.pb");
+    writeAgent("A1", "a1", "agent-1.pb");
+    writeAgent("A2", "a2", "agent-2.pb");
+
+    const result = readSynthesisOutput(dir);
+
+    expect(result.agents.map((a) => a.metadata?.slug)).toEqual(["a0", "a1", "a2"]);
+  });
+
+  it("tolerates a directory with no dependencies.json", () => {
+    writeAgent("Solo", "solo", "agent-0.pb");
+    // No dependencies.json written — must not throw.
+    expect(() => readSynthesisOutput(dir)).not.toThrow();
+  });
+
+  it("ignores unrelated files", () => {
+    writeAgent("Solo", "solo", "agent-0.pb");
+    writeFileSync(join(dir, "dependencies.json"), "{}");
+    writeFileSync(join(dir, "notes.txt"), "hi");
+    const result = readSynthesisOutput(dir);
+    expect(result.agents).toHaveLength(1);
+  });
+
+  it("throws when the output has no resources", () => {
+    expect(() => readSynthesisOutput(dir)).toThrow(/no resources found/);
+  });
+
+  it("throws when the output directory does not exist", () => {
+    expect(() => readSynthesisOutput(join(dir, "missing"))).toThrow(/no resources found/);
+  });
+});

package/src/resources/apply/synth/reader.ts

@@ -0,0 +1,68 @@
+// Reader for SDK synthesis output.
+//
+// The SDK writes one binary proto per resource into the out dir:
+//   skill-N.pb       (SkillSynth — input for skill push)
+//   mcpserver-N.pb   (McpServer)
+//   agent-N.pb       (Agent)
+//   workflow-N.pb    (Workflow)
+// We glob each `<kind>-*.pb`, sort lexically (matching Go's reader so the same
+// bytes read identically on both consumers), and decode with `fromBinary`
+// (DD-009 §3). At least one resource must be present.
+//
+// `dependencies.json` (Go's local-only dependency graph) is deliberately NOT
+// consumed: no dependency-graph validation feature exists, and the TS SDK does
+// not emit it. Its absence is therefore tolerated by construction (DD-009).
+// Port of `internal/cli/synthesis/reader.go`.
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type DescMessage, fromBinary, type MessageShape } from "@bufbuild/protobuf";
+import { type Agent, AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { type McpServer, McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { type SkillSynth, SkillSynthSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/synth_pb";
+import { type Workflow, WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { UsageError } from "../../../errors/index.js";
+
+/** Decoded synthesis output, grouped by kind in read order. */
+export interface SynthesisResult {
+  readonly skillSynths: SkillSynth[];
+  readonly mcpServers: McpServer[];
+  readonly agents: Agent[];
+  readonly workflows: Workflow[];
+}
+
+/**
+ * Read and decode all synthesized `.pb` files from `outputDir`. Throws a
+ * UsageError if the synthesis produced no resources (a program that registered
+ * nothing, or wrote to the wrong directory).
+ */
+export function readSynthesisOutput(outputDir: string): SynthesisResult {
+  const skillSynths = readProtoFiles(outputDir, "skill-", SkillSynthSchema);
+  const mcpServers = readProtoFiles(outputDir, "mcpserver-", McpServerSchema);
+  const agents = readProtoFiles(outputDir, "agent-", AgentSchema);
+  const workflows = readProtoFiles(outputDir, "workflow-", WorkflowSchema);
+
+  if (skillSynths.length + mcpServers.length + agents.length + workflows.length === 0) {
+    throw new UsageError(
+      "no resources found in synthesis output\n\n" +
+        "The entry point ran but registered no resources. Register at least one " +
+        "agent, workflow, MCP server, or skill, and end with `await project.synth()`.",
+    );
+  }
+
+  return { skillSynths, mcpServers, agents, workflows };
+}
+
+// Glob `<prefix>*.pb` in `dir`, sort lexically (parity with Go's sort.Strings),
+// and decode each. A missing directory yields an empty list (the caller's
+// zero-resource check produces the user-facing error).
+function readProtoFiles<Desc extends DescMessage>(dir: string, prefix: string, schema: Desc): MessageShape<Desc>[] {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const matches = names.filter((name) => name.startsWith(prefix) && name.endsWith(".pb")).sort();
+  return matches.map((name) => fromBinary(schema, readFileSync(join(dir, name))));
+}

package/src/resources/apply/synth/runtime.test.ts

@@ -0,0 +1,29 @@
+// Runtime inference: every supported extension maps to its runtime; unknown
+// extensions raise actionable guidance listing the supported set.
+
+import { describe, expect, it } from "vitest";
+import { inferRuntime } from "./runtime.js";
+
+describe("inferRuntime", () => {
+  it("maps Go, Python, and Node extensions", () => {
+    expect(inferRuntime("main.go")).toBe("go");
+    expect(inferRuntime("pipelines/main.py")).toBe("python");
+    expect(inferRuntime("src/index.ts")).toBe("node");
+    expect(inferRuntime("index.js")).toBe("node");
+    expect(inferRuntime("index.mts")).toBe("node");
+    expect(inferRuntime("index.mjs")).toBe("node");
+  });
+
+  it("is case-insensitive on the extension", () => {
+    expect(inferRuntime("Main.GO")).toBe("go");
+  });
+
+  it("throws with the supported extensions when the extension is unknown", () => {
+    expect(() => inferRuntime("main.rb")).toThrow(/cannot infer runtime/);
+    expect(() => inferRuntime("main.rb")).toThrow(/\.go, \.py, \.ts, \.js, \.mts, \.mjs/);
+  });
+
+  it("throws when there is no extension", () => {
+    expect(() => inferRuntime("Makefile")).toThrow(/cannot infer runtime/);
+  });
+});