babavoss 0.0.1 → 0.12.0

package/index.ts

@@ -0,0 +1,15 @@
+// babavoss: the framework. What a baba imports.
+export { baba, effect, source, accept, resource, shape, manifestOf, isBaba, isSystem, nameOf, SYSTEM } from "./src/ecs/baba.ts";
+export { system, declare, part } from "./src/ecs/system.ts";
+export type { Decl, Entry, Handles, HandlesOf, Building, Maker, Part, Piece, Maybe, StepPiece, OnPiece, ActionPiece, QueryPiece, BindingOf, Scope, Reader, StateOf, ReaderOf, Act, Read } from "./src/ecs/system.ts";
+export { not, added, changed, removed, select } from "./src/ecs/state.ts";
+export type { AcceptDef, System, SystemData, Contract, ActOf, ReadOf, Refs, Baba, AppSpec, RoutesOf, Step, ActionDef, ResourceDef, EffectDef, QueryDef, SkillDef, Manifest, Call, Calls, Shape, SchemaOf, Of } from "./src/ecs/baba.ts";
+export { route, matchRoute, type RouteParams, type RouteMatch } from "./src/desktop/routes.ts";
+export { State, StateError } from "./src/ecs/state.ts";
+export type { Entity, Component, Ask, Resource, Effect, Value, Args, Result, EventOf, MirrorEvent, Row, Values, Done, Failed, Job, Snapshot, Model, Not, Change, Select, Term } from "./src/ecs/state.ts";
+export type { Delta, StateAnswer } from "./src/ecs/snapshot.ts";
+export { applyDelta, isDelta } from "./src/ecs/snapshot.ts";
+export { s, SchemaError, OPTIONAL } from "./src/kernel/schema.ts";
+// Optional and ObjectOf are named by the types a system or spec exports: a baba that installs babavoss must be able to name them too.
+export type { Schema, Infer, Optional, ObjectOf, Json } from "./src/kernel/schema.ts";
+export type { Context, Fs, Http, Exec, ExecOptions, ExecEvent, Secrets, BabaConfig } from "./src/kernel/context.ts";

package/package.json

@@ -1,8 +1,54 @@
 {
   "name": "babavoss",
-  "version": "0.0.1",
-  "description": "Baba Voss: a project's own program, run by voss. Coming soon.",
+  "version": "0.12.0",
+  "license": "Apache-2.0",
+  "repository": "github:alanremarc/babavoss",
   "homepage": "https://babavoss.org",
-  "author": "Alan Remarc",
-  "license": "Apache-2.0"
+  "description": "A framework for a project's OS: one application fitted to one project. TypeScript on Bun.",
+  "type": "module",
+  "bin": {
+    "voss": "bin/voss.ts"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./web": "./src/web/index.tsx",
+    "./test": "./src/test/index.ts",
+    "./bench": "./src/bench/index.ts",
+    "./prompt": "./src/prompt/index.ts",
+    "./prompt/jsx-runtime": "./src/prompt/jsx-runtime.ts",
+    "./prompt/jsx-dev-runtime": "./src/prompt/jsx-dev-runtime.ts",
+    "./desktop": "./src/desktop/index.ts",
+    "./kit": "./src/kit/index.ts",
+    "./spec": "./src/spec/index.ts",
+    "./prompt/register": "./src/build/mdx-register.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "gui",
+    "index.ts",
+    "NOTICE"
+  ],
+  "engines": {
+    "bun": ">=1.4"
+  },
+  "scripts": {
+    "voss": "bun bin/voss.ts",
+    "test": "bun test",
+    "check": "bunx tsc --noEmit -p ../..",
+    "prepack": "bun ../../tools/release/pack.ts prepack",
+    "postpack": "bun ../../tools/release/pack.ts postpack"
+  },
+  "devDependencies": {
+    "@types/react-dom": "19"
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "@types/bun": "^1.4.2",
+    "@types/react": "19",
+    "react": "19",
+    "react-dom": "19",
+    "remark-gfm": "^4.0.1",
+    "typescript": "^7"
+  }
 }

