@valerypopoff/rivet2-cli 2.0.11 → 2.1.1

package/README.md

@@ -6,8 +6,13 @@ Command-line tools for running and serving Rivet 2 projects through the Node run
 
 ```bash
 npx @valerypopoff/rivet2-cli --help
+npx @valerypopoff/rivet2-cli list my-project.rivet-project
+npx @valerypopoff/rivet2-cli inspect my-project.rivet-project
+npx @valerypopoff/rivet2-cli doctor my-project.rivet-project
 npx @valerypopoff/rivet2-cli run my-project.rivet-project
 npx @valerypopoff/rivet2-cli serve my-project.rivet-project --port 8080
+npx @valerypopoff/rivet2-cli serve-app my-project.rivet-project "My web app"
+npx @valerypopoff/rivet2-cli completion
 ```
 
 The CLI package exposes the `rivet` binary when installed globally:
@@ -23,6 +28,13 @@ rivet --help
 yarn workspace @valerypopoff/rivet2-cli run build
 yarn workspace @valerypopoff/rivet2-cli run test
 yarn workspace @valerypopoff/rivet2-cli run lint
+yarn workspace @valerypopoff/rivet2-cli run smoke:package
+yarn workspace @valerypopoff/rivet2-cli run smoke:docker
+yarn workspace @valerypopoff/rivet2-cli run verify
 ```
 
+`smoke:package` is part of `verify` and checks the generated package contents, direct built binary, and installed `rivet` command. `smoke:docker` is opt-in because it requires a local Docker daemon; it removes its temporary smoke image after the check.
+
+Publish the public packages through the repo-root publish script or GitHub workflow, not by running `npm publish` inside `packages/cli`.
+
 See the root [README](../../README.md), [package docs](../../developer-docs/PACKAGES.md), and public CLI docs under [packages/docs/docs/cli.md](../docs/docs/cli.md).

package/bin/cli.js

@@ -1,10 +1,36 @@
 #!/usr/bin/env node
+import chalk from 'chalk';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
+import { inspect, list, makeInspectCommand, makeListCommand, } from './commands/list.js';
+import { doctor, makeDoctorCommand } from './commands/doctor.js';
 import { makeCommand as makeRunCommand, run } from './commands/run.js';
 import { makeCommand as makeServeCommand, serve } from './commands/serve.js';
+import { makeCommand as makeServeAppCommand, serveApp } from './commands/serveApp.js';
 await yargs(hideBin(process.argv))
-    .command('run <projectFile> [graphName]', 'Run a graph in a project file, or the main graph if graphName is not specified.', (y) => makeRunCommand(y), (args) => run(args))
-    .command('serve [projectFile]', 'Serve a project file as a REST API.', (y) => makeServeCommand(y), (args) => serve(args))
+    .command('list <projectFile>', 'List graphs, web apps, library nodes, and plugins in a project file.', (y) => makeListCommand(y), (args) => runCli(() => list(args)))
+    .command('inspect <projectFile>', 'Print a machine-readable project summary.', (y) => makeInspectCommand(y), (args) => runCli(() => inspect(args.projectFile)))
+    .command('doctor <projectFile>', 'Check a project file for common CLI/runtime problems.', (y) => makeDoctorCommand(y), (args) => runCli(() => doctor(args)))
+    .command('run <projectFile> [graphName]', 'Run a graph in a project file, or the main graph if graphName is not specified.', (y) => makeRunCommand(y), (args) => runCli(() => run(args)))
+    .command('serve [projectFile]', 'Serve a project file as a REST API.', (y) => makeServeCommand(y), (args) => runCli(() => serve(args)))
+    .command('serve-app <projectFile> [uiGraph]', 'Serve a project-contained Rivet web app.', (y) => makeServeAppCommand(y), (args) => runCli(() => serveApp(args)))
+    .completion('completion', 'Generate a shell completion script.')
     .demandCommand()
     .parseAsync();
+async function runCli(action) {
+    try {
+        await action();
+    }
+    catch (err) {
+        console.error(chalk.red(formatCliError(err)));
+        process.exit(1);
+    }
+}
+function formatCliError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const stack = err instanceof Error ? err.stack : undefined;
+    if (!process.env.RIVET_CLI_DEBUG || !stack) {
+        return `Error: ${message}`;
+    }
+    return `Error: ${message}\n\n${stack}`;
+}

package/bin/cliRuntime.js

@@ -0,0 +1,228 @@
+import { loadProjectFromFile, NodeDatasetProvider, } from '@valerypopoff/rivet2-node';
+import chalk from 'chalk';
+import didYouMean from 'didyoumean2';
+import { readdir, stat } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+export async function loadProjectRuntime(projectFile, datasetOptions) {
+    const projectPath = await getProjectFile(projectFile);
+    const project = await loadProjectFromFile(projectPath);
+    const datasetProvider = await createDatasetProvider(projectPath, datasetOptions);
+    return { datasetProvider, project, projectPath };
+}
+export async function createDatasetProvider(projectPath, { datasetFile, requireDatasetFile = false, saveDatasets = false }) {
+    const datasetsFilePath = resolveDatasetFilePath(projectPath, datasetFile);
+    if (datasetFile) {
+        return NodeDatasetProvider.fromDatasetsFile(datasetsFilePath, {
+            requireFile: requireDatasetFile,
+            save: saveDatasets,
+        });
+    }
+    return NodeDatasetProvider.fromProjectFile(projectPath, {
+        requireFile: requireDatasetFile,
+        save: saveDatasets,
+    });
+}
+export function resolveDatasetFilePath(projectPath, datasetFile) {
+    return datasetFile ? resolve(process.cwd(), datasetFile) : projectPath.replace(/\.rivet-project$/i, '.rivet-data');
+}
+export function withRuntimeProcessorOptions(runtime, options) {
+    return {
+        ...options,
+        datasetProvider: runtime.datasetProvider,
+        projectPath: runtime.projectPath,
+    };
+}
+export function withCliProcessorOptions(runtime, providerOptions, options) {
+    return withRuntimeProcessorOptions(runtime, withProviderProcessorOptions(providerOptions, options));
+}
+export function withProviderProcessorOptions(providerOptions, options) {
+    const providerSettings = {};
+    if (providerOptions.openaiEndpoint != null) {
+        providerSettings.openAiEndpoint = providerOptions.openaiEndpoint;
+    }
+    if (providerOptions.openaiApiKey != null) {
+        providerSettings.openAiKey = providerOptions.openaiApiKey;
+    }
+    if (providerOptions.openaiOrganization != null) {
+        providerSettings.openAiOrganization = providerOptions.openaiOrganization;
+    }
+    return {
+        ...options,
+        ...providerSettings,
+    };
+}
+export function addProviderOptions(y) {
+    return y
+        .option('openai-api-key', {
+        describe: 'The OpenAI API key to use for the project. If omitted, the environment variable OPENAI_API_KEY is used.',
+        type: 'string',
+        demandOption: false,
+    })
+        .option('openai-endpoint', {
+        describe: 'The OpenAI API endpoint to use for the project. If omitted, the environment variable OPENAI_ENDPOINT is used.',
+        type: 'string',
+        demandOption: false,
+    })
+        .option('openai-organization', {
+        describe: 'The OpenAI organization to use for the project. If omitted, the environment variable OPENAI_ORGANIZATION is used.',
+        type: 'string',
+        demandOption: false,
+    });
+}
+export function addDatasetOptions(y, { includeSaveDatasets = true } = {}) {
+    let result = y.option('dataset-file', {
+        describe: 'Use a specific .rivet-data file instead of the project-adjacent default',
+        type: 'string',
+    });
+    if (includeSaveDatasets) {
+        result = result.option('save-datasets', {
+            describe: 'Persist dataset mutations back to the dataset file',
+            type: 'boolean',
+            default: false,
+        });
+    }
+    return result.option('require-dataset-file', {
+        describe: 'Fail if the dataset file does not exist',
+        type: 'boolean',
+        default: false,
+    });
+}
+export function warnIfServerSavesDatasets(saveDatasets, label = 'CLI server') {
+    if (!saveDatasets) {
+        return;
+    }
+    console.warn(chalk.yellow(`--save-datasets persists mutations from this ${label} process. Avoid concurrent production writes; use a wrapper with explicit write policy for shared deployments.`));
+}
+export function getGraphSummaries(project) {
+    return Object.values(project.graphs).map((graph) => ({
+        id: graph.metadata.id,
+        name: graph.metadata.name,
+    }));
+}
+export function findGraph(project, graphIdOrName) {
+    if (!graphIdOrName) {
+        return undefined;
+    }
+    return getGraphSummaries(project).find((graph) => graph.id === graphIdOrName || graph.name === graphIdOrName);
+}
+export function formatGraphList(project) {
+    return getGraphSummaries(project)
+        .map((graph) => `- "${graph.name}" (${graph.id})`)
+        .join('\n');
+}
+export function resolveServedGraphName(project, graph) {
+    const servedGraph = findGraph(project, graph ?? project.metadata.mainGraphId);
+    if (!servedGraph) {
+        throw new Error(`Project main graph "${project.metadata.mainGraphId}" was not found in the project file.`);
+    }
+    return servedGraph.name;
+}
+export function throwIfNoMainGraph(project, graph, projectFilePath, argumentStyle = 'option') {
+    if (project.metadata.mainGraphId || graph) {
+        return;
+    }
+    const validGraphs = getGraphSummaries(project);
+    if (validGraphs.length === 0) {
+        throw new Error('No graphs found in the project file. Please edit the project file in Rivet and add a graph.');
+    }
+    const firstExample = formatGraphSelectionExample(projectFilePath, validGraphs[0].id, argumentStyle);
+    const secondExample = formatGraphSelectionExample(projectFilePath, `"${validGraphs[0].name}"`, argumentStyle);
+    throw new Error(`No graph name provided, and project does not specify a main graph. Valid graphs are: \n\n${formatGraphList(project)}\n\nUse either the graph's name or its ID. For example, \n- \`${chalk.bold(firstExample)}\` or\n- \`${chalk.bold(secondExample)}\``);
+}
+export function throwIfInvalidGraph(project, graph, argumentStyle = 'option') {
+    if (!graph) {
+        const mainGraphId = project.metadata.mainGraphId;
+        if (!mainGraphId || findGraph(project, mainGraphId)) {
+            return;
+        }
+        throw new Error(`Project main graph "${mainGraphId}" was not found in the project file.`);
+    }
+    if (findGraph(project, graph)) {
+        return;
+    }
+    const validGraphsAndIds = getGraphSummaries(project).flatMap((validGraph) => [validGraph.id, validGraph.name]);
+    const suggestion = didYouMean(graph, validGraphsAndIds);
+    if (suggestion) {
+        const suggestedArgument = formatGraphArgument(suggestion, argumentStyle);
+        throw new Error(`Graph "${graph}" not found in project file. Did you mean \`${chalk.bold(suggestedArgument)}\`?`);
+    }
+    throw new Error(`Graph "${graph}" not found in project file. Valid graphs are: \n${formatGraphList(project)}`);
+}
+function formatGraphSelectionExample(projectFilePath, graph, argumentStyle) {
+    return argumentStyle === 'positional'
+        ? `rivet run ${projectFilePath} ${graph}`
+        : `rivet serve ${projectFilePath} --graph ${graph}`;
+}
+function formatGraphArgument(graph, argumentStyle) {
+    return argumentStyle === 'positional' ? `"${graph}"` : `--graph "${graph}"`;
+}
+export function getUiGraphSummaries(project) {
+    return Object.values(project.uiGraphs ?? {}).map((uiGraph) => ({
+        id: uiGraph.id,
+        name: uiGraph.name,
+    }));
+}
+export function resolveUiGraph(project, uiGraphIdOrName) {
+    const uiGraphs = Object.values(project.uiGraphs ?? {});
+    if (uiGraphIdOrName) {
+        const uiGraph = uiGraphs.find((candidate) => candidate.id === uiGraphIdOrName || candidate.name === uiGraphIdOrName);
+        if (uiGraph) {
+            return uiGraph;
+        }
+        const validUiGraphs = getUiGraphSummaries(project).flatMap((uiGraph) => [uiGraph.id, uiGraph.name]);
+        const suggestion = didYouMean(uiGraphIdOrName, validUiGraphs);
+        const suffix = suggestion ? ` Did you mean "${suggestion}"?` : '';
+        throw new Error(`Web app "${uiGraphIdOrName}" not found in project file.${suffix}`);
+    }
+    if (uiGraphs.length === 1) {
+        return uiGraphs[0];
+    }
+    if (uiGraphs.length === 0) {
+        throw new Error('No Rivet web apps found in the project file.');
+    }
+    const validUiGraphs = getUiGraphSummaries(project)
+        .map((uiGraph) => `- "${uiGraph.name}" (${uiGraph.id})`)
+        .join('\n');
+    throw new Error(`Multiple Rivet web apps found. Specify one by name or ID:\n${validUiGraphs}`);
+}
+export async function getProjectFile(initialProjectFilePath) {
+    let projectFilePath = resolve(process.cwd(), initialProjectFilePath ?? (await getProjectFilePathFromDirectory(process.cwd())));
+    await throwIfMissingFile(projectFilePath);
+    if ((await stat(projectFilePath)).isDirectory()) {
+        projectFilePath = await getProjectFilePathFromDirectory(projectFilePath);
+    }
+    return projectFilePath;
+}
+async function getProjectFilePathFromDirectory(directory) {
+    const files = await readdir(directory);
+    const projectFiles = files.filter((file) => extname(file).toLowerCase() === '.rivet-project');
+    if (projectFiles.length === 0) {
+        throw new Error('No project file found in the current directory. Project files should end with .rivet-project.');
+    }
+    if (projectFiles.length > 1) {
+        throw new Error(`Multiple project files found in the current directory. Please specify which one to serve: \n${projectFiles.join('\n')}`);
+    }
+    return join(directory, projectFiles[0]);
+}
+async function throwIfMissingFile(filePath) {
+    try {
+        await stat(filePath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        let possibleFiles = [];
+        try {
+            possibleFiles = await readdir(dirname(filePath));
+        }
+        catch {
+            throw new Error(`Could not find project file "${filePath}".`);
+        }
+        const suggestion = didYouMean(basename(filePath), possibleFiles);
+        if (suggestion) {
+            throw new Error(`Could not find project file "${filePath}". Did you mean "${join(dirname(filePath), suggestion)}"?`);
+        }
+        throw new Error(`Could not find project file "${filePath}".`);
+    }
+}

package/bin/commandInputs.js

@@ -1,3 +1,5 @@
+import { jsonValueToDataValue } from '@valerypopoff/rivet2-node';
+import { readFile } from 'node:fs/promises';
 function isInputRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -16,7 +18,7 @@ export function parseJsonInputRecord(text, source) {
     if (!isInputRecord(parsed)) {
         throw new Error(`${source} must be a JSON object.`);
     }
-    return parsed;
+    return Object.fromEntries(Object.entries(parsed).map(([key, value]) => [key, jsonValueToInputValue(value)]));
 }
 export function parseKeyValueInputRecord(values, source) {
     return Object.fromEntries(values.map((item) => {
@@ -31,3 +33,37 @@ export function parseKeyValueInputRecord(values, source) {
         return [key, item.slice(separatorIndex + 1)];
     }));
 }
+export function parseJsonKeyValueInputRecord(values, source) {
+    return Object.fromEntries(values.map((item) => {
+        const separatorIndex = item.indexOf('=');
+        if (separatorIndex <= 0) {
+            throw new Error(`Invalid ${source} value "${item}". Expected key=json.`);
+        }
+        const key = item.slice(0, separatorIndex).trim();
+        if (!key) {
+            throw new Error(`Invalid ${source} value "${item}". Expected a non-empty key.`);
+        }
+        const json = item.slice(separatorIndex + 1);
+        try {
+            return [key, jsonValueToInputValue(JSON.parse(json))];
+        }
+        catch (error) {
+            throw new Error(`Invalid ${source} value "${item}". Expected valid JSON after "=".`, { cause: error });
+        }
+    }));
+}
+export async function parseJsonInputRecordFromFile(filePath, source) {
+    return parseJsonInputRecord(await readFile(filePath, 'utf8'), source);
+}
+export function throwIfConflictingInputSources(sources, sourceKind) {
+    const enabledSources = sources.filter((source) => source.enabled).map((source) => source.name);
+    if (enabledSources.length > 1) {
+        throw new Error(`Use only one ${sourceKind} source. Received: ${enabledSources.join(', ')}.`);
+    }
+}
+function jsonValueToInputValue(value) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    return jsonValueToDataValue(value);
+}

package/bin/commands/doctor.js

@@ -0,0 +1,188 @@
+import { loadProjectFromFile } from '@valerypopoff/rivet2-node';
+import { access } from 'node:fs/promises';
+import { addDatasetOptions, findGraph, getGraphSummaries, getProjectFile, getUiGraphSummaries, resolveDatasetFilePath, } from '../cliRuntime.js';
+export function makeDoctorCommand(y) {
+    const command = y
+        .positional('projectFile', {
+        describe: 'The project file to check',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('json', {
+        describe: 'Print machine-readable JSON',
+        type: 'boolean',
+        default: false,
+    });
+    return addDatasetOptions(command, { includeSaveDatasets: false });
+}
+export async function doctor(args) {
+    const report = await buildDoctorReport(args.projectFile, args);
+    console.log(args.json ? JSON.stringify(report, null, 2) : formatDoctorReport(report));
+    if (!report.ok) {
+        process.exitCode = 1;
+    }
+}
+export async function buildDoctorReport(projectFile, options = {}) {
+    const projectPath = await getProjectFile(projectFile);
+    const project = await loadProjectFromFile(projectPath);
+    const checks = [
+        buildProjectCheck(project),
+        buildGraphCheck(project),
+        buildMainGraphCheck(project),
+        buildWebAppCheck(project),
+        buildNodeLibraryCheck(project),
+        buildPluginCheck(project),
+        buildProjectReferenceCheck(project.references ?? []),
+        await buildDatasetCheck(projectPath, options),
+    ];
+    const warnings = checks.filter((check) => check.status === 'warning').length;
+    const errors = checks.filter((check) => check.status === 'error').length;
+    return {
+        checks,
+        ok: errors === 0,
+        path: projectPath,
+        summary: {
+            errors,
+            warnings,
+        },
+    };
+}
+function buildProjectCheck(project) {
+    return {
+        id: 'project-file',
+        message: `Loaded project "${project.metadata.title}" (${project.metadata.id}).`,
+        status: 'ok',
+    };
+}
+function buildGraphCheck(project) {
+    const graphs = getGraphSummaries(project);
+    return graphs.length > 0
+        ? {
+            id: 'graphs',
+            message: `Found ${formatCount(graphs.length, 'graph')}.`,
+            status: 'ok',
+        }
+        : {
+            id: 'graphs',
+            message: 'No workflow graphs found.',
+            status: 'error',
+        };
+}
+function buildMainGraphCheck(project) {
+    const mainGraphId = project.metadata.mainGraphId;
+    if (!mainGraphId) {
+        return {
+            id: 'main-graph',
+            message: 'No main graph is set. Commands must specify a graph explicitly.',
+            status: 'warning',
+        };
+    }
+    const mainGraph = findGraph(project, mainGraphId);
+    return mainGraph
+        ? {
+            id: 'main-graph',
+            message: `Main graph resolves to "${mainGraph.name}" (${mainGraph.id}).`,
+            status: 'ok',
+        }
+        : {
+            id: 'main-graph',
+            message: `Main graph "${mainGraphId}" is set but does not exist.`,
+            status: 'error',
+        };
+}
+function buildWebAppCheck(project) {
+    const uiGraphs = getUiGraphSummaries(project);
+    return {
+        id: 'web-apps',
+        message: uiGraphs.length > 0
+            ? `Found ${formatCount(uiGraphs.length, 'Rivet web app')}.`
+            : 'No Rivet web apps found.',
+        status: 'ok',
+    };
+}
+function buildNodeLibraryCheck(project) {
+    const libraryNodes = Object.values(project.nodePrefabs ?? {});
+    return {
+        id: 'node-library',
+        message: libraryNodes.length > 0
+            ? `Found ${formatCount(libraryNodes.length, 'Node library item')}.`
+            : 'No Node library items found.',
+        status: 'ok',
+    };
+}
+function buildPluginCheck(project) {
+    const plugins = project.plugins ?? [];
+    return {
+        id: 'plugins',
+        message: plugins.length > 0
+            ? `Project declares ${formatCount(plugins.length, 'plugin')}: ${plugins.map(formatPlugin).join(', ')}.`
+            : 'No plugins declared.',
+        status: 'ok',
+    };
+}
+function buildProjectReferenceCheck(references) {
+    const missingHints = references.filter((reference) => !reference.hintPaths || reference.hintPaths.length === 0);
+    if (references.length === 0) {
+        return {
+            id: 'project-references',
+            message: 'No project references declared.',
+            status: 'ok',
+        };
+    }
+    if (missingHints.length > 0) {
+        return {
+            id: 'project-references',
+            message: `${formatCount(missingHints.length, 'project reference')} has no hint paths. Runtime resolution may depend on the host loader.`,
+            status: 'warning',
+        };
+    }
+    return {
+        id: 'project-references',
+        message: `Found ${formatCount(references.length, 'project reference')} with hint paths.`,
+        status: 'ok',
+    };
+}
+async function buildDatasetCheck(projectPath, options) {
+    const datasetPath = resolveDatasetFilePath(projectPath, options.datasetFile);
+    if (await fileExists(datasetPath)) {
+        return {
+            id: 'dataset-file',
+            message: `Dataset file found at ${datasetPath}.`,
+            status: 'ok',
+        };
+    }
+    return {
+        id: 'dataset-file',
+        message: `Dataset file not found at ${datasetPath}; runs will start without datasets.`,
+        status: options.requireDatasetFile ? 'error' : 'ok',
+    };
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function formatDoctorReport(report) {
+    const status = report.ok ? 'OK' : 'Needs attention';
+    const lines = [
+        'Rivet project doctor',
+        `Path: ${report.path}`,
+        `Status: ${status} (${report.summary.errors} errors, ${report.summary.warnings} warnings)`,
+        '',
+        ...report.checks.map((check) => `${formatCheckStatus(check.status)} ${check.message}`),
+    ];
+    return lines.join('\n');
+}
+function formatCheckStatus(status) {
+    return status === 'ok' ? '[ok]  ' : status === 'warning' ? '[warn]' : '[err] ';
+}
+function formatCount(count, singular) {
+    return `${count} ${singular}${count === 1 ? '' : 's'}`;
+}
+function formatPlugin(plugin) {
+    return typeof plugin === 'string' ? plugin : JSON.stringify(plugin);
+}

package/bin/commands/list.js

@@ -0,0 +1,81 @@
+import { loadProjectFromFile } from '@valerypopoff/rivet2-node';
+import { getGraphSummaries, getProjectFile, getUiGraphSummaries } from '../cliRuntime.js';
+export function makeListCommand(y) {
+    return y
+        .positional('projectFile', {
+        describe: 'The project file to inspect',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('json', {
+        describe: 'Print machine-readable JSON',
+        type: 'boolean',
+        default: false,
+    });
+}
+export function makeInspectCommand(y) {
+    return y.positional('projectFile', {
+        describe: 'The project file to inspect',
+        type: 'string',
+        demandOption: true,
+    });
+}
+export async function list(args) {
+    const summary = await inspectProject(args.projectFile);
+    console.log(args.json ? JSON.stringify(summary, null, 2) : formatProjectInspection(summary));
+}
+export async function inspect(projectFile) {
+    console.log(JSON.stringify(await inspectProject(projectFile), null, 2));
+}
+export async function inspectProject(projectFile) {
+    const projectPath = await getProjectFile(projectFile);
+    const project = await loadProjectFromFile(projectPath);
+    return buildProjectInspection(project, projectPath);
+}
+export function buildProjectInspection(project, projectPath) {
+    const mainGraphId = project.metadata.mainGraphId;
+    return {
+        graphs: getGraphSummaries(project).map((graph) => ({
+            ...graph,
+            main: graph.id === mainGraphId,
+            nodes: project.graphs[graph.id]?.nodes.length ?? 0,
+        })),
+        libraryNodes: Object.values(project.nodePrefabs ?? {}).map((prefab) => ({
+            id: prefab.id,
+            nodeType: prefab.sourceNode.type,
+            title: prefab.sourceNode.title,
+        })),
+        path: projectPath,
+        plugins: project.plugins ?? [],
+        project: {
+            description: project.metadata.description,
+            id: project.metadata.id,
+            mainGraphId,
+            title: project.metadata.title,
+        },
+        webApps: getUiGraphSummaries(project).map((uiGraph) => ({
+            ...uiGraph,
+            components: project.uiGraphs?.[uiGraph.id]?.components.length ?? 0,
+        })),
+    };
+}
+function formatProjectInspection(summary) {
+    const lines = [
+        `Project: ${summary.project.title} (${summary.project.id})`,
+        `Path: ${summary.path}`,
+        `Main graph: ${formatMainGraph(summary)}`,
+        '',
+        formatSection('Graphs', summary.graphs.map((graph) => `${graph.main ? '* ' : '- '}${graph.name} (${graph.id}) - ${graph.nodes} nodes`)),
+        formatSection('Web apps', summary.webApps.map((webApp) => `- ${webApp.name} (${webApp.id}) - ${webApp.components} components`)),
+        formatSection('Node library', summary.libraryNodes.map((node) => `- ${node.title} (${node.id}) - ${node.nodeType}`)),
+        formatSection('Plugins', summary.plugins.map((plugin) => `- ${typeof plugin === 'string' ? plugin : JSON.stringify(plugin)}`)),
+    ];
+    return lines.filter(Boolean).join('\n');
+}
+function formatMainGraph(summary) {
+    const mainGraph = summary.graphs.find((graph) => graph.main);
+    return mainGraph ? `${mainGraph.name} (${mainGraph.id})` : summary.project.mainGraphId ?? 'Not set';
+}
+function formatSection(title, lines) {
+    return lines.length > 0 ? `${title}:\n${lines.join('\n')}` : `${title}: none`;
+}