create-syrinx-agent 4.4.0

package/src/templates/package-json.ts

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: MIT
+//
+// Builds the generated project's package.json — dependencies limited to
+// exactly the chosen providers (LDT-21 requirement), plus the fixed
+// infrastructure every combination needs: core, the CLI (for `syrinx turn`/
+// `syrinx text` in the check:* scripts), and tsx (the --agent seam needs it
+// for a .ts module — see AGENTS.md).
+
+import type { ResolvedOptions } from "../options.js";
+import { STT_STAGE_PROVIDERS } from "../providers/stt.js";
+import { TTS_STAGE_PROVIDERS } from "../providers/tts.js";
+import { REASONER_PROVIDERS } from "../providers/reasoner.js";
+import { REALTIME_PROVIDERS } from "../providers/realtime.js";
+import { VAD_SIDECAR_PROVIDERS, ENDPOINTING_SIDECAR_PROVIDERS } from "../providers/vad-endpointing.js";
+
+const CORE_VERSION = "^4.3.0";
+
+// @kuralle-syrinx/server-websocket (and any ws-based STT/TTS/realtime provider,
+// transitively through @kuralle-syrinx/ws) ships raw TS as "main" and declares
+// `ws` as a runtime dep but `@types/ws` only as a devDependency — devDeps of a
+// dependency are never installed for the consumer, so a project that typechecks
+// server-websocket's source needs its own `@types/ws` (mirrors
+// examples/02-hello-voice-headless/package.json, which declares both directly).
+function transportPackage(): Readonly<Record<string, string>> {
+  return { "@kuralle-syrinx/server-websocket": CORE_VERSION, ws: "^8.21.0" };
+}
+
+export function collectDependencies(opts: ResolvedOptions): Record<string, string> {
+  const deps: Record<string, string> = {
+    "@kuralle-syrinx/core": CORE_VERSION,
+    ...transportPackage(),
+  };
+
+  if (opts.mode === "cascade") {
+    const stt = STT_STAGE_PROVIDERS[opts.stt];
+    const tts = TTS_STAGE_PROVIDERS[opts.tts];
+    const reasoner = REASONER_PROVIDERS[opts.reasoner];
+    if (stt) deps[stt.packageName] = stt.packageVersion;
+    if (tts) deps[tts.packageName] = tts.packageVersion;
+    // ReasoningBridge (the VoicePlugin wrapper any Reasoner needs in cascade mode) lives here.
+    deps["@kuralle-syrinx/aisdk"] = CORE_VERSION;
+    if (reasoner) {
+      deps[reasoner.packageName] = reasoner.packageVersion;
+      Object.assign(deps, reasoner.extraPackages);
+    }
+    const vad = opts.vad !== undefined ? VAD_SIDECAR_PROVIDERS[opts.vad] : undefined;
+    if (vad) deps[vad.packageName] = vad.packageVersion;
+    const eos = opts.endpointing !== undefined ? ENDPOINTING_SIDECAR_PROVIDERS[opts.endpointing] : undefined;
+    if (eos) deps[eos.packageName] = eos.packageVersion;
+  } else {
+    const realtime = REALTIME_PROVIDERS[opts.realtime];
+    // RealtimeBridge (the generic VoicePlugin wrapper around any RealtimeAdapter) lives here.
+    deps["@kuralle-syrinx/realtime"] = CORE_VERSION;
+    deps["@kuralle-syrinx/ws"] = CORE_VERSION;
+    if (realtime) deps[realtime.packageName] = realtime.packageVersion;
+  }
+
+  return deps;
+}
+
+export function buildPackageJson(opts: ResolvedOptions): string {
+  const dependencies = collectDependencies(opts);
+  const agentSpec = "./src/agent.ts#createAgent";
+
+  const scripts: Record<string, string> = {
+    dev: `tsx scripts/dev-server.ts --agent ${agentSpec}`,
+    "check:typecheck": "tsc --noEmit",
+    "check:turn": `syrinx turn --in test/fixtures/smoke.wav --agent ${agentSpec} --json`,
+  };
+  const devDependencies: Record<string, string> = {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    tsx: "^4.20.0",
+    typescript: "^5.7.0",
+  };
+
+  // --runtime cloudflare additionally ships src/index.ts (the deploy artifact, a
+  // withVoice(Agent) Durable Object) + wrangler.jsonc alongside the SAME src/agent.ts
+  // + scripts/dev-server.ts used for local iteration and check:turn — the deploy
+  // artifact's own typecheck is covered by check:typecheck (tsconfig includes all of
+  // src/), but it is not live-verified (see AGENTS.md / the --transport telnyx warning).
+  if (opts.runtime === "cloudflare") {
+    dependencies["@kuralle-syrinx/cf-agents"] = CORE_VERSION;
+    dependencies["agents"] = "0.14.0";
+    // `agents` peer-depends on ai@^6.0.0, but its own optional @cloudflare/ai-chat
+    // dependency pulls a newer `ai` major transitively — without a direct pin here
+    // npm's resolver lands on the newer major and ERESOLVEs against agents' peer.
+    // examples/03-cf-agent-voice/package.json pins the same "ai": "^6.0.0" for the
+    // same reason, in both its cascaded AND realtime example classes.
+    dependencies["ai"] = "^6.0.0";
+    // Pinned exact, not a caret range: `wrangler`'s peer on @cloudflare/workers-types
+    // moved to v5 in newer releases while `agents`/`partyserver` still peer on v4,
+    // so a loose `^4.19.0` resolves npm to the newest 4.x wrangler and hits an
+    // ERESOLVE conflict. This exact pair is the one this monorepo's own
+    // pnpm-lock.yaml already resolves.
+    devDependencies["@cloudflare/workers-types"] = "^4.20260601.1";
+    devDependencies["wrangler"] = "4.97.0";
+    scripts["check:wrangler-dry-run"] = "wrangler deploy --dry-run";
+  }
+
+  const pkg = {
+    name: opts.name,
+    version: "0.0.1",
+    private: true,
+    type: "module",
+    license: "MIT",
+    scripts,
+    dependencies: sortKeys({ ...dependencies, "@kuralle-syrinx/cli": CORE_VERSION }),
+    devDependencies: sortKeys(devDependencies),
+  };
+
+  return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+
+function sortKeys(obj: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of Object.keys(obj).sort()) out[key] = obj[key] as string;
+  return out;
+}

