proteum 2.1.0-5 → 2.1.1

package/agents/project/AGENTS.md

@@ -1,104 +1,76 @@
 # Project Guide
 
-This file only adds project-local rules on top of the canonical Proteum app contract.
+This file adds project-local rules on top of the canonical Proteum app contract.
 
 Framework contract:
 
 - framework repo: `agents/framework/AGENTS.md`
 - installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
 
-Coding style source of truth:
-
-- `./CODING_STYLE.md`
+Coding style source of truth: `./CODING_STYLE.md`.
 
 ## Fast Start
 
-Start project inspection with:
-
-- `./.proteum/manifest.json`
-- `npx proteum explain`
-- `npx proteum doctor`
-
-For request-time issues in dev, inspect traces before adding temporary logs:
-
-- `npx proteum trace requests`
-- `npx proteum trace latest`
-- `npx proteum trace arm --capture deep`
-
-If you need to diagnose or test against a running app:
-
-- read the default port from `PORT` or `./.proteum/manifest.json`
-- check whether a server is already running on that port
-- if it is, inspect existing traces first to collect past errors and their context before reproducing the issue
+- Start with `./.proteum/manifest.json`, `npx proteum explain`, and `npx proteum doctor`.
+- For request-time issues in dev, inspect traces before adding logs.
+- If a server is already running on the default port from `PORT` or `./.proteum/manifest.json`, inspect existing traces before reproducing the issue.
+- If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request.
 
-## Project Structure
+## Project Shape
 
-This is a full-stack monolith project using TypeScript, Node.js, Preact, and Proteum.
+This is a TypeScript, Node.js, Preact, Proteum monolith:
 
-- `/client`
-  - `/assets`: CSS, images, and other frontend assets
-  - `/catalogs`: client-only catalogs and registries
-  - `/components`: reusable components
-  - `/pages`: page route files and page-local UI
-  - `/hooks`
-- `/common`: shared functions, constants, typings, and cross-runtime catalogs
-- `/server`
-  - `/catalogs`: server-only catalogs and registries
-  - `/config`: service configuration
-  - `/services`: backend services
-  - `/routes`: explicit non-controller routes
-  - `/lib`: helper functions
+- `/client`: assets, catalogs, components, hooks, pages
+- `/common`: shared functions, constants, types, and catalogs
+- `/server`: catalogs, config, services, routes, lib
 - `/tests`
 
 ## Local Deltas
 
-- Always keep one class or one React/Preact component per file.
-- Prefer a deep tree structure grouped by business concern instead of long file names.
-- The default `*.ts` or `*.tsx` file is the normal implementation. Use `*.ssr.ts` or `*.ssr.tsx` only when an SSR-specific variant is actually required.
-- Generated files live under `./.proteum` and should never be edited by hand.
-- Project code should use `@generated/client/*`, `@generated/common/*`, and `@generated/server/*` for generated surfaces.
+- Keep one class or one React/Preact component per file.
+- Prefer a deep tree grouped by business concern instead of long file names.
+- Use the default `*.ts` or `*.tsx` file unless an `*.ssr.ts` or `*.ssr.tsx` variant is truly required.
+- Never edit generated files under `./.proteum`.
+- Use `@generated/client/*`, `@generated/common/*`, and `@generated/server/*` for generated surfaces.
 - Client context is typically imported from `@/client/context`.
 - Prefer type inference from the explicit application class in `./server/index.ts`.
-- If the project already exposes shared Shadcn-based UI primitives, reuse them before creating bespoke primitives.
+- Reuse shared Shadcn-based UI primitives when the project already provides them.
 
-## Catalog Single Source Of Truth
+## Dependency Selection
 
-When a feature depends on a curated list, keep one canonical catalog or registry file and import it everywhere else.
+- Before implementing a feature or change, first check whether the repo already includes a suitable dependency.
+- If not, search npm before building a new utility, abstraction, component primitive, parser, formatter, or integration from scratch.
+- Prefer the most popular, flexible, maintained packages that fit the project constraints.
+- Only reinvent the wheel when existing packages are clearly inadequate on bundle size, SSR behavior, performance, typing quality, flexibility, licensing, or maintenance risk.
+- When you choose custom over a package, explain the reason briefly.
 
-- client-only catalogs live in `/client/catalogs/**`
-- server-only catalogs live in `/server/catalogs/**`
-- shared catalogs live in `/common/catalogs/**`
-- do not create nested `catalogs/` folders under pages, components, services, tests, or other feature folders
+## Catalogs And Typing
 
