@theoremjs/studio 0.0.0-stage → 0.3.2

package/source.d.ts

@@ -0,0 +1,75 @@
+/**
+ * One serializer writes the values, and each tool's schemas as the Zod expressions
+ * `zodFromJsonSchema` would build.
+ */
+import type { CompiledStudio } from './compile.ts';
+import type { CompiledWorkspace } from './compile-workspace.ts';
+import { type StudioProvider } from './providers.ts';
+import type { ToolRegistration } from './registrations.ts';
+import type { ProjectOrigins, ProviderPlace } from './server/save-wire.ts';
+/** How a value is laid out: the studio's own files, or a file of the builder's. */
+export interface SourceStyle {
+    /** One level of indentation. */
+    unit: string;
+    /** The indentation of the line the value starts on. */
+    base: string;
+    /** Text of several lines as a template literal, not as lines joined. */
+    template: boolean;
+    /** Text of one line as source. Default: the studio's, which escapes what could close a script tag. */
+    quote?: (text: string) => string;
+}
+/** A plain value as source, in `style`. */
+export declare function valueSource(value: unknown, style: SourceStyle): string;
+/** The package an exported module imports the kernel from. */
+export declare const AGENTS_PACKAGE = "@theoremjs/agents";
+/**
+ * What a project's files hold that an export names where it stands, since the studio does not
+ * hold it: each provider's definition, and the settings its profiles set in code.
+ */
+export interface ProjectCode {
+    /** Where the files define each provider that is still as they define it. */
+    providers: readonly ProviderPlace[];
+    /** The settings set in code, by profile id. */
+    origins: ProjectOrigins['profiles'];
+}
+/**
+ * A provider's module: the function `name` that registers it, for the setup to call before every
+ * agent. `from` is where the module imports the kernel from. None for a definition that is the
+ * project's own.
+ */
+export declare function providerModule(provider: StudioProvider, name: string, from?: string): string | undefined;
+/** A provider as the code view shows it: the call that registers it, or why the studio writes none. */
+export declare function providerSource(provider: StudioProvider): string;
+export declare function studioSource(compiled: CompiledStudio): string;
+/** A file of an exported workspace: its path from the folder it lands in, and its text. */
+export interface SourceFile {
+    path: string;
+    code: string;
+}
+/** Where an agent's module lands, and how `theorem.ts` imports it. */
+export declare function agentModulePath(agentId: string): string;
+/** The import specifier for a module path: relative, without its extension. */
+export declare function importSpecifier(path: string): string;
+/** A camelCase identifier for an id, unique among `taken`; `kind` leads one that starts with a digit. */
+export declare function agentIdentifier(agentId: string, taken: Set<string>, kind?: string): string;
+/**
+ * An agent's module: its profile, and its structured reply and questions when it has them.
+ * Registers nothing. `from` is where the module imports the kernel from. With `checks` (the
+ * settings set in code, by profile id), each item rule is written with its check.
+ */
+export declare function agentModule(compiled: CompiledStudio, from?: string, checks?: ProjectOrigins['profiles']): string;
+/**
+ * One tool's module: a function that registers it, for the setup to call where the tool belongs
+ * in its order. `from` is where the module imports the kernel and `z` from.
+ */
+export declare function toolModule(tool: ToolRegistration, register: string, from: {
+    agents: string;
+    zod: string;
+}): string;
+/**
+ * A workspace as source: `tools.ts` with the shared tools, one `agents/<id>.ts`
+ * per agent, and `theorem.ts`, which registers them all. Each agent is registered
+ * after the agents it names, and each agent tool after the agent it runs, so the
+ * order is the one a scope needs and reads in one place.
+ */
+export declare function workspaceSource(compiled: CompiledWorkspace, project?: ProjectCode): SourceFile[];

package/source.js

