@stigmer/sdk 3.0.8-dev.20260613074252 → 3.0.8

package/synth/index.d.ts

@@ -0,0 +1,35 @@
+import { type SynthCounts } from "./writer";
+import type { ProjectContext } from "./context";
+export type { ProjectContext, Registration, SkillFromDirOptions, SkillFromGitInput, SkillHandle, } from "./context";
+export type { SynthCounts, SynthFile } from "./writer";
+export { serializeRegistrations } from "./writer";
+/** Options for {@link ProjectApp.synth}. */
+export interface SynthOptions {
+    /** Output directory; defaults to `process.env.STIGMER_OUT_DIR`. */
+    readonly outDir?: string;
+    /** Default org for resources that omit one; defaults to `STIGMER_ORG_ID`. */
+    readonly org?: string;
+}
+/** Outcome of a synthesis run. */
+export interface SynthResult {
+    /** Directory the `.pb` files were written to. */
+    readonly outDir: string;
+    /** Names of the written `.pb` files, in registration order. */
+    readonly files: readonly string[];
+    /** Per-kind resource counts. */
+    readonly counts: SynthCounts;
+}
+/** A builder that registers resources on the given context (sync or async). */
+export type ProjectBuilder = (ctx: ProjectContext) => void | Promise<void>;
+/** A synthesizable project produced by {@link defineProject}. */
+export interface ProjectApp {
+    /** Run the builder and write the `.pb` artifacts; resolves to a summary. */
+    synth(opts?: SynthOptions): Promise<SynthResult>;
+}
+/**
+ * Define a synthesizable project. The `build` callback is NOT run here — it runs
+ * lazily inside {@link ProjectApp.synth}, so importing the module has no side
+ * effects and the same app can be synthesized to different out dirs in tests.
+ */
+export declare function defineProject(build: ProjectBuilder): ProjectApp;
+//# sourceMappingURL=index.d.ts.map

package/synth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/synth/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAsB,KAAK,WAAW,EAAsB,MAAM,UAAU,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,kCAAkC;AAClC,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3E,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,KAAK,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,UAAU,CAmB/D"}

package/synth/index.js

