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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-spatius-app",
-  "version": "0.1.1",
-  "description": "Create a Spatius app with a web frontend, Cloudflare Worker, and LiveKit agent.",
+  "version": "0.1.3-beta.1",
+  "description": "Create a Spatius voice-avatar app with LiveKit or Agora and your choice of hosting.",
   "type": "module",
   "bin": {
     "create-spatius-app": "./dist/cli.js"
@@ -34,7 +34,7 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.25.0",
+  "packageManager": "pnpm@12.3.4",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -60,7 +60,7 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.4.1",
     "@vercel/detect-agent": "1.2.5",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/coverage-v8": "5.0.0",
     "ajv": "8.20.0",
     "commander": "^15.0.0",
     "concurrently": "10.0.5",
@@ -73,7 +73,7 @@
     "tsx": "^4.23.13",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.69.0",
-    "vitest": "^4.1.11",
+    "vitest": "^5.0.0",
     "yaml": "2.9.0"
   }
 }

package/schemas/result-v3.schema.json

@@ -0,0 +1,174 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "create-spatius-app result v3",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/success"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "success": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "ok",
+        "command",
+        "dryRun",
+        "generatorVersion",
+        "projectDirectory",
+        "template",
+        "created",
+        "wouldCreate",
+        "actions",
+        "packageManagers",
+        "nextSteps",
+        "stack",
+        "humanSteps"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": 3
+        },
+        "ok": {
+          "const": true
+        },
+        "command": {
+          "const": "create"
+        },
+        "dryRun": {
+          "type": "boolean"
+        },
+        "generatorVersion": {
+          "type": "string"
+        },
+        "projectDirectory": {
+          "type": "string"
+        },
+        "template": {
+          "type": "string"
+        },
+        "created": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "wouldCreate": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "actions": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["dependenciesInstalled", "gitInitialized", "deployed"],
+          "properties": {
+            "dependenciesInstalled": {
+              "type": "boolean"
+            },
+            "gitInitialized": {
+              "const": false
+            },
+            "deployed": {
+              "const": false
+            }
+          }
+        },
+        "packageManagers": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["javascript"],
+          "properties": {
+            "javascript": {
+              "enum": ["npm", "pnpm", "bun"]
+            },
+            "python": {
+              "enum": ["pip", "uv"]
+            }
+          }
+        },
+        "nextSteps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "stack": {
+          "type": "string"
+        },
+        "humanSteps": {
+          "type": "array",
+          "description": "Human prerequisites before running the app. Commands run from projectDirectory. On dry runs these are planned steps after creation, not actions already performed.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command", "reason", "requiresHuman", "requiresTty"],
+            "properties": {
+              "command": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "requiresHuman": {
+                "const": true
+              },
+              "requiresTty": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "ok", "error"],
+      "properties": {
+        "schemaVersion": {
+          "const": 3
+        },
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "enum": [
+                "CANCELLED",
+                "FILESYSTEM_ERROR",
+                "INSTALL_FAILED",
+                "INVALID_ARGUMENT",
+                "PACKAGE_MANAGER_NOT_FOUND",
+                "PACKAGE_MANAGER_UNAVAILABLE",
+                "TARGET_NOT_DIRECTORY",
+                "TARGET_NOT_EMPTY",
+                "TEMPLATE_NOT_FOUND",
+                "UNSAFE_TARGET",
+                "UNKNOWN_ERROR"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "recovery": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/result-v4.schema.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "create-spatius-app result v4",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/success"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "success": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "ok",
+        "command",
+        "dryRun",
+        "generatorVersion",
+        "projectDirectory",
+        "created",
+        "wouldCreate",
+        "actions",
+        "packageManagers",
+        "nextSteps",
+        "stack",
+        "humanSteps"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": 4
+        },
+        "ok": {
+          "const": true
+        },
+        "command": {
+          "const": "create"
+        },
+        "dryRun": {
+          "type": "boolean"
+        },
+        "generatorVersion": {
+          "type": "string"
+        },
+        "projectDirectory": {
+          "type": "string"
+        },
+        "created": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "wouldCreate": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "actions": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["dependenciesInstalled", "gitInitialized", "deployed"],
+          "properties": {
+            "dependenciesInstalled": {
+              "type": "boolean"
+            },
+            "gitInitialized": {
+              "const": false
+            },
+            "deployed": {
+              "const": false
+            }
+          }
+        },
+        "packageManagers": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["javascript"],
+          "properties": {
+            "javascript": {
+              "enum": ["npm", "pnpm", "bun"]
+            },
+            "python": {
+              "enum": ["pip", "uv"]
+            }
+          }
+        },
+        "nextSteps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "stack": {
+          "type": "string"
+        },
+        "humanSteps": {
+          "type": "array",
+          "description": "Human prerequisites before running the app. Commands run from projectDirectory. On dry runs these are planned steps after creation, not actions already performed.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command", "reason", "requiresHuman", "requiresTty"],
+            "properties": {
+              "command": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "requiresHuman": {
+                "const": true
+              },
+              "requiresTty": {
+                "const": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "ok", "error"],
+      "properties": {
+        "schemaVersion": {
+          "const": 4
+        },
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "enum": [
+                "CANCELLED",
+                "FILESYSTEM_ERROR",
+                "INSTALL_FAILED",
+                "INVALID_ARGUMENT",
+                "PACKAGE_MANAGER_NOT_FOUND",
+                "PACKAGE_MANAGER_UNAVAILABLE",
+                "TARGET_NOT_DIRECTORY",
+                "TARGET_NOT_EMPTY",
+                "TEMPLATE_NOT_FOUND",
+                "UNSAFE_TARGET",
+                "UNKNOWN_ERROR"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "recovery": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/cloudflare-livekit/AGENTS.md

@@ -18,6 +18,10 @@ Run from the project root:
 - Start only the Python agent: `__SPATIUS_AGENT_DEV_COMMAND__`
 - Check frontend/Worker: `__SPATIUS_CHECK_COMMAND__`
 - Check Python: `__SPATIUS_AGENT_CHECK_COMMAND__`
+- Check browser flows with mocks: `__SPATIUS_E2E_COMMAND__`
+
+All checks can run after dependency installation, before credential setup.
+Browser tests require Chromium; see README.md for the installation command.
 
 ## Working guidelines
 

package/templates/cloudflare-livekit/README.md

@@ -28,6 +28,22 @@ npx create-spatius-app setup . --interactive
 Follow the prompts to connect LiveKit and Spatius, select an avatar, and choose
 a matching voice. This configures local development only, not deployment.
 
+#### Manual credential setup
+
+Alternatively, copy `.dev.vars.example` to `.dev.vars` and
+`agent/.env.example` to `agent/.env.local`, then edit the copies locally:
+
+- Use the same LiveKit Cloud project’s `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and
+  `LIVEKIT_API_SECRET` in both files.
+- Set the same `SPATIUS_APP_ID` in both files and set `SPATIUS_API_KEY` in
+  `agent/.env.local` to a key for that app.
+- In `.dev.vars`, set `SPATIUS_AVATAR_ID` to your chosen avatar.
+  `SPATIUS_AVATAR_BACKGROUND_URL` is optional and can stay empty. Keep the
+  example `CARTESIA_VOICE_ID` to use the default voice.
+
+Keep the example `LIVEKIT_AGENT_NAME` so the Worker dispatches the bundled
+agent. Both credential files are ignored by Git; keep their values local.
+
 ### 3. Start the app
 
 ```sh
@@ -37,3 +53,28 @@ __SPATIUS_DEV_COMMAND__
 This starts the Python agent first, then starts the frontend and Cloudflare
 Worker once the agent has registered with LiveKit. If registration takes more
 than 60 seconds, startup stops with an error.
+
+## Validate without credentials
+
+After installing both dependency sets, you can run these checks before account
+setup. Run them from the project root:
+
+```sh
+__SPATIUS_CHECK_COMMAND__
+__SPATIUS_AGENT_CHECK_COMMAND__
+```
+
+These check formatting, lint, types, unit tests, development-process behavior,
+and the production build. They do not require LiveKit or Spatius credentials.
+
+Browser tests use mocked services and also run without credentials:
+
+```sh
+npx playwright install chromium
+__SPATIUS_E2E_COMMAND__
+```
+
+The first command downloads Chromium if needed. On Linux, use
+`npx playwright install --with-deps chromium` to also install required system
+libraries. These tests verify the local UI flow; a real voice-avatar
+conversation still requires account setup and starting the app.

package/templates/cloudflare-livekit/agent/README.md

@@ -22,10 +22,6 @@ LiveKit room as the browser.
   enhanced noise-cancellation model in the browser; standard browser echo
   cancellation can stay enabled.
 
-The noise-cancellation dependency stays on the BVC-compatible `0.2.x` series.
-LiveKit's newer voice-isolation recommendation is Krisp VIVA; switching to that
-is a separate choice, not an implicit dependency upgrade.
-
 See [Cartesia TTS](https://docs.livekit.io/agents/models/tts/cartesia/),
 [expressive mode](https://docs.livekit.io/agents/models/tts/expressive/), and
 [noise cancellation](https://docs.livekit.io/transport/media/noise-cancellation/).

package/templates/cloudflare-livekit/agent/env.example

@@ -6,3 +6,6 @@ LIVEKIT_API_SECRET=your-livekit-api-secret
 # Spatius credentials
 SPATIUS_API_KEY=your-spatius-api-key
 SPATIUS_APP_ID=your-spatius-app-id
+
+# Companion only: public web API origin (local Vite default).
+SPATIUS_API_ORIGIN=http://localhost:5173

package/templates/cloudflare-livekit/agent/pyproject.toml

@@ -6,7 +6,7 @@ readme = "README.md"
 requires-python = ">=3.11,<3.15"
 dependencies = [
   "livekit-agents[spatius]~=1.8.0",
-  "livekit-plugins-noise-cancellation~=0.2.6",
+  "livekit-plugins-noise-cancellation~=0.3.0",
   "python-dotenv>=1.2.1,<2",
 ]
 

package/templates/cloudflare-livekit/agent/src/agent.py

@@ -25,10 +25,11 @@ load_dotenv(".env.local")
 
 
 class Assistant(Agent):
-    def __init__(self) -> None:
+    def __init__(self, instructions: str | None = None) -> None:
         super().__init__(
             llm=inference.LLM(model="google/gemma-4-31b-it"),
-            instructions=textwrap.dedent(
+            instructions=instructions
+            or textwrap.dedent(
                 """\
                 You are a warm, concise voice assistant speaking through a digital
                 avatar. Help the user directly and conversationally.
@@ -82,8 +83,9 @@ async def spatius_agent(ctx: JobContext) -> None:
     avatar = spatius.AvatarSession(avatar_id=dispatch_metadata.avatar_id)
     await avatar.start(session, room=ctx.room)
 
+    assistant = Assistant()
     await session.start(
-        agent=Assistant(),
+        agent=assistant,
         room=ctx.room,
         room_options=room_io.RoomOptions(
             audio_input=room_io.AudioInputOptions(

package/templates/cloudflare-livekit/agent/uv.lock

@@ -920,17 +920,17 @@ wheels = [
 
 [[package]]
 name = "livekit-plugins-noise-cancellation"
-version = "0.2.6"
+version = "0.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "livekit" },
 ]
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/19/90/fdb859b5745feb0b130b89b2d6bf0433fb70346d87e0307518cfc9c57c11/livekit_plugins_noise_cancellation-0.2.6-py3-none-macosx_10_9_x86_64.whl", hash = "sha256:6a607767abfc266a5fa9d90fc549371fc2f91401f761b4ca89227e04ce4fa8b5", size = 66080343, upload-time = "2026-06-26T11:14:11.815Z" },
-    { url = "https://files.pythonhosted.org/packages/63/a7/36b7800a9dc7ef167b3e47cc8b53620cfe8fd3d6d2d374ae11ebbbd39ffc/livekit_plugins_noise_cancellation-0.2.6-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6c50b8ace36e5a75ea096af38c9a799b325676db7b9a5f0d67a228f222e0150a", size = 64620411, upload-time = "2026-06-26T11:14:15.308Z" },
-    { url = "https://files.pythonhosted.org/packages/72/5c/8f4623bbc665a0552a1ee6089dc346f5bf0b929b49afb174cd1085411ac5/livekit_plugins_noise_cancellation-0.2.6-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:ae3598ac886b239faeed7bbe2ca1b20e6066d5744da80618d0a9d7fc7fa70fba", size = 70236105, upload-time = "2026-06-26T11:14:18.293Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/bd/ea16d2492cd159e4685ca4160864e7d55bfaf8d199dbd4b5433cb366d0d0/livekit_plugins_noise_cancellation-0.2.6-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:a01ebe5a610ef693a5b5b24e077c1d677bab365ac9316c1339850ad0960c87ec", size = 73017542, upload-time = "2026-06-26T11:14:22.325Z" },
-    { url = "https://files.pythonhosted.org/packages/16/a4/2ec98ead17ae6cb9e488a11baf9c91b4c4767af16611eacf36e084122364/livekit_plugins_noise_cancellation-0.2.6-py3-none-win_amd64.whl", hash = "sha256:d8b7a0876124cdd861dec657c7d698b3a7cab09ccb11c3af0fc536b0b43c42b2", size = 65771262, upload-time = "2026-06-26T11:14:25.638Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/ad/e049eeca9c5175cc70c036c6dc5ce048215949b5d7ea83dbea6e2e06260c/livekit_plugins_noise_cancellation-0.3.0-py3-none-macosx_10_9_x86_64.whl", hash = "sha256:6c877ca3f31278ce3b6ba7a3adc0eaaf813a53ba5a900445616be69ce7e4b3a8", size = 66079924, upload-time = "2026-07-17T10:35:02.671Z" },
+    { url = "https://files.pythonhosted.org/packages/07/61/7a860386cf0c9d27f4d3fdcfeee411153e1618552d6a15ad46d32df64ac5/livekit_plugins_noise_cancellation-0.3.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:1d100f249d25556696d8fe358b7c22d81017df67f256ee3b5c9c36830409621f", size = 64625049, upload-time = "2026-07-17T10:35:06.186Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/0d/df886e71b463911a9190cea948100f89c1e0546cff7e84dd93862b73e2d9/livekit_plugins_noise_cancellation-0.3.0-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:4b48de9ffdb8af47820ecd5e44ef0dbb910dfd05f17f6fadcbfd64deceb7a09a", size = 70250046, upload-time = "2026-07-17T10:35:09.376Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/43/701df4746e4e8b660f1399ec0a3da80de211f1624725a7496d28f7443b4a/livekit_plugins_noise_cancellation-0.3.0-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:1703099d634d26171e2f0402c81fc84f13bf0bc92a7f9ba16f9af1d0eefee980", size = 73004876, upload-time = "2026-07-17T10:35:12.775Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/b4/3ed7bac7aabec196c1e8969b407b71f69bdb0c942b1b3cd2aed07ae276cf/livekit_plugins_noise_cancellation-0.3.0-py3-none-win_amd64.whl", hash = "sha256:7f6001d0dd3b00c7748949b7a8349de002118fc03faa2d38411ad0d05180ccab", size = 65788455, upload-time = "2026-07-17T10:35:15.759Z" },
 ]
 
 [[package]]
@@ -1892,7 +1892,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "livekit-agents", extras = ["spatius"], specifier = "~=1.8.0" },
-    { name = "livekit-plugins-noise-cancellation", specifier = "~=0.2.6" },
+    { name = "livekit-plugins-noise-cancellation", specifier = "~=0.3.0" },
     { name = "python-dotenv", specifier = ">=1.2.1,<2" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.15,<1" },
 ]