create-spatius-app 0.1.0-beta.0

package/templates/cloudflare-livekit/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+allowBuilds:
+  core-js: true
+  esbuild: true
+  workerd: true
+autoInstallPeers: false
+preferFrozenLockfile: true
+saveExact: true
+strictPeerDependencies: true

package/templates/cloudflare-livekit/scripts/agent-runtime.mjs

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { parseEnv } from 'node:util';
+import { resolveCommand } from './command.mjs';
+
+export const projectDirectory = resolve(import.meta.dirname, '..');
+export const agentDirectory = join(projectDirectory, 'agent');
+export const usesUv = existsSync(join(agentDirectory, 'uv.lock'));
+const virtualEnvironment = join(agentDirectory, '.venv');
+const virtualBin = join(
+  virtualEnvironment,
+  process.platform === 'win32' ? 'Scripts' : 'bin',
+);
+export const python = join(
+  virtualBin,
+  process.platform === 'win32' ? 'python.exe' : 'python',
+);
+
+export function pythonEnvironment(environment = process.env) {
+  // lk's pip launcher resolves Python through PATH. Pin both launch paths to
+  // this project's environment, even when another environment is activated.
+  const env = { ...environment };
+  const pathKey =
+    Object.keys(env).find((key) => key.toUpperCase() === 'PATH') ?? 'PATH';
+  let inheritedPath = env[pathKey] ?? '';
+  if (process.platform === 'win32') {
+    // lk checks python3 before python and only recognizes POSIX venv paths.
+    // Exclude other python3 installations so its pip path finds our python.exe.
+    inheritedPath = inheritedPath
+      .split(delimiter)
+      .filter(
+        (directory) =>
+          !['.exe', '.com', '.cmd', '.bat'].some((suffix) =>
+            existsSync(join(directory, `python3${suffix}`)),
+          ),
+      )
+      .join(delimiter);
+  }
+  env[pathKey] = `${virtualBin}${delimiter}${inheritedPath}`;
+  env.VIRTUAL_ENV = virtualEnvironment;
+  env.UV_PROJECT_ENVIRONMENT = virtualEnvironment;
+  env.UV_PYTHON = python;
+  env.UV_NO_SYNC = '1';
+  env.UV_PYTHON_DOWNLOADS = 'never';
+  env.UV_OFFLINE = '1';
+  env.UV_NO_ENV_FILE = '1';
+  return env;
+}
+
+export function requirePythonEnvironment() {
+  if (!existsSync(python)) {
+    throw new Error(
+      'Python dependencies are not installed in agent/.venv. Follow the Python installation instructions in README.md, then try again.',
+    );
+  }
+}
+
+export function pythonCommand(arguments_) {
+  return usesUv
+    ? {
+        command: resolveCommand('uv'),
+        arguments_: [
+          'run',
+          '--no-sync',
+          '--directory',
+          agentDirectory,
+          '--extra',
+          'dev',
+          'python',
+          ...arguments_,
+        ],
+      }
+    : { command: python, arguments_ };
+}
+
+export function devEnvironment() {
+  let local = {};
+  try {
+    local = parseEnv(readFileSync(join(agentDirectory, '.env.local'), 'utf8'));
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw new Error(
+        'Could not read agent/.env.local. Check its contents and permissions.',
+        { cause: error },
+      );
+    }
+  }
+
+  // Explicit inherited values, including empty values, take precedence.
+  const env = { ...local, ...process.env };
+  const required = [
+    'LIVEKIT_URL',
+    'LIVEKIT_API_KEY',
+    'LIVEKIT_API_SECRET',
+    'SPATIUS_API_KEY',
+    'SPATIUS_APP_ID',
+  ];
+  const missing = required.filter((key) => !env[key]?.trim());
+  if (missing.length) {
+    throw new Error(
+      `Missing agent development credentials: ${missing.join(', ')}. Set them in agent/.env.local or the environment. See README.md for credential setup.`,
+    );
+  }
+  const placeholders = required.filter((key) =>
+    /^(?:your[-_]|<)|your-project\.livekit\.cloud/i.test(env[key].trim()),
+  );
+  if (placeholders.length) {
+    throw new Error(
+      `Replace example values for ${placeholders.join(', ')} in agent/.env.local or the environment. See README.md for credential setup.`,
+    );
+  }
+  let validUrl = false;
+  try {
+    const url = new URL(env.LIVEKIT_URL);
+    validUrl =
+      ['https:', 'wss:'].includes(url.protocol) &&
+      Boolean(url.hostname) &&
+      !url.username &&
+      !url.password;
+  } catch {
+    /* Report only the variable name, never the supplied value. */
+  }
+  if (!validUrl) {
+    throw new Error(
+      'LIVEKIT_URL must be a valid https:// or wss:// server URL without embedded credentials. Set it in agent/.env.local or the environment. See README.md for credential setup.',
+    );
+  }
+  return pythonEnvironment(env);
+}