@@ -0,0 +1,414 @@
+/**
+ * One serializer writes the values, and each tool's schemas as the Zod expressions
+ * `zodFromJsonSchema` would build.
+ */
+import { listsPatterns } from '@theoremjs/agents/guardrails';
+import { withoutStudioFills } from "./policy.js";
+import { definitionFactory, kernelDefinitions } from "./providers.js";
+import { stubOutputFromSchema } from "./stub.js";
+import { keySource, quoteSource } from "./tool-schema.js";
+/** Source text written as-is into the module. */
+class Expr {
+    code;
+    constructor(code) {
+        this.code = code;
+    }
+}
+/** Arrays of primitives shorter than this stay on one line. */
+const INLINE_ARRAY_WIDTH = 60;
+const STUDIO_STYLE = { unit: '  ', base: '', template: false };
+/** `text` as a template literal, each line as it is. */
+function templateSource(text) {
+    return `\`${text.replaceAll('\\', '\\\\').replaceAll('`', '\\`').replaceAll('${', '\\${')}\``;
+}
+/** A plain value as source, in `style`. */
+export function valueSource(value, style) {
+    return literal(value, 0, style);
+}
+function literal(value, depth, style = STUDIO_STYLE) {
+    if (value instanceof Expr)
+        return value.code;
+    const pad = style.base + style.unit.repeat(depth + 1);
+    const close = style.base + style.unit.repeat(depth);
+    if (typeof value === 'string') {
+        if (!value.includes('\n'))
+            return (style.quote ?? quoteSource)(value);
+        if (style.template)
+            return templateSource(value);
+        // One line of the text on each line of the source.
+        const lines = value.split('\n').map((line) => `${pad}${quoteSource(line)},`);
+        return `[\n${lines.join('\n')}\n${close}].join('\\n')`;
+    }
+    if (Array.isArray(value)) {
+        if (!value.length)
+            return '[]';
+        const items = value.map((item) => literal(item, depth + 1, style));
+        const inline = `[${items.join(', ')}]`;
+        const primitive = value.every((item) => item === null || typeof item !== 'object');
+        if (primitive && inline.length <= INLINE_ARRAY_WIDTH)
+            return inline;
+        return `[\n${items.map((item) => `${pad}${item},`).join('\n')}\n${close}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value).filter(([, item]) => item !== undefined);
+        if (!entries.length)
+            return '{}';
+        const lines = entries.map(([key, item]) => `${pad}${keySource(key, style.quote)}: ${literal(item, depth + 1, style)},`);
+        return `{\n${lines.join('\n')}\n${close}}`;
+    }
+    if (value === null || typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    throw new Error(`Studio source cannot write a ${typeof value} value.`);
+}
+/** The package an exported module imports the kernel from. */
+export const AGENTS_PACKAGE = '@theoremjs/agents';
+const COMPILE_IMPORT = `import { compileDetect } from '${AGENTS_PACKAGE}/guardrails/compile';`;
+/**
+ * The profile's `defineProfile` call. A detector's own patterns need their compiled table, so
+ * `detect` is wrapped in `compileDetect`, which compiles them as the host starts; `compiles`
+ * says the module needs its import.
+ */
+function profileSource(profile) {
+    const { guardrails } = profile;
+    const detect = guardrails && 'detect' in guardrails ? guardrails.detect : undefined;
+    if (typeof detect !== 'object' || !listsPatterns(detect)) {
+        return { code: `defineProfile(${literal(profile, 0)})`, compiles: false };
+    }
+    const compiled = new Expr(`compileDetect(${literal(detect, 2)})`);
+    const written = { ...profile, guardrails: { ...guardrails, detect: compiled } };
+    return { code: `defineProfile(${literal(written, 0)})`, compiles: true };
+}
+/**
+ * The profile with the check of each list's item rule as the project's files write it. A check is
+ * code, so the studio holds none: a rule the files do not place gets a line that says what is owed.
+ */
+function withItemChecks(profile, checks) {
+    if (!('outputs' in profile))
+        return profile;
+    const validation = profile.outputs?.validation;
+    if (!validation?.items)
+        return profile;
+    const origins = checks[profile.id] ?? [];
+    const items = Object.fromEntries(Object.entries(validation.items).map(([list, rule]) => {
+        const path = ['outputs', 'validation', 'items', list, 'check'];
+        const at = origins.find((origin) => origin.kind === 'code' &&
+            origin.text !== undefined &&
+            origin.path.join('\n') === path.join('\n'));
+        const check = at?.text !== undefined
+            ? `${at.text} /* ${String(at.file)}:${String(at.line)} */`
+            : `undefined /* The check of each item of ${quoteSource(list)} is your own code: name it here. */`;
+        return [list, { check: new Expr(check), onFail: rule.onFail }];
+    }));
+    return { ...profile, outputs: { ...profile.outputs, validation: { ...validation, items } } };
+}
+/** A tool's registration, as a call; `indent` places it in a function body. */
+function toolSource(tool, indent = 0) {
+    const call = (fields) => {
+        const pad = '  '.repeat(indent);
+        return `${pad}registerTool(${literal(fields, indent)});\n`;
+    };
+    const { inputSchema, outputSchema, ...fields } = tool;
+    // The kernel fixes an agent tool's schemas.
+    if (fields.type === 'agent')
+        return call(fields);
+    // The schema as it is, read by zod: hand-written zod would keep its shape and lose the rest.
+    const read = (schema) => new Expr(`z.fromJSONSchema(${literal(schema, indent + 1)})`);
+    const zod = { input: read(inputSchema), output: read(outputSchema) };
+    if (fields.type !== 'function')
+        return call({ ...fields, ...zod });
+    const { stubResponse, ...functionFields } = fields;
+    // The page answers the call, so the tool has no handler; the stub is the studio's stand-in.
+    if (functionFields.answeredBy === 'page')
+        return call({ ...functionFields, ...zod });
+    const stub = stubResponse ?? stubOutputFromSchema(outputSchema);
+    const handler = new Expr(`() => Promise.resolve(${literal(stub, indent + 1)})`);
+    return call({ ...functionFields, ...zod, handler });
+}
+/** The call that registers `provider` from the kernel definition `factory` names, at `indent`. */
+function registrationCall(provider, factory, indent = 0) {
+    const pad = '  '.repeat(indent);
+    const held = Object.entries(provider.connection ?? {}).map(([key, value]) => `${keySource(key)}: ${quoteSource(value)}`);
+    const settings = [
+        `id: ${quoteSource(provider.id)}`,
+        ...(held.length ? [`connection: { ${held.join(', ')} }`] : []),
+        ...['keySlot', 'fallbackKeySlot'].flatMap((slot) => provider[slot] === undefined ? [] : [`${slot}: ${quoteSource(provider[slot])}`]),
+    ];
+    return `${pad}registerProvider(${factory}, {\n${settings.map((line) => `${pad}  ${line},\n`).join('')}${pad}});\n`;
+}
+/**
+ * A provider's module: the function `name` that registers it, for the setup to call before every
+ * agent. `from` is where the module imports the kernel from. None for a definition that is the
+ * project's own.
+ */
+export function providerModule(provider, name, from = AGENTS_PACKAGE) {
+    const factory = definitionFactory(provider.definition);
+    if (!factory)
+        return undefined;
+    return [
+        `import { ${factory}, registerProvider } from ${quoteSource(from)};\n`,
+        `/** Registers the provider \`${provider.id}\`. Call it before any agent whose models name it. */\nexport function ${name}(): void {\n${registrationCall(provider, factory, 1)}}\n`,
+    ].join('\n');
+}
+/** A provider as the code view shows it: the call that registers it, or why the studio writes none. */
+export function providerSource(provider) {
+    const factory = definitionFactory(provider.definition);
+    return factory
+        ? registrationCall(provider, factory)
+        : `// The provider ${quoteSource(provider.id)} registers from your own definition ${quoteSource(provider.definition)}, so it stays in your code.\n`;
+}
+/**
+ * The registration of each provider a model of `profiles` names. One the project's files define
+ * (`places`) is imported under its own name, by its path from the project's folder, or named by
+ * its line when the files do not export it. One whose definition is the project's own is not the
+ * studio's to write: the code says so where its registration belongs.
+ */
+function providerRegistrations(profiles, providers, places = []) {
+    const ids = new Set(profiles.flatMap((profile) => profile.type === 'host'
+        ? []
+        : Object.values(profile.models).map((binding) => binding.provider)));
+    const imports = new Set();
+    const own = new Map();
+    const code = [];
+    for (const id of ids) {
+        const place = places.find((held) => held.id === id);
+        if (place?.name !== undefined && place.exported) {
+            imports.add('registerProvider');
+            const from = importSpecifier(place.file);
+            own.set(from, [...(own.get(from) ?? []), place.name]);
+            code.push(`registerProvider(${place.name});\n`);
+            continue;
+        }
+        if (place) {
+            code.push(`// Register the provider ${quoteSource(id)} here, before the agents: ${place.file}:${String(place.line)} defines it and does not export it.\n`);
+            continue;
+        }
+        const provider = providers.find((held) => held.id === id);
+        const factory = provider && definitionFactory(provider.definition);
+        if (!provider || !factory) {
+            code.push(`// Register the provider ${quoteSource(id)} here, before the agents: its definition is the project's own.\n`);
+            continue;
+        }
+        imports.add('registerProvider');
+        imports.add(factory);
+        code.push(registrationCall(provider, factory));
+    }
+    return {
+        imports: [...imports],
+        own: [...own].map(([from, names]) => `import { ${names.join(', ')} } from ${quoteSource(from)};`),
+        code,
+    };
+}
+export function studioSource(compiled) {
+    const { profile, customTools, structured } = compiled;
+    const providers = providerRegistrations([profile], compiled.providers);
+    const imports = [
+        'defineProfile',
+        'registerProfile',
+        ...providers.imports,
+        ...(structured ? ['registerStructured'] : []),
+        ...(customTools.length ? ['registerTool'] : []),
+    ];
+    const defined = profileSource(profile);
+    const blocks = [
+        [
+            ...(customTools.length ? [`import { z } from 'zod';`] : []),
+            ...(defined.compiles ? [COMPILE_IMPORT] : []),
+            `import {\n${[
+                ...(compiled.images ? ['type DecisionAsset'] : []),
+                ...(compiled.questions ? ['type DecisionQuestion'] : []),
+                ...imports,
+            ]
+                .map((name) => `  ${name},`)
+                .join('\n')}\n} from '@theoremjs/agents';\n`,
+        ].join('\n'),
+        ...providers.code,
+        ...customTools.map((tool) => toolSource(tool)),
+        ...(structured
+            ? [`registerStructured(${quoteSource(structured.id)}, ${literal(structured.spec, 0)});\n`]
+            : []),
+        `const profile = ${defined.code};\n\nregisterProfile(profile);\n`,
+        ...(compiled.questions
+            ? [
+                `/** What every decision asks about the state, by id. */\nconst questions = ${literal(compiled.questions, 0)} satisfies Record<string, DecisionQuestion>;\n`,
+            ]
+            : []),
+        ...(compiled.images ? [imagesSource(compiled.images, 'const')] : []),
+    ];
+    return blocks.join('\n');
+}
+function imagesSource(images, declare) {
+    return `/** The pictures every decision sends, by the reference its questions write. */\n${declare} images = ${literal(images, 0)} satisfies Record<string, DecisionAsset>;\n`;
+}
+/** Where an agent's module lands, and how `theorem.ts` imports it. */
+export function agentModulePath(agentId) {
+    return `agents/${agentId}.ts`;
+}
+/** The import specifier for a module path: relative, without its extension. */
+export function importSpecifier(path) {
+    return `./${path.replace(/\.tsx?$/, '')}`;
+}
+/**
+ * What no identifier the studio writes may be: a word JavaScript keeps for itself, and a name the
+ * modules it writes import beside one, which the identifier would hide.
+ */
+const UNNAMEABLE = new Set([
+    ...'arguments await break case catch class const continue debugger default delete do else enum eval export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof undefined var void while with yield'.split(' '),
+    ...'compileDetect DecisionQuestion defineProfile defineProvider registerProfile registerProvider registerProviders registerStructured registerTool registerToolLibrary z'.split(' '),
+    ...kernelDefinitions().flatMap((definition) => definitionFactory(definition) ?? []),
+]);
+/** A camelCase identifier for an id, unique among `taken`; `kind` leads one that starts with a digit. */
+export function agentIdentifier(agentId, taken, kind = 'agent') {
+    const words = agentId.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const joined = words
+        .map((word, index) => (index ? word[0].toUpperCase() + word.slice(1) : word.toLowerCase()))
+        .join('');
+    const base = /^[A-Za-z_$]/.test(joined) ? joined : `${kind}${joined}`;
+    let name = base;
+    for (let n = 2; taken.has(name) || UNNAMEABLE.has(name); n++)
+        name = `${base}${n}`;
+    taken.add(name);
+    return name;
+}
+/**
+ * An agent's module: its profile, and its structured reply and questions when it has them.
+ * Registers nothing. `from` is where the module imports the kernel from. With `checks` (the
+ * settings set in code, by profile id), each item rule is written with its check.
+ */
+export function agentModule(compiled, from = AGENTS_PACKAGE, checks) {
+    const { profile, structured, questions, images } = compiled;
+    const imports = [
+        ...(images ? ['type DecisionAsset'] : []),
+        ...(questions ? ['type DecisionQuestion'] : []),
+        'defineProfile',
+    ];
+    const defined = profileSource(withoutStudioFills(checks ? withItemChecks(profile, checks) : profile));
+    const blocks = [
+        `import { ${imports.join(', ')} } from ${quoteSource(from)};\n${defined.compiles ? `${COMPILE_IMPORT}\n` : ''}`,
+        ...(structured
+            ? [
+                `/** The reply's shape, registered before the profile. */\nexport const structured = ${literal(structured, 0)};\n`,
+            ]
+            : []),
+        `export const profile = ${defined.code};\n`,
+        ...(questions
+            ? [
+                `/** What every decision asks about the state, by id. */\nexport const questions = ${literal(questions, 0)} satisfies Record<string, DecisionQuestion>;\n`,
+            ]
+            : []),
+        ...(images ? [imagesSource(images, 'export const')] : []),
+    ];
+    return blocks.join('\n');
+}
+/**
+ * One tool's module: a function that registers it, for the setup to call where the tool belongs
+ * in its order. `from` is where the module imports the kernel and `z` from.
+ */
+export function toolModule(tool, register, from) {
+    const zod = tool.type === 'agent' ? undefined : from.zod;
+    const imports = zod === from.agents
+        ? `import { registerTool, z } from ${quoteSource(from.agents)};\n`
+        : `${zod ? `import { z } from ${quoteSource(zod)};\n` : ''}import { registerTool } from ${quoteSource(from.agents)};\n`;
+    const order = tool.type === 'agent'
+        ? 'Call it after the agent it runs is registered, and before any agent that allows it.'
+        : 'Call it before any agent that allows it is registered.';
+    // A function tool made in the studio answers with its sample until its handler is written.
+    const stands = tool.type === 'function' && tool.answeredBy !== 'page';
+    const note = stands
+        ? `${order}\n * Its handler returns the studio's sample answer: write the real one here.`
+        : order;
+    return [
+        imports,
+        `/**${stands ? '\n *' : ''} Registers \`${tool.name}\`. ${note}${stands ? '\n' : ''} */\nexport function ${register}(): void {\n${toolSource(tool, 1)}}\n`,
+    ].join('\n');
+}
+/** The library's function, HTTP, and MCP tools, each once; agent tools wait for their agents. */
+function libraryModule(tools) {
+    return [
+        `import { z } from 'zod';\nimport { registerTool } from '@theoremjs/agents';\n`,
+        `/** Registers the tools the agents share. \`theorem.ts\` calls it before any agent. */\nexport function registerToolLibrary(): void {\n${tools
+            .map((tool) => toolSource(tool, 1))
+            .join('\n')}}\n`,
+    ].join('\n');
+}
+/**
+ * A workspace as source: `tools.ts` with the shared tools, one `agents/<id>.ts`
+ * per agent, and `theorem.ts`, which registers them all. Each agent is registered
+ * after the agents it names, and each agent tool after the agent it runs, so the
+ * order is the one a scope needs and reads in one place.
+ */
+export function workspaceSource(compiled, project) {
+    const library = new Map();
+    for (const tool of compiled.agents.flatMap((agent) => agent.customTools)) {
+        if (tool.type !== 'agent' && !library.has(tool.name))
+            library.set(tool.name, tool);
+    }
+    const taken = new Set([
+        'registerProfile',
+        'registerStructured',
+        'registerTool',
+        'registerToolLibrary',
+        ...(project?.providers ?? []).flatMap((place) => place.name === undefined ? [] : [place.name]),
+    ]);
+    const agents = compiled.agents.map((agent) => ({
+        agent,
+        path: agentModulePath(agent.agentId),
+        name: agentIdentifier(agent.agentId, taken),
+    }));
+    const structured = agents.some(({ agent }) => agent.structured);
+    const agentTools = agents.some(({ agent }) => agent.customTools.some((tool) => tool.type === 'agent'));
+    const registered = new Set();
+    const steps = agents.map(({ agent, name }) => {
+        const lines = [];
+        for (const tool of agent.customTools) {
+            if (tool.type !== 'agent' || registered.has(tool.name))
+                continue;
+            registered.add(tool.name);
+            lines.push(toolSource(tool));
+        }
+        if (agent.structured) {
+            lines.push(`registerStructured(${name}.structured.id, ${name}.structured.spec);\n`);
+        }
+        lines.push(`registerProfile(${name}.profile);\n`);
+        return lines.join('\n');
+    });
+    const providers = providerRegistrations(agents.map(({ agent }) => agent.profile), agents[0]?.agent.providers ?? [], project?.providers);
+    const theorem = [
+        [
+            '/**',
+            ' * Registers every agent and tool, server side. Import it once, before any',
+            ' * route that runs an agent. Each agent comes after the agents it names, and',
+            ' * each agent tool after the agent it runs.',
+            ' */',
+            `import {\n${[
+                'registerProfile',
+                ...providers.imports,
+                ...(structured ? ['registerStructured'] : []),
+                ...(agentTools ? ['registerTool'] : []),
+            ]
+                .map((each) => `  ${each},`)
+                .join('\n')}\n} from '@theoremjs/agents';`,
+            ...(library.size ? [`import { registerToolLibrary } from './tools';`] : []),
+            ...agents.map(({ path, name }) => `import * as ${name} from '${importSpecifier(path)}';`),
+            ...(providers.own.length
+                ? [
+                    "// The project's own providers, each by its path from the project's folder.",
+                    ...providers.own,
+                ]
+                : []),
+            '',
+        ].join('\n'),
+        ...providers.code,
+        ...(library.size ? ['registerToolLibrary();\n'] : []),
+        ...steps,
+    ];
+    return [
+        ...(library.size ? [{ path: 'tools.ts', code: libraryModule([...library.values()]) }] : []),
+        ...agents.map(({ agent, path }) => ({
+            path,
+            code: agentModule(agent, AGENTS_PACKAGE, project?.origins ?? {}),
+        })),
+        { path: 'theorem.ts', code: theorem.join('\n') },
+    ];
+}

package/start.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Opens the studio on a project, with one command:
+ *
+ *   theorem-studio [setup] [--editor <command>] [--deno-config <file>] [--no-watch]
+ *
+ * That is the installed package's command (`npx theorem-studio`); in the repo it is
+ * `node studio/start.mjs`.
+ *
+ * `setup` is a setup's file or its name. A setup is a file named `studio.setup.ts`, named for its
+ * folder, or `<name>.studio.setup.ts`. With no `setup` the project's one setup opens, and when the
+ * project has several the command asks which. A project gives this a short name of its own:
+ * `"studio": "theorem-studio"` in its scripts makes it `npm run studio`.
+ *
+ * It starts the project's local server (`server/serve.ts`, under Deno, with the project's own
+ * permissions) and the studio's page, and stops both together. Only this machine reaches either.
+ * `--editor` names the editor the studio opens a line of the project's files in; without it the
+ * studio uses `$VISUAL` or `$EDITOR` when that opens a window, and `code` otherwise. When that one
+ * does not start, the machine's default editor opens the file.
+ * The studio watches the files the setup reads and takes in what the builder's editor changes;
+ * `--no-watch` turns that off, and the studio then reads them when the builder comes back to it.
+ * The project loads with its own Deno config: the one `--deno-config` names, else the `deno.json`
+ * or `deno.jsonc` in the folder the command ran in, else the studio's.
+ * A project already open in a studio is not opened twice: the command says where it is. A second
+ * project opens beside the first, on the next free pair of ports.
+ * The studio is opt-in, so this checks for its install and never installs it.
+ */
+import { builtPage } from './installed.mjs';
+import { heldPairs, pageAddress, placeFor, serverAddress } from './ports.mjs';
+import { chooseSetup, findSetups, setupLines, setupsNamed } from './setups.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const USAGE = `usage: ${builtPage ? 'theorem-studio' : 'node studio/start.mjs'} [setup] [--editor <command>] [--deno-config <file>] [--no-watch]`;
+/** The value after each flag that takes one. A flag with none, a second setup, or anything else, is a mistake. */
+const VALUED = ['--editor', '--deno-config'];
+const given = {};
+let wanted;
+let noWatch = false;
+let mistaken = false;
+const args = process.argv.slice(2);
+for (let at = 0; at < args.length; at += 1) {
+  const arg = args[at];
+  if (arg === '--no-watch') noWatch = true;
+  else if (VALUED.includes(arg)) {
+    const value = args[at + 1];
+    if (!value || value.startsWith('--')) mistaken = true;
+    else given[arg] = value;
+    at += 1;
+  } else if (arg.startsWith('--') || wanted !== undefined) mistaken = true;
+  else wanted = arg;
+}
+if (mistaken) {
+  console.error(USAGE);
+  process.exit(2);
+}
+const editor = given['--editor'];
+
+// The setup module is named from where the command was run, which is also the project's name.
+const from = process.env.INIT_CWD ?? process.cwd();
+const setup = await setupToOpen();
+
+/** Says why no setup opens, and stops. */
+function refuse(message) {
+  console.error(`${message}\n\n${USAGE}`);
+  process.exit(2);
+}
+
+/** The setup this run opens: the file named, else the one found, else the one the builder picks. */
+async function setupToOpen() {
+  if (wanted !== undefined && existsSync(path.resolve(from, wanted))) return wanted;
+  const found = findSetups(from);
+  const setups = wanted === undefined ? found : setupsNamed(found, wanted);
+  if (setups.length === 1) return setups[0].file;
+  const why = whyNoSetup(found, setups);
+  if (why) refuse(why);
+  const chosen = await chooseSetup(setups, process.stdin, process.stdout);
+  if (!chosen) process.exit(130);
+  return chosen.file;
+}
+
+/** Why the builder cannot be asked which setup to open, when that is so. */
+function whyNoSetup(found, setups) {
+  if (found.length === 0) {
+    return `No setup in ${from}. A setup is a file named studio.setup.ts, or <name>.studio.setup.ts.`;
+  }
+  if (setups.length === 0) {
+    return `No setup is named ${wanted}. This project has:\n\n${setupLines(found).join('\n')}`;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return `This project has more than one setup. Name the one to open:\n\n${setupLines(setups).join('\n')}`;
+  }
+  return undefined;
+}
+const place = placeFor(realpathSync(path.resolve(from, setup)), await heldPairs());
+if (!place) refuse('Too many studios are open on this machine. Stop one, then run this again.');
+const PAGE = pageAddress(place.pair);
+if (place.running) {
+  console.log(`theorem studio: already open on ${setup}: ${PAGE}/studio/`);
+  process.exit(0);
+}
+if (setup !== wanted) console.log(`theorem studio: opening ${setup}`);
+const ownConfig = ['deno.json', 'deno.jsonc'].map((name) => path.join(from, name)).find(existsSync);
+const projectConfig = given['--deno-config']
+  ? path.resolve(from, given['--deno-config'])
+  : (ownConfig ?? path.join(here, 'deno.json'));
+const server = spawn(
+  'deno',
+  [
+    'run',
+    '--config',
+    path.join(here, 'deno.json'),
+    '-A',
+    path.join(here, builtPage ? 'server/serve.js' : 'server/serve.ts'),
+    path.resolve(from, setup),
+    '--port',
+    String(place.pair.server),
+    '--page',
+    `${PAGE},http://localhost:${String(place.pair.page)}`,
+    '--deno-config',
+    projectConfig,
+    ...(editor ? ['--editor', editor] : []),
+    ...(noWatch ? ['--no-watch'] : []),
+  ],
+  { cwd: from, stdio: ['ignore', 'ignore', 'inherit'] },
+);
+const project = `${serverAddress(place.pair)}/api/studio`;
+// An installed studio serves the page it was built with; the repo's is Vite on the sources.
+const page = builtPage
+  ? spawn(
+      process.execPath,
+      [path.join(here, 'serve-page.mjs'), '--port', String(place.pair.page), '--project', project],
+      { stdio: ['ignore', 'ignore', 'inherit'] },
+    )
+  : spawn(
+      process.execPath,
+      [
+        path.join(here, 'node_modules/vite/bin/vite.js'),
+        '--config',
+        path.join(here, 'app/vite.config.ts'),
+        '--port',
+        String(place.pair.page),
+      ],
+      {
+        cwd: here,
+        stdio: ['ignore', 'ignore', 'inherit'],
+        env: { ...process.env, THEOREM_STUDIO_PROJECT: project },
+      },
+    );
+
+console.log(`theorem studio: ${PAGE}/studio/`);
+
+let stopping = false;
+/** Stops both when either ends or the command is interrupted. */
+function stop(code) {
+  if (stopping) return;
+  stopping = true;
+  server.kill();
+  page.kill();
+  process.exitCode = code;
+}
+server.on('exit', (code) => stop(code ?? 1));
+page.on('exit', (code) => stop(code ?? 1));
+process.on('SIGINT', () => stop(0));
+process.on('SIGTERM', () => stop(0));

package/stream-lines.d.ts

@@ -0,0 +1,9 @@
+/** Hands a line on to whoever reads the stream. */
+export type SendLine = (line: string) => void;
+/**
+ * A newline-delimited stream read a line at a time: `each` sees every line and sends on the ones
+ * it keeps, and `end` runs after the last.
+ */
+export declare function eachLine(each: (line: string, send: SendLine) => void, end?: (send: SendLine) => void): TransformStream<Uint8Array, Uint8Array>;
+/** The content type of a run's stream. */
+export declare const NDJSON = "application/x-ndjson";