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

package/templates/cloudflare-livekit/tests/dev-fixtures.mjs

@@ -219,12 +219,17 @@ export async function readEvents(path) {
 
 export async function waitForEvents(path, predicate) {
   const deadline = Date.now() + 8000;
+  let events = [];
   while (Date.now() < deadline) {
-    const events = await readEvents(path);
+    events = await readEvents(path);
     if (predicate(events)) return events;
     await delay(25);
   }
-  assert.fail('Timed out waiting for fake processes to become ready.');
+  // Include progress without logging the fixture's environment or credentials.
+  const progress = events.map(({ role, type }) => `${role}:${type}`).join(', ');
+  assert.fail(
+    `Timed out waiting for fake processes to become ready. Events: ${progress || 'none'}`,
+  );
 }
 
 export async function assertStopped(pids) {

package/templates/cloudflare-livekit/tests/dev-supervision.test.mjs

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { delimiter, dirname, join } from 'node:path';
@@ -27,7 +28,7 @@ const concurrentlyBin = join(
   require(concurrentlyPackage).bin.concurrently,
 );
 
-async function supervise(f, extraEnv) {
+async function supervise(f, extraEnv, manager = 'npm', executable = manager) {
   const viteBin = join(f.root, 'node_modules', 'vite', 'bin');
   await mkdir(viteBin, { recursive: true });
   await writeFile(
@@ -37,14 +38,25 @@ async function supervise(f, extraEnv) {
   const sourcePackage = JSON.parse(
     await readFile(join(templateDirectory, 'package.json'), 'utf8'),
   );
-  // Exercise the production startup gate and supervisor with npm, available alongside
-  // Node in both generated projects and root CI. Only PM selection changes.
+  // npm is available alongside Node. The pnpm regression also exercises the
+  // package manager running this suite, without downloading another version.
   const scripts = Object.fromEntries(
     ['dev', 'dev:web', 'agent:dev'].map((name) => [
       name,
-      sourcePackage.scripts[name].replaceAll('pnpm run ', 'npm run '),
+      sourcePackage.scripts[name].replaceAll('pnpm run ', `${manager} run `),
     ]),
   );
+  // Observe completed production cleanup independently of pipe closure. A package
+  // manager can exit early while descendants still hold its output pipes open.
+  const finished = join(f.root, 'dev-finished');
+  await writeFile(
+    join(f.root, 'scripts', 'dev-finished.mjs'),
+    `import { writeFileSync } from 'node:fs'; await import('./dev.mjs'); writeFileSync(${JSON.stringify(finished)}, '');`,
+  );
+  scripts.dev = scripts.dev.replace(
+    'scripts/dev.mjs',
+    'scripts/dev-finished.mjs',
+  );
   await writeFile(
     join(f.root, 'package.json'),
     JSON.stringify({
@@ -72,7 +84,7 @@ async function supervise(f, extraEnv) {
   );
   const env = { ...f.env, ...extraEnv };
   env.PATH += `${delimiter}${process.env.PATH ?? process.env.Path ?? ''}`;
-  const spec = commandSpec('npm', ['run', 'dev'], env);
+  const spec = commandSpec(executable, ['run', 'dev'], env);
   const child = spawn(spec.command, spec.arguments_, {
     cwd: f.root,
     env,
@@ -92,23 +104,30 @@ async function supervise(f, extraEnv) {
     child.once('error', reject);
     child.once('close', (code, signal) => resolve({ code, signal, output }));
   });
-  return { child, done };
+  const exited = new Promise((resolve) => {
+    child.once('exit', () => resolve({ finished: existsSync(finished) }));
+  });
+  return { child, done, exited };
 }
 
-for (const [name, side, code] of [
+for (const [name, side, code, probe] of [
   ['web exits zero', 'web', '0'],
   ['web fails', 'web', '7'],
   ['agent exits zero', 'agent', '0'],
   ['agent fails', 'agent', '29'],
+  ['web exits zero after a timed-out CLI probe', 'web', '0', 'version-hang'],
 ]) {
   test(
     `root dev supervisor: ${name} stops its sibling and all grandchildren`,
     { timeout: 15000 },
     async (t) => {
-      const f = await fixture(t);
+      // Windows has only a preflight python.exe stub. Use the runnable uv shim
+      // so a slow CLI probe can fall back without exiting before registration.
+      const f = await fixture(t, { uv: windows || Boolean(probe) });
       const run = await supervise(f, {
         DEV_TEST_RUNTIME_HOLD: '1',
         DEV_TEST_GRANDCHILD: '1',
+        ...(probe ? { DEV_TEST_PROBE: probe } : {}),
         ...(side === 'web'
           ? { DEV_TEST_WEB_EXIT: code }
           : { DEV_TEST_EXIT_WHEN_RELEASED: '1', DEV_TEST_RUNTIME_EXIT: code }),
@@ -130,15 +149,14 @@ for (const [name, side, code] of [
       await assertStopped(events.map(({ pid }) => pid));
       // A bounded CLI probe may select Python fallback on a busy machine.
       // Supervision must launch exactly one runtime through either supported path.
-      assert.equal(
-        (await readEvents(f.events)).filter(
-          ({ role, args, type }) =>
-            ['lk', 'uv', 'python'].includes(role) &&
-            type === 'invoked' &&
-            args.includes('src/agent.py'),
-        ).length,
-        1,
+      const runtimes = (await readEvents(f.events)).filter(
+        ({ role, args, type }) =>
+          ['lk', 'uv', 'python'].includes(role) &&
+          type === 'invoked' &&
+          args.includes('src/agent.py'),
       );
+      assert.equal(runtimes.length, 1);
+      if (probe) assert.equal(runtimes[0].role, 'uv');
     },
   );
 }
@@ -152,7 +170,7 @@ test(
       'Node cannot send console Ctrl+C events on Windows; taskkill tree cleanup is tested separately.',
   },
   async (t) => {
-    const f = await fixture(t);
+    const f = await fixture(t, { uv: windows });
     const run = await supervise(f, {
       DEV_TEST_RUNTIME_HOLD: '1',
       DEV_TEST_GRANDCHILD: '1',
@@ -180,6 +198,50 @@ test(
   },
 );
 
+// Generated npm/bun projects need not install pnpm just to run their checks.
+// Root CI and generated pnpm checks supply the exact invoking pnpm executable.
+const pnpmExecutable = process.env.npm_execpath;
+test(
+  'pnpm waits for dev cleanup before exiting after one Ctrl+C',
+  {
+    timeout: 15000,
+    skip:
+      windows ||
+      !pnpmExecutable ||
+      !/pnpm(?:\.[cm]?js)?$/i.test(pnpmExecutable),
+  },
+  async (t) => {
+    const f = await fixture(t);
+    const run = await supervise(
+      f,
+      {
+        DEV_TEST_RUNTIME_HOLD: '1',
+        DEV_TEST_GRANDCHILD: '1',
+        DEV_TEST_DETACHED: '1',
+      },
+      'pnpm',
+      pnpmExecutable,
+    );
+    const events = await waitForEvents(
+      f.events,
+      (events) =>
+        events.filter(
+          ({ role, type }) => role === 'grandchild' && type === 'ready',
+        ).length === 2,
+    );
+    await delay(250);
+    process.kill(-run.child.pid, 'SIGINT');
+    assert.equal(
+      (await run.exited).finished,
+      true,
+      'pnpm returned before dev cleanup finished; use a pnpm launcher >=12.4.1 when using pnpm 12.',
+    );
+    const result = await run.done;
+    assertNoCredentials(result.output);
+    await assertStopped(events.map(({ pid }) => pid));
+  },
+);
+
 test(
   'a timed-out CLI probe reaps its descendants before Python fallback, including Windows cmd wrappers',
   { timeout: 15000 },
@@ -252,7 +314,7 @@ test(
   'agent failure before registration never starts web',
   { timeout: 15000 },
   async (t) => {
-    const f = await fixture(t);
+    const f = await fixture(t, { uv: windows });
     const run = await supervise(f, { DEV_TEST_RUNTIME_EXIT: '29' });
     const result = await run.done;
     assert.notEqual(result.code, 0);
@@ -265,7 +327,7 @@ test(
   'registration timeout stops the agent without starting web',
   { timeout: 15000 },
   async (t) => {
-    const f = await fixture(t);
+    const f = await fixture(t, { uv: windows });
     // Accelerate only the copied fixture's deadline; exercise the real web gate.
     const path = join(f.root, 'scripts', 'wait-for-agent.mjs');
     await writeFile(
@@ -290,7 +352,7 @@ test(
   'Ctrl+C while waiting for registration stops the agent without starting web',
   { timeout: 15000, skip: windows },
   async (t) => {
-    const f = await fixture(t);
+    const f = await fixture(t, { uv: windows });
     const run = await supervise(f, {
       DEV_TEST_RUNTIME_HOLD: '1',
       DEV_TEST_REGISTER: join(f.root, 'never-register'),

package/templates/layers/agora/AGENTS.md

@@ -1,8 +1,13 @@
 # Generated Agora application
 
 Use `__DEV__` for local development and `__CHECK__` for verification.
-The Node backend calls hosted Conversational AI over HTTP; do not add a Python
-worker. Browser audio uses Agora RTC, text input and transcripts use the official
+The Cloudflare Worker API calls hosted Conversational AI over HTTP. Agora owns
+the conversational agent; this application has no Python worker or Node server.
+Browser audio uses Agora RTC, and text input and transcripts use the official
 Agora client toolkit. Spatius renders the avatar locally.
-Keep secrets in .env.local or deployment environment variables. Preserve session
-cleanup on disconnect and failed startup. See DEPLOYMENT.md for Zeabur setup.
+
+Keep secrets in `.dev.vars` locally and Cloudflare Worker secrets in production.
+Wrangler generates the ignored `worker-configuration.d.ts` during installation
+and before lint, type checking, and builds. Update `wrangler.jsonc` to change bindings.
+Preserve session cleanup on disconnect and failed startup.
+Use mocks for provider calls in tests. See DEPLOYMENT.md for Cloudflare setup.

package/templates/layers/agora/README.md

@@ -1,6 +1,9 @@
-# Spatius voice assistant — Zeabur + Agora
+# Spatius voice assistant — Cloudflare + Agora
+
+A minimal React avatar conversation with a Cloudflare Worker API and Agora
+Conversational AI. The frontend and API deploy together on Cloudflare Workers;
+Agora hosts the conversational agent.
 
-A minimal React avatar conversation with an HTTP backend and Agora Conversational AI.
 Requires Node.js 22.12+, an Agora project with Conversational AI and RTM enabled,
 a published English assistant pipeline, and Spatius credentials. No Python is needed.
 
@@ -10,10 +13,13 @@ npx create-spatius-app setup . --interactive
 __DEV__
 ```
 
-Open the Vite URL, start a conversation, and speak or type. Microphone permission
-is optional: typed messages go to the model through Agora RTM. The transcript
-stays visible after disconnecting. Configure the assistant persona, speech
-recognition language, model, and voice in the published Agora pipeline. Match
-AGORA_AVATAR_SAMPLE_RATE to that pipeline's TTS output.
+Local setup saves credentials in `.dev.vars`. The Vite Cloudflare plugin runs
+both the frontend and Worker API locally. Open the printed URL, start a
+conversation, and speak or type. Microphone permission is optional: typed
+messages use Agora RTM. The transcript stays visible after disconnecting.
+
+Configure the assistant persona, speech recognition language, model, and voice
+in the published Agora pipeline. Match `AGORA_AVATAR_SAMPLE_RATE` to its TTS output.
 
-See DEPLOYMENT.md to deploy the frontend and API together to Zeabur.
+Run `__CHECK__` to verify the application. See [DEPLOYMENT.md](DEPLOYMENT.md)
+to deploy the frontend and API together to Cloudflare Workers.