create-spatius-app 0.1.2 → 0.1.3-beta.1

package/dist/templates.js

@@ -79,6 +79,96 @@ var init_errors = __esm({
   }
 });
 
+// src/catalog.ts
+function validateSelection(stack) {
+  if (!Object.hasOwn(stacks, stack)) {
+    throw new CliError("INVALID_ARGUMENT", `Unsupported stack: ${stack}`, {
+      exitCode: EXIT_CODES.invalidArgument
+    });
+  }
+  return { stack };
+}
+var stacks;
+var init_catalog = __esm({
+  "src/catalog.ts"() {
+    "use strict";
+    init_errors();
+    stacks = {
+      "cloudflare-livekit": {
+        label: "Cloudflare + LiveKit Cloud Agents",
+        web: "cloudflare",
+        agent: "livekit",
+        provider: "livekit"
+      },
+      "cloudflare-livekit-railway": {
+        label: "Cloudflare + LiveKit Agents on Railway",
+        web: "cloudflare",
+        agent: "railway",
+        provider: "livekit"
+      },
+      "railway-livekit-cloud": {
+        label: "Railway + LiveKit Cloud Agents",
+        web: "railway",
+        agent: "livekit",
+        provider: "livekit"
+      },
+      "railway-livekit": {
+        label: "Railway + LiveKit Agents on Railway",
+        web: "railway",
+        agent: "railway",
+        provider: "livekit"
+      },
+      "zeabur-agora": {
+        label: "Zeabur + Agora Conversational AI",
+        web: "zeabur",
+        agent: "agora",
+        provider: "agora"
+      }
+    };
+  }
+});
+
+// src/project-config.ts
+import { lstat, readFile } from "fs/promises";
+import { join } from "path";
+async function readProjectConfig(directory) {
+  const path = join(directory, "spatius.config.json");
+  try {
+    const stats = await lstat(path);
+    if (!stats.isFile() || stats.isSymbolicLink())
+      throw new Error("Expected a regular file");
+    const value = JSON.parse(await readFile(path, "utf8"));
+    if (value && typeof value === "object" && "version" in value && value.version !== 2)
+      throw new CliError(
+        "INVALID_ARGUMENT",
+        "Unsupported spatius.config.json version. Expected version 2.",
+        { path, exitCode: EXIT_CODES.invalidArgument }
+      );
+    if (!value || typeof value !== "object" || !("version" in value) || value.version !== 2 || !("stack" in value) || typeof value.stack !== "string")
+      throw new Error("Unsupported project configuration");
+    return { version: 2, ...validateSelection(value.stack) };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return void 0;
+    throw new CliError("INVALID_ARGUMENT", "Invalid spatius.config.json.", {
+      path,
+      exitCode: EXIT_CODES.invalidArgument
+    });
+  }
+}
+async function webEnvironmentPath(directory) {
+  const config = await readProjectConfig(directory);
+  return config && !config.stack.startsWith("cloudflare") ? ".env.local" : ".dev.vars";
+}
+var init_project_config = __esm({
+  "src/project-config.ts"() {
+    "use strict";
+    init_catalog();
+    init_errors();
+  }
+});
+
 // src/package-managers.ts
 import { execFile, spawn } from "child_process";
 function requiresWindowsCommandShell(command, platform = process.platform) {
@@ -201,23 +291,32 @@ var init_package_managers = __esm({
 });
 
 // src/setup/project.ts
-import { lstat } from "fs/promises";
-import { join } from "path";
+import { lstat as lstat2 } from "fs/promises";
+import { join as join3 } from "path";
 async function assertSpatiusProject(targetDirectory) {
   try {
-    const target = await lstat(targetDirectory);
+    const target = await lstat2(targetDirectory);
     if (!target.isDirectory() || target.isSymbolicLink()) {
       throw new Error("not a regular directory");
     }
+    const config = await readProjectConfig(targetDirectory);
+    const paths = config ? [
+      "package.json",
+      "spatius.config.json",
+      await webEnvironmentPath(targetDirectory) + ".example",
+      "worker/index.ts",
+      "agent/src/agent.py",
+      "agent/.env.example"
+    ] : requiredProjectPaths;
     await Promise.all([
       ...requiredProjectDirectories.map(async (relativePath) => {
-        const stats = await lstat(join(targetDirectory, relativePath));
+        const stats = await lstat2(join3(targetDirectory, relativePath));
         if (!stats.isDirectory() || stats.isSymbolicLink()) {
           throw new Error(`${relativePath} is not a regular directory`);
         }
       }),
-      ...requiredProjectPaths.map(async (relativePath) => {
-        const stats = await lstat(join(targetDirectory, relativePath));
+      ...paths.map(async (relativePath) => {
+        const stats = await lstat2(join3(targetDirectory, relativePath));
         if (!stats.isFile() || stats.isSymbolicLink()) {
           throw new Error(`${relativePath} is not a regular file`);
         }
@@ -239,6 +338,7 @@ var requiredProjectPaths, requiredProjectDirectories;
 var init_project = __esm({
   "src/setup/project.ts"() {
     "use strict";
+    init_project_config();
     init_errors();
     requiredProjectPaths = [
       "package.json",
@@ -277,14 +377,14 @@ var init_voices = __esm({
 // src/setup/environment.ts
 import {
   chmod,
-  lstat as lstat2,
-  readFile as readFile2,
+  lstat as lstat3,
+  readFile as readFile3,
   rename,
   rm,
   writeFile as writeFile2
 } from "fs/promises";
 import { randomUUID as randomUUID2 } from "crypto";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 function parseQuotedValue(rawValue) {
   const value = rawValue.trim();
   if (value.startsWith('"')) {
@@ -439,7 +539,7 @@ function isMissingFile(error) {
 }
 async function readOptionalCredentialFile(path) {
   try {
-    const stats = await lstat2(path);
+    const stats = await lstat3(path);
     if (stats.isSymbolicLink() || !stats.isFile()) {
       throw new CliError(
         "FILESYSTEM_ERROR",
@@ -451,7 +551,7 @@ async function readOptionalCredentialFile(path) {
         }
       );
     }
-    return await readFile2(path, "utf8");
+    return await readFile3(path, "utf8");
   } catch (error) {
     if (isMissingFile(error)) {
       return void 0;
@@ -460,10 +560,11 @@ async function readOptionalCredentialFile(path) {
   }
 }
 async function readCredentialFileState(targetDirectory) {
+  const webPath = await webEnvironmentPath(targetDirectory);
   const [worker, agent, workerExample] = await Promise.all([
-    readOptionalCredentialFile(join3(targetDirectory, ".dev.vars")),
-    readOptionalCredentialFile(join3(targetDirectory, "agent", ".env.local")),
-    readOptionalCredentialFile(join3(targetDirectory, ".dev.vars.example"))
+    readOptionalCredentialFile(join4(targetDirectory, webPath)),
+    readOptionalCredentialFile(join4(targetDirectory, "agent", ".env.local")),
+    readOptionalCredentialFile(join4(targetDirectory, webPath + ".example"))
   ]);
   return {
     agent,
@@ -535,23 +636,24 @@ async function pathExists(path, fileSystem) {
   }
 }
 async function writeCredentialFilesAtomically(targetDirectory, contents, fileSystem = defaultAtomicFileSystem) {
+  const webPath = await webEnvironmentPath(targetDirectory);
   const nonce = randomUUID2();
   const targets = [
     {
       backupMoved: false,
-      backupPath: join3(targetDirectory, `.dev.vars.${nonce}.backup`),
-      destinationPath: join3(targetDirectory, ".dev.vars"),
+      backupPath: join4(targetDirectory, `.dev.vars.${nonce}.backup`),
+      destinationPath: join4(targetDirectory, webPath),
       hadOriginal: false,
       installed: false,
-      stagedPath: join3(targetDirectory, `.dev.vars.${nonce}.tmp`)
+      stagedPath: join4(targetDirectory, `.dev.vars.${nonce}.tmp`)
     },
     {
       backupMoved: false,
-      backupPath: join3(targetDirectory, "agent", `.env.local.${nonce}.backup`),
-      destinationPath: join3(targetDirectory, "agent", ".env.local"),
+      backupPath: join4(targetDirectory, "agent", `.env.local.${nonce}.backup`),
+      destinationPath: join4(targetDirectory, "agent", ".env.local"),
       hadOriginal: false,
       installed: false,
-      stagedPath: join3(targetDirectory, "agent", `.env.local.${nonce}.tmp`)
+      stagedPath: join4(targetDirectory, "agent", `.env.local.${nonce}.tmp`)
     }
   ];
   const payloads = [contents.worker, contents.agent];
@@ -612,9 +714,10 @@ async function writeCredentialFilesAtomically(targetDirectory, contents, fileSys
   }
 }
 async function readCredentialExamples(targetDirectory) {
+  const webPath = await webEnvironmentPath(targetDirectory);
   const [worker, agent] = await Promise.all([
-    readFile2(join3(targetDirectory, ".dev.vars.example"), "utf8"),
-    readFile2(join3(targetDirectory, "agent", ".env.example"), "utf8")
+    readFile3(join4(targetDirectory, webPath + ".example"), "utf8"),
+    readFile3(join4(targetDirectory, "agent", ".env.example"), "utf8")
   ]);
   return { agent, worker };
 }
@@ -622,6 +725,7 @@ var WORKER_MANAGED_KEYS, AGENT_MANAGED_KEYS, assignmentPattern, defaultAtomicFil
 var init_environment = __esm({
   "src/setup/environment.ts"() {
     "use strict";
+    init_project_config();
     init_errors();
     WORKER_MANAGED_KEYS = [
       "LIVEKIT_URL",
@@ -641,8 +745,8 @@ var init_environment = __esm({
     assignmentPattern = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z\d_]*)\s*=\s*(.*)$/u;
     defaultAtomicFileSystem = {
       chmod,
-      lstat: lstat2,
-      readFile: (path) => readFile2(path),
+      lstat: lstat3,
+      readFile: (path) => readFile3(path),
       rename,
       rm: (path) => rm(path, { force: true }),
       writeFile: writeFile2
@@ -7980,12 +8084,12 @@ var require_dist = __commonJS({
 // src/setup/livekit.ts
 import { createHmac } from "crypto";
 import { spawn as spawn2 } from "child_process";
-import { chmod as chmod2, mkdtemp, readFile as readFile3, rm as rm2, writeFile as writeFile3 } from "fs/promises";
+import { chmod as chmod2, mkdtemp, readFile as readFile4, rm as rm2, writeFile as writeFile3 } from "fs/promises";
 import { homedir, tmpdir } from "os";
-import { join as join4 } from "path";
-async function readLiveKitProjects(configPath = join4(homedir(), ".livekit", "cli-config.yaml")) {
+import { join as join5 } from "path";
+async function readLiveKitProjects(configPath = join5(homedir(), ".livekit", "cli-config.yaml")) {
   try {
-    const config = (0, import_yaml.parse)(await readFile3(configPath, "utf8"));
+    const config = (0, import_yaml.parse)(await readFile4(configPath, "utf8"));
     if (config == null) return [];
     if (typeof config !== "object" || !("projects" in config) || !Array.isArray(config.projects))
       throw new Error();
@@ -8148,12 +8252,12 @@ async function loadLiveKitCredentialsWithCli({
   projectName
 } = {}) {
   const directory = await fileSystem.mkdtemp(
-    join4(temporaryRoot, "create-spatius-app-livekit-")
+    join5(temporaryRoot, "create-spatius-app-livekit-")
   );
   try {
     await fileSystem.chmod(directory, 448);
     await fileSystem.writeFile(
-      join4(directory, ".env.example"),
+      join5(directory, ".env.example"),
       "LIVEKIT_URL=\nLIVEKIT_API_KEY=\nLIVEKIT_API_SECRET=\n",
       384
     );
@@ -8172,7 +8276,7 @@ async function loadLiveKitCredentialsWithCli({
       }
     );
     const values = parseDotenv(
-      await fileSystem.readFile(join4(directory, ".env.local"))
+      await fileSystem.readFile(join5(directory, ".env.local"))
     );
     const validated = validateCredentialBundle({
       liveKit: {
@@ -8272,7 +8376,7 @@ var init_livekit = __esm({
     defaultTemporaryFileSystem = {
       chmod: chmod2,
       mkdtemp,
-      readFile: (path) => readFile3(path, "utf8"),
+      readFile: (path) => readFile4(path, "utf8"),
       remove: (path) => rm2(path, {
         force: true,
         maxRetries: 3,
@@ -9723,7 +9827,7 @@ async function runCredentialSetup({
   const examples = await readExamples(targetDirectory);
   const rendered = buildCredentialFileContents(state, examples, credentials);
   await writeFiles(targetDirectory, rendered);
-  onStatus("Saved .dev.vars and agent/.env.local for local development only.");
+  onStatus("Saved local web and agent credentials for local development only.");
   return "configured";
 }
 var init_wizard = __esm({
@@ -9743,18 +9847,18 @@ var init_wizard = __esm({
 });
 
 // src/templates.ts
-init_errors();
-import { fileURLToPath } from "url";
+init_project_config();
+init_catalog();
 
-// src/templates/cloudflare-livekit/index.ts
-init_errors();
+// src/templates/agora.ts
 init_package_managers();
-init_project();
+import { readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
+import { basename as basename3, join as join7 } from "path";
 
 // src/templates/cloudflare-livekit/configure.ts
 init_package_managers();
 import { randomUUID } from "crypto";
-import { readFile, writeFile } from "fs/promises";
+import { access, readFile as readFile2, writeFile } from "fs/promises";
 import { basename, join as join2 } from "path";
 function toValidPackageName(value) {
   const normalized = value.trim().toLowerCase().replace(/\s+/gu, "-").replace(/^[._-]+/u, "").replace(/[^a-z\d~._-]+/gu, "-").replace(/-+/gu, "-").slice(0, 214).replace(/-$/u, "");
@@ -9770,6 +9874,7 @@ function npmRequiresScriptAllowlist(version) {
 function createReplacements(packageManagers, platform) {
   const javascript = packageManagers.javascript;
   const python = packageManagers.python;
+  if (!python) throw new Error("LiveKit templates require Python tooling.");
   return /* @__PURE__ */ new Map([
     [
       "{{SPATIUS_JAVASCRIPT_PACKAGE_MANAGER}}",
@@ -9841,7 +9946,7 @@ function createReplacements(packageManagers, platform) {
   ]);
 }
 async function renderFile(path, replacements) {
-  let contents = await readFile(path, "utf8");
+  let contents = await readFile2(path, "utf8");
   for (const [token, replacement] of replacements) {
     contents = contents.replaceAll(token, replacement);
   }
@@ -9853,7 +9958,7 @@ async function configureGeneratedTemplate(targetDirectory, {
   projectName = basename(targetDirectory)
 }) {
   const packagePath = join2(targetDirectory, "package.json");
-  const packageContents = await readFile(packagePath, "utf8");
+  const packageContents = await readFile2(packagePath, "utf8");
   const metadata = JSON.parse(packageContents);
   const javascript = packageManagers.javascript;
   const run = (script) => javascriptRunCommand(javascript.name, script);
@@ -9892,7 +9997,7 @@ async function configureGeneratedTemplate(targetDirectory, {
   if (javascript.name === "npm") {
     const packageLockPath = join2(targetDirectory, "package-lock.json");
     const packageLock = JSON.parse(
-      await readFile(packageLockPath, "utf8")
+      await readFile2(packageLockPath, "utf8")
     );
     packageLock.name = metadata.name;
     if (packageLock.packages?.[""] !== void 0) {
@@ -9911,12 +10016,18 @@ async function configureGeneratedTemplate(targetDirectory, {
   await Promise.all(
     [
       ".dev.vars.example",
+      ".env.local.example",
       "wrangler.jsonc",
       "agent/src/agent.py",
       "agent/README.md",
       "worker/index.test.ts"
     ].map(
-      async (relativePath) => renderFile(join2(targetDirectory, relativePath), agentReplacements)
+      async (relativePath) => access(join2(targetDirectory, relativePath)).then(
+        () => renderFile(join2(targetDirectory, relativePath), agentReplacements)
+      ).catch((error) => {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+          throw error;
+      })
     )
   );
   await Promise.all(
@@ -9951,6 +10062,7 @@ function createInstallPlan(targetDirectory, packageManagers, platform = process.
       `Installing JavaScript dependencies with ${javascript.name}`
     )
   ];
+  if (!python) return steps;
   if (python.name === "uv") {
     steps.push(
       commandStep(
@@ -9989,6 +10101,9 @@ function createInstallPlan(targetDirectory, packageManagers, platform = process.
 }
 
 // src/templates/cloudflare-livekit/index.ts
+init_errors();
+init_package_managers();
+init_project();
 var credentialSetupStep = {
   command: "npx create-spatius-app setup . --interactive",
   reason: "Connect LiveKit and Spatius accounts and select an avatar and voice in a secure interactive terminal. Never paste secrets into chat.",
@@ -10017,7 +10132,7 @@ var cloudflareLivekitTemplate = {
   ],
   includeFile(path, configuration) {
     const javascript = configuration?.packageManagers.javascript.name ?? "pnpm";
-    const python = configuration?.packageManagers.python.name ?? "uv";
+    const python = configuration?.packageManagers.python?.name ?? "uv";
     if (path === "package-lock.json") return javascript === "npm";
     if (["npmrc", "pnpm-lock.yaml", "pnpm-workspace.yaml"].includes(path)) {
       return javascript === "pnpm";
@@ -10041,6 +10156,8 @@ var cloudflareLivekitTemplate = {
     platform,
     pythonPackageManager
   }) {
+    if (!pythonPackageManager)
+      throw new Error("LiveKit templates require Python tooling.");
     return [
       ...dependenciesInstalled ? [] : [
         javascriptInstallCommand(javascriptPackageManager),
@@ -10073,16 +10190,409 @@ var cloudflareLivekitTemplate = {
   ]
 };
 
+// src/setup/agora.ts
+init_environment();
+init_errors();
+init_project_config();
+import { lstat as lstat4, readFile as readFile5, rename as rename2, rm as rm3, writeFile as writeFile4 } from "fs/promises";
+import { join as join6 } from "path";
+import { randomUUID as randomUUID3 } from "crypto";
+var runAgoraSetup = async ({
+  targetDirectory,
+  prompts,
+  onStatus = () => void 0
+}) => {
+  const target = await lstat4(targetDirectory);
+  if (!target.isDirectory() || target.isSymbolicLink())
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      "Expected a regular project directory.",
+      { exitCode: EXIT_CODES.invalidArgument }
+    );
+  const config = await readProjectConfig(targetDirectory);
+  if (config?.stack !== "zeabur-agora")
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      "Expected a Zeabur + Agora project.",
+      { exitCode: EXIT_CODES.invalidArgument }
+    );
+  for (const name of [
+    "package.json",
+    ".env.local.example",
+    "worker/agora.ts"
+  ]) {
+    const stats = await lstat4(join6(targetDirectory, name));
+    if (!stats.isFile() || stats.isSymbolicLink())
+      throw new CliError(
+        "INVALID_ARGUMENT",
+        "Expected regular project files.",
+        { exitCode: EXIT_CODES.invalidArgument }
+      );
+  }
+  const path = join6(targetDirectory, ".env.local");
+  let existing;
+  try {
+    const stats = await lstat4(path);
+    if (!stats.isFile() || stats.isSymbolicLink())
+      throw new Error("Unsafe credential path");
+    existing = await readFile5(path, "utf8");
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+      throw new CliError("FILESYSTEM_ERROR", "Cannot safely read .env.local.", {
+        exitCode: EXIT_CODES.filesystem,
+        path
+      });
+  }
+  if (existing && !await prompts.confirm(
+    "Replace existing Agora and Spatius credentials? Other variables are preserved.",
+    false
+  ))
+    return "unchanged";
+  const values = {};
+  const previous = parseDotenv(existing ?? "");
+  const secretKeys = ["AGORA_APP_CERTIFICATE", "SPATIUS_API_KEY"];
+  for (const key of [
+    "AGORA_APP_ID",
+    "AGORA_APP_CERTIFICATE",
+    "AGORA_PIPELINE_ID",
+    "SPATIUS_APP_ID",
+    "SPATIUS_API_KEY",
+    "SPATIUS_AVATAR_ID",
+    "SPATIUS_REGION",
+    "AGORA_AVATAR_SAMPLE_RATE"
+  ]) {
+    const defaults = {
+      SPATIUS_REGION: "cn-beijing",
+      AGORA_AVATAR_SAMPLE_RATE: "24000"
+    };
+    while (true) {
+      const value = secretKeys.includes(key) ? await prompts.password(key) : await prompts.input(key, {
+        initialValue: previous.get(key) ?? defaults[key]
+      });
+      if (isPlaceholderValue(value) || new RegExp("\\p{Cc}", "u").test(value)) {
+        onStatus("Enter a non-empty value without control characters.");
+        continue;
+      }
+      if (["AGORA_APP_ID", "AGORA_APP_CERTIFICATE"].includes(key) && !/^[a-f\d]{32}$/iu.test(value)) {
+        onStatus(
+          "Agora App ID and certificate must contain 32 hexadecimal characters."
+        );
+        continue;
+      }
+      if (key === "AGORA_AVATAR_SAMPLE_RATE" && ![8e3, 16e3, 22050, 24e3, 32e3, 44100, 48e3].includes(
+        Number(value)
+      )) {
+        onStatus("Choose a supported audio sample rate.");
+        continue;
+      }
+      values[key] = value;
+      break;
+    }
+  }
+  const rendered = mergeDotenv(
+    existing ?? await readFile5(join6(targetDirectory, ".env.local.example"), "utf8"),
+    values
+  );
+  const temporary = join6(targetDirectory, `.env.local.${randomUUID3()}.tmp`);
+  try {
+    await writeFile4(temporary, rendered, { flag: "wx", mode: 384 });
+    await rename2(temporary, path);
+  } finally {
+    await rm3(temporary, { force: true });
+  }
+  onStatus(
+    "Saved .env.local. Configure an English assistant in the published Agora pipeline, with its TTS sample rate matching AGORA_AVATAR_SAMPLE_RATE. No cloud services were started."
+  );
+  return "configured";
+};
+
+// src/templates/agora.ts
+init_project_config();
+var files = /* @__PURE__ */ new Set([
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "npmrc",
+  "gitignore",
+  "dockerignore",
+  "Dockerfile",
+  ".editorconfig",
+  ".prettierrc.json",
+  ".prettierignore",
+  "README.md",
+  "AGENTS.md",
+  "DEPLOYMENT.md",
+  "spatius.config.json",
+  "index.html",
+  "tsconfig.json",
+  "vite.config.ts",
+  "vitest.config.ts",
+  "eslint.config.mjs",
+  "env.example",
+  "server/index.ts",
+  "worker/index.ts",
+  "worker/agora.ts",
+  "worker/agora.test.ts",
+  "worker/capability.ts",
+  "worker/capability.test.ts",
+  "web/App.tsx",
+  "web/main.tsx",
+  "web/styles.css",
+  "web/agora-session.ts",
+  "web/agora-session.test.ts",
+  "web/components/transcript-view.tsx",
+  "web/components/transcript-panel.tsx",
+  "web/components/icons.tsx",
+  "web/components/agents-ui/agent-chat-input.tsx",
+  "web/components/agents-ui/LICENSE",
+  "web/components/agents-ui/PROVENANCE.md"
+]);
+var agoraTemplate = {
+  id: "zeabur-agora",
+  stack: "zeabur-agora",
+  requiresPython: false,
+  humanSteps: [
+    {
+      command: "npx create-spatius-app setup . --interactive",
+      reason: "Enter Agora and Spatius credentials in a secure interactive terminal and configure a published English Agora pipeline. Never paste secrets into chat.",
+      requiresHuman: true,
+      requiresTty: true
+    }
+  ],
+  directory: "templates/cloudflare-livekit",
+  description: "Zeabur + Agora Conversational AI",
+  components: [
+    "- web/       React + Spatius AvatarKit + Agora",
+    "- server/    Node HTTP API; Agora hosts the conversational agent"
+  ],
+  layers: [
+    { directory: "templates/layers/catalog" },
+    {
+      directory: "templates/layers/node",
+      overrides: ["vite.config.ts", "package-lock.json", "pnpm-lock.yaml"]
+    },
+    {
+      directory: "templates/layers/agora",
+      overrides: [
+        "package.json",
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "web/App.tsx",
+        "worker/index.ts",
+        "tsconfig.json",
+        "vitest.config.ts",
+        "README.md",
+        "AGENTS.md"
+      ]
+    }
+  ],
+  includeFile(path, configuration) {
+    if (!cloudflareLivekitTemplate.includeFile(path, configuration)) return false;
+    return files.has(path) || [...files].some((file) => file.startsWith(path + "/")) || path === "web/assets" || path.startsWith("web/assets/");
+  },
+  mapFile(path) {
+    return path === "env.example" ? ".env.local.example" : cloudflareLivekitTemplate.mapFile(path);
+  },
+  async configure(directory, configuration) {
+    const manager = configuration.packageManagers.javascript;
+    const run = (script) => javascriptRunCommand(manager.name, script);
+    const path = join7(directory, "package.json");
+    const pkg = JSON.parse(await readFile6(path, "utf8"));
+    pkg.name = toValidPackageName(
+      configuration.projectName ?? basename3(directory)
+    );
+    if (manager.version && manager.version !== "unknown")
+      pkg.packageManager = `${manager.name}@${manager.version}`;
+    pkg.scripts.check = ["format:check", "lint", "typecheck", "test", "build"].map(run).join(" && ");
+    if (manager.name === "bun") pkg.trustedDependencies = ["esbuild"];
+    await writeFile5(path, JSON.stringify(pkg, null, 2) + "\n");
+    if (manager.name === "npm") {
+      const lockPath = join7(directory, "package-lock.json");
+      const lock = JSON.parse(await readFile6(lockPath, "utf8"));
+      lock.name = pkg.name;
+      lock.packages[""].name = pkg.name;
+      await writeFile5(lockPath, JSON.stringify(lock, null, 2) + "\n");
+    }
+    await writeFile5(
+      join7(directory, "spatius.config.json"),
+      JSON.stringify({ version: 2, stack: "zeabur-agora" }, null, 2) + "\n"
+    );
+    const serverPath = join7(directory, "server/index.ts");
+    await writeFile5(
+      serverPath,
+      (await readFile6(serverPath, "utf8")).replace(
+        "import { handleRequest }",
+        "import type { AgoraEnvironment } from '../worker/agora.js';\nimport { handleRequest }"
+      ).replace(
+        "const env = process.env;",
+        "const env = process.env as unknown as AgoraEnvironment;"
+      )
+    );
+    const dockerPath = join7(directory, "Dockerfile");
+    const install = manager.name === "pnpm" ? "npm install --global pnpm@12.3.4 && pnpm install --frozen-lockfile" : manager.name === "bun" ? "npm install --global bun && bun install" : "npm ci";
+    await writeFile5(
+      dockerPath,
+      (await readFile6(dockerPath, "utf8")).replace("__SPATIUS_CONTAINER_INSTALL__", install).replace("__SPATIUS_CONTAINER_BUILD__", run("build"))
+    );
+    for (const name of ["README.md", "AGENTS.md"]) {
+      const path2 = join7(directory, name);
+      await writeFile5(
+        path2,
+        (await readFile6(path2, "utf8")).replaceAll("__INSTALL__", javascriptInstallCommand(manager.name)).replaceAll("__DEV__", run("dev")).replaceAll("__CHECK__", run("check"))
+      );
+    }
+    await writeFile5(
+      join7(directory, "DEPLOYMENT.md"),
+      "# Zeabur + Agora Conversational AI\n\nCreate one Zeabur service from this repository with the repository root as build root. Set ZBPACK_DOCKERFILE_PATH=Dockerfile and PORT=8787. Copy the environment variables from .env.local.example into Zeabur service variables, then generate an HTTPS domain. Use /api/health for the health check. Git redeployments rebuild the same service.\n\nThe Node service serves both frontend and API. There is no Python worker or database. Enable Agora Conversational AI and RTM, publish an English assistant pipeline, and set AGORA_PIPELINE_ID. The pipeline owns its models and voice. Match AGORA_AVATAR_SAMPLE_RATE to its TTS output.\n\nSession creation starts a hosted agent. Disconnect and initialization failures stop it through the backend. Page-close cleanup is best effort, with a 60-second idle timeout fallback. Sessions and client tokens last 30 minutes; start a fresh conversation afterward.\n\nLocal setup writes .env.local only. It never provisions Zeabur or uploads secrets.\n"
+    );
+  },
+  createInstallPlan(directory, managers, platform) {
+    return createInstallPlan(
+      directory,
+      { javascript: managers.javascript },
+      platform
+    );
+  },
+  nextSteps({
+    dependenciesInstalled,
+    credentialsConfigured,
+    javascriptPackageManager
+  }) {
+    return [
+      ...dependenciesInstalled ? [] : [javascriptInstallCommand(javascriptPackageManager)],
+      ...credentialsConfigured ? [] : ["npx create-spatius-app setup . --interactive"],
+      javascriptRunCommand(javascriptPackageManager, "dev")
+    ];
+  },
+  setup: {
+    recognizes: async (directory) => (await readProjectConfig(directory))?.stack === "zeabur-agora",
+    run: runAgoraSetup
+  },
+  verification: [
+    { javascript: "npm", scripts: ["check"] },
+    { javascript: "pnpm", scripts: ["check"] }
+  ]
+};
+
+// src/templates/composed.ts
+init_catalog();
+import { readFile as readFile7, writeFile as writeFile6 } from "fs/promises";
+import { join as join8 } from "path";
+init_package_managers();
+function composeTemplate(stack) {
+  if (stack === "zeabur-agora") return agoraTemplate;
+  const selected = stacks[stack];
+  const node = selected.web === "railway";
+  return {
+    ...cloudflareLivekitTemplate,
+    id: stack,
+    stack,
+    requiresPython: true,
+    description: selected.label,
+    components: [
+      "- web/       React + Spatius AvatarKit",
+      `- ${node ? "server/" : "worker/"}    ${selected.web} API`,
+      "- agent/     Python LiveKit agent"
+    ],
+    layers: [
+      { directory: "templates/layers/catalog" },
+      ...selected.agent === "railway" ? [{ directory: "templates/layers/railway-agent" }] : [],
+      ...node ? [
+        {
+          directory: "templates/layers/node",
+          overrides: [
+            "vite.config.ts",
+            "scripts/dev-web.mjs",
+            "package-lock.json",
+            "pnpm-lock.yaml"
+          ]
+        }
+      ] : []
+    ],
+    includeFile(path, configuration) {
+      if (node && ["wrangler.jsonc"].includes(path)) return false;
+      return cloudflareLivekitTemplate.includeFile(path, configuration);
+    },
+    mapFile(path) {
+      return node && path === "dev.vars.example" ? ".env.local.example" : cloudflareLivekitTemplate.mapFile(path);
+    },
+    async configure(directory, configuration) {
+      await cloudflareLivekitTemplate.configure(directory, configuration);
+      await writeFile6(
+        join8(directory, "spatius.config.json"),
+        JSON.stringify({ version: 2, stack }, null, 2) + "\n"
+      );
+      const packagePath = join8(directory, "package.json");
+      const pkg = JSON.parse(await readFile7(packagePath, "utf8"));
+      const manager = configuration.packageManagers.javascript.name;
+      const run = (script) => javascriptRunCommand(manager, script);
+      let deployment = `# ${selected.label}
+
+`;
+      if (node) {
+        for (const name of ["README.md", "AGENTS.md", "agent/README.md"]) {
+          const path = join8(directory, name);
+          await writeFile6(
+            path,
+            (await readFile7(path, "utf8")).replaceAll("Cloudflare Workers", "Railway").replaceAll("Cloudflare Worker", "Node API").replaceAll(".dev.vars", ".env.local") + "\nSee DEPLOYMENT.md for this stack\u2019s deployment steps.\n"
+          );
+        }
+        const workerConfigPath = join8(directory, "tsconfig.worker.json");
+        await writeFile6(
+          workerConfigPath,
+          (await readFile7(workerConfigPath, "utf8")).replace(
+            '"types": ["./worker-configuration.d.ts"]',
+            '"types": ["./worker-configuration.d.ts", "node"]'
+          ).replace(
+            '"include": ["worker", "worker-configuration.d.ts"]',
+            '"include": ["worker", "worker-configuration.d.ts", "server"]'
+          )
+        );
+        delete pkg.devDependencies["@cloudflare/vite-plugin"];
+        delete pkg.devDependencies.wrangler;
+        pkg.dependencies.tsx = "4.23.13";
+        delete pkg.scripts["cf-typegen"];
+        delete pkg.scripts.wrangler;
+        pkg.scripts.start = "node --env-file-if-exists=.env.local node_modules/tsx/dist/cli.mjs server/index.ts";
+        pkg.scripts.deploy = "railway up";
+        const dockerPath = join8(directory, "Dockerfile");
+        const install = manager === "pnpm" ? "npm install --global pnpm@12.3.4 && pnpm install --frozen-lockfile" : manager === "bun" ? "npm install --global bun && bun install" : "npm ci";
+        await writeFile6(
+          dockerPath,
+          (await readFile7(dockerPath, "utf8")).replace("__SPATIUS_CONTAINER_INSTALL__", install).replace("__SPATIUS_CONTAINER_BUILD__", run("build"))
+        );
+        deployment += "Create a Railway service from this repository with the repository root as its build root and railway.json as its configuration. Add the variables from .env.local.example in Railway. Generate a public domain. The web service serves both the frontend and /api. Deploy with `railway up`; subsequent Git deployments rebuild the service.\n\n";
+      } else {
+        deployment += `Run \`${run("wrangler -- login")}\`, set the non-secret configuration from .dev.vars.example in wrangler.jsonc, and upload LIVEKIT_API_KEY and LIVEKIT_API_SECRET using \`${run("wrangler -- secret put LIVEKIT_API_SECRET")}\` (repeat for the key). Run \`${run("deploy")}\`.
+
+`;
+      }
+      if (selected.agent === "railway") {
+        deployment += "Create a separate Railway agent service from this repository, with root directory /agent and configuration /agent/railway.json. Add the variables from agent/.env.example. Keep it running continuously; do not enable sleeping. No public domain is needed. Set PORT=8081 for the agent health check. Deploy this service independently of the web service.\n";
+      } else
+        deployment += "From agent/, run `lk cloud auth` and `lk agent create` for the first deployment. Configure the agent secrets from agent/.env.example. Use `lk agent deploy` for updates.\n";
+      deployment += "\nDeploy the agent before opening conversations. Use separate LiveKit projects for development and production. Local setup never uploads secrets.\n";
+      await writeFile6(join8(directory, "DEPLOYMENT.md"), deployment);
+      await writeFile6(packagePath, JSON.stringify(pkg, null, 2) + "\n");
+    }
+  };
+}
+
+// src/templates.ts
+init_errors();
+import { fileURLToPath } from "url";
+
 // src/scaffold.ts
 init_errors();
 import { constants } from "fs";
-import { copyFile, lstat as lstat4, mkdir, readdir as readdir2, rm as rm3 } from "fs/promises";
-import { basename as basename3, dirname, isAbsolute, join as join5, win32 as win322 } from "path";
+import { copyFile, lstat as lstat6, mkdir, readdir as readdir2, rm as rm4 } from "fs/promises";
+import { basename as basename4, dirname, isAbsolute, join as join9, win32 as win322 } from "path";
 
 // src/project-directory.ts
 init_errors();
 import { homedir as homedir2 } from "os";
-import { lstat as lstat3, readdir } from "fs/promises";
+import { lstat as lstat5, readdir } from "fs/promises";
 import { parse as parse2, resolve } from "path";
 function normalizeTargetDirectory(input, currentWorkingDirectory = process.cwd()) {
   return resolve(currentWorkingDirectory, input);
@@ -10114,7 +10624,7 @@ function assertSafeTargetDirectory(targetDirectory, homeDirectory = homedir2())
 }
 async function inspectTargetDirectory(targetDirectory) {
   try {
-    const stats = await lstat3(targetDirectory);
+    const stats = await lstat5(targetDirectory);
     if (!stats.isDirectory() || stats.isSymbolicLink()) {
       return "not-a-directory";
     }
@@ -10186,10 +10696,10 @@ function assertRelativeDestination(path) {
   }
 }
 async function listTemplateFiles(templateDirectory, template, configuration, relativeDirectory = "") {
-  const entries = await readdir2(join5(templateDirectory, relativeDirectory), {
+  const entries = await readdir2(join9(templateDirectory, relativeDirectory), {
     withFileTypes: true
   });
-  const files = [];
+  const files2 = [];
   for (const entry of entries) {
     if (shouldIgnoreTemplateEntry(entry.name)) continue;
     const source = [relativeDirectory, entry.name].filter(Boolean).join("/");
@@ -10198,7 +10708,7 @@ async function listTemplateFiles(templateDirectory, template, configuration, rel
       throw new Error("Bundled templates must not contain symbolic links.");
     }
     if (entry.isDirectory()) {
-      files.push(
+      files2.push(
         ...await listTemplateFiles(
           templateDirectory,
           template,
@@ -10209,12 +10719,12 @@ async function listTemplateFiles(templateDirectory, template, configuration, rel
     } else if (entry.isFile()) {
       const destination = template.mapFile(source);
       assertRelativeDestination(destination);
-      files.push({ source, destination });
+      files2.push({ source, destination });
     } else {
       throw new Error("Bundled templates must contain regular files.");
     }
   }
-  return files;
+  return files2;
 }
 async function createScaffoldPlan({
   configuration,
@@ -10226,7 +10736,7 @@ async function createScaffoldPlan({
   const targetState = await assertTargetDirectoryAvailable(targetDirectory);
   let entries;
   try {
-    const root = await lstat4(templateDirectory);
+    const root = await lstat6(templateDirectory);
     if (!root.isDirectory() || root.isSymbolicLink()) {
       throw new Error("The template must be a regular directory.");
     }
@@ -10235,6 +10745,33 @@ async function createScaffoldPlan({
       template,
       configuration
     );
+    for (const layer of template.layers ?? []) {
+      const directory = resolveTemplateDirectory({
+        ...template,
+        directory: layer.directory
+      });
+      const root2 = await lstat6(directory);
+      if (!root2.isDirectory() || root2.isSymbolicLink())
+        throw new Error("Invalid template layer.");
+      const additions = await listTemplateFiles(
+        directory,
+        template,
+        configuration
+      );
+      for (const addition of additions) {
+        const index = entries.findIndex(
+          (entry) => entry.destination === addition.destination
+        );
+        if (index >= 0) {
+          if (!layer.overrides?.includes(addition.destination))
+            throw new Error(
+              `Undeclared template override: ${addition.destination}`
+            );
+          entries.splice(index, 1);
+        }
+        entries.push({ ...addition, directory });
+      }
+    }
     const destinations = /* @__PURE__ */ new Set();
     const directories = /* @__PURE__ */ new Map();
     for (const { destination } of entries) {
@@ -10293,11 +10830,11 @@ async function createScaffoldPlan({
 }
 async function rollback(targetDirectory, targetCreated, createdPaths) {
   if (targetCreated) {
-    await rm3(targetDirectory, { force: true, recursive: true });
+    await rm4(targetDirectory, { force: true, recursive: true });
     return;
   }
   for (const path of [...createdPaths].reverse()) {
-    await rm3(path, { force: true, recursive: true });
+    await rm4(path, { force: true, recursive: true });
   }
 }
 async function scaffoldProject({
@@ -10332,9 +10869,9 @@ async function scaffoldProject({
       targetCreated = true;
     }
     for (const entry of plan.entries) {
-      const source = join5(templateDirectory, entry.source);
-      const destination = join5(targetDirectory, entry.destination);
-      const stats = await lstat4(source);
+      const source = join9(entry.directory ?? templateDirectory, entry.source);
+      const destination = join9(targetDirectory, entry.destination);
+      const stats = await lstat6(source);
       if (!stats.isFile() || stats.isSymbolicLink()) {
         throw new Error("A template source is no longer a regular file.");
       }
@@ -10351,7 +10888,7 @@ async function scaffoldProject({
     );
     throw new CliError(
       "FILESYSTEM_ERROR",
-      "Could not create " + basename3(targetDirectory) + ": " + (error instanceof Error ? error.message : "unknown filesystem error"),
+      "Could not create " + basename4(targetDirectory) + ": " + (error instanceof Error ? error.message : "unknown filesystem error"),
       {
         exitCode: EXIT_CODES.filesystem,
         path: targetDirectory,
@@ -10365,16 +10902,26 @@ async function scaffoldProject({
 // src/templates.ts
 init_package_managers();
 var DEFAULT_TEMPLATE_ID = "cloudflare-livekit";
-var templateRegistry = {
-  [DEFAULT_TEMPLATE_ID]: cloudflareLivekitTemplate
-};
+var templateRegistry = Object.fromEntries(
+  Object.keys(stacks).map((stack) => [
+    stack,
+    composeTemplate(stack)
+  ])
+);
 function getTemplate(id = DEFAULT_TEMPLATE_ID) {
-  return templateRegistry[id];
+  const template = templateRegistry[id];
+  if (!template)
+    throw new CliError("INVALID_ARGUMENT", `Unknown template: ${id}`, {
+      exitCode: EXIT_CODES.invalidArgument
+    });
+  return template;
 }
 function resolveTemplateDirectory(template = getTemplate()) {
   return fileURLToPath(new URL(`../${template.directory}/`, import.meta.url));
 }
-async function resolveProjectTemplate(targetDirectory, templates = Object.values(templateRegistry)) {
+async function resolveProjectTemplate(targetDirectory, templates = [getTemplate()]) {
+  const config = await readProjectConfig(targetDirectory);
+  if (config) return getTemplate(config.stack);
   const matches = [];
   for (const template of templates) {
     if (await template.setup.recognizes(targetDirectory))
@@ -10405,4 +10952,3 @@ export {
   selectPythonPackageManager,
   templateRegistry
 };
-//# sourceMappingURL=templates.js.map