-## Typings
-
-- Keep strong, consistent TypeScript typings across the whole project.
+- Keep one canonical catalog or registry file and import it everywhere else.
+- Client-only catalogs live in `/client/catalogs/**`, server-only catalogs in `/server/catalogs/**`, and shared catalogs in `/common/catalogs/**`.
+- Do not create nested `catalogs/` folders under pages, components, services, tests, or other feature folders.
+- Keep strong TypeScript typings across the project.
 - Do not introduce `any` or `unknown`, including through casts, helper aliases, or fallback generic defaults.
-- Fix typing issues only on the code you wrote.
-- Never cast with `as any` or `as unknown`. Fix the contract or introduce an explicit typed adapter instead.
+- Fix typing issues only on code you wrote.
+- Never cast with `as any` or `as unknown`; fix the contract or add an explicit typed adapter.
 
 ## Workflow
 
-- Every time I input error messages without any instructions, do not implement fixes. Instead, investigate the potential causes and, for each one:
-  1. evaluate or quantify the probability
-  2. explain why
-  3. suggest how to fix it
-- When the issue is request-time behavior in dev, first check whether a server is already running on the default port from `PORT` or `./.proteum/manifest.json`. If it is, prefer `npx proteum trace` to inspect past errors and their context before reproducing the issue or adding logs.
-- When you have finished your work, summarize in one top-level short sentence the changes you made since the beginning of the conversation. Output as `Commit message`.
+- If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
+- For request-time behavior in dev, check whether a server is already running on the default port and prefer `npx proteum trace` before reproducing the issue or adding logs.
+- End your work with `Commit message`: one short top-level sentence.
 
 ## High-Impact Files
 