@@ -0,0 +1,44 @@
+// `@stigmer/sdk/synth` — the project-synthesis authoring API (the "producer").
+//
+// A user's entry point describes resources functionally and synthesizes them to
+// proto `.pb` files that `stigmer apply` consumes:
+//
+//   import { defineProject } from "@stigmer/sdk/synth";
+//
+//   const project = defineProject((ctx) => {
+//     ctx.skill.fromDir("./skills/calculator");
+//     ctx.agent({ name: "support-bot", org: "acme", instructions: "…" });
+//   });
+//
+//   await project.synth();
+//
+// `synth()` is EXPLICIT (no import-time / beforeExit magic): the builder runs
+// lazily inside it, honoring `@stigmer/sdk`'s `sideEffects: false` and staying
+// trivially testable via `synth({ outDir })` (DD-009 §1). Node-only — it writes
+// files — and exported from the dedicated `/synth` subpath (DD-009 §2).
+import { RegistrationContext } from "./context";
+import { countRegistrations, writeRegistrations } from "./writer";
+export { serializeRegistrations } from "./writer";
+/**
+ * Define a synthesizable project. The `build` callback is NOT run here — it runs
+ * lazily inside {@link ProjectApp.synth}, so importing the module has no side
+ * effects and the same app can be synthesized to different out dirs in tests.
+ */
+export function defineProject(build) {
+    return {
+        async synth(opts) {
+            const outDir = opts?.outDir ?? process.env.STIGMER_OUT_DIR;
+            if (outDir === undefined || outDir === "") {
+                throw new Error("no synthesis output directory\n\n" +
+                    "Run this project via `stigmer apply` (which sets STIGMER_OUT_DIR), " +
+                    "or call project.synth({ outDir }) with an explicit directory.");
+            }
+            const ctx = new RegistrationContext(opts?.org ?? process.env.STIGMER_ORG_ID ?? "");
+            await build(ctx);
+            const registrations = ctx.collect();
+            const files = writeRegistrations(outDir, registrations);
+            return { outDir, files, counts: countRegistrations(registrations) };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/synth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/synth/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,mDAAmD;AACnD,EAAE;AACF,wDAAwD;AACxD,EAAE;AACF,6CAA6C;AAC7C,gDAAgD;AAChD,0EAA0E;AAC1E,QAAQ;AACR,EAAE;AACF,2BAA2B;AAC3B,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,wEAAwE;AAExE,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAoB,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAWpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA6BlD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,IAAmB;YAC7B,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;YAC3D,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;gBAC1C,MAAM,IAAI,KAAK,CACb,mCAAmC;oBACjC,qEAAqE;oBACrE,+DAA+D,CAClE,CAAC;YACJ,CAAC;YAED,MAAM,GAAG,GAAG,IAAI,mBAAmB,CAAC,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;YACnF,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;YACjB,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;YACxD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,CAAC,aAAa,CAAC,EAAE,CAAC;QACtE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/synth/writer.d.ts

@@ -0,0 +1,28 @@
+import type { Registration } from "./context";
+/** One serialized synthesis artifact: its file name and binary proto bytes. */
+export interface SynthFile {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}
+/** Per-kind counts of synthesized resources. */
+export interface SynthCounts {
+    readonly agents: number;
+    readonly workflows: number;
+    readonly mcpServers: number;
+    readonly skills: number;
+}
+/**
+ * Serialize registrations into named `.pb` artifacts, in registration order,
+ * with a per-kind zero-based index. Pure (no filesystem) so it is trivially
+ * unit-testable and reusable by callers that want the bytes without writing.
+ */
+export declare function serializeRegistrations(registrations: readonly Registration[]): SynthFile[];
+/** Tally registrations by kind (for the synth result summary). */
+export declare function countRegistrations(registrations: readonly Registration[]): SynthCounts;
+/**
+ * Serialize and write all registrations into `outDir`, returning the written
+ * file names. The directory is created if absent (idempotent) — synthesis owns
+ * its output target, like CDK's `app.synth()` creating `cdk.out`.
+ */
+export declare function writeRegistrations(outDir: string, registrations: readonly Registration[]): string[];
+//# sourceMappingURL=writer.d.ts.map

package/synth/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/synth/writer.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,EAAE,CA0B1F;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,CAYtF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,EAAE,CAOnG"}

package/synth/writer.js

@@ -0,0 +1,86 @@
+// Writer — turns ordered {@link Registration}s into the proto `.pb` files the
+// CLI's synthesis reader consumes.
+//
+// Each kind gets its own zero-based counter, producing `agent-N.pb`,
+// `workflow-N.pb`, `mcpserver-N.pb`, and `skill-N.pb`. These names and the
+// binary encoding are the SDK↔CLI handoff contract: they must match the reader's
+// glob/sort (`<kind>-*.pb`, lexically sorted) on both the Go and TS consumers
+// (reader.go / reader.ts). Resources are serialized via protobuf-es `toBinary`
+// (DD-009 §3); the full proto is built by reusing the generated, package-private
+// `build<Kind>Proto` helpers (DD-009 §4) so synthesis and the imperative SDK
+// share one field mapping. Skills are already `SkillSynth` messages and are
+// encoded directly.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { 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 { SkillSynthSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/synth_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { buildAgentProto } from "../gen/agent";
+import { buildMcpServerProto } from "../gen/mcpserver";
+import { buildWorkflowProto } from "../gen/workflow";
+/**
+ * Serialize registrations into named `.pb` artifacts, in registration order,
+ * with a per-kind zero-based index. Pure (no filesystem) so it is trivially
+ * unit-testable and reusable by callers that want the bytes without writing.
+ */
+export function serializeRegistrations(registrations) {
+    const next = { agent: 0, workflow: 0, mcpServer: 0, skill: 0 };
+    const files = [];
+    for (const reg of registrations) {
+        switch (reg.kind) {
+            case "agent":
+                files.push({ name: `agent-${next.agent++}.pb`, bytes: toBinary(AgentSchema, buildAgentProto(reg.input)) });
+                break;
+            case "workflow":
+                files.push({
+                    name: `workflow-${next.workflow++}.pb`,
+                    bytes: toBinary(WorkflowSchema, buildWorkflowProto(reg.input)),
+                });
+                break;
+            case "mcpServer":
+                files.push({
+                    name: `mcpserver-${next.mcpServer++}.pb`,
+                    bytes: toBinary(McpServerSchema, buildMcpServerProto(reg.input)),
+                });
+                break;
+            case "skill":
+                files.push({ name: `skill-${next.skill++}.pb`, bytes: toBinary(SkillSynthSchema, reg.synth) });
+                break;
+        }
+    }
+    return files;
+}
+/** Tally registrations by kind (for the synth result summary). */
+export function countRegistrations(registrations) {
+    let agents = 0;
+    let workflows = 0;
+    let mcpServers = 0;
+    let skills = 0;
+    for (const reg of registrations) {
+        if (reg.kind === "agent")
+            agents++;
+        else if (reg.kind === "workflow")
+            workflows++;
+        else if (reg.kind === "mcpServer")
+            mcpServers++;
+        else
+            skills++;
+    }
+    return { agents, workflows, mcpServers, skills };
+}
+/**
+ * Serialize and write all registrations into `outDir`, returning the written
+ * file names. The directory is created if absent (idempotent) — synthesis owns
+ * its output target, like CDK's `app.synth()` creating `cdk.out`.
+ */
+export function writeRegistrations(outDir, registrations) {
+    const files = serializeRegistrations(registrations);
+    mkdirSync(outDir, { recursive: true });
+    for (const file of files) {
+        writeFileSync(join(outDir, file.name), file.bytes);
+    }
+    return files.map((file) => file.name);
+}
+//# sourceMappingURL=writer.js.map

package/synth/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/synth/writer.ts"],"names":[],"mappings":"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"}

package/synth.d.ts

@@ -0,0 +1,2 @@
+export * from "./synth/index.js";
+//# sourceMappingURL=synth.d.ts.map

package/synth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synth.d.ts","sourceRoot":"","sources":["../src/synth.ts"],"names":[],"mappings":"AAOA,cAAc,kBAAkB,CAAC"}

package/synth.js

@@ -0,0 +1,8 @@
+// Node-only entry point for the project-synthesis authoring API.
+//
+// Re-exports `@stigmer/sdk/synth` (see ./synth/index.ts). Kept as a thin
+// top-level module so the package `exports` map can expose `"./synth"` the same
+// way `"./node"` maps to ./node.ts — a capability subpath, not a client noun
+// (DD-009 §2).
+export * from "./synth/index.js";
+//# sourceMappingURL=synth.js.map

package/synth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synth.js","sourceRoot":"","sources":["../src/synth.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,yEAAyE;AACzE,gFAAgF;AAChF,6EAA6E;AAC7E,eAAe;AAEf,cAAc,kBAAkB,CAAC"}