@streamotter/cli 0.1.0-rc.1

package/src/cli.ts

@@ -0,0 +1,302 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import {
+  canonicalJsonPretty, validateProjectConfig,
+  type ConfigIssue, type DevelopmentOptions, type HandlerRegistry, type Json, type ProjectConfig
+} from "@streamotter/contracts";
+import { createGateway, type Gateway, type GatewayLogger } from "@streamotter/gateway";
+import { startManagementServer } from "@streamotter/gateway/management";
+import { getGatewayInternals } from "@streamotter/gateway/internals";
+import { fingerprint, generateFiles, GENERATED_MARKER } from "./generate.ts";
+import { scaffoldFiles } from "./templates.ts";
+
+export const EXIT = { ok: 0, runtime: 1, invalid: 2 } as const;
+
+export interface CliIO {
+  out(line: string): void;
+  err(line: string): void;
+  /** Resolves when the process should shut down (SIGINT/SIGTERM). */
+  shutdownSignal: Promise<string>;
+}
+
+class CliError extends Error {
+  readonly exitCode: number;
+
+  constructor(exitCode: number, message: string) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+const USAGE = `Usage:
+  streamotter init <directory>
+  streamotter validate --config <path>
+  streamotter generate --config <path> --out <directory>
+  streamotter dev --config <path> --handlers <module> [--management-port <port>]
+  streamotter start --config <path> --handlers <module>`;
+
+function formatIssues(issues: readonly ConfigIssue[]): string {
+  return issues.map(issue => `  ${issue.path || "/"}  ${issue.code}: ${issue.message}`).join("\n");
+}
+
+async function loadConfig(path: string | undefined): Promise<{ config: ProjectConfig; path: string }> {
+  if (path === undefined) throw new CliError(EXIT.invalid, "--config <path> is required.");
+  const absolute = resolve(path);
+  let text: string;
+  try {
+    text = await readFile(absolute, "utf8");
+  } catch {
+    throw new CliError(EXIT.invalid, `Cannot read configuration file ${path}.`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new CliError(EXIT.invalid, `${path} is not valid JSON: ${(error as Error).message}`);
+  }
+  const { valid, issues } = validateProjectConfig(parsed);
+  if (!valid) throw new CliError(EXIT.invalid, `${path} is invalid (${issues.length} issue${issues.length === 1 ? "" : "s"}):\n${formatIssues(issues)}`);
+  return { config: parsed as ProjectConfig, path: absolute };
+}
+
+async function loadHandlers(path: string | undefined): Promise<{ handlers: HandlerRegistry<never>; development: DevelopmentOptions | undefined }> {
+  if (path === undefined) throw new CliError(EXIT.invalid, "--handlers <module> is required.");
+  const absolute = resolve(path);
+  const extension = extname(absolute);
+  if ([".ts", ".tsx", ".mts", ".cts"].includes(extension)) {
+    throw new CliError(EXIT.invalid, `${path} is TypeScript. StreamOtter loads compiled JavaScript modules; compile your handlers and pass the .js output.`);
+  }
+  if (!existsSync(absolute)) throw new CliError(EXIT.invalid, `Handler module ${path} does not exist.`);
+  let module: Record<string, unknown>;
+  try {
+    module = await import(pathToFileURL(absolute).href) as Record<string, unknown>;
+  } catch (error) {
+    throw new CliError(EXIT.runtime, `Failed to load handler module ${path}: ${(error as Error).message}`);
+  }
+  if (typeof module["handlers"] !== "object" || module["handlers"] === null) {
+    throw new CliError(EXIT.invalid, `${path} must export \`handlers\` (a HandlerRegistry).`);
+  }
+  return {
+    handlers: module["handlers"] as HandlerRegistry<never>,
+    development: module["development"] as DevelopmentOptions | undefined
+  };
+}
+
+function cliLogger(io: CliIO): GatewayLogger {
+  const line = (level: string, message: string, fields?: Readonly<Record<string, Json>>) =>
+    `${new Date().toISOString()} ${level.padEnd(5)} ${message}${fields !== undefined && Object.keys(fields).length > 0 ? ` ${JSON.stringify(fields)}` : ""}`;
+  return {
+    info: (message, fields) => io.out(line("info", message, fields)),
+    warn: (message, fields) => io.err(line("warn", message, fields)),
+    error: (message, fields) => io.err(line("error", message, fields))
+  };
+}
+
+function workbenchDirectory(): string | null {
+  try {
+    const require = createRequire(import.meta.url);
+    const manifest = require.resolve("@streamotter/workbench/package.json");
+    const dir = join(dirname(manifest), "dist");
+    return existsSync(join(dir, "index.html")) ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+async function reportStartupFailure(io: CliIO, gateway: Gateway, error: unknown): Promise<never> {
+  io.err(`Gateway startup failed: ${(error as Error).message}`);
+  try {
+    for (const { sourceId, steps } of await getGatewayInternals(gateway).checkAllSources()) {
+      io.err(`Source "${sourceId}" diagnostics:`);
+      for (const step of steps) io.err(`  ${step.outcome === "ok" ? "✓" : step.outcome === "failed" ? "✗" : "-"} ${step.stage.padEnd(12)} ${step.message}`);
+    }
+  } catch {
+    // Diagnostics are best effort.
+  }
+  await gateway.stop({ timeoutMs: 2_000 }).catch(() => undefined);
+  const code = (error as { code?: string }).code;
+  throw new CliError(code === "CONFIG_INVALID" ? EXIT.invalid : EXIT.runtime, "The gateway did not start.");
+}
+
+async function runUntilSignal(io: CliIO, gateway: Gateway): Promise<number> {
+  const signal = await io.shutdownSignal;
+  io.out(`Received ${signal}; shutting down gracefully.`);
+  await gateway.stop({ timeoutMs: 10_000 });
+  return EXIT.ok;
+}
+
+async function commandInit(positionals: string[], io: CliIO): Promise<number> {
+  const directory = positionals[0];
+  if (directory === undefined || positionals.length > 1) throw new CliError(EXIT.invalid, "Usage: streamotter init <directory>");
+  const target = resolve(directory);
+  if (existsSync(target) && !(await stat(target)).isDirectory()) throw new CliError(EXIT.invalid, `${directory} exists and is not a directory.`);
+  const projectId = basename(target).replace(/[^A-Za-z0-9_-]/g, "-").replace(/^[^A-Za-z]+/, "") || "streamotter-app";
+  const files = scaffoldFiles(projectId.slice(0, 64));
+  const conflicts = files.filter(file => existsSync(join(target, file.path))).map(file => file.path);
+  if (conflicts.length > 0) throw new CliError(EXIT.invalid, `Refusing to overwrite existing files: ${conflicts.join(", ")}`);
+  for (const file of files) {
+    await mkdir(dirname(join(target, file.path)), { recursive: true });
+    await writeFile(join(target, file.path), file.content, { flag: "wx" });
+    io.out(`  created ${join(directory, file.path)}`);
+  }
+  io.out(`\nNext:\n  cd ${directory}\n  streamotter dev --config streamotter.json --handlers server/handlers.mjs`);
+  return EXIT.ok;
+}
+
+async function commandValidate(values: Record<string, unknown>, io: CliIO): Promise<number> {
+  const { config, path } = await loadConfig(values["config"] as string | undefined);
+  io.out(`${path} is valid.`);
+  io.out(`Fingerprint: sha256:${fingerprint(config)}`);
+  if (canonicalJsonPretty(config) !== await readFile(path, "utf8")) {
+    io.out("Note: the file is not in canonical form (workbench exports use sorted keys and two-space indentation); the fingerprint is unaffected.");
+  }
+  return EXIT.ok;
+}
+
+async function commandGenerate(values: Record<string, unknown>, io: CliIO): Promise<number> {
+  const { config } = await loadConfig(values["config"] as string | undefined);
+  const out = values["out"] as string | undefined;
+  if (out === undefined) throw new CliError(EXIT.invalid, "--out <directory> is required.");
+  const target = resolve(out);
+  const files = generateFiles(config);
+  const blocked: string[] = [];
+  for (const file of files) {
+    const path = join(target, file.path);
+    if (existsSync(path) && !(await readFile(path, "utf8")).startsWith(GENERATED_MARKER)) blocked.push(file.path);
+  }
+  if (blocked.length > 0) {
+    throw new CliError(EXIT.invalid, `Refusing to overwrite files that were not created by the generator: ${blocked.join(", ")}`);
+  }
+  await mkdir(target, { recursive: true });
+  for (const file of files) {
+    await writeFile(join(target, file.path), file.content);
+    io.out(`  wrote ${join(out, file.path)}`);
+  }
+  return EXIT.ok;
+}
+
+async function commandDev(values: Record<string, unknown>, io: CliIO): Promise<number> {
+  const { config, path } = await loadConfig(values["config"] as string | undefined);
+  const { handlers, development } = await loadHandlers(values["handlers"] as string | undefined);
+  const managementPort = values["management-port"] === undefined ? 7401 : Number(values["management-port"]);
+  if (!Number.isInteger(managementPort) || managementPort < 0 || managementPort > 65_535) throw new CliError(EXIT.invalid, "--management-port must be a port number.");
+  let gateway: Gateway;
+  try {
+    gateway = createGateway({
+      config, handlers, mode: "development", configDir: dirname(path), logger: cliLogger(io),
+      ...(development === undefined ? {} : { development })
+    });
+  } catch (error) {
+    throw new CliError(EXIT.invalid, (error as Error).message);
+  }
+  let address: { origin: string; path: string };
+  try {
+    address = await gateway.start();
+  } catch (error) {
+    return reportStartupFailure(io, gateway, error);
+  }
+  const workbenchDir = workbenchDirectory();
+  let management;
+  try {
+    management = await startManagementServer({ gateway, port: managementPort, workbenchDir });
+  } catch (error) {
+    await gateway.stop();
+    throw new CliError(EXIT.runtime, `The management server could not start: ${(error as Error).message}`);
+  }
+  const internals = getGatewayInternals(gateway);
+  io.out("");
+  io.out("StreamOtter development gateway");
+  io.out(`  Gateway      ${address.origin}  (Socket.IO path ${address.path})`);
+  io.out(`  Workbench    ${workbenchDir === null ? "(not built; run pnpm build)" : `${management.origin}/`}`);
+  io.out(`  Management   ${management.origin}/management/v1  (local only)`);
+  io.out(`  Token        ${management.token}`);
+  io.out(`  Config       ${path}  sha256:${internals.fingerprint.slice(0, 16)}…`);
+  io.out(`  Sources      ${internals.sources().map(source => `${source.sourceId} (${source.kind}, ${source.status})`).join(", ")}`);
+  const principals = development === undefined ? [] : Object.keys(development.principals ?? {});
+  io.out(`  Principals   ${principals.length === 0 ? "(none registered)" : principals.join(", ")}`);
+  io.out("");
+  io.out("Enter the token in the workbench. It is valid only for this run. Configuration edits in the");
+  io.out("workbench are candidates: export them and restart this command to apply. Press Ctrl+C to stop.");
+  return runUntilSignal(io, gateway);
+}
+
+async function commandStart(values: Record<string, unknown>, io: CliIO): Promise<number> {
+  const { config, path } = await loadConfig(values["config"] as string | undefined);
+  const { handlers } = await loadHandlers(values["handlers"] as string | undefined);
+  let gateway: Gateway;
+  try {
+    // The module's development export is deliberately ignored in production.
+    gateway = createGateway({ config, handlers, mode: "production", configDir: dirname(path), logger: cliLogger(io) });
+  } catch (error) {
+    throw new CliError(EXIT.invalid, (error as Error).message);
+  }
+  let address: { origin: string; path: string };
+  try {
+    address = await gateway.start();
+  } catch (error) {
+    return reportStartupFailure(io, gateway, error);
+  }
+  io.out(`StreamOtter gateway (production) listening on ${address.origin} path ${address.path}. No management or development endpoints are exposed.`);
+  return runUntilSignal(io, gateway);
+}
+
+/** Runs the CLI and returns its exit code: 0 success, 2 invalid input/configuration, 1 startup/runtime failure. */
+export async function runCli(argv: readonly string[], io: CliIO): Promise<number> {
+  const [command, ...rest] = argv;
+  if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+    io.out(USAGE);
+    return command === undefined ? EXIT.invalid : EXIT.ok;
+  }
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: [...rest],
+      allowPositionals: true,
+      strict: true,
+      options: {
+        config: { type: "string" },
+        handlers: { type: "string" },
+        out: { type: "string" },
+        "management-port": { type: "string" }
+      }
+    });
+  } catch (error) {
+    io.err(`${(error as Error).message}\n\n${USAGE}`);
+    return EXIT.invalid;
+  }
+  const { values, positionals } = parsed;
+  const allowed: Record<string, readonly string[]> = {
+    init: [], validate: ["config"], generate: ["config", "out"], dev: ["config", "handlers", "management-port"], start: ["config", "handlers"]
+  };
+  const permitted = allowed[command];
+  if (permitted === undefined) {
+    io.err(`Unknown command "${command}".\n\n${USAGE}`);
+    return EXIT.invalid;
+  }
+  const extra = Object.keys(values).filter(key => !permitted.includes(key));
+  if (extra.length > 0 || (command !== "init" && positionals.length > 0)) {
+    io.err(`Unexpected arguments for ${command}: ${[...extra.map(key => `--${key}`), ...(command === "init" ? [] : positionals)].join(" ")}\n\n${USAGE}`);
+    return EXIT.invalid;
+  }
+  try {
+    switch (command) {
+      case "init": return await commandInit(positionals, io);
+      case "validate": return await commandValidate(values, io);
+      case "generate": return await commandGenerate(values, io);
+      case "dev": return await commandDev(values, io);
+      case "start": return await commandStart(values, io);
+      default: return EXIT.invalid;
+    }
+  } catch (error) {
+    if (error instanceof CliError) {
+      io.err(error.message);
+      return error.exitCode;
+    }
+    io.err(`Unexpected failure: ${(error as Error).stack ?? String(error)}`);
+    return EXIT.runtime;
+  }
+}