+Edit these only when required, and keep changes minimal and explicit:
+
 - `tsconfig*.json`
 - `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
 - Prisma-generated files
 - symbolic links
 
-Edit those files only when the task actually requires it, and keep the change minimal and explicit.
-
 ## Commands Not To Run
 
-Do not run:
-
 - `git restore`
 - `git reset`
 - `prisma *`
@@ -106,10 +78,4 @@ Do not run:
 
 ## Product And UX Docs
 
-If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first.
-
-Prefer these when they exist:
-
-- `docs/PERSONAS.md`
-- `docs/PRODUCT.md`
-- `docs/MARKETING.md`
+If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist.

package/cli/commands/command.ts

@@ -0,0 +1,243 @@
+import got from 'got';
+import path from 'path';
+import { spawn } from 'child_process';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import app from '../app';
+import {
+    normalizeDevCommandPath,
+    type TDevCommandErrorResponse,
+    type TDevCommandExecution,
+    type TDevCommandRunResponse,
+} from '../../common/dev/commands';
+
+const localCommandResultMarker = '__PROTEUM_COMMAND_RESULT__';
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!require('fs-extra').existsSync(manifestFilepath)) return undefined;
+
+    const manifest = require('fs-extra').readJsonSync(manifestFilepath, { throws: false }) as
+        | { env?: { resolved?: { routerPort?: number } } }
+        | undefined;
+    const port = manifest?.env?.resolved?.routerPort;
+
+    if (typeof port !== 'number' || port <= 0) return undefined;
+
+    return String(port);
+};
+
+const getRouterPort = () => {
+    const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
+    if (overridePort) return overridePort;
+
+    const envPort = process.env.PORT?.trim();
+    if (envPort) return envPort;
+
+    const manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
+
+    throw new UsageError(
+        `Could not determine the router port from PORT or .proteum/manifest.json in ${cli.args.workdir as string}. Pass --port or --url explicitly.`,
+    );
+};
+
+const getRouterBaseUrls = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    return [...new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`])];
+};
+
+const getCommandErrorMessage = (body: TDevCommandErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Command request failed with status ${statusCode}.`;
+};
+
+const requestJson = async <TResponse>(pathname: string, options?: { method?: 'GET' | 'POST'; json?: object }) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                method: options?.method || 'GET',
+                json: options?.json,
+                responseType: 'json',
+                throwHttpErrors: false,
+                retry: { limit: 0 },
+            });
+
+            if (response.statusCode >= 400) {
+                throw new UsageError(
+                    getCommandErrorMessage(response.body as TDevCommandErrorResponse | object | string | undefined, response.statusCode),
+                );
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}${pathname}: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum command server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or omit --port/--url to run the command locally.',
+        ].join('\n'),
+    );
+};
+
+const printJson = (value: object) => {
+    console.log(JSON.stringify(value, null, 2));
+};
+
+const renderExecution = (execution: TDevCommandExecution) => {
+    const lines = [
+        `Command ${execution.command.path}`,
+        `- status=${execution.status} durationMs=${execution.durationMs}`,
+        `- source=${execution.command.filepath}:${execution.command.sourceLocation.line}:${execution.command.sourceLocation.column}`,
+    ];
+
+    if (execution.errorMessage) {
+        lines.push(`- error=${execution.errorMessage}`);
+    } else if (execution.result?.json !== undefined) {
+        lines.push('Result');
+        lines.push(JSON.stringify(execution.result.json, null, 2));
+    } else if (execution.result?.summary !== undefined) {
+        lines.push('Result');
+        lines.push(JSON.stringify(execution.result.summary, null, 2));
+    } else {
+        lines.push('- result=undefined');
+    }
+
+    return lines.join('\n');
+};
+
+const runLocalCommand = async (commandPath: string) => {
+    if (app.env.profile !== 'dev') {
+        throw new UsageError(`Proteum commands are only available when ENV_PROFILE=dev. Current profile: ${app.env.profile}.`);
+    }
+
+    const runnerFilepath = path.join(cli.paths.core.root, 'cli', 'commands', 'commandLocalRunner.js');
+
+    return await new Promise<TDevCommandExecution>((resolve, reject) => {
+        const stdoutChunks: Buffer[] = [];
+        const stderrChunks: Buffer[] = [];
+        const child = spawn(process.execPath, [runnerFilepath, app.paths.root, commandPath], {
+            cwd: app.paths.root,
+            env: { ...process.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        child.stdout.on('data', (chunk: Buffer | string) => {
+            stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+
+        child.stderr.on('data', (chunk: Buffer | string) => {
+            stderrChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+
+        child.on('error', (error) => reject(error));
+        child.on('close', (exitCode) => {
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            const markerLine = stdout
+                .split(/\r?\n/)
+                .find((line) => line.startsWith(localCommandResultMarker));
+
+            if (stderr.trim()) {
+                process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
+            }
+
+            if (!markerLine) {
+                reject(
+                    new Error(
+                        [
+                            `Local command runner exited without returning a structured result (exit code ${exitCode ?? 'unknown'}).`,
+                            stdout.trim() ? `stdout:\n${stdout.trim()}` : undefined,
+                        ]
+                            .filter(Boolean)
+                            .join('\n\n'),
+                    ),
+                );
+                return;
+            }
+
+            const payload = JSON.parse(markerLine.slice(localCommandResultMarker.length)) as
+                | { execution: TDevCommandExecution }
+                | { error: string };
+
+            if ('execution' in payload) {
+                if (exitCode && exitCode !== 0) {
+                    const error = new Error(payload.execution.errorMessage || `Command "${commandPath}" failed.`) as Error & {
+                        execution?: TDevCommandExecution;
+                    };
+
+                    error.execution = payload.execution;
+                    reject(error);
+                    return;
+                }
+
+                resolve(payload.execution);
+                return;
+            }
+
+            reject(new Error(payload.error || `Command "${commandPath}" failed.`));
+        });
+    });
+};
+
+export const run = async () => {
+    const rawPath = typeof cli.args.path === 'string' ? cli.args.path : '';
+    const commandPath = normalizeDevCommandPath(rawPath);
+    const shouldPrintJson = cli.args.json === true;
+    const shouldUseRemoteServer =
+        (typeof cli.args.port === 'string' && cli.args.port.length > 0) ||
+        (typeof cli.args.url === 'string' && cli.args.url.length > 0);
+
+    if (!commandPath) {
+        throw new UsageError('A command path is required. Example: proteum command diagnostics/ping');
+    }
+
+    try {
+        const execution = shouldUseRemoteServer
+            ? (await requestJson<TDevCommandRunResponse>('/__proteum/commands/run', {
+                  method: 'POST',
+                  json: { path: commandPath },
+              })).execution
+            : await runLocalCommand(commandPath);
+
+        if (shouldPrintJson) {
+            printJson({ execution });
+            return;
+        }
+
+        console.log(renderExecution(execution));
+    } catch (error) {
+        if (error instanceof Error && 'execution' in error && typeof error.execution === 'object' && error.execution) {
+            const execution = error.execution as TDevCommandExecution;
+
+            if (shouldPrintJson) {
+                printJson({ execution });
+            } else {
+                console.log(renderExecution(execution));
+            }
+
+            process.exitCode = 1;
+            return;
+        }
+
+        throw error;
+    }
+};

package/cli/commands/commandLocalRunner.js

@@ -0,0 +1,198 @@
+const path = require('path');
+const net = require('net');
+const { spawn } = require('child_process');
+const tsNode = require('ts-node');
+
+const resultMarker = '__PROTEUM_COMMAND_RESULT__';
+
+const printPayload = (payload) => {
+    process.stdout.write(`${resultMarker}${JSON.stringify(payload)}\n`);
+};
+
+const fail = (error, execution) => {
+    if (execution) {
+        printPayload({ execution });
+        process.exitCode = 1;
+        return;
+    }
+
+    printPayload({ error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+};
+
+const getAvailablePort = async () =>
+    await new Promise((resolve, reject) => {
+        const server = net.createServer();
+
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+
+            if (!address || typeof address === 'string') {
+                server.close(() => reject(new Error('Could not determine a local port for the command runner.')));
+                return;
+            }
+
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                resolve(address.port);
+            });
+        });
+    });
+
+const closeMultiCompiler = async (multiCompiler) =>
+    await new Promise((resolve, reject) => {
+        multiCompiler.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+
+            resolve();
+        });
+    });
+
+const runCompiler = async (compiler) => {
+    const multiCompiler = await compiler.create();
+
+    try {
+        await new Promise((resolve, reject) => {
+            multiCompiler.run((error, stats) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                if (stats && stats.hasErrors()) {
+                    reject(new Error('Compilation failed for the local dev command runner.'));
+                    return;
+                }
+
+                resolve();
+            });
+        });
+    } finally {
+        compiler.dispose();
+        await closeMultiCompiler(multiCompiler);
+    }
+};
+
+const waitForServerReady = async (child) =>
+    await new Promise((resolve, reject) => {
+        let settled = false;
+
+        const finish = (callback, value) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timeout);
+            child.off('message', onMessage);
+            child.off('error', onError);
+            child.off('exit', onExit);
+            callback(value);
+        };
+
+        const onMessage = (message) => {
+            if (!message || message.type !== 'proteum:server-ready' || typeof message.publicUrl !== 'string') return;
+            finish(resolve, message.publicUrl);
+        };
+
+        const onError = (error) => finish(reject, error);
+        const onExit = (code, signal) =>
+            finish(reject, new Error(`Local command server exited before becoming ready (code=${code}, signal=${signal}).`));
+        const timeout = setTimeout(
+            () => finish(reject, new Error('Timed out while waiting for the local command server to become ready.')),
+            30000,
+        );
+
+        child.on('message', onMessage);
+        child.once('error', onError);
+        child.once('exit', onExit);
+    });
+
+const stopServerProcess = async (child) => {
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+
+    child.kill('SIGTERM');
+
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+        }, 5000);
+
+        child.once('exit', () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+};
+
+const requestCommand = async (baseUrl, commandPath) => {
+    const response = await fetch(`${baseUrl}/__proteum/commands/run`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ path: commandPath }),
+    });
+    const body = await response.json();
+
+    if (body && typeof body === 'object' && body.execution) {
+        return { statusCode: response.status, execution: body.execution };
+    }
+
+    throw new Error((body && body.error) || `Command request failed with status ${response.status}.`);
+};
+
+(async () => {
+    const [, , appRootArg = '', commandPath = ''] = process.argv;
+    const appRoot = path.resolve(appRootArg);
+
+    if (!appRootArg || !commandPath) {
+        fail(new Error('commandLocalRunner requires <appRoot> and <commandPath>.'));
+        return;
+    }
+
+    process.chdir(appRoot);
+
+    tsNode.register({
+        transpileOnly: true,
+        project: path.join(__dirname, '..', 'tsconfig.json'),
+        files: true,
+    });
+
+    const port = await getAvailablePort();
+    const cli = require('../context.ts').default;
+    cli.setArgs({ workdir: appRoot, path: commandPath, port: String(port), url: '', json: true });
+
+    const app = require('../app/index.ts').default;
+    const Compiler = require('../compiler/index.ts').default;
+
+    if (app.env.profile !== 'dev') {
+        fail(new Error(`Proteum commands are only available when ENV_PROFILE=dev. Current profile: ${app.env.profile}.`));
+        return;
+    }
+
+    const compiler = new Compiler('dev');
+    await runCompiler(compiler);
+
+    const serverProcess = spawn(process.execPath, ['--preserve-symlinks', path.join(app.outputPath('dev'), 'server.js')], {
+        cwd: app.paths.root,
+        stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+    });
+
+    try {
+        const publicUrl = await waitForServerReady(serverProcess);
+        const { statusCode, execution } = await requestCommand(publicUrl, commandPath);
+
+        printPayload({ execution });
+        if (statusCode >= 400 || execution.status === 'error') {
+            process.exitCode = 1;
+        }
+    } finally {
+        await stopServerProcess(serverProcess);
+    }
+})().catch((error) => {
+    fail(error);
+});