package/src/baba/check.ts

@@ -0,0 +1,90 @@
+import { bundleProject } from "../build/project.ts";
+// voss baba check: the TypeScript checker over the project, once per
+// config voss wrote (the backend and the views), with a hint under each
+// error that names a guarded global or module.
+import { dirname, join } from "node:path";
+import { viewsConfigPath, writeEditorConfig } from "./config.ts";
+import { advice, forbiddenGlobals, forbiddenModules } from "../build/guard.ts";
+import type { Project } from "./project.ts";
+
+// The checker's colors, removed only to read its lines.
+const ansi = /\x1b\[[0-9;]*m/g;
+
+// What an error line says when it hits the guard: a guard type's name, or a forbidden module in quotes.
+const hints: [string, string][] = [
+  ...Object.values(forbiddenGlobals).map((r) => [`'${r.type}'`, advice(r)] as [string, string]),
+  ...Object.values(forbiddenModules).map((r) => [`'${r.type}'`, advice(r)] as [string, string]),
+  ...Object.entries(forbiddenModules).map(([spec, r]) => [`"${spec}"`, `${spec}: ${advice(r)}`] as [string, string]),
+];
+
+/** The checker's output with a hint line under each error message that names the guard. */
+export function annotate(out: string): string {
+  return out.split("\n").map((line) => {
+    const plain = line.replace(ansi, "");
+    if (/^\d+ /.test(plain)) return line; // a line of the source under the message
+    const hit = hints.find(([needle]) => plain.includes(needle));
+    return hit ? `${line}\n  hint: ${hit[1]}` : line;
+  }).join("\n");
+}
+
+/** One diagnostic of the checker's pretty output: its file (empty for a config error) and its text. */
+export interface Diagnostic { file: string; text: string }
+
+/** Splits the checker's pretty output into diagnostics, leaving out its closing count. */
+export function diagnostics(out: string): Diagnostic[] {
+  const found: Diagnostic[] = [];
+  for (const line of out.split("\n")) {
+    const plain = line.replace(ansi, "");
+    if (/^Found \d+ errors?\b/.test(plain)) break;
+    const head = /^(?:(.+?):\d+:\d+ - )?error TS\d+:/.exec(plain);
+    if (head) found.push({ file: head[1] ?? "", text: line });
+    else if (found.length) found[found.length - 1]!.text += "\n" + line;
+  }
+  return found.map((d) => ({ file: d.file, text: d.text.replace(/\n+$/, "") }));
+}
+
+// The project's own .ts files belong to the backend program, which reports
+// them; the views program sees them through a view's imports and would
+// report the same errors twice.
+const backendFile = (file: string) => /\.[cm]?ts$/.test(file) && !file.endsWith(".d.ts") && !file.includes("node_modules/") && !file.startsWith("..");
+
+export async function check(p: Project, stdout: (s: string) => void, stderr: (s: string) => void): Promise<number> {
+  const backend = await writeEditorConfig(p);
+  // The checker: the project's, else the one the framework carries.
+  let tsc: string | null = null;
+  for (const from of [p.baba, import.meta.dir]) {
+    try { tsc = join(dirname(Bun.resolveSync("typescript/package.json", from)), "bin", "tsc"); break; } catch { /* next */ }
+  }
+  if (!tsc) { stderr(`voss: no typescript for ${p.baba}; run \`voss baba install\`\n`); return 1; }
+  // An editor finds the project's tsconfig.json; views belong to the program it references.
+  const root = await Bun.file(join(p.baba, "tsconfig.json")).text().catch(() => "");
+  if (!root.includes("tsconfig.views.json")) stderr(`voss: ${p.baba}/tsconfig.json does not reference ./.voss/tsconfig.views.json, so an editor checks views without it; add "references": [{ "path": "./.voss/tsconfig.views.json" }]\n`);
+  let failed = false;
+  // The one runner of the specs: bun test finds it, and through it every systems/NAME/spec.ts.
+  if (!(await Bun.file(join(p.baba, "spec.test.ts")).exists())) { stdout(`specs: .baba/spec.test.ts is missing; it is one line, \`await proveAll(import.meta.dir);\` with proveAll from babavoss/test, so bun test proves every spec\n`); failed = true; }
+  for (const [name, config] of [["backend", backend], ["views", viewsConfigPath(p)]] as const) {
+    const proc = Bun.spawn([process.execPath, tsc, "--noEmit", "--pretty", "-p", config], { cwd: p.baba, env: { ...process.env, BUN_BE_BUN: "1" }, stdout: "pipe", stderr: "pipe" });
+    const [out, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+    const all = diagnostics(out);
+    // The views program reaches the backend's files and the framework's source; each is checked under its own program,
+    // except what only a declaration emit finds: a type an editor cannot name (TS2742, TS2883), which the backend program never emits.
+    const emitOnly = (d: Diagnostic) => /error TS(2742|2883):/.test(d.text.replace(ansi, ""));
+    const found = name === "views" ? all.filter((d) => (!backendFile(d.file) || emitOnly(d)) && !d.file.startsWith("..") && !d.file.includes("node_modules/")) : all;
+    if (code === 0 || (all.length > 0 && found.length === 0)) { stdout(`${name}: clean\n`); continue; }
+    failed = true;
+    if (!found.length) {
+      // Output the parser does not know: shown whole.
+      stdout(`${name}: failed\n`);
+      if (out) stdout(annotate(out));
+    } else {
+      stdout(`${name}: ${found.length} ${found.length === 1 ? "error" : "errors"}\n\n${found.map((d) => annotate(d.text)).join("\n\n")}\n\n`);
+    }
+    if (err) stderr(err);
+  }
+  const mdx = [...new Bun.Glob("promptware/**/*.mdx").scanSync({ cwd: p.baba })];
+  if (mdx.length) {
+    try { await bundleProject(p); stdout("promptware MDX: clean\n"); }
+    catch (error) { failed = true; stderr(`promptware MDX: ${String(error)}\n`); }
+  }
+  return failed ? 1 : 0;
+}

package/src/baba/config.ts

@@ -0,0 +1,261 @@
+// What voss writes into a project's .baba: the editor config the one-line
+// tsconfig.json extends, the views config and the guard, regenerated on
+// every load and never edited.
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import type { Project } from "./project.ts";
+import { advice, forbiddenGlobals, forbiddenModules, type Refusal } from "../build/guard.ts";
+
+export const VOSS = ".voss";
+
+// Two programs, because TypeScript has one lib per program. By convention
+// a .ts file is backend (the entry, the systems and what they import) and a
+// .tsx file is the view and what it imports: the backend sees ECMAScript
+// and the guard, the view sees ECMAScript and the DOM. Neither sees Bun or
+// Node types. A helper the view shares with nothing backend is written as .tsx.
+
+const options = {
+  target: "ESNext",
+  module: "Preserve",
+  moduleResolution: "bundler",
+  moduleDetection: "force",
+  allowImportingTsExtensions: true,
+  verbatimModuleSyntax: true,
+  noEmit: true,
+  strict: true,
+  skipLibCheck: true,
+  noUncheckedIndexedAccess: true,
+  types: [],
+};
+
+/** `@/` is the .baba root: how an app reaches the kit, `@/ui/button`. The views program states it relative to .voss/; the project's own tsconfig.json states it relative to .baba. */
+const alias = { "@/*": ["../*"] };
+
+const note = "Written by voss on every load. Edit .baba/tsconfig.json to extend it, not this file.";
+
+/** The backend config, .voss/tsconfig.json: ECMAScript, the guard, every .ts of the project. */
+export function editorConfig(): string {
+  return JSON.stringify({
+    "//": note,
+    // JSX is React's unless a file says otherwise: promptware, TSX that renders to Markdown, names its runtime with a pragma.
+    // No alias here: the project's tsconfig.json, which extends this, states `@/` relative to itself, and tools that read it resolve it there.
+    compilerOptions: { lib: ["ESNext"], ...options, jsx: "react-jsx", jsxImportSource: "react" },
+    include: ["guard.d.ts", "assets.d.ts", "../**/*.ts"],
+    // Tests run under bun test, with its own globals; they are not backend code.
+    exclude: ["../node_modules/**", "../.voss/types/**", "../**/*.test.ts"],
+  }, null, 2) + "\n";
+}
+
+/**
+ * The views config, .voss/tsconfig.views.json: ECMAScript and the DOM, JSX
+ * for React, every .tsx of the project. Composite, since the project's
+ * tsconfig.json references it: that is how an editor finds the program a
+ * view belongs to. Declarations it would emit go under .voss/types.
+ */
+export function viewsConfig(): string {
+  const { noEmit: _, ...rest } = options;
+  // The whole DOM: a view runs in the browser, whose sandbox is its own.
+  return JSON.stringify({
+    "//": note,
+    compilerOptions: { lib: ["ESNext", "DOM", "DOM.Iterable"], ...rest, jsx: "react-jsx", jsxImportSource: "react", paths: alias, composite: true, declaration: true, emitDeclarationOnly: true, rootDir: "..", outDir: "./types/views" },
+    // A composite program lists every file it reaches: the backend modules a view imports types from too.
+    include: ["assets.d.ts", "../**/*.ts", "../**/*.tsx"],
+    exclude: ["../node_modules/**", "../.voss/types/**", "../**/*.test.ts", "../**/*.test.tsx"],
+  }, null, 2) + "\n";
+}
+
+const doc = (s: string) => `/** ${s} */`;
+const quote = (s: string) => JSON.stringify(s);
+
+/**
+ * .voss/guard.d.ts: the backend's state. A forbidden global or module has
+ * a type whose name and only member say the alternative, so the checker's
+ * error names it; the few pure Web APIs the runtime has are declared.
+ */
+export function guardDeclarations(): string {
+  const types = new Map<string, Refusal>();
+  for (const r of [...Object.values(forbiddenGlobals), ...Object.values(forbiddenModules)]) types.set(r.type, r);
+  const lines = [
+    "// Written by voss on every load: what a baba's backend sees beyond ECMAScript.",
+    "// A baba has no OS; an effect's context is its door. See README.md.",
+    "",
+    ...[...types].map(([name, r]) => `${doc(advice(r))}\ninterface ${name} { readonly ${quote(advice(r))}: never }`),
+    "",
+    ...Object.entries(forbiddenGlobals).map(([name, r]) => `${doc(`Not in a baba: ${advice(r)}`)}\ndeclare var ${name}: ${r.type};`),
+    "",
+    ...Object.entries(forbiddenModules).map(([spec, r]) =>
+      `${doc(`${spec} is not for a baba: ${advice(r)}`)}\ndeclare module ${quote(spec)} {\n  ${doc(advice(r))}\n  const denied: ${r.type};\n  export = denied;\n}`),
+    "",
+    pure,
+  ];
+  return lines.join("\n");
+}
+
+// The Web APIs of the runtime that are computation, not the OS. ECMAScript
+// has none of them; the DOM lib would bring fetch and document with them.
+const pure = `interface Console {
+  log(...data: unknown[]): void;
+  info(...data: unknown[]): void;
+  warn(...data: unknown[]): void;
+  error(...data: unknown[]): void;
+  debug(...data: unknown[]): void;
+}
+declare var console: Console;
+
+declare function setTimeout(handler: (...args: unknown[]) => void, timeout?: number, ...args: unknown[]): number;
+declare function clearTimeout(id: number | undefined): void;
+declare function setInterval(handler: (...args: unknown[]) => void, timeout?: number, ...args: unknown[]): number;
+declare function clearInterval(id: number | undefined): void;
+declare function queueMicrotask(callback: () => void): void;
+declare function structuredClone<T>(value: T): T;
+declare function atob(data: string): string;
+declare function btoa(data: string): string;
+
+/** Cancellation, as the context's signal: aborted when the caller cancels a call. */
+declare class AbortSignal {
+  readonly aborted: boolean;
+  readonly reason: unknown;
+  throwIfAborted(): void;
+  addEventListener(type: "abort", listener: () => void, options?: { once?: boolean }): void;
+  removeEventListener(type: "abort", listener: () => void): void;
+  static abort(reason?: unknown): AbortSignal;
+  static timeout(ms: number): AbortSignal;
+}
+declare class AbortController {
+  readonly signal: AbortSignal;
+  abort(reason?: unknown): void;
+}
+
+declare class TextEncoder {
+  readonly encoding: string;
+  encode(input?: string): Uint8Array;
+}
+declare class TextDecoder {
+  constructor(label?: string, options?: { fatal?: boolean; ignoreBOM?: boolean });
+  readonly encoding: string;
+  decode(input?: ArrayBuffer | ArrayBufferView, options?: { stream?: boolean }): string;
+}
+
+declare class URLSearchParams {
+  constructor(init?: string | Record<string, string> | [string, string][] | URLSearchParams);
+  readonly size: number;
+  append(name: string, value: string): void;
+  delete(name: string, value?: string): void;
+  get(name: string): string | null;
+  getAll(name: string): string[];
+  has(name: string, value?: string): boolean;
+  set(name: string, value: string): void;
+  sort(): void;
+  toString(): string;
+  entries(): IterableIterator<[string, string]>;
+  keys(): IterableIterator<string>;
+  values(): IterableIterator<string>;
+  forEach(callback: (value: string, key: string, parent: URLSearchParams) => void): void;
+  [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+declare class URL {
+  constructor(url: string | URL, base?: string | URL);
+  static canParse(url: string | URL, base?: string | URL): boolean;
+  static parse(url: string | URL, base?: string | URL): URL | null;
+  hash: string;
+  host: string;
+  hostname: string;
+  href: string;
+  readonly origin: string;
+  password: string;
+  pathname: string;
+  port: string;
+  protocol: string;
+  search: string;
+  readonly searchParams: URLSearchParams;
+  username: string;
+  toString(): string;
+  toJSON(): string;
+}
+
+interface Crypto {
+  getRandomValues<T extends ArrayBufferView | null>(array: T): T;
+  randomUUID(): \`\${string}-\${string}-\${string}-\${string}-\${string}\`;
+}
+declare var crypto: Crypto;
+
+interface Performance { now(): number; readonly timeOrigin: number }
+declare var performance: Performance;
+`;
+
+/** Files a view imports for their URL: the bundler emits them beside the view and the import is the URL. */
+const urlAssets = ["png", "jpg", "jpeg", "gif", "webp", "avif", "svg", "ico", "woff", "woff2", "ttf", "otf", "mp3", "mp4", "webm", "wasm"];
+
+/**
+ * .voss/assets.d.ts, for both programs: what a baba imports besides
+ * code. Text files as text, stylesheets for their effect, CSS modules as
+ * their class names, and images, fonts and media as the URL they are
+ * served at beside the view.
+ */
+export function assetDeclarations(): string {
+  return [
+    "// Written by voss on every load: what a baba imports besides code.",
+    "// Text: `import guide from \"./guide.md\" with { type: \"text\" }`.",
+    ...["md", "txt"].map((ext) => `declare module "*.${ext}" {\n  const text: string;\n  export default text;\n}`),
+    `declare module "*.mdx" { const prompt: import("babavoss/prompt").Prompt; export default prompt; }`,
+    "// Every spec of the baba, found where it lives (systems/NAME/spec.ts, spec.ts): what the Maker's page runs.",
+    `declare module "babavoss:specs" { const specs: import("babavoss/spec").Spec<any, any>[]; export default specs; }`,
+    "// A stylesheet, bundled with the view and attached to its windows: `import \"./view.css\"`.",
+    `declare module "*.module.css" {\n  const classes: Record<string, string>;\n  export default classes;\n}`,
+    `declare module "*.css" {}`,
+    "// A file served beside the view; the import is its URL: `import pic from \"./pic.png\"`.",
+    ...urlAssets.map((ext) => `declare module "*.${ext}" {\n  const url: string;\n  export default url;\n}`),
+    "",
+  ].join("\n");
+}
+
+async function put(path: string, want: string): Promise<void> {
+  const f = Bun.file(path);
+  if (!(await f.exists()) || (await f.text()) !== want) await Bun.write(path, want);
+}
+
+/** The configs voss writes, by file name under .baba/.voss. */
+export function configs(): Record<string, string> {
+  return { "tsconfig.json": editorConfig(), "tsconfig.views.json": viewsConfig(), "guard.d.ts": guardDeclarations(), "assets.d.ts": assetDeclarations() };
+}
+
+/** Writes .baba/.voss/tsconfig.json, tsconfig.views.json, guard.d.ts and assets.d.ts where they differ from what voss would write; returns the backend config's path. */
+export async function writeEditorConfig(p: Project): Promise<string> {
+  await moveOldDir(p);
+  const dir = join(p.baba, VOSS);
+  await mkdir(dir, { recursive: true });
+  for (const [name, want] of Object.entries(configs())) await put(join(dir, name), want);
+  return join(dir, "tsconfig.json");
+}
+
+/**
+ * Voss's files lived in .baba/state until the baba's state took the name: a
+ * project that still has it is moved once, and the lines of its own
+ * tsconfig.json and .gitignore that pointed there follow.
+ */
+export async function moveOldDir(p: Project): Promise<void> {
+  const old = join(p.baba, "state");
+  if (!existsSync(old) || existsSync(join(p.baba, VOSS))) return;
+  await rename(old, join(p.baba, VOSS));
+  const follow = async (name: string, from: RegExp, to: string) => {
+    const file = join(p.baba, name);
+    const text = await readFile(file, "utf8").catch(() => null);
+    if (text !== null && from.test(text)) await writeFile(file, text.replace(from, to));
+  };
+  await follow("tsconfig.json", /\.\/state\//g, `./${VOSS}/`);
+  await follow(".gitignore", /^state$/m, VOSS);
+}
+
+/** The views config's path, beside the backend one. */
+export function viewsConfigPath(p: Project): string {
+  return join(p.baba, VOSS, "tsconfig.views.json");
+}
+
+/** The files `voss init` writes beside the entry. */
+export const scaffold = {
+  // The editor finds this file; the backend program is its own, the views program is reached through the reference.
+  // The alias is stated here too, relative to .baba: tools that read only the project's own file, shadcn's CLI among them, find it where they look.
+  tsconfig: `{ "extends": "./${VOSS}/tsconfig.json", "compilerOptions": { "paths": { "@/*": ["./*"] } }, "references": [{ "path": "./${VOSS}/tsconfig.views.json" }] }\n`,
+  gitignore: `node_modules\n${VOSS}\n.env.local\n`,
+};

package/src/baba/find.ts

@@ -0,0 +1,12 @@
+// The nearest project: the closest directory at or above `from` with .baba/package.json.
+import { dirname, join } from "node:path";
+
+export async function findProject(from: string): Promise<string | null> {
+  let dir = from;
+  for (;;) {
+    if (await Bun.file(join(dir, ".baba", "package.json")).exists()) return dir;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}

package/src/baba/init.ts

@@ -0,0 +1,176 @@
+// voss init: a .baba in a directory, its dependencies installed. One entry,
+// one interface, one system to start from, and the promptware: what the baba tells
+// agents, as code, versioned with the project.
+import { basename, join, resolve } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { scaffold } from "./config.ts";
+import { kitDependencies, kitFiles } from "../kit/index.ts";
+import { exists, PAGE_WORDS } from "./project.ts";
+
+export interface InitOptions {
+  name?: string;
+  title?: string;
+  /** What package.json says for babavoss: a version, or link:babavoss from source. */
+  framework: string;
+  /** More dependencies to write: from source, the types the linked framework does not carry over. */
+  extra?: Record<string, string>;
+  install?: boolean;
+}
+
+export async function init(dir: string, o: InitOptions): Promise<{ name: string; dir: string }> {
+  dir = resolve(dir);
+  const baba = join(dir, ".baba");
+  if (await exists(join(baba, "package.json"))) throw new Error(`${dir} already has a .baba`);
+  const name = o.name ?? basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error(`name ${JSON.stringify(name)}: lowercase letters, digits and dashes; give --name`);
+  if (PAGE_WORDS.has(name)) throw new Error(`name ${name}: the page's own address; give --name`);
+  await mkdir(join(baba, "systems", "hello"), { recursive: true });
+  const pkg = {
+    name,
+    private: true,
+    type: "module",
+    baba: { title: o.title ?? name },
+    dependencies: { babavoss: o.framework, ...kitDependencies, ...(o.extra ?? {}) },
+  };
+  await Bun.write(join(baba, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+  await Bun.write(join(baba, "tsconfig.json"), scaffold.tsconfig);
+  await Bun.write(join(baba, ".gitignore"), scaffold.gitignore);
+  await Bun.write(join(baba, "index.ts"), entry);
+  await Bun.write(join(baba, "interface.tsx"), viewFile);
+  // The kit: shadcn's config, the bridge over voss's theme, the class helper; components arrive through the kit system, ui-add.
+  for (const [file, text] of Object.entries(kitFiles)) await Bun.write(join(baba, file), text);
+  await Bun.write(join(baba, "systems", "hello", "index.ts"), systemFile("hello"));
+  await Bun.write(join(baba, "systems", "hello", "spec.ts"), systemSpecFile("hello"));
+  await Bun.write(join(baba, "spec.test.ts"), specRunnerFile);
+  await Bun.write(join(baba, "promptware", "index.ts"), promptwareFile(o.title ?? name));
+  if (o.install !== false) await install(baba);
+  return { name, dir };
+}
+
+/** Bun's installer, run by the Bun that runs voss. */
+export async function install(baba: string): Promise<void> {
+  // Its output is kept, not shown: the shell's stdout and stderr carry one line each; a failure says what it printed last.
+  const p = Bun.spawn([process.execPath, "install"], { cwd: baba, env: { ...process.env, BUN_BE_BUN: "1" }, stdout: "pipe", stderr: "pipe" });
+  const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited]);
+  if (code !== 0) throw new Error(`bun install failed in ${baba}: ${(err || out).trim().split("\n").slice(-5).join("; ")}`);
+}
+
+/** The promptware: what the baba tells agents, as code. The contract is not here: agents get it at `voss baba`. */
+export const promptwareFile = (title: string) => `import { context, md } from "babavoss/prompt";
+
+// What this baba tells agents: its section of the context file, its skills
+// (one skill(...) per .tsx beside this file), its hooks. Code, rendered to
+// Markdown and compiled by voss into CLAUDE.md and the skills.
+export default [
+  context(md\`
+    ${title.replaceAll("\\", "\\\\").replaceAll("`", "\\`").replaceAll("$", "\\$")}: say here what this project is, in a sentence or two.
+
+    How to work on it: the conventions, the checks to run before a commit, what not to touch.
+
+    ## Rules
+
+    - Keep the tests green on every commit.
+  \`),
+];
+`;
+
+/** The entry: the baba, its systems listed, its promptware; `harness` for which harnesses get the files. */
+export const entry = `import { baba } from "babavoss";
+import { kit } from "babavoss/kit";
+import hello from "./systems/hello/index.ts";
+import promptware from "./promptware/index.ts";
+
+// kit keeps the baba's components, under ui/, as objects: \`voss baba ui\` lists them, \`ui-add\` brings more from shadcn.
+// The apps voss's shell offers; interface.tsx gives each its component.
+export default baba({ systems: [hello, kit], apps: [{ key: "hello", title: "Hello", icon: "hand" }], promptware });
+`;
+
+/** A system: a data model, one action, one query, written as one expression: the declaration, then its pieces made from it. */
+export const systemFile = (name: string, v = declared(name)) => `import { system, s } from "babavoss";
+
+export default system({
+  name: ${JSON.stringify(name)},
+  model: {
+    greeting: { text: s.string(), at: s.integer() },
+  },
+}, (${v}, p) => [
+  p.action("say", {
+    summary: "greet someone",
+    args: { name: s.string(), loud: s.optional(s.boolean()) },
+    positional: ["name"],
+    result: s.object({ entity: s.entity(), text: s.string() }),
+    run: (w, { name, loud }) => {
+      const text = loud ? \`Hello, \${name}!\`.toUpperCase() : \`Hello, \${name}!\`;
+      return { entity: w.spawn(${v}.greeting, { text, at: w.now }), text };
+    },
+  }),
+
+  p.query("greetings", {
+    summary: "every greeting, oldest first",
+    result: s.array(s.object({ text: s.string(), at: s.integer() })),
+    read: (w) => w.query(${v}.greeting).map((r) => r.greeting),
+  }),
+]);
+`;
+/** A system's spec, beside it: the system and the systems it reads, and a first scenario. */
+export const systemSpecFile = (name: string, v = declared(name)) => `import { spec } from "babavoss/spec";
+import ${v} from "./index.ts";
+
+export default spec(${v}, {
+  scenarios: [{
+    name: "a greeting is kept",
+    intent: "someone greeted is in the greetings, in the words they were greeted with",
+    script: ({ fire, tick, check }) => [
+      fire("say", { name: "Ada" }),
+      tick(),
+      check("Ada is greeted", (t) => t.read("greetings").map((g) => g.text), ["Hello, Ada!"]),
+    ],
+  }],
+});
+`;
+
+/** The one runner of the baba's specs: bun test finds it, and it proves every systems/NAME/spec.ts and spec.ts. */
+export const specRunnerFile = `// Every spec of this baba under bun test: each system's systems/NAME/spec.ts,
+// the whole baba's spec.ts, and the scenarios saved beside them. Verdicts land
+// in .voss/spec, where the Maker shows them.
+import { proveAll } from "babavoss/test";
+
+await proveAll(import.meta.dir);
+`;
+
+/** A system's name as the template's name for the system inside its pieces: dashes become camel case; one the template or JavaScript already uses gets "System" after it. */
+const TAKEN = new Set(["s", "p", "w", "r", "system", "name", "loud", "text", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "import", "in", "instanceof", "new", "null", "return", "super", "switch", "this", "throw", "true", "try", "typeof", "var", "void", "while", "with", "yield", "let", "static", "await"]);
+const declared = (name: string) => { const v = name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase()); return TAKEN.has(v) ? `${v}System` : v; };
+
+/** The interface: a component for each app, here the state, live, and the actions. */
+export const viewFile = `import { useState } from "react";
+import { compose, useBabaState, Button, Input } from "babavoss/web";
+import "./ui.css";
+import baba from "./index.ts";
+import hello from "./systems/hello/index.ts";
+
+function Hello() {
+  const { w, fire, ready } = useBabaState(baba);
+  const [name, setName] = useState("World");
+  return (
+    <main style={{ maxWidth: 640, margin: "0 auto", padding: 24 }}>
+      <h1>{ready ? "Hello" : "…"}</h1>
+      <p><Input value={name} onChange={(e) => setName(e.target.value)} /> <Button onClick={() => void fire("say", { name })}>Say</Button></p>
+      <ul>{w.query(hello.greeting).map((r) => <li key={r.entity}>{r.greeting.text}</li>)}</ul>
+    </main>
+  );
+}
+
+export default compose<typeof baba>({ apps: { hello: Hello } });
+`;
+
+/** voss baba add-system: a system under .baba/systems/NAME, to be listed in the entry. */
+export async function addSystem(baba: string, name: string): Promise<{ name: string; dir: string; next: string }> {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error(`system name ${JSON.stringify(name)}: lowercase letters, digits and dashes`);
+  const dir = join(baba, "systems", name);
+  if (await exists(dir)) throw new Error(`${dir} already exists`);
+  await mkdir(dir, { recursive: true });
+  await Bun.write(join(dir, "index.ts"), systemFile(name));
+  await Bun.write(join(dir, "spec.ts"), systemSpecFile(name));
+  return { name, dir, next: `import it in ${join(baba, "index.ts")} and list it in baba({ systems: [...] })` };
+}