package/templates/cloudflare-livekit/scripts/command.mjs

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs';
+import { delimiter, extname, isAbsolute, join } from 'node:path';
+
+// Node cannot execute Windows .cmd/.bat launchers directly. Resolve PATH first
+// so a missing CLI stays a bounded spawn failure instead of a shell diagnostic.
+export function resolveCommand(command, env = process.env) {
+  if (process.platform !== 'win32') return command;
+  const value = (key) =>
+    env[Object.keys(env).find((entry) => entry.toUpperCase() === key)] ?? '';
+  const suffixes = extname(command)
+    ? ['']
+    : (value('PATHEXT') || '.COM;.EXE;.BAT;.CMD').split(';');
+  const directories = isAbsolute(command)
+    ? ['']
+    : value('PATH').split(delimiter);
+  let executable;
+  for (const directory of directories) {
+    for (const suffix of suffixes) {
+      const candidate = join(directory, `${command}${suffix}`);
+      if (existsSync(candidate)) {
+        executable = candidate;
+        break;
+      }
+    }
+    if (executable) break;
+  }
+  return executable ?? command;
+}
+
+export function commandSpec(command, arguments_, env = process.env) {
+  const executable = resolveCommand(command, env);
+  if (process.platform !== 'win32' || !/\.(cmd|bat)$/i.test(executable)) {
+    return { command: executable, arguments_ };
+  }
+
+  const escapeMeta = (text) => text.replace(/([()[\]%!^"`<>&|;, *?])/g, '^$1');
+  const quoteArgument = (argument) => {
+    const quoted = `"${argument.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1')}"`;
+    const escaped = escapeMeta(quoted);
+    return /node_modules[\\/]\.bin[\\/]/i.test(executable)
+      ? escapeMeta(escaped)
+      : escaped;
+  };
+  const line = [escapeMeta(executable), ...arguments_.map(quoteArgument)].join(
+    ' ',
+  );
+  return {
+    command: env.ComSpec || env.COMSPEC || env.comspec || 'cmd.exe',
+    arguments_: ['/d', '/s', '/c', `"${line}"`],
+    windowsVerbatimArguments: true,
+  };
+}

package/templates/cloudflare-livekit/scripts/dev-agent.mjs

@@ -0,0 +1,77 @@
+import {
+  agentDirectory,
+  devEnvironment,
+  pythonCommand,
+  requirePythonEnvironment,
+} from './agent-runtime.mjs';
+import { runProcess } from './managed-process.mjs';
+import { resolveCommand } from './command.mjs';
+
+// v2.18.2 first passes dev credentials to Python through env rather than argv.
+// https://github.com/livekit/livekit-cli/releases/tag/v2.18.2
+function compatibleVersion(output) {
+  const version =
+    /^lk version v?(\d+)\.(\d+)\.(\d+)(?:\+[^\s]+)?(?:\s|$)/m.exec(
+      output.trim(),
+    );
+  if (!version) return false;
+  const [major, minor, patch] = version.slice(1).map(Number);
+  return (
+    major > 2 || (major === 2 && (minor > 18 || (minor === 18 && patch >= 2)))
+  );
+}
+
+async function main() {
+  // Resolve before restricting Windows Python lookup: lk/uv may share a PATH
+  // directory with an unrelated global python3 installation.
+  const liveKitCommand = resolveCommand('lk');
+  const env = devEnvironment();
+  requirePythonEnvironment();
+  // Neither compatibility probe needs credentials, including inherited ones.
+  const probeEnv = Object.fromEntries(
+    Object.entries(env).filter(([key]) => !/^(LIVEKIT_|SPATIUS_)/i.test(key)),
+  );
+  const probeOptions = { cwd: agentDirectory, env: probeEnv, probe: true };
+  const version = await runProcess(liveKitCommand, ['--version'], probeOptions);
+  if (version.interrupted) return version.code;
+  let useLiveKit =
+    !version.failed && version.code === 0 && compatibleVersion(version.output);
+  if (useLiveKit) {
+    const help = await runProcess(
+      liveKitCommand,
+      ['agent', 'dev', '--help'],
+      probeOptions,
+    );
+    if (help.interrupted) return help.code;
+    useLiveKit =
+      !help.failed &&
+      help.code === 0 &&
+      /lk agent dev\b/.test(help.output) &&
+      /entrypoint/.test(help.output);
+  }
+
+  const { command, arguments_ } = useLiveKit
+    ? { command: liveKitCommand, arguments_: ['agent', 'dev', 'src/agent.py'] }
+    : pythonCommand(['-m', 'livekit.agents', 'start', 'src/agent.py', '--dev']);
+  if (!useLiveKit) {
+    console.error(
+      'A compatible LiveKit CLI (>=2.18.2) was not found. Starting the selected Python runtime in dev mode without CLI auto-reload.',
+    );
+  }
+  const result = await runProcess(command, arguments_, {
+    cwd: agentDirectory,
+    env,
+  });
+  if (result.failed)
+    console.error(
+      'Could not launch the selected agent runtime. Check its installation and try again.',
+    );
+  return result.code;
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/templates/cloudflare-livekit/scripts/dev-web.mjs

@@ -0,0 +1,18 @@
+import { join } from 'node:path';
+import { projectDirectory } from './agent-runtime.mjs';
+import { runProcess } from './managed-process.mjs';
+
+const result = await runProcess(
+  process.execPath,
+  [
+    join(projectDirectory, 'node_modules', 'vite', 'bin', 'vite.js'),
+    ...process.argv.slice(2),
+  ],
+  { cwd: projectDirectory, env: process.env },
+);
+if (result.failed) {
+  console.error(
+    'Could not launch Vite. Install JavaScript dependencies and try again.',
+  );
+}
+process.exitCode = result.code;

package/templates/cloudflare-livekit/scripts/managed-process.mjs

@@ -0,0 +1,144 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { join } from 'node:path';
+import { commandSpec } from './command.mjs';
+import { trackProcessTree } from './process-tree.mjs';
+
+export function exitCode(code, signal) {
+  return code ?? (signal ? 128 + (constants.signals[signal] ?? 1) : 1);
+}
+
+// Runtime processes inherit output. Probes capture bounded output privately;
+// never print spawn errors or captured probe data, which can contain secrets.
+export function runProcess(
+  command,
+  arguments_,
+  { cwd, env, probe = false, timeout = 2000 } = {},
+) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      const spec = commandSpec(command, arguments_, env);
+      child = spawn(spec.command, spec.arguments_, {
+        cwd,
+        env,
+        stdio: probe ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+        windowsVerbatimArguments: spec.windowsVerbatimArguments,
+      });
+    } catch {
+      resolve({ code: 1, output: '', failed: true, interrupted: false });
+      return;
+    }
+    let output = '';
+    let interrupted;
+    let failed = false;
+    let forceTimer;
+    let timeoutTimer;
+    let stopRequest;
+    const treeKills = [];
+    const tree = child.pid ? trackProcessTree(child.pid) : undefined;
+
+    const kill = (signal) => {
+      if (!child.pid) return;
+      try {
+        if (process.platform === 'win32') {
+          const killer = spawn(
+            join(
+              process.env.SystemRoot ?? 'C:\\Windows',
+              'System32',
+              'taskkill.exe',
+            ),
+            ['/pid', String(child.pid), '/T', '/F'],
+            { windowsHide: true, stdio: 'ignore' },
+          );
+          treeKills.push(
+            new Promise((done) => {
+              killer.on('error', () => {
+                child.kill();
+              });
+              killer.once('close', done);
+            }),
+          );
+        } else process.kill(-child.pid, signal);
+      } catch (error) {
+        if (error.code !== 'ESRCH') child.kill(signal);
+      }
+    };
+    const stop = (signal) => {
+      if (stopRequest) return;
+      stopRequest = (async () => {
+        // Capture and signal descendants before their parent can exit and
+        // reparent them. Repeated signals from npm/concurrently share teardown.
+        if (tree) await tree.kill(signal);
+        kill(signal);
+        if (child.exitCode === null && child.signalCode === null) {
+          forceTimer = setTimeout(() => {
+            if (tree) treeKills.push(tree.kill('SIGKILL'));
+            kill('SIGKILL');
+          }, 1500);
+        }
+      })();
+      treeKills.push(stopRequest);
+    };
+    const onInterrupt = () => {
+      interrupted ??= 'SIGINT';
+      stop('SIGINT');
+    };
+    const onTerminate = () => {
+      interrupted ??= 'SIGTERM';
+      stop('SIGTERM');
+    };
+    process.on('SIGINT', onInterrupt);
+    process.on('SIGTERM', onTerminate);
+
+    if (probe) {
+      const capture = (chunk) => {
+        if (failed) return;
+        if (Buffer.byteLength(output) + chunk.length > 64 * 1024) {
+          failed = true;
+          stop('SIGKILL');
+          return;
+        }
+        output += chunk.toString();
+      };
+      child.stdout.on('data', capture);
+      child.stderr.on('data', capture);
+      timeoutTimer = setTimeout(() => {
+        failed = true;
+        stop('SIGKILL');
+      }, timeout);
+    }
+    child.on('error', () => {
+      failed = true;
+    });
+    // 'exit' occurs before 'close': an orphan can keep inherited output pipes
+    // open, so waiting for 'close' to clean up would hang indefinitely.
+    child.once('exit', () => {
+      tree?.stop();
+      if (tree) treeKills.push(tree.kill('SIGKILL'));
+      if (process.platform !== 'win32') kill('SIGKILL');
+    });
+    child.once('close', async (code, signal) => {
+      clearTimeout(timeoutTimer);
+      clearTimeout(forceTimer);
+      process.off('SIGINT', onInterrupt);
+      process.off('SIGTERM', onTerminate);
+      tree?.stop();
+      // Reap remaining members of our process group when its leader exits.
+      if (process.platform !== 'win32') kill('SIGKILL');
+      await Promise.all(treeKills);
+      resolve({
+        code: interrupted
+          ? exitCode(null, interrupted)
+          : failed
+            ? 1
+            : exitCode(code, signal),
+        output,
+        failed,
+        interrupted: Boolean(interrupted),
+      });
+    });
+  });
+}