package/src/templates/tsconfig.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+//
+// Generated project's tsconfig.json — mirrors examples/02-hello-voice-headless/tsconfig.json.
+// --runtime cloudflare additionally needs @cloudflare/workers-types: src/index.ts's
+// `Request`/`Response`/`fetch` globals come from there, not from a DOM lib (this
+// tsconfig has no "DOM" in `lib`, matching the node-runtime file it sits beside).
+
+import type { Runtime } from "../options.js";
+
+export function buildTsconfig(runtime: Runtime): string {
+  const types = runtime === "cloudflare" ? ["node", "@cloudflare/workers-types"] : ["node"];
+  const tsconfig = {
+    compilerOptions: {
+      target: "ES2022",
+      module: "NodeNext",
+      moduleResolution: "NodeNext",
+      strict: true,
+      skipLibCheck: true,
+      noEmit: true,
+      types,
+    },
+    include: ["src/**/*.ts", "scripts/**/*.ts"],
+  };
+  return `${JSON.stringify(tsconfig, null, 2)}\n`;
+}

package/src/version.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+
+// Kept in sync with package.json "version" by hand (mirrors packages/cli's
+// version.ts convention) — no build-time codegen step for one constant.
+export const GENERATOR_VERSION = "0.1.0";

package/src/write-project.test.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MIT
+
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { resolveOptions } from "./options.js";
+import { CliError } from "./exit-codes.js";
+import { buildFileMap, writeProject } from "./write-project.js";
+
+describe("buildFileMap — the cascade slice (deepgram/aisdk/cartesia/browser)", () => {
+  const opts = resolveOptions({ stt: "deepgram", reasoner: "aisdk", tts: "cartesia", transport: "browser" }, ["x"]);
+  const files = buildFileMap(opts);
+
+  it("emits exactly the node-runtime file set — no Cloudflare artifacts", () => {
+    expect(files.map((f) => f.relPath).sort()).toEqual([
+      ".env.example",
+      "AGENTS.md",
+      "package.json",
+      "scripts/dev-server.ts",
+      "src/agent.ts",
+      "test/fixtures/smoke.wav",
+      "tsconfig.json",
+    ]);
+  });
+
+  it("package.json depends on exactly the chosen providers, not the whole matrix", () => {
+    const pkgFile = files.find((f) => f.relPath === "package.json");
+    const pkg = JSON.parse(pkgFile?.content as string) as { dependencies: Record<string, string> };
+    expect(Object.keys(pkg.dependencies).sort()).toEqual(
+      [
+        "@ai-sdk/openai",
+        "@kuralle-syrinx/aisdk",
+        "@kuralle-syrinx/cartesia",
+        "@kuralle-syrinx/cli",
+        "@kuralle-syrinx/core",
+        "@kuralle-syrinx/deepgram",
+        "@kuralle-syrinx/server-websocket",
+        "ai",
+        "ws",
+      ].sort(),
+    );
+    // Not present: any provider from a stage that wasn't chosen.
+    expect(pkg.dependencies).not.toHaveProperty("@kuralle-syrinx/elevenlabs");
+    expect(pkg.dependencies).not.toHaveProperty("@kuralle-syrinx/mastra");
+  });
+
+  it(".env.example names exactly the required keys for this combination", () => {
+    const envFile = files.find((f) => f.relPath === ".env.example");
+    const content = envFile?.content as string;
+    expect(content).toContain("DEEPGRAM_API_KEY=");
+    expect(content).toContain("CARTESIA_API_KEY=");
+    expect(content).toContain("CARTESIA_VOICE_ID=");
+    expect(content).toContain("OPENAI_API_KEY=");
+    expect(content).not.toContain("ELEVENLABS_API_KEY");
+  });
+
+  it("src/agent.ts wires the chosen stage plugins with provider_stt endpointing", () => {
+    const agentFile = files.find((f) => f.relPath === "src/agent.ts");
+    const content = agentFile?.content as string;
+    expect(content).toContain("DeepgramSTTPlugin");
+    expect(content).toContain("CartesiaTTSPlugin");
+    expect(content).toContain("fromStreamText");
+    expect(content).toContain('endpointingOwner: "provider_stt"');
+  });
+
+  it("AGENTS.md states plainly what this generator's checks cannot verify", () => {
+    const agentsMd = files.find((f) => f.relPath === "AGENTS.md");
+    const content = agentsMd?.content as string;
+    expect(content).toMatch(/CANNOT verify/);
+    expect(content).toMatch(/barge-in/);
+    expect(content).toMatch(/tsx/);
+  });
+});
+
+describe("buildFileMap — --endpointing sets smart_turn ownership", () => {
+  it("switches endpointingOwner and registers the eos plugin", () => {
+    const opts = resolveOptions(
+      { stt: "deepgram", reasoner: "aisdk", tts: "cartesia", transport: "browser", endpointing: "pipecat-smart-turn" },
+      ["x"],
+    );
+    const files = buildFileMap(opts);
+    const content = files.find((f) => f.relPath === "src/agent.ts")?.content as string;
+    expect(content).toContain('endpointingOwner: "smart_turn"');
+    expect(content).toContain("PipecatEOSPlugin");
+  });
+});
+
+describe("buildFileMap — realtime (speech-to-speech) mode", () => {
+  it("emits RealtimeBridge wiring, not STT/TTS stages", () => {
+    const opts = resolveOptions({ realtime: "grok" }, ["x"]);
+    const files = buildFileMap(opts);
+    const content = files.find((f) => f.relPath === "src/agent.ts")?.content as string;
+    expect(content).toContain("RealtimeBridge");
+    expect(content).toContain("fromGrokRealtime");
+    expect(content).toContain('endpointingOwner: "timer"');
+  });
+});
+
+describe("buildFileMap — --runtime cloudflare", () => {
+  it("additionally emits src/index.ts and wrangler.jsonc", () => {
+    const opts = resolveOptions(
+      { stt: "deepgram", reasoner: "aisdk", tts: "cartesia", transport: "browser", runtime: "cloudflare" },
+      ["x"],
+    );
+    const files = buildFileMap(opts);
+    const relPaths = files.map((f) => f.relPath);
+    expect(relPaths).toContain("src/index.ts");
+    expect(relPaths).toContain("wrangler.jsonc");
+    const worker = files.find((f) => f.relPath === "src/index.ts")?.content as string;
+    expect(worker).toContain("withVoice");
+    expect(worker).toContain('transport: "edge"');
+  });
+
+  it("refuses --runtime cloudflare --transport smartpbx (no such binding in cf-agents)", () => {
+    const opts = resolveOptions(
+      { stt: "deepgram", reasoner: "aisdk", tts: "cartesia", transport: "smartpbx", runtime: "cloudflare" },
+      ["x"],
+    );
+    expect(() => buildFileMap(opts)).toThrow(CliError);
+    expect(() => buildFileMap(opts)).toThrow(/no smartpbx transport binding/);
+  });
+});
+
+describe("buildFileMap — not-yet-implemented providers refuse cleanly", () => {
+  it("--reasoner kuralle", () => {
+    const opts = resolveOptions({ stt: "deepgram", reasoner: "kuralle", tts: "cartesia", transport: "browser" }, ["x"]);
+    expect(() => buildFileMap(opts)).toThrow(/--reasoner kuralle is not yet implemented/);
+  });
+
+  it("--endpointing vap", () => {
+    const opts = resolveOptions(
+      { stt: "deepgram", reasoner: "aisdk", tts: "cartesia", transport: "browser", endpointing: "vap" },
+      ["x"],
+    );
+    expect(() => buildFileMap(opts)).toThrow(/--endpointing vap is not yet implemented/);
+  });
+});
+
+describe("writeProject", () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "create-syrinx-agent-write-"));
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, maxRetries: 3, force: true }).catch(() => {});
+  });
+
+  it("writes every file, including a binary fixture, to the target directory", async () => {
+    const opts = resolveOptions({ stt: "deepgram", reasoner: "aisdk", tts: "cartesia", transport: "browser" }, ["x"]);
+    const files = buildFileMap(opts);
+    const targetDir = join(root, "generated");
+
+    await writeProject(targetDir, files);
+
+    const pkgRaw = await readFile(join(targetDir, "package.json"), "utf8");
+    expect(JSON.parse(pkgRaw)).toHaveProperty("name");
+    const wav = await readFile(join(targetDir, "test/fixtures/smoke.wav"));
+    expect(wav.subarray(0, 4).toString("ascii")).toBe("RIFF");
+  });
+});

