@theoremjs/studio 0.0.0-stage → 0.3.2

package/vite.mjs

@@ -0,0 +1,277 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The package repo when the studio is linked from it (`studio/vite.mjs` there). An install from the
+ * registry has none: the declarations are the ones the installed `@theoremjs/agents` ships.
+ */
+const theoremaiRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const linked = existsSync(path.join(theoremaiRoot, 'mod.ts'));
+/** The package's own folder: `studio/` in the repo, or the installed package. */
+const studioRoot = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * What the screen imports that comes from the host's install when the host has it, so there is
+ * one copy of each. A host that reaches the package by a link has only what it lists itself; the
+ * rest is the package's own copy, which only the package imports.
+ */
+const HOST_PACKAGES = [
+    'react',
+    'react-dom',
+    '@astryxdesign/core',
+    '@fontsource/figtree',
+    '@tabler/icons-react',
+    'monaco-editor',
+    'fflate',
+];
+const CODICONS = 'virtual:studio-codicons/';
+/** Bump when the declaration shape changes, so a warm cache is not reused. */
+const CACHE_VERSION = 1;
+/**
+ * What a Vite build needs to show the studio screen (`@theoremjs/studio/ui`). `hostRoot` is the
+ * app that shows it; its install holds React and the design library.
+ *
+ * - The screen's packages resolve to the host's install where it has them, so there is one copy
+ *   of each. Monaco, fflate, and zod are the package's own dependencies: an install from the
+ *   registry puts them in the host, and a linked package keeps them beside itself.
+ * - `virtual:studio-codicons/*` is Monaco's icon sheets.
+ * - `virtual:studio-type-sources` is the declarations for the open agent's file. The Monaco
+ *   worker typechecks that one file. It does not typecheck the kernel: these are the
+ *   declarations for `@theoremjs/agents` (emitted from the repo when the package is linked from
+ *   it, or the ones the installed package ships), plus the zod declarations that entry imports. Locale files and anything the entries do not reach are
+ *   left out. The worker resolves a `.js` import in a declaration to the `.d.ts` beside it.
+ */
+export function studioVite({ hostRoot }) {
+    const virtual = '\0virtual:studio-type-sources';
+    const codicons = path.join(hostPackage(hostRoot, 'monaco-editor'), 'esm/vs/base/browser/ui/codicons/codicon');
+    return {
+        name: 'theorem-studio',
+        config() {
+            return { resolve: { dedupe: HOST_PACKAGES.filter((name) => installedFrom(hostRoot, name)) } };
+        },
+        resolveId(source) {
+            if (source === 'virtual:studio-type-sources')
+                return virtual;
+            if (source.startsWith(CODICONS))
+                return path.join(codicons, source.slice(CODICONS.length));
+        },
+        load(source) {
+            if (source !== virtual)
+                return;
+            const files = loadDeclarations(hostRoot);
+            addTree(files, hostPackage(hostRoot, 'zod'), 'file:///node_modules/zod', '.d.ts');
+            const reached = reachableDeclarations(files);
+            return `export const typeSources = ${JSON.stringify(reached)};\n`;
+        },
+    };
+}
+function loadDeclarations(hostRoot) {
+    if (!linked)
+        return installedDeclarations(hostRoot);
+    const cacheFile = path.join(hostRoot, 'node_modules/.vite/studio-declarations.json');
+    const stamp = sourceStamp();
+    const cached = readCache(cacheFile);
+    if (cached?.stamp === stamp)
+        return cached.files;
+    const files = emitDeclarations(hostRoot);
+    mkdirSync(path.dirname(cacheFile), { recursive: true });
+    writeFileSync(cacheFile, JSON.stringify({ stamp, files }));
+    return files;
+}
+function readCache(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Changes when the kernel sources the declarations are emitted from change. */
+function sourceStamp() {
+    let newest = 0;
+    let count = 0;
+    const note = (file) => {
+        const stat = statSync(file);
+        count += 1;
+        if (stat.mtimeMs > newest)
+            newest = stat.mtimeMs;
+    };
+    note(path.join(theoremaiRoot, 'mod.ts'));
+    walk(path.join(theoremaiRoot, 'src'), (full) => {
+        if (full.endsWith('.ts') && !full.endsWith('.test.ts'))
+            note(full);
+    });
+    const zod = path.join(theoremaiRoot, 'node_modules/zod/index.d.ts');
+    note(zod);
+    return `${CACHE_VERSION}:${count}:${Math.round(newest)}`;
+}
+function walk(dir, visit) {
+    for (const name of readdirSync(dir)) {
+        if (name === 'node_modules')
+            continue;
+        const full = path.join(dir, name);
+        if (statSync(full).isDirectory())
+            walk(full, visit);
+        else
+            visit(full);
+    }
+}
+/**
+ * `dir`'s files of one extension, keyed by `prefix` plus their path.
+ * Skips tests.
+ */
+function addTree(files, dir, prefix, extension) {
+    for (const name of readdirSync(dir)) {
+        if (name === 'node_modules' || name.endsWith('.test.ts'))
+            continue;
+        const full = path.join(dir, name);
+        const key = `${prefix}/${name}`;
+        if (statSync(full).isDirectory())
+            addTree(files, full, key, extension);
+        else if (name.endsWith(extension))
+            files[key] = readFileSync(full, 'utf8');
+    }
+}
+/** The public entry and the guardrails compiler, as `.d.ts`, under the paths the file imports. */
+function emitDeclarations(hostRoot) {
+    const ts = loadTypeScript(hostRoot);
+    const options = {
+        declaration: true,
+        emitDeclarationOnly: true,
+        skipLibCheck: true,
+        strict: true,
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        allowImportingTsExtensions: true,
+        rewriteRelativeImportExtensions: true,
+        jsx: ts.JsxEmit.ReactJSX,
+    };
+    const host = ts.createCompilerHost(options);
+    const written = new Map();
+    host.writeFile = (fileName, contents) => {
+        written.set(fileName, contents);
+    };
+    const program = ts.createProgram([
+        path.join(theoremaiRoot, 'mod.ts'),
+        path.join(theoremaiRoot, 'src/guardrails/compile-egress.ts'),
+    ], options, host);
+    const diagnostics = [...ts.getPreEmitDiagnostics(program), ...program.emit().diagnostics];
+    const errors = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    if (errors.length > 0) {
+        const text = errors
+            .slice(0, 8)
+            .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
+            .join('\n');
+        throw new Error(`Studio declarations failed to emit.\n${text}`);
+    }
+    const prefix = 'file:///node_modules/@theoremjs/agents';
+    const files = {};
+    for (const [fileName, contents] of written) {
+        const relative = path.relative(theoremaiRoot, fileName).split(path.sep).join('/');
+        files[`${prefix}/${relative}`] = rewriteTypeSpecifiers(contents);
+    }
+    return files;
+}
+/** The installed package's declarations, under the paths the open file imports them by. */
+function installedDeclarations(hostRoot) {
+    const files = {};
+    addTree(files, path.join(hostPackage(hostRoot, '@theoremjs/agents'), 'esm'), 'file:///node_modules/@theoremjs/agents', '.d.ts');
+    return files;
+}
+/** Relative `.ts` specifiers become `.js`, which resolution reads as the `.d.ts`. */
+function rewriteTypeSpecifiers(contents) {
+    return contents.replaceAll(/((?:from|import)\s*\(?\s*['"])(\.{1,2}\/[^'"]+?)\.ts(['"])/g, '$1$2.js$3');
+}
+/** A package's folder as `root` resolves it: in its own `node_modules`, or the nearest one above. */
+export function installedFrom(root, name) {
+    let dir = root;
+    for (;;) {
+        const found = path.join(dir, 'node_modules', name);
+        if (existsSync(found))
+            return found;
+        const up = path.dirname(dir);
+        if (up === dir)
+            return undefined;
+        dir = up;
+    }
+}
+/** A package's folder: the host's install when it has one, or the copy the studio package came with. */
+export function hostPackage(hostRoot, name, ownRoot = studioRoot) {
+    const found = installedFrom(hostRoot, name) ?? installedFrom(ownRoot, name);
+    if (!found)
+        throw new Error(`studio: ${name} is not installed for ${hostRoot} or for the studio package`);
+    return found;
+}
+/** The host's TypeScript: the compiler its own build uses. */
+function loadTypeScript(hostRoot) {
+    return createRequire(path.join(hostRoot, 'package.json'))('typescript');
+}
+const ENTRY_FILES = [
+    'file:///node_modules/@theoremjs/agents/mod.d.ts',
+    'file:///node_modules/@theoremjs/agents/src/guardrails/compile-egress.d.ts',
+    'file:///node_modules/zod/index.d.ts',
+];
+const SPECIFIER = /(?:from\s+|import\s*\(\s*|import\s+)['"]([^'"]+)['"]|\/\/\/\s*<reference\s+path=['"]([^'"]+)['"]/g;
+/** The entries and every declaration they import. Nothing else is sent to the worker. */
+function reachableDeclarations(files) {
+    const reached = {};
+    const pending = [...ENTRY_FILES];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const key = pending.pop();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const contents = files[key];
+        if (contents === undefined) {
+            throw new Error(`Studio declarations are missing ${key}.`);
+        }
+        reached[key] = contents;
+        for (const specifier of specifiersIn(contents)) {
+            const next = resolveSpecifier(key, specifier, files);
+            if (next === undefined)
+                continue;
+            if (next === null) {
+                throw new Error(`Studio declarations: ${key} imports ${specifier}, which is not emitted.`);
+            }
+            pending.push(next);
+        }
+    }
+    return reached;
+}
+function specifiersIn(contents) {
+    return [...contents.matchAll(SPECIFIER)].map((match) => match[1] ?? match[2]);
+}
+/**
+ * A relative import, or an import of the two packages these files are allowed
+ * to name. Other packages are not part of this file's types.
+ * `null` means the specifier should have been in `files` and was not.
+ */
+function resolveSpecifier(fromKey, specifier, files) {
+    // Error-message catalogues. The schema API does not need them, and each one
+    // would be parsed into the program through `export * as locales`.
+    if (specifier.includes('/locales/') || specifier.endsWith('/locales'))
+        return undefined;
+    if (specifier.startsWith('.'))
+        return resolveFile(new URL(specifier, fromKey).href, files);
+    if (specifier === 'zod' || specifier.startsWith('zod/')) {
+        const rest = specifier === 'zod' ? 'index.d.ts' : specifier.slice('zod/'.length);
+        return resolveFile(`file:///node_modules/zod/${rest}`, files);
+    }
+    if (specifier === '@theoremjs/agents' || specifier.startsWith('@theoremjs/agents/')) {
+        const rest = specifier === '@theoremjs/agents' ? 'mod.d.ts' : specifier.slice('@theoremjs/agents/'.length);
+        return resolveFile(`file:///node_modules/@theoremjs/agents/${rest}`, files);
+    }
+    return undefined;
+}
+function resolveFile(href, files) {
+    const candidates = [href];
+    if (href.endsWith('.js'))
+        candidates.push(`${href.slice(0, -3)}.d.ts`);
+    if (!href.endsWith('.d.ts')) {
+        candidates.push(`${href}.d.ts`);
+        candidates.push(`${href}/index.d.ts`);
+    }
+    return candidates.find((candidate) => candidate in files) ?? null;
+}

package/workspace.d.ts

@@ -0,0 +1,230 @@
+/**
+ * A workspace holds several agents and one library of tools they share. Each
+ * agent is a draft without the library: it names the tools it allows by key.
+ * Every draft helper still works on one agent through `agentDraft`, which puts
+ * its allowed tools back, and `withAgentDraft`, which takes them out again.
+ */
+import { type StudioDraft, type ToolSpecDraft, type ToolsDraft } from './draft.ts';
+import type { StudioProvider } from './providers.ts';
+import { type StudioNodeRef, type StudioTreeNode } from './tree.ts';
+export declare const STUDIO_WORKSPACE_VERSION = 5;
+export interface AgentToolsDraft extends ToolsDraft {
+    /** The library tools this agent allows, by `ToolSpecDraft.key`. */
+    allow: string[];
+}
+/** One agent: a draft without the tool library, plus its own key and allow list. */
+export interface AgentDraft extends Omit<StudioDraft, 'toolSpecs' | 'tools' | 'providers'> {
+    key: string;
+    tools: AgentToolsDraft;
+}
+/**
+ * What each agent and tool held when it joined the workspace, by key, and each provider, by id: an
+ * example as it loaded, or a new one as it was made. Reset puts one back. A tool that left the
+ * library keeps its start while an agent that started with it is still here, so resetting that
+ * agent brings the tool back.
+ */
+export interface WorkspaceStarts {
+    agents: Record<string, AgentDraft>;
+    tools: Record<string, ToolSpecDraft>;
+    providers: Record<string, StudioProvider>;
+}
+export interface StudioWorkspace {
+    v: typeof STUDIO_WORKSPACE_VERSION;
+    /** In the tree's order. */
+    agents: AgentDraft[];
+    /** The tools every agent picks from. */
+    toolSpecs: ToolSpecDraft[];
+    /** The providers every agent's models pick from. */
+    providers: StudioProvider[];
+    /** The open node's id. */
+    selected: string;
+    /** The agent the preview chats with, by key. */
+    chatWith: string;
+    starts: WorkspaceStarts;
+}
+/** An agent's node id: its root, or a facet or binding under it (`identity` is the root). */
+export declare function agentNodeId(agentKey: string, inner?: string): string;
+/** A single draft's node id, under `agentKey`. Tools carry no agent: every agent shares them. */
+export declare function scopedNodeId(agentKey: string, id: string): string;
+export type WorkspaceNodeRef = {
+    agent: string;
+    ref: StudioNodeRef;
+} | {
+    tool: string;
+} | {
+    provider: string;
+};
+/** What a workspace node id names; `undefined` when it names nothing there. */
+export declare function workspaceNodeRef(workspace: StudioWorkspace, id: string): WorkspaceNodeRef | undefined;
+/** One agent as a single draft: its tools are the library's it allows, in the order it allows them. */
+export declare function agentDraft(workspace: StudioWorkspace, key: string): StudioDraft | undefined;
+/** Makes what an agent holds now its start: for an example that links its agents after adding them. */
+export declare function markAgentStart(workspace: StudioWorkspace, key: string): StudioWorkspace;
+/**
+ * Writes one agent's draft back. Its tools go to the library: a changed tool
+ * changes there for every agent, a new one joins the library and this agent's
+ * allow list, and one the draft dropped leaves only this agent's allow list.
+ * `registered` updates the library for a tool the file defines and does not allow.
+ */
+export declare function withAgentDraft(workspace: StudioWorkspace, key: string, draft: StudioDraft, registered?: readonly ToolSpecDraft[]): StudioWorkspace;
+/**
+ * A v1 single draft as a workspace: it becomes the one agent, its tools become
+ * the library and it allows them all, and the open node moves under it.
+ */
+export declare function workspaceFromDraft(draft: StudioDraft, selectedId?: string): StudioWorkspace;
+/** A workspace with one blank agent. */
+export declare function createBlankWorkspace(): StudioWorkspace;
+/**
+ * One agent as the editor shows it: its own settings, with the whole library
+ * as its tools. Which of them it allows stays on the agent (`setToolAllowed`).
+ */
+export declare function libraryDraft(workspace: StudioWorkspace, key: string): StudioDraft | undefined;
+/**
+ * Writes back a `libraryDraft`. Its tools become the library: a tool it
+ * dropped leaves every agent, and a tool it added is allowed on this agent.
+ */
+export declare function withLibraryDraft(workspace: StudioWorkspace, key: string, draft: StudioDraft): StudioWorkspace;
+/**
+ * Appends `draft` as a new agent, with an id no other agent has. A tool whose
+ * name the library already has is shared, not copied; the rest join the library.
+ */
+export declare function addAgent(workspace: StudioWorkspace, draft?: StudioDraft): StudioWorkspace;
+/** A copy of an agent right after it, allowing the same tools, with an id it doesn't share. */
+export declare function duplicateAgent(workspace: StudioWorkspace, key: string): StudioWorkspace;
+/**
+ * Removes an agent; the last one stays. Nothing is left pointing at it: the
+ * agent tools that ran it leave the library and every agent, and a model it
+ * summarised for goes back to summarising itself. The open node and the chat
+ * move to a neighbour when they were on it.
+ */
+export declare function removeAgent(workspace: StudioWorkspace, key: string): StudioWorkspace;
+/** Allows or stops allowing a library tool on one agent. */
+export declare function setToolAllowed(workspace: StudioWorkspace, agentKey: string, toolKey: string, allowed: boolean): StudioWorkspace;
+/** Removes a tool from the library and from every agent that allowed it. */
+export declare function removeLibraryTool(workspace: StudioWorkspace, toolKey: string): StudioWorkspace;
+/** Whether every agent, tool, and provider is as it started, and no tool was added or removed. */
+export declare function atStart(workspace: StudioWorkspace): boolean;
+/** Makes what the workspace holds now its start: after a Save, the project's files hold it. */
+export declare function startedHere(workspace: StudioWorkspace): StudioWorkspace;
+/**
+ * Puts one agent back to its start: its own settings and the tools it allowed. The tools keep
+ * their edits, since other agents share them; one that left the library comes back as it started.
+ * Nothing else changes. An agent already at its start returns the same workspace.
+ */
+export declare function resetAgent(workspace: StudioWorkspace, key: string): StudioWorkspace;
+/**
+ * Puts every agent, every library tool, and every provider back to its start, in one step. A tool that left the
+ * library comes back when an agent started out allowing it. An agent or a tool added here stays: it
+ * started as it is. A workspace already at its start is returned as it is.
+ */
+export declare function resetAll(workspace: StudioWorkspace): StudioWorkspace;
+/**
+ * The files' workspace, opened again over the one the studio holds. An agent or a tool the studio
+ * already opened from the files keeps its key, so what is open, each conversation, and the
+ * settings agents share carry on. One the builder removed comes back under a new key.
+ */
+export declare function reopened(files: StudioWorkspace, before: StudioWorkspace): StudioWorkspace;
+/**
+ * The builder's edits brought back over files that changed since they were made. What the builder
+ * changed or added stays as they left it, and what they did not touch is as the files hold it
+ * now. Every start is the files', so an edit made on the old files is one the new files do not
+ * hold. A tool the builder removed stays removed; an agent they removed comes back.
+ */
+export declare function rebased(edits: StudioWorkspace, files: StudioWorkspace): StudioWorkspace;
+/**
+ * A project's files as the studio opened them, as a short text that stays the same until they
+ * change. An agent's or a tool's key is new on every open, so each is named by where it first
+ * stands. What is open and who the preview talks to are not part of it.
+ */
+export declare function filesPrint(workspace: StudioWorkspace): string;
+/**
+ * Whether the workspace holds edits the files it stands on do not: a change, or an agent or a
+ * tool added or removed. `files` is the print of those files.
+ */
+export declare function editedSince(workspace: StudioWorkspace, files: string): boolean;
+/** One setting inside an agent, a tool, or a provider, as the fields that lead to it. Empty for the whole of it. */
+export type SettingPath = readonly (string | number)[];
+/** A setting the project's files changed. */
+export interface FileUpdate {
+    kind: 'agent' | 'tool' | 'provider';
+    /** The agent's or the tool's key in the merged workspace, or the provider's id. */
+    key: string;
+    /** The agent's or the provider's id, or the tool's name, as the files hold it. */
+    name: string;
+    path: SettingPath;
+}
+/** A setting the builder and the files both changed, to different values. Undefined is a removal. */
+export interface FileConflict extends FileUpdate {
+    mine: unknown;
+    theirs: unknown;
+}
+export interface FilesMerge {
+    /** The builder's edits over the files as they are now, with the builder's value at every conflict. */
+    workspace: StudioWorkspace;
+    /** What the files changed that the builder had not touched: it is as the files hold it. */
+    updated: FileUpdate[];
+    conflicts: FileConflict[];
+    /** The files as they are now, under the keys the workspace holds them by. */
+    files: StudioWorkspace;
+}
+/**
+ * The builder's edits merged with files that changed under them, setting by setting. What only
+ * the files changed is as the files hold it; what only the builder changed stays; what both
+ * changed to different values is a conflict, and the builder's value stands until they choose
+ * (`withFilesChosen`). Every start is the files', so what is left to save is the builder's edits.
+ *
+ * `before` is the files as the studio last read them. It tells an agent the files took away from
+ * one the builder added, and names the agents the builder removed, which keep no start. Without
+ * it nothing the studio holds is taken away, and an agent the builder removed comes back.
+ */
+export declare function mergedWithFiles(edits: StudioWorkspace, files: StudioWorkspace, before?: StudioWorkspace): FilesMerge;
+/**
+ * A merge's workspace with the files' value at each conflict named in `theirs`, by its place in
+ * `merge.conflicts`. Every other conflict keeps the builder's value.
+ */
+export declare function withFilesChosen(merge: FilesMerge, theirs: readonly number[]): StudioWorkspace;
+/**
+ * Puts one library tool back to its start, for every agent that allows it. Which agents allow it
+ * stays as it is. A tool already at its start returns the same workspace.
+ */
+export declare function resetLibraryTool(workspace: StudioWorkspace, toolKey: string): StudioWorkspace;
+/** The workspace with one provider as `provider` holds it, by its id. Every agent's models read it. */
+export declare function withProvider(workspace: StudioWorkspace, provider: StudioProvider): StudioWorkspace;
+/** How many models run on the provider `id`, and across how many agents. */
+export declare function providerUse(workspace: StudioWorkspace, id: string): {
+    models: number;
+    agents: number;
+};
+/**
+ * Who else calls the model `apiId` on the provider `id`, besides the model `bindingKey` of the
+ * agent `agentKey`: that agent's other models, by id, and the other agents, by name.
+ */
+export declare function modelSharers(workspace: Pick<StudioWorkspace, 'agents'>, agentKey: string, bindingKey: string, id: string, apiId: string): {
+    models: string[];
+    agents: string[];
+};
+/** A provider from the kernel definition `definition` under the first free id: what the + beside a provider picker adds. */
+export declare function newProvider(taken: Iterable<string>, definition: string): StudioProvider;
+/** Adds a provider for every agent's models to pick, and opens it. One whose id is taken changes nothing. */
+export declare function addProvider(workspace: StudioWorkspace, provider: StudioProvider): StudioWorkspace;
+/**
+ * Removes a provider no model runs on. One a model runs on stays: a model has no provider to fall
+ * to, so its models move first.
+ */
+export declare function removeProvider(workspace: StudioWorkspace, id: string): StudioWorkspace;
+/**
+ * Renames the provider `from` to `to`, and every model that runs on it with it. A blank or taken
+ * `to` changes nothing. Only a provider the files do not hold yet is renamed: code names the others.
+ */
+export declare function renameProvider(workspace: StudioWorkspace, from: string, to: string): StudioWorkspace;
+/** The providers that are as they started: the ones the project's files still say. */
+export declare function providersAtStart(workspace: StudioWorkspace): string[];
+/** Puts one provider back to its start. A provider already at its start returns the same workspace. */
+export declare function resetProvider(workspace: StudioWorkspace, id: string): StudioWorkspace;
+export interface WorkspaceTree {
+    /** One root per agent; its tools are picked in its Tools facet, not listed under it. */
+    agents: StudioTreeNode[];
+    /** The shared library. */
+    tools: StudioTreeNode[];
+}
+export declare function workspaceTree(workspace: StudioWorkspace): WorkspaceTree;