package/templates/cloudflare-livekit/scripts/process-tree.mjs

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+
+// lk puts its Python subprocess in a separate process group. Remember the
+// descendant identities while lk is alive so an unexpected leader exit cannot
+// leave that group behind. ps reads only process IDs and start times, not argv.
+export function trackProcessTree(rootPid) {
+  const known = new Map();
+  let pending;
+  let stopped = false;
+  const windows = process.platform === 'win32';
+
+  const snapshot = () => {
+    pending ??= new Promise((resolve) => {
+      execFile(
+        windows
+          ? join(
+              process.env.SystemRoot ?? 'C:\\Windows',
+              'System32',
+              'WindowsPowerShell',
+              'v1.0',
+              'powershell.exe',
+            )
+          : '/bin/ps',
+        windows
+          ? [
+              '-NoProfile',
+              '-NonInteractive',
+              '-Command',
+              'Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate | Where-Object { $_.CreationDate } | ForEach-Object { "{0} {1} {2}" -f $_.ProcessId,$_.ParentProcessId,$_.CreationDate.ToFileTimeUtc() }',
+            ]
+          : ['-A', '-o', 'pid=,ppid=,lstart='],
+        {
+          timeout: windows ? 3000 : 1000,
+          maxBuffer: 1024 * 1024,
+          windowsHide: true,
+        },
+        (error, stdout) => {
+          const rows = error
+            ? []
+            : stdout
+                .trim()
+                .split('\n')
+                .map((line) => {
+                  const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+                  return match
+                    ? {
+                        pid: Number(match[1]),
+                        parent: Number(match[2]),
+                        identity: match[3],
+                      }
+                    : null;
+                })
+                .filter(Boolean);
+          const descendants = new Set([rootPid]);
+          for (const row of rows) {
+            if (known.get(row.pid) === row.identity) descendants.add(row.pid);
+          }
+          let changed = true;
+          while (changed) {
+            changed = false;
+            for (const row of rows) {
+              if (descendants.has(row.parent) && !descendants.has(row.pid)) {
+                descendants.add(row.pid);
+                changed = true;
+              }
+            }
+          }
+          known.clear();
+          for (const row of rows) {
+            if (row.pid !== rootPid && descendants.has(row.pid))
+              known.set(row.pid, row.identity);
+          }
+          resolve([...known.keys()].reverse());
+        },
+      );
+    })
+      .catch(() => [])
+      .finally(() => {
+        pending = undefined;
+      });
+    return pending;
+  };
+
+  // Windows retains the creation-time ParentProcessId even after parent exit;
+  // one shutdown snapshot suffices. POSIX reparents orphans, requiring tracking.
+  const timer = windows
+    ? undefined
+    : setInterval(() => {
+        if (!stopped) void snapshot();
+      }, 100);
+  timer?.unref();
+  return {
+    async kill(signal) {
+      // A polling snapshot may predate a just-spawned grandchild. Refresh it
+      // before signalling its parent, while that ancestry is still observable.
+      if (pending) await pending;
+      for (const pid of await snapshot()) {
+        try {
+          process.kill(pid, signal);
+        } catch {
+          /* Already exited. */
+        }
+      }
+    },
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+    },
+  };
+}

package/templates/cloudflare-livekit/scripts/run-agent-python.mjs

@@ -0,0 +1,25 @@
+import {
+  agentDirectory,
+  pythonCommand,
+  pythonEnvironment,
+  requirePythonEnvironment,
+} from './agent-runtime.mjs';
+import { runProcess } from './managed-process.mjs';
+
+try {
+  requirePythonEnvironment();
+  const { command, arguments_ } = pythonCommand(process.argv.slice(2));
+  const result = await runProcess(command, arguments_, {
+    cwd: agentDirectory,
+    env: pythonEnvironment(),
+  });
+  if (result.failed) {
+    console.error(
+      'Could not launch the selected Python runtime. Follow the Python installation instructions in README.md.',
+    );
+  }
+  process.exitCode = result.code;
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}