package/src/generate.ts

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import { canonicalJson, type ProjectConfig, type Schema } from "@streamotter/contracts";
+
+export const GENERATED_MARKER = "// @generated by streamotter generate";
+
+const RESERVED = new Set([
+  "AppChannels", "ChannelContract", "Client", "Subscription", "Array", "Boolean", "Date", "Error", "Function", "JSON", "Map",
+  "Math", "Number", "Object", "Promise", "Record", "Set", "String", "Symbol"
+]);
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+export function fingerprint(config: unknown): string {
+  return createHash("sha256").update(canonicalJson(config)).digest("hex");
+}
+
+function pascalCase(id: string): string {
+  return id.split(/[-_]+/).filter(Boolean).map(part => part[0]!.toUpperCase() + part.slice(1)).join("");
+}
+
+/** Maps schema IDs to unique, valid, non-shadowing TypeScript type names. */
+export function typeNames(schemaIds: readonly string[]): Map<string, string> {
+  const names = new Map<string, string>();
+  const used = new Set<string>();
+  for (const id of schemaIds) {
+    let name = pascalCase(id);
+    if (RESERVED.has(name)) name = `${name}Schema`;
+    let candidate = name;
+    for (let suffix = 2; used.has(candidate); suffix++) candidate = `${name}${suffix}`;
+    used.add(candidate);
+    names.set(id, candidate);
+  }
+  return names;
+}
+
+function propertyKey(name: string): string {
+  return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+
+function describe(schema: Schema): string | null {
+  switch (schema.type) {
+    case "string": {
+      const parts = [];
+      if (schema.minLength !== undefined) parts.push(`minLength ${schema.minLength}`);
+      if (schema.maxLength !== undefined) parts.push(`maxLength ${schema.maxLength}`);
+      return parts.length > 0 ? parts.join(", ") : null;
+    }
+    case "number":
+    case "integer": {
+      const parts: string[] = [schema.type];
+      if (schema.minimum !== undefined) parts.push(`minimum ${schema.minimum}`);
+      if (schema.maximum !== undefined) parts.push(`maximum ${schema.maximum}`);
+      return schema.type === "integer" || parts.length > 1 ? parts.join(", ") : null;
+    }
+    case "array":
+      return `maxItems ${schema.maxItems}`;
+    default:
+      return null;
+  }
+}
+
+/** Renders a schema as a TypeScript type expression (type aliases, never interfaces, so values stay assignable to Json). */
+export function renderType(schema: Schema, indent = ""): string {
+  switch (schema.type) {
+    case "string":
+      return schema.enum !== undefined ? schema.enum.map(value => JSON.stringify(value)).join(" | ") : "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "array": {
+      const item = renderType(schema.items, indent);
+      return /[|&]/.test(item) && !item.startsWith("{") ? `(${item})[]` : `${item}[]`;
+    }
+    case "object": {
+      const entries = Object.entries(schema.properties);
+      if (entries.length === 0) return "Record<string, never>";
+      const inner = `${indent}  `;
+      const lines = entries.map(([name, child]) => {
+        const note = describe(child);
+        const comment = note === null ? "" : `${inner}/** ${note} */\n`;
+        const optional = schema.required.includes(name) ? "" : "?";
+        return `${comment}${inner}${propertyKey(name)}${optional}: ${renderType(child, inner)};`;
+      });
+      return `{\n${lines.join("\n")}\n${indent}}`;
+    }
+    default:
+      return "never";
+  }
+}
+
+export interface GeneratedFile { path: string; content: string }
+
+/**
+ * Generates the application channel contract (AppChannels with each channel's
+ * parameter type, payload type, and literal version) plus a vanilla TypeScript
+ * integration example. Numeric ranges and string lengths remain runtime checks.
+ */
+export function generateFiles(config: ProjectConfig): GeneratedFile[] {
+  const fp = fingerprint(config);
+  const header = `${GENERATED_MARKER} (config sha256:${fp}). Do not edit; rerun the generator.\n`;
+  const names = typeNames(Object.keys(config.schemas));
+  const schemaTypes = Object.entries(config.schemas).map(([id, schema]) =>
+    `/** Schema "${id}". */\nexport type ${names.get(id)} = ${renderType(schema)};`
+  );
+  const channels = Object.entries(config.channels).map(([name, channel]) =>
+    `  ${propertyKey(name)}: ChannelContract<${names.get(channel.paramsSchema)}, ${names.get(channel.payloadSchema)}, ${channel.version}>;`
+  );
+  const versions = Object.entries(config.channels).map(([name, channel]) => `  ${propertyKey(name)}: ${channel.version}`);
+  const types = [
+    header,
+    `import type { ChannelContract } from "@streamotter/client";`,
+    "",
+    ...schemaTypes.flatMap(block => [block, ""]),
+    `/** Channel contracts for createClient<AppChannels>(). Project "${config.projectId}". */`,
+    "export type AppChannels = {",
+    ...channels,
+    "};",
+    "",
+    "/** Deployed channel versions; subscribe requests must name them exactly. */",
+    "export const channelVersions = {",
+    versions.join(",\n"),
+    "} as const;",
+    ""
+  ].join("\n");
+
+  const [firstName, firstChannel] = Object.entries(config.channels)[0] ?? [];
+  const paramsSchema = firstChannel === undefined ? undefined : config.schemas[firstChannel.paramsSchema];
+  const exampleParams = paramsSchema?.type === "object"
+    ? `{ ${Object.entries(paramsSchema.properties).map(([key, schema]) =>
+      `${propertyKey(key)}: ${schema.type === "string" ? (schema.enum?.[0] !== undefined ? JSON.stringify(schema.enum[0]) : `"example"`) : schema.type === "boolean" ? "true" : "1"}`).join(", ")} }`
+    : "{}";
+  const example = firstName === undefined ? `${header}\nexport {};\n` : [
+    header,
+    `import { createClient, type StreamError, type SubscriptionState } from "@streamotter/client";`,
+    `import { channelVersions, type AppChannels } from "./streamotter.generated.js";`,
+    "",
+    "/**",
+    ` * Subscribes to "${firstName}" and returns a cleanup function. Replace render/showState/showError`,
+    " * with your view code. getToken must return your application's session token for the gateway.",
+    " */",
+    `export async function mount${pascalCase(firstName)}(options: {`,
+    "  origin: string;",
+    `  params: AppChannels[${JSON.stringify(firstName)}]["params"];`,
+    "  getToken: (signal: AbortSignal) => Promise<string>;",
+    `  render: (data: AppChannels[${JSON.stringify(firstName)}]["data"]) => void;`,
+    "  showState?: (state: SubscriptionState) => void;",
+    "  showError?: (error: StreamError) => void;",
+    "}): Promise<() => Promise<void>> {",
+    "  const client = createClient<AppChannels>({ origin: options.origin, getToken: ({ signal }) => options.getToken(signal) });",
+    `  const subscription = client.subscribe(${JSON.stringify(firstName)}, {`,
+    `    channelVersion: channelVersions[${JSON.stringify(firstName)}],`,
+    "    params: options.params",
+    "  });",
+    "  subscription.on(\"data\", event => options.render(event.data));",
+    "  subscription.on(\"state\", ({ state }) => options.showState?.(state));",
+    "  subscription.on(\"error\", error => options.showError?.(error));",
+    "  try {",
+    "    await subscription.ready({ timeoutMs: 30_000 });",
+    "  } catch (error) {",
+    "    await subscription.unsubscribe();",
+    "    await client.close();",
+    "    throw error;",
+    "  }",
+    "  return async () => {",
+    "    await subscription.unsubscribe();",
+    "    await client.close();",
+    "  };",
+    "}",
+    "",
+    `// Example: await mount${pascalCase(firstName)}({ origin: "http://localhost:${config.gateway.port}", params: ${exampleParams}, getToken, render });`,
+    ""
+  ].join("\n");
+
+  return [
+    { path: "streamotter.generated.ts", content: types },
+    { path: "streamotter.client.example.ts", content: example }
+  ];
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { EXIT, runCli, type CliIO } from "./cli.ts";
+export { fingerprint, generateFiles, GENERATED_MARKER, renderType, typeNames, type GeneratedFile } from "./generate.ts";
+export { scaffoldFiles } from "./templates.ts";

package/src/main.ts

@@ -0,0 +1,14 @@
+import { runCli } from "./cli.ts";
+
+const shutdownSignal = new Promise<string>(resolve => {
+  process.once("SIGINT", () => resolve("SIGINT"));
+  process.once("SIGTERM", () => resolve("SIGTERM"));
+});
+
+const code = await runCli(process.argv.slice(2), {
+  out: line => { process.stdout.write(`${line}\n`); },
+  err: line => { process.stderr.write(`${line}\n`); },
+  shutdownSignal
+});
+// Flush output, then exit even if a dependency left a handle open.
+process.stdout.write("", () => process.stderr.write("", () => process.exit(code)));

package/src/templates.ts

@@ -0,0 +1,163 @@
+/** Files created by `streamotter init`. The scaffold is fixture-only and has no production credentials. */
+export function scaffoldFiles(projectId: string): { path: string; content: string }[] {
+  const config = {
+    configVersion: 1,
+    projectId,
+    gateway: { host: "127.0.0.1", port: 7400, path: "/streamotter/socket.io", allowedOrigins: ["http://localhost:5173"] },
+    connections: {},
+    sources: { jobs: { kind: "fixture", generation: "jobs-fixture-1", fixtureRef: "jobs" } },
+    schemas: {
+      JobParams: {
+        type: "object", additionalProperties: false, required: ["jobId"],
+        properties: { jobId: { type: "string", minLength: 1, maxLength: 64 } }
+      },
+      JobProgress: {
+        type: "object", additionalProperties: false, required: ["jobId", "state", "percent"],
+        properties: {
+          jobId: { type: "string", minLength: 1, maxLength: 64 },
+          state: { type: "string", enum: ["queued", "running", "succeeded", "failed"] },
+          percent: { type: "integer", minimum: 0, maximum: 100 }
+        }
+      }
+    },
+    channels: {
+      jobProgress: {
+        version: 1, source: "jobs", paramsSchema: "JobParams", payloadSchema: "JobProgress",
+        handlersRef: "jobProgress", delivery: { kind: "state", overflow: "resync" }
+      }
+    }
+  };
+
+  const handlers = `// @ts-check
+/**
+ * Trusted server handlers for StreamOtter, loaded by:
+ *   streamotter dev --config streamotter.json --handlers server/handlers.mjs
+ *
+ * StreamOtter loads compiled JavaScript. If you write handlers in TypeScript,
+ * compile them first and point --handlers at the output.
+ */
+
+/**
+ * Development read model. Replace it with your application's authoritative store.
+ * Snapshots and mapped records must describe the same revision progression.
+ * @type {Map<string, { revision: string; data: { jobId: string; state: string; percent: number } }>}
+ */
+const jobs = new Map([
+  ["local/job_1", { revision: "1", data: { jobId: "job_1", state: "queued", percent: 0 } }]
+]);
+
+/** @type {import("@streamotter/gateway").HandlerRegistry<any>} */
+export const handlers = {
+  async authenticate({ token }) {
+    // TODO: verify your application's session token and return its Principal
+    // ({ subject, tenantId, sessionId, expiresAt, claims }), or null to reject it.
+    // Workbench previews use short-lived preview tokens resolved by the gateway itself,
+    // so this scaffold intentionally accepts no application tokens yet.
+    void token;
+    return null;
+  },
+  channels: {
+    jobProgress: {
+      async authorize({ principal, params }) {
+        return jobs.has(\`\${principal.tenantId}/\${params.jobId}\`);
+      },
+      map({ record }) {
+        const value = /** @type {{ tenantId: string; revision: string; job: { jobId: string; state: string; percent: number } }} */ (record.value);
+        // Development only: keep the in-memory read model in step with the fixture stream.
+        const key = \`\${value.tenantId}/\${value.job.jobId}\`;
+        const current = jobs.get(key);
+        if (current === undefined || BigInt(value.revision) > BigInt(current.revision)) {
+          jobs.set(key, { revision: value.revision, data: value.job });
+        }
+        return [{ tenantId: value.tenantId, params: { jobId: value.job.jobId }, revision: value.revision, data: value.job }];
+      },
+      async snapshot({ principal, params }) {
+        const job = jobs.get(\`\${principal.tenantId}/\${params.jobId}\`);
+        if (job === undefined) throw new Error("Unknown job");
+        return { revision: job.revision, data: job.data };
+      }
+    }
+  }
+};
+
+/** Development-only principals and fixture records. Never used by \`streamotter start\`. */
+export const development = {
+  principals: {
+    developer: { subject: "developer", tenantId: "local", sessionId: "dev-session", expiresAt: "2099-01-01T00:00:00.000Z", claims: {} }
+  },
+  fixtures: {
+    jobs: [
+      { key: "job_1", value: { tenantId: "local", revision: "2", job: { jobId: "job_1", state: "running", percent: 25 } } },
+      { key: "job_1", value: { tenantId: "local", revision: "3", job: { jobId: "job_1", state: "running", percent: 60 } } },
+      { key: "job_1", value: { tenantId: "local", revision: "4", job: { jobId: "job_1", state: "running", percent: 90 } } },
+      { key: "job_1", value: { tenantId: "local", revision: "5", job: { jobId: "job_1", state: "succeeded", percent: 100 } } }
+    ]
+  }
+};
+`;
+
+  const example = `import { createClient } from "@streamotter/client";
+import { channelVersions, type AppChannels } from "../generated/streamotter.generated.js";
+
+/**
+ * Renders one job's live progress. Run \`streamotter generate --config streamotter.json --out generated\`
+ * first. getToken must return your application's session token (or, during local development,
+ * a preview token from the workbench).
+ */
+export async function watchJob(jobId: string, getToken: () => Promise<string>, element: HTMLElement): Promise<() => Promise<void>> {
+  const client = createClient<AppChannels>({ origin: "http://localhost:7400", getToken: () => getToken() });
+  const job = client.subscribe("jobProgress", { channelVersion: channelVersions.jobProgress, params: { jobId } });
+  job.on("data", ({ data, revision }) => {
+    element.textContent = \`\${data.state} — \${data.percent}% (revision \${revision})\`;
+  });
+  job.on("state", ({ state }) => {
+    element.dataset["delivery"] = state; // "live" means synchronized; anything else may be stale.
+  });
+  job.on("error", error => console.warn(\`[\${error.code}] \${error.message}\`));
+  await job.ready();
+  return async () => {
+    await job.unsubscribe();
+    await client.close();
+  };
+}
+`;
+
+  const readme = `# ${projectId}
+
+A StreamOtter V1 project created by \`streamotter init\`. It uses a deterministic fixture source,
+so no Kafka broker is needed to start.
+
+## Run locally
+
+\`\`\`bash
+streamotter validate --config streamotter.json
+streamotter dev --config streamotter.json --handlers server/handlers.mjs
+\`\`\`
+
+\`dev\` prints the workbench URL and a one-time management token. In the workbench, create a
+preview session for the \`developer\` principal, subscribe to \`jobProgress\` with \`{"jobId": "job_1"}\`,
+and advance the \`jobs\` fixture to watch revisions arrive.
+
+## Integrate
+
+\`\`\`bash
+streamotter generate --config streamotter.json --out generated
+\`\`\`
+
+\`generated/streamotter.generated.ts\` contains \`AppChannels\`; \`web/example.ts\` shows a subscription
+with cleanup and error handling.
+
+## Before production
+
+- Implement \`authenticate\` in \`server/handlers.mjs\` with your real session verification.
+- Replace the in-memory read model with your authoritative store.
+- Replace the fixture source with a Kafka source using TLS; \`streamotter start\` rejects fixtures and plaintext Kafka.
+`;
+
+  return [
+    { path: "streamotter.json", content: `${JSON.stringify(config, null, 2)}\n` },
+    { path: "server/handlers.mjs", content: handlers },
+    { path: "web/example.ts", content: example },
+    { path: "README.md", content: readme }
+  ];
+}