package/src/write-project.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+//
+// Orchestrates file emission: builds the file map from a resolved combination,
+// then either lists it (--dry-run) or writes it and (unless skipped) installs.
+
+import { spawnSync } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { ResolvedOptions } from "./options.js";
+import { buildAgentModule } from "./templates/agent-module.js";
+import { buildDevServer } from "./templates/dev-server.js";
+import { buildPackageJson } from "./templates/package-json.js";
+import { buildEnvExample } from "./templates/env-example.js";
+import { buildAgentsMd } from "./templates/agents-md.js";
+import { buildTsconfig } from "./templates/tsconfig.js";
+import { buildSmokeWav } from "./templates/fixture.js";
+import { buildCloudflareWorkerSource, buildWranglerJsonc } from "./templates/cloudflare-worker.js";
+
+export interface ProjectFile {
+  readonly relPath: string;
+  readonly content: string | Buffer;
+}
+
+export function buildFileMap(opts: ResolvedOptions): readonly ProjectFile[] {
+  const files: ProjectFile[] = [
+    { relPath: "package.json", content: buildPackageJson(opts) },
+    { relPath: "tsconfig.json", content: buildTsconfig(opts.runtime) },
+    { relPath: ".env.example", content: buildEnvExample(opts) },
+    { relPath: "AGENTS.md", content: buildAgentsMd(opts) },
+    { relPath: "src/agent.ts", content: buildAgentModule(opts) },
+    { relPath: "scripts/dev-server.ts", content: buildDevServer(opts.transport) },
+    { relPath: "test/fixtures/smoke.wav", content: buildSmokeWav() },
+  ];
+
+  if (opts.runtime === "cloudflare") {
+    files.push(
+      { relPath: "src/index.ts", content: buildCloudflareWorkerSource(opts) },
+      { relPath: "wrangler.jsonc", content: buildWranglerJsonc(opts) },
+    );
+  }
+
+  return files;
+}
+
+export async function writeProject(targetDir: string, files: readonly ProjectFile[]): Promise<void> {
+  for (const file of files) {
+    const abs = join(targetDir, file.relPath);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, file.content);
+  }
+}
+
+/** Runs `npm install` in targetDir. Errors surface to the caller (never swallowed). */
+export function runNpmInstall(targetDir: string): void {
+  const result = spawnSync("npm", ["install"], { cwd: targetDir, stdio: "inherit" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm install exited with code ${String(result.status)}`);
+}