@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/live.js

@@ -0,0 +1,96 @@
+/**
+ * A voice call with one of the project's live profiles: the page's socket on one side, the
+ * project's own session on the other. The call opens with the page's open message, as a call to
+ * the application's relay does.
+ *
+ * @module
+ */
+import { resolveObservabilityPolicy, runSession, TheoremError, } from '@theoremjs/agents';
+import { clientError } from '@theoremjs/agents/host';
+import { createMemorySessionStore, createTheoremSessionBoundary, parseLiveOpenMessage, } from '@theoremjs/react/server';
+import { attachStudioLiveSession } from "../live-session-bridge.js";
+import { STUDIO_READER } from "../reader.js";
+/** The call's records reach the page through its own sink, so the bridge has no route to close. */
+const NO_ROUTE = { metadata: {}, close: () => { } };
+/**
+ * Where a call's trace goes: to the page, as each record is written. A call made in the studio is
+ * a test, so its records stay out of the store the profile writes to. A profile that records
+ * nothing sends nothing, and what the profile keeps private stays out, as in any trace.
+ */
+function pageSink(socket, profile) {
+    if (!resolveObservabilityPolicy(profile.observability).record)
+        return undefined;
+    return {
+        write: (record) => {
+            const line = { type: 'trace', record };
+            if (socket.readyState === WebSocket.OPEN)
+                socket.send(JSON.stringify(line));
+            return Promise.resolve();
+        },
+    };
+}
+/** The page's first message. A failure when it is malformed, or the page leaves before it. */
+function openMessage(socket) {
+    return new Promise((resolve, reject) => {
+        const onMessage = (event) => {
+            socket.removeEventListener('close', onClose);
+            try {
+                resolve(parseLiveOpenMessage(typeof event.data === 'string' ? event.data : ''));
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        const onClose = () => {
+            socket.removeEventListener('message', onMessage);
+            // labels-exempt: internal diagnostic; the user reads error.network
+            reject(new TheoremError('network', 'Live socket closed before its first message'));
+        };
+        socket.addEventListener('message', onMessage, { once: true });
+        socket.addEventListener('close', onClose, { once: true });
+    });
+}
+/** Runs the call until either side ends it. A failure to open reaches the page worded, with its kind. */
+async function relay(socket, profile, provider, boundary) {
+    let session;
+    try {
+        // Listen before anything waits: the page sends its open message as the socket opens.
+        const open = await openMessage(socket);
+        session = await runSession({ ...(await boundary.prepareLiveOpen(open)), profile: profile.id }, { ...provider, execution: boundary.toolExecution, pageExecution: boundary.pageExecution }, pageSink(socket, profile));
+    }
+    catch (error) {
+        if (socket.readyState !== WebSocket.OPEN)
+            return;
+        socket.send(JSON.stringify({ type: 'error', ...clientError(error, profile.labels, STUDIO_READER) }));
+        socket.close(1011, 'session error');
+        return;
+    }
+    // The page may have left while the session opened; its close event has already fired.
+    if (socket.readyState !== WebSocket.OPEN) {
+        await session.close('client disconnected');
+        return;
+    }
+    await attachStudioLiveSession(socket, session, profile.id, crypto.randomUUID(), NO_ROUTE, profile.labels, {
+        clientEvents: STUDIO_READER,
+        pageResult: boundary.answerPageResult,
+        beforeEvent: async (event) => {
+            if ((event.type === 'done' || event.type === 'provider_checkpoint') && event.providerState)
+                await boundary.recordCheckpoint(event.providerState);
+        },
+    });
+}
+/** Serves a live profile: a socket upgrade starts a call, and anything else is told to upgrade. */
+export function createStudioLiveHandler(profile, provider, upgrade) {
+    const sessionStore = createMemorySessionStore();
+    return async (request) => {
+        if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
+            return new Response(null, { status: 426, headers: { upgrade: 'websocket' } });
+        }
+        const boundary = await createTheoremSessionBoundary({ request, sessionStore });
+        const { socket, response } = upgrade(request);
+        if (boundary.setCookie)
+            response.headers.append('set-cookie', boundary.setCookie);
+        void relay(socket, profile, provider, boundary);
+        return response;
+    };
+}

package/server/open-editor.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Opens one of the project's files in the builder's editor, on a line. The
+ * studio starts the editor's own command and never a shell, and only for a
+ * file the project's setup reads.
+ *
+ * @module
+ */
+import type { OpenAnswer, OpenRequest } from './save-wire.ts';
+/**
+ * The editor the studio starts: the one the command named, else the first of the environment's
+ * that opens in a window, else VS Code. A terminal editor in `$EDITOR` is passed over, since the
+ * studio has no terminal to run it in.
+ */
+export declare function chosenEditor(flag: string | undefined, environment: readonly (string | undefined)[]): string;
+/** The command that opens `file` at `line` in an editor, or undefined when the studio does not know the editor. */
+export declare function editorCommand(editor: string, file: string, line: number | undefined): {
+    command: string;
+    args: string[];
+} | undefined;
+/**
+ * Where an editor's command is when it is not on the path: inside its macOS app, in the machine's
+ * Applications folder and then the builder's own. Empty for an editor with no known app, and off macOS.
+ */
+export declare function installedCommands(editor: string, os: string | undefined, home: string | undefined): string[];
+/**
+ * The machine's own way to open a file in its default editor, or undefined where it has none that
+ * is safe: macOS opens it as text and Linux asks the desktop. Windows is left out, since its
+ * default for a script is to run it.
+ */
+export declare function defaultOpener(os: string, file: string): {
+    command: string;
+    args: string[];
+} | undefined;
+/** What opening needs from the machine. */
+export interface EditorHost {
+    /** The editor's command, as the builder set it when the studio started. */
+    editor: string;
+    /** The absolute path of a project file named from the project's folder, or undefined when the project has none there. */
+    place(file: string): string | undefined;
+    /** Starts a command without a shell. False when it did not start. */
+    start(command: string, args: string[]): boolean;
+    /** The machine's kind, as `defaultOpener` takes it; without one there is no default to fall back on. */
+    os?: string;
+    /** The builder's home folder, where an app of their own is installed. */
+    home?: string;
+}
+/** The editor the studio starts when the page names none, by the command the studio lists it under. */
+export declare function defaultEditor(host: EditorHost): string;
+/**
+ * Opens the file a request names, in the editor it names or else the one the studio started with.
+ * The answer says which editor, or why not and the place to go to by hand. An editor whose command
+ * is not on the path is started from its app. When the editor is not one the studio can start, or
+ * did not start, the machine's default editor opens the file instead.
+ */
+export declare function openInEditor(host: EditorHost, request: OpenRequest): OpenAnswer;
+/**
+ * What the studio answers a request to open a file with, as a status and a body. Undefined when
+ * the request is not one.
+ */
+export declare function answerOpen(host: EditorHost, at: string, request: Request): Promise<{
+    status: number;
+    body: unknown;
+} | undefined>;

package/server/open-editor.js

@@ -0,0 +1,115 @@
+/**
+ * Opens one of the project's files in the builder's editor, on a line. The
+ * studio starts the editor's own command and never a shell, and only for a
+ * file the project's setup reads.
+ *
+ * @module
+ */
+import { basename } from 'node:path';
+import { isEditorChoice, studioEditor } from "../editors.js";
+/** The arguments each form of command takes for a file and a line. */
+const LINE_ARGS = {
+    goto: (file, line) => ['-g', `${file}:${line}`],
+    colon: (file, line) => [`${file}:${line}`],
+    'line-flag': (file, line) => ['--line', String(line), file],
+    'l-flag': (file, line) => ['-l', String(line), file],
+};
+/** The command an editor setting names: `code --wait` is `code`. */
+const commandOf = (editor) => editor.trim().split(/\s+/)[0] ?? '';
+/** An editor's command name as the table has it: `/usr/local/bin/Code.exe` is `code`. */
+function editorName(editor) {
+    return basename(commandOf(editor))
+        .toLowerCase()
+        .replace(/\.(exe|cmd|sh)$/, '');
+}
+/**
+ * The editor the studio starts: the one the command named, else the first of the environment's
+ * that opens in a window, else VS Code. A terminal editor in `$EDITOR` is passed over, since the
+ * studio has no terminal to run it in.
+ */
+export function chosenEditor(flag, environment) {
+    if (flag?.trim())
+        return flag;
+    return (environment.find((editor) => editor !== undefined && studioEditor(editorName(editor))) ?? 'code');
+}
+/** The command that opens `file` at `line` in an editor, or undefined when the studio does not know the editor. */
+export function editorCommand(editor, file, line) {
+    const known = studioEditor(editorName(editor));
+    if (!known)
+        return undefined;
+    return {
+        command: commandOf(editor),
+        args: line === undefined ? [file] : LINE_ARGS[known.form](file, line),
+    };
+}
+/**
+ * Where an editor's command is when it is not on the path: inside its macOS app, in the machine's
+ * Applications folder and then the builder's own. Empty for an editor with no known app, and off macOS.
+ */
+export function installedCommands(editor, os, home) {
+    const inApp = studioEditor(editorName(editor))?.macCommand;
+    if (os !== 'darwin' || !inApp)
+        return [];
+    return [`/Applications/${inApp}`, ...(home ? [`${home}/Applications/${inApp}`] : [])];
+}
+/**
+ * The machine's own way to open a file in its default editor, or undefined where it has none that
+ * is safe: macOS opens it as text and Linux asks the desktop. Windows is left out, since its
+ * default for a script is to run it.
+ */
+export function defaultOpener(os, file) {
+    if (os === 'darwin')
+        return { command: 'open', args: ['-t', file] };
+    if (os === 'linux')
+        return { command: 'xdg-open', args: [file] };
+    return undefined;
+}
+/**
+ * A page may name the editor only by a command Settings offers, exactly: never a path or a
+ * command of its own, since the studio starts what is named.
+ */
+function isOpenRequest(body) {
+    const { file, line, editor } = (body ?? {});
+    if (editor !== undefined && (typeof editor !== 'string' || !isEditorChoice(editor)))
+        return false;
+    return typeof file === 'string' && (line === undefined || (Number.isInteger(line) && line > 0));
+}
+/** The editor the studio starts when the page names none, by the command the studio lists it under. */
+export function defaultEditor(host) {
+    return editorName(host.editor);
+}
+/**
+ * Opens the file a request names, in the editor it names or else the one the studio started with.
+ * The answer says which editor, or why not and the place to go to by hand. An editor whose command
+ * is not on the path is started from its app. When the editor is not one the studio can start, or
+ * did not start, the machine's default editor opens the file instead.
+ */
+export function openInEditor(host, request) {
+    const path = host.place(request.file);
+    if (path === undefined)
+        return { ok: false, reason: 'file' };
+    // Only a command the studio lists is taken from the page; `answerOpen` refuses any other.
+    const named = request.editor !== undefined && isEditorChoice(request.editor) ? request.editor : host.editor;
+    const editor = editorName(named);
+    const place = request.line === undefined ? path : `${path}:${request.line}`;
+    const run = editorCommand(named, path, request.line);
+    const commands = run ? [run.command, ...installedCommands(named, host.os, host.home)] : [];
+    if (run && commands.some((command) => host.start(command, run.args)))
+        return { ok: true, editor };
+    const other = host.os === undefined ? undefined : defaultOpener(host.os, path);
+    if (other && host.start(other.command, other.args))
+        return { ok: true, editor, byDefault: true };
+    return { ok: false, reason: run ? 'failed' : 'editor', editor, place };
+}
+/**
+ * What the studio answers a request to open a file with, as a status and a body. Undefined when
+ * the request is not one.
+ */
+export async function answerOpen(host, at, request) {
+    if (request.method !== 'POST' || new URL(request.url).pathname !== at)
+        return undefined;
+    const body = await request.json().catch(() => null);
+    return isOpenRequest(body)
+        ? { status: 200, body: openInEditor(host, body) }
+        : { status: 400, body: {} };
+}

package/server/origins.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which of a project's settings its files set in code. The studio shows those
+ * and does not change them, and says where each one is. It also says where each
+ * value others read too is written, so a change to one is asked about first. It
+ * reads the same way Save plans a change (`save-plan.ts`), so what a row says is
+ * what Save would do. A tool's schema is open when it reads as Zod: Save changes
+ * it there, and says in its review which part, if any, is left for code.
+ *
+ * @module
+ */
+import { type ProjectSource } from './project-source.ts';
+import type { ProjectOrigins } from './save-wire.ts';
+/**
+ * The settings the project's files set in code, for each profile, tool, and provider the files
+ * define. One with none is left out. `decisions` names the decision profiles the studio
+ * shows: each one's questions and pictures are set in the setup module.
+ */
+export declare function sourceOrigins(project: ProjectSource, decisions?: readonly string[]): ProjectOrigins;

package/server/origins.js

@@ -0,0 +1,330 @@
+/**
+ * Which of a project's settings its files set in code. The studio shows those
+ * and does not change them, and says where each one is. It also says where each
+ * value others read too is written, so a change to one is asked about first. It
+ * reads the same way Save plans a change (`save-plan.ts`), so what a row says is
+ * what Save would do. A tool's schema is open when it reads as Zod: Save changes
+ * it there, and says in its review which part, if any, is left for code.
+ *
+ * @module
+ */
+import ts from 'typescript';
+import { followed, holderOf, isHeldId, isInCall, isInTarget, isKernelName, propertyName, setupExport, shapeOf, unwrapped, usersOf, } from "./project-source.js";
+import { NOT_PLAIN, plain } from "./save-plan.js";
+import { readZod, zodObject } from "./zod-edit.js";
+/** The most of an expression a row shows. */
+const TEXT_LENGTH = 48;
+/** An expression as the file writes it, on one line and cut to fit a row. */
+function textOf(node, source) {
+    const text = node.getText(source).replace(/\s+/g, ' ');
+    return text.length > TEXT_LENGTH ? `${text.slice(0, TEXT_LENGTH - 1)}…` : text;
+}
+function lineOf(node, source) {
+    return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+}
+/** A tool's schemas are its `input` and `output` in the file, written in Zod there. */
+const TOOL_SCHEMAS = { input: 'inputSchema', output: 'outputSchema' };
+class Reader {
+    project;
+    kind;
+    target;
+    found = [];
+    /** Where each value the walk followed a name to is written, the whole target first. */
+    written = [];
+    constructor(project, kind, target) {
+        this.project = project;
+        this.kind = kind;
+        this.target = target;
+    }
+    note(kind, path, at, more = {}) {
+        this.found.push({
+            path,
+            kind,
+            text: textOf(at.node, at.source),
+            file: at.source.fileName,
+            line: lineOf(at.node, at.source),
+            ...more,
+        });
+    }
+    /** The whole target. */
+    read() {
+        const { options, source, env, call } = this.target;
+        // A function that makes the call holds it for each profile it makes.
+        const maker = call && holderOf({ node: options, source })?.name;
+        this.written.push({
+            path: [],
+            at: { node: options, source },
+            ...(maker ? { name: maker } : {}),
+        });
+        this.walk({ node: options, source, env }, []);
+    }
+    /** What holds `at`: the target's own options, a constant or a function, or nothing the studio follows. */
+    regionOf(at) {
+        if (isInTarget(this.target, at))
+            return this.target.options;
+        return isInCall(this.target, at) ? this.target.call?.node : holderOf(at)?.initializer;
+    }
+    walk(at, path) {
+        const node = unwrapped(at.node);
+        if (plain(node) !== NOT_PLAIN)
+            return;
+        const here = { ...at, node };
+        const shape = shapeOf(this.project, here);
+        if (shape) {
+            this.object(shape, here, path);
+            return;
+        }
+        const whole = ts.isArrayLiteralExpression(node) &&
+            !node.elements.some((element) => ts.isSpreadElement(element) || ts.isOmittedExpression(element));
+        if (whole) {
+            for (const [index, element] of node.elements.entries())
+                this.walk({ ...at, node: element }, [...path, String(index)]);
+            return;
+        }
+        this.named(here, path);
+    }
+    /** A value the files reach by a name, a call, or a key: read where it is written. */
+    named(at, path) {
+        const origin = followed(this.project, at);
+        if (origin.node === at.node && origin.source === at.source)
+            this.note('code', path, at);
+        else
+            this.enter(origin, path, at);
+    }
+    /**
+     * A value written somewhere other than where the walk is. In the target's own call it is the
+     * target's. In a constant or a function it is read there, with each line of other code that
+     * reads it too.
+     */
+    enter(origin, path, from) {
+        if (isInTarget(this.target, origin) || isInCall(this.target, origin)) {
+            this.written.push({ path, at: origin });
+            this.walk(origin, path);
+            return;
+        }
+        const holder = holderOf(origin);
+        if (!holder)
+            this.note('code', path, from);
+        else {
+            const users = usersOf(this.project, holder);
+            if (users.code && isHeldId(this.kind, path, origin)) {
+                this.note('constant', path, { node: holder.initializer.parent, source: holder.source }, { text: holder.name });
+                return;
+            }
+            const readBy = users.readBy.map((read) => ({
+                file: read.source.fileName,
+                line: lineOf(read.node, read.source),
+            }));
+            this.written.push({ path, at: origin, name: holder.name, ...(users.code ? { readBy } : {}) });
+            this.walk(origin, path);
+        }
+    }
+    object(shape, at, path) {
+        const { open } = shape;
+        const region = this.regionOf(at);
+        // The last one of a name is the one that counts.
+        for (const entry of [...shape.entries.values()].reverse()) {
+            const schema = this.kind === 'tool' && path.length === 0 ? TOOL_SCHEMAS[entry.key] : undefined;
+            const here = [...path, schema ?? entry.key];
+            const place = entry.property ? { node: entry.property, source: entry.source } : at;
+            if (schema) {
+                if (entry.value && !(open && !open.after.has(entry.key)))
+                    this.schema(entry.value, here, place);
+                else
+                    this.note('code', here, place);
+            } // A spread, or a key the file computes: what the object holds past it is not written here.
+            else if (open && !open.after.has(entry.key))
+                this.note('code', here, open);
+            // A model's provider is the name its line is built on: a change rewrites the name, never the provider's id.
+            else if (entry.receiver) {
+                const named = entry.value && ts.isIdentifier(unwrapped(entry.receiver.node));
+                if (!named)
+                    this.note('code', here, { node: entry.receiver.node, source: entry.receiver.source });
+            }
+            else if (!entry.value)
+                this.note('code', here, place);
+            // A model's protocol is the kernel's name for it: Save rewrites the name.
+            else if (entry.key === 'protocol' && isKernelName(entry.value))
+                continue;
+            else if (entry.property && ts.isShorthandPropertyAssignment(entry.property))
+                this.named(entry.value, here);
+            else if (this.regionOf(entry.value) === region)
+                this.walk(entry.value, here);
+            else
+                this.enter(entry.value, here, place);
+        }
+        if (open)
+            this.note('spread', path, open, { written: [...open.after] });
+    }
+    /** A tool's schema. One that does not read as Zod is code's to change. */
+    schema(at, path, place) {
+        const read = readZod(this.project, at);
+        if (read)
+            this.zod(read, path, this.target.options);
+        else
+            this.note('code', path, place);
+    }
+    /**
+     * Each constant a schema is written in, at the part of the schema it writes: the schema several
+     * tools take, a field's schema a constant holds. The place is the part's own `z.` call, so two
+     * tools that reach one call hold one value. `within` is what holds the schema around this one:
+     * the target's own call, or a constant.
+     */
+    zod(read, path, within) {
+        /** Notes `node` at `at` when another constant than `outer` holds it, and says which one does. */
+        const reach = (node, source, at, outer) => {
+            const place = { node: node, source };
+            if (isInTarget(this.target, place))
+                return this.target.options;
+            if (this.target.call && isInCall(this.target, place))
+                return this.target.call.node;
+            const holder = holderOf(place);
+            if (!holder || holder.initializer === outer)
+                return outer;
+            const users = usersOf(this.project, holder);
+            const readBy = users.readBy.map((each) => ({
+                file: each.source.fileName,
+                line: lineOf(each.node, each.source),
+            }));
+            this.written.push({
+                path: at,
+                at: { node, source },
+                name: holder.name,
+                ...(users.code ? { readBy } : {}),
+            });
+            return holder.initializer;
+        };
+        const { base } = read;
+        const around = reach(base.call, base.source, path, within);
+        const inside = (node, at) => {
+            const part = readZod(this.project, {
+                node,
+                source: base.source,
+                ...(base.env ? { env: base.env } : {}),
+            });
+            if (part)
+                this.zod(part, at, around);
+        };
+        const [first] = base.call.arguments;
+        const list = first && base.name === 'union' ? unwrapped(first) : undefined;
+        if (first && base.name === 'array' && !ts.isSpreadElement(first))
+            inside(first, [...path, 'items']);
+        if (list && ts.isArrayLiteralExpression(list)) {
+            list.elements.forEach((member, index) => {
+                if (!ts.isSpreadElement(member))
+                    inside(member, [...path, 'anyOf', String(index)]);
+            });
+        }
+        const object = zodObject(this.project, read);
+        if (!object)
+            return;
+        for (const entry of object.entries.values()) {
+            const part = entry.value && readZod(this.project, entry.value);
+            if (part)
+                this.zod(part, [...path, 'properties', entry.key], around);
+        }
+        // Which fields an extended object needs is its own to say.
+        if (object.extended)
+            reach(object.own.node, object.own.source, [...path, 'required'], around);
+    }
+}
+function originsOf(project, kind, targets) {
+    const [target] = targets;
+    if (!target)
+        return { origins: [], written: [] };
+    if (targets.length > 1) {
+        // Written twice: the studio cannot tell which one runs.
+        const twice = {
+            path: [],
+            kind: 'twice',
+            file: target.file,
+            line: lineOf(target.options, target.source),
+        };
+        return { origins: [twice], written: [] };
+    }
+    const reader = new Reader(project, kind, target);
+    reader.read();
+    return { origins: reader.found, written: reader.written };
+}
+/**
+ * Where a decision profile's questions or pictures are set: the setup module's export of `name`,
+ * at the profile's own key when it writes one. A profile does not hold them, so the studio shows
+ * them and does not change them. No place when the setup exports them another way.
+ */
+function setupOrigin(project, profileId, name) {
+    const origin = {
+        path: ['decision', name],
+        kind: 'code',
+        text: `export const ${name}`,
+    };
+    const source = project.files.get(project.entry);
+    const held = source && setupExport(source, name);
+    if (!source || !held)
+        return origin;
+    const value = held.initializer && unwrapped(held.initializer);
+    const own = value && ts.isObjectLiteralExpression(value)
+        ? value.properties.findLast((property) => propertyName(property) === profileId)
+        : undefined;
+    return { ...origin, file: source.fileName, line: lineOf(own ?? held, source) };
+}
+/**
+ * The settings the project's files set in code, for each profile, tool, and provider the files
+ * define. One with none is left out. `decisions` names the decision profiles the studio
+ * shows: each one's questions and pictures are set in the setup module.
+ */
+export function sourceOrigins(project, decisions = []) {
+    const places = new Map();
+    const read = (kind, targets) => {
+        const origins = {};
+        const written = {};
+        for (const [name, held] of targets) {
+            const found = originsOf(project, kind, held);
+            if (found.origins.length)
+                origins[name] = found.origins;
+            written[name] = found.written;
+            for (const { at } of found.written) {
+                const place = places.get(at.node) ?? { site: places.size + 1, held: 0 };
+                places.set(at.node, { ...place, held: place.held + 1 });
+            }
+        }
+        return { origins, written };
+    };
+    const [profiles, tools] = [read('profile', project.profiles), read('tool', project.tools)];
+    const providers = read('provider', project.providers);
+    for (const id of decisions)
+        profiles.origins[id] = [
+            ...(profiles.origins[id] ?? []),
+            setupOrigin(project, id, 'questions'),
+            setupOrigin(project, id, 'images'),
+        ];
+    /** The places something else reads too, and under each of them the ones a setting has to itself. */
+    const sites = (written) => {
+        const sites = {};
+        for (const [name, held] of Object.entries(written)) {
+            const shared = held.filter(({ at }) => (places.get(at.node)?.held ?? 0) > 1);
+            const reached = held.filter((each) => shared.includes(each) || each.readBy);
+            const under = (path) => reached.some((each) => each.path.every((key, index) => path[index] === key));
+            const kept = held.filter((each) => under(each.path));
+            if (!reached.length)
+                continue;
+            sites[name] = kept.map(({ path, at, name: holder, readBy }) => ({
+                path,
+                site: places.get(at.node)?.site ?? 0,
+                shared: shared.some((each) => each.at.node === at.node),
+                ...(holder ? { name: holder } : {}),
+                file: at.source.fileName,
+                line: lineOf(at.node, at.source),
+                ...(readBy ? { readBy } : {}),
+            }));
+        }
+        return sites;
+    };
+    const held = { profiles: sites(profiles.written), tools: sites(tools.written) };
+    const some = Object.keys(held.profiles).length + Object.keys(held.tools).length > 0;
+    return {
+        profiles: profiles.origins,
+        tools: tools.origins,
+        providers: providers.origins,
+        ...(some ? { sites: held } : {}),
+    };
+}