proteum 2.1.2 → 2.1.6

package/cli/runtime/commands.ts

@@ -10,7 +10,7 @@ class InitCommand extends ProteumCommand {
     public static usage = buildUsage('init');
 
     public name = Option.String('--name', { description: 'Human-readable app name.' });
-    public description = Option.String('--description', { description: 'App description used in identity.yaml and package.json.' });
+    public description = Option.String('--description', { description: 'App description used in identity.config.ts and package.json.' });
     public identifier = Option.String('--identifier', { description: 'Application class and identity identifier.' });
     public port = Option.String('--port', { description: 'Default local router port used in .env.' });
     public url = Option.String('--url', { description: 'Default absolute URL used in .env.' });
@@ -179,19 +179,43 @@ class CheckCommand extends ProteumCommand {
     }
 }
 
+class ConnectCommand extends ProteumCommand {
+    public static paths = [['connect']];
+
+    public static usage = buildUsage('connect');
+
+    public controllers = Option.Boolean('--controllers', false, {
+        description: 'Include imported connected controllers in the output.',
+    });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any connect diagnostics exist.' });
+    public legacyArgs = Option.Rest();
+
+    public async execute() {
+        const args = { controllers: this.controllers, json: this.json, strict: this.strict } satisfies TArgsObject;
+
+        applyLegacyBooleanArgs('connect', this.legacyArgs, ['controllers', 'json', 'strict'], args);
+        this.setCliArgs(args);
+        await runCommandModule(() => import('../commands/connect'));
+    }
+}
+
 class DoctorCommand extends ProteumCommand {
     public static paths = [['doctor']];
 
     public static usage = buildUsage('doctor');
 
+    public contracts = Option.Boolean('--contracts', false, {
+        description: 'Run contract-focused diagnostics for generated artifacts and manifest-owned source files.',
+    });
     public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
     public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any diagnostics exist.' });
     public legacyArgs = Option.Rest();
 
     public async execute() {
-        const args = { json: this.json, strict: this.strict } satisfies TArgsObject;
+        const args = { contracts: this.contracts, json: this.json, strict: this.strict } satisfies TArgsObject;
 
-        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['json', 'strict'], args);
+        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['contracts', 'json', 'strict'], args);
         this.setCliArgs(args);
         await runCommandModule(() => import('../commands/doctor'));
     }
@@ -207,6 +231,7 @@ class ExplainCommand extends ProteumCommand {
     public app = Option.Boolean('--app', false, { description: 'Include the app section.' });
     public conventions = Option.Boolean('--conventions', false, { description: 'Include the conventions section.' });
     public env = Option.Boolean('--env', false, { description: 'Include the env section.' });
+    public connected = Option.Boolean('--connected', false, { description: 'Include the connected-projects section.' });
     public services = Option.Boolean('--services', false, { description: 'Include the services section.' });
     public controllers = Option.Boolean('--controllers', false, { description: 'Include the controllers section.' });
     public commands = Option.Boolean('--commands', false, { description: 'Include the commands section.' });
@@ -215,14 +240,25 @@ class ExplainCommand extends ProteumCommand {
     public diagnostics = Option.Boolean('--diagnostics', false, {
         description: 'Include the diagnostics section.',
     });
-    public legacyArgs = Option.Rest();
+    public args = Option.Rest();
 
     public async execute() {
+        const [mode = '', ...restArgs] = this.args;
+        if (mode === 'owner') {
+            this.setCliArgs({
+                json: this.json,
+                ownerQuery: restArgs.join(' ').trim(),
+            });
+            await runCommandModule(() => import('../commands/explain'));
+            return;
+        }
+
         const args = {
             json: this.json,
             all: this.all,
             app: this.app,
             conventions: this.conventions,
+            connected: this.connected,
             env: this.env,
             services: this.services,
             controllers: this.controllers,
@@ -234,8 +270,8 @@ class ExplainCommand extends ProteumCommand {
 
         applyLegacyBooleanArgs(
             'explain',
-            this.legacyArgs,
-            ['json', 'all', 'app', 'conventions', 'env', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
+            this.args,
+            ['json', 'all', 'app', 'conventions', 'env', 'connected', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
             args,
         );
         this.setCliArgs(args);
@@ -296,6 +332,147 @@ class CommandCommand extends ProteumCommand {
     }
 }
 
+class SessionCommand extends ProteumCommand {
+    public static paths = [['session']];
+
+    public static usage = buildUsage('session');
+
+    public role = Option.String('--role', { description: 'Require the resolved user to have the given role.' });
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [email = ''] = this.args;
+
+        this.setCliArgs({
+            email,
+            role: this.role ?? '',
+            port: this.port ?? '',
+            url: this.url ?? '',
+            json: this.json,
+        });
+
+        await runCommandModule(() => import('../commands/session'));
+    }
+}
+
+class DiagnoseCommand extends ProteumCommand {
+    public static paths = [['diagnose']];
+
+    public static usage = buildUsage('diagnose');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public hit = Option.String('--hit', { description: 'Issue one HTTP request before diagnosing. Defaults to the target path when it starts with /.' });
+    public method = Option.String('--method', { description: 'HTTP method used with `--hit`.' });
+    public dataJson = Option.String('--data-json', { description: 'JSON request body used with `--hit`.' });
+    public sessionEmail = Option.String('--session-email', {
+        description: 'Mint a dev session before `--hit` and attach the returned cookie.',
+    });
+    public sessionRole = Option.String('--session-role', { description: 'Require the dev session user to have this role.' });
+    public capture = Option.String('--capture', { description: 'Trace capture mode armed before `--hit`.' });
+    public logsLevel = Option.String('--logs-level', { description: 'Minimum server log level included in the diagnose response.' });
+    public logsLimit = Option.String('--logs-limit', { description: 'Maximum number of server log lines included in the diagnose response.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [target = ''] = this.args;
+
+        this.setCliArgs({
+            capture: this.capture ?? '',
+            dataJson: this.dataJson ?? '',
+            hit: this.hit ?? '',
+            json: this.json,
+            logsLevel: this.logsLevel ?? '',
+            logsLimit: this.logsLimit ?? '',
+            method: this.method ?? '',
+            port: this.port ?? '',
+            sessionEmail: this.sessionEmail ?? '',
+            sessionRole: this.sessionRole ?? '',
+            target,
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/diagnose'));
+    }
+}
+
+class PerfCommand extends ProteumCommand {
+    public static paths = [['perf']];
+
+    public static usage = buildUsage('perf');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public since = Option.String('--since', { description: 'Window used by `top` and `memory`, for example `today`, `yesterday`, or `1h`.' });
+    public baseline = Option.String('--baseline', { description: 'Baseline window used by `compare`.' });
+    public target = Option.String('--target', { description: 'Target window used by `compare`.' });
+    public groupBy = Option.String('--group-by', { description: 'Aggregate by `path`, `route`, or `controller`.' });
+    public limit = Option.String('--limit', { description: 'Maximum number of rows to print.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = 'top', target = ''] = this.args;
+
+        this.setCliArgs({
+            action,
+            baseline: this.baseline ?? '',
+            groupBy: this.groupBy ?? '',
+            json: this.json,
+            limit: this.limit ?? '',
+            port: this.port ?? '',
+            since: this.since ?? '',
+            target,
+            targetWindow: this.target ?? '',
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/perf'));
+    }
+}
+
+class VerifyCommand extends ProteumCommand {
+    public static paths = [['verify']];
+
+    public static usage = buildUsage('verify');
+
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public crosspath = Option.String('--crosspath', { description: 'Override the CrossPath reference app path.' });
+    public product = Option.String('--product', { description: 'Override the Unique Domains Product reference app path.' });
+    public website = Option.String('--website', { description: 'Override the Unique Domains Website reference app path.' });
+    public crosspathPort = Option.String('--crosspath-port', { description: 'Port used for the CrossPath validation server.' });
+    public productPort = Option.String('--product-port', {
+        description: 'Port used for the Unique Domains Product validation server.',
+    });
+    public websitePort = Option.String('--website-port', {
+        description: 'Port used for the Unique Domains Website validation server.',
+    });
+    public route = Option.String('--route', { description: 'Route loaded in both apps during validation.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = 'framework-change'] = this.args;
+
+        this.setCliArgs({
+            action,
+            crosspath: this.crosspath ?? '',
+            crosspathPort: this.crosspathPort ?? '',
+            json: this.json,
+            product: this.product ?? '',
+            productPort: this.productPort ?? '',
+            route: this.route ?? '',
+            website: this.website ?? '',
+            websitePort: this.websitePort ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/verify'));
+    }
+}
+
 export const registeredCommands = {
     init: InitCommand,
     create: CreateCommand,
@@ -305,10 +482,15 @@ export const registeredCommands = {
     typecheck: TypecheckCommand,
     lint: LintCommand,
     check: CheckCommand,
+    connect: ConnectCommand,
     doctor: DoctorCommand,
     explain: ExplainCommand,
+    diagnose: DiagnoseCommand,
+    perf: PerfCommand,
     trace: TraceCommand,
     command: CommandCommand,
+    session: SessionCommand,
+    verify: VerifyCommand,
 } as const;
 
 export const createCli = (version: string) => {
@@ -329,10 +511,15 @@ export const createCli = (version: string) => {
     clipanion.register(TypecheckCommand);
     clipanion.register(LintCommand);
     clipanion.register(CheckCommand);
+    clipanion.register(ConnectCommand);
     clipanion.register(DoctorCommand);
     clipanion.register(ExplainCommand);
+    clipanion.register(DiagnoseCommand);
+    clipanion.register(PerfCommand);
     clipanion.register(TraceCommand);
     clipanion.register(CommandCommand);
+    clipanion.register(SessionCommand);
+    clipanion.register(VerifyCommand);
 
     return clipanion;
 };

package/cli/scaffold/index.ts

@@ -1,10 +1,10 @@
 import fs from 'fs-extra';
 import path from 'path';
 import slugify from 'slugify';
-import yaml from 'yaml';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
+import { loadApplicationIdentityConfig } from '../../common/applicationConfigLoader';
 import { ensureProjectAgentSymlinks } from '../utils/agents';
 import { runProcess } from '../utils/runProcess';
 import {
@@ -18,6 +18,7 @@ import {
     createInitSummary,
     createPackageJsonTemplate,
     createPageTemplate,
+    createProteumConfigTemplate,
     createRouteTemplate,
     createRouterConfigTemplate,
     createServerIndexTemplate,
@@ -133,16 +134,16 @@ const defaultRouteFromSegments = (segments: string[]) => {
 const resolveRootServiceLeaf = (segments: string[]) => segments[segments.length - 1];
 
 const readIdentityConfig = (appRoot: string): TIdentityConfig => {
-    const identityFilepath = path.join(appRoot, 'identity.yaml');
+    const identityFilepath = path.join(appRoot, 'identity.config.ts');
     if (!fs.existsSync(identityFilepath)) {
-        throw new UsageError(`Missing identity.yaml in ${appRoot}. Run \`proteum init\` first or target a Proteum app root.`);
+        throw new UsageError(`Missing identity.config.ts in ${appRoot}. Run \`proteum init\` first or target a Proteum app root.`);
     }
 
-    const parsed = yaml.parse(fs.readFileSync(identityFilepath, 'utf8')) as Partial<TIdentityConfig> | null;
-    const identifier = typeof parsed?.identifier === 'string' ? parsed.identifier.trim() : '';
-    const name = typeof parsed?.name === 'string' ? parsed.name.trim() : '';
+    const parsed = loadApplicationIdentityConfig(appRoot);
+    const identifier = typeof parsed.identifier === 'string' ? parsed.identifier.trim() : '';
+    const name = typeof parsed.name === 'string' ? parsed.name.trim() : '';
 
-    if (!identifier) throw new UsageError(`identity.yaml in ${appRoot} is missing a valid "identifier" field.`);
+    if (!identifier) throw new UsageError(`identity.config.ts in ${appRoot} is missing a valid "identifier" field.`);
 
     return {
         identifier,
@@ -151,7 +152,7 @@ const readIdentityConfig = (appRoot: string): TIdentityConfig => {
 };
 
 const assertProteumAppRoot = (appRoot: string) => {
-    const expectedEntries = ['package.json', 'identity.yaml', 'client', 'server'];
+    const expectedEntries = ['package.json', 'identity.config.ts', 'proteum.config.ts', 'client', 'server'];
     const missing = expectedEntries.filter((entry) => !fs.existsSync(path.join(appRoot, entry)));
     if (missing.length > 0) {
         throw new UsageError(
@@ -459,21 +460,9 @@ const createServicePlan = ({
     const configExportName = `${configFileBase}Config`;
     const relativeServiceDir = path.join('server', 'services', ...segments);
     const relativeServiceFilepath = path.join(relativeServiceDir, 'index.ts');
-    const relativeServiceConfigFilepath = path.join(relativeServiceDir, 'service.json');
     const relativeConfigFilepath = path.join('server', 'config', `${configFileBase}.ts`);
     const propertyName = serviceImportName;
 
-    const serviceJson = JSON.stringify(
-        {
-            id: `${appIdentifier}/${serviceImportName}`,
-            name: `${appIdentifier}${serviceImportName}`,
-            parent: 'app',
-            dependences: [],
-        },
-        null,
-        4,
-    ) + '\n';
-
     return {
         files: [
             {
@@ -483,10 +472,6 @@ const createServicePlan = ({
                     className,
                 }),
             },
-            {
-                relativePath: relativeServiceConfigFilepath,
-                content: serviceJson,
-            },
             {
                 relativePath: relativeConfigFilepath,
                 content: createServiceConfigTemplate({
@@ -628,13 +613,17 @@ const createInitFilePlans = (config: TScaffoldInitConfig): TScaffoldFilePlan[] =
         }),
     },
     {
-        relativePath: 'identity.yaml',
+        relativePath: 'identity.config.ts',
         content: createIdentityTemplate({
             appName: config.name,
             appIdentifier: config.identifier,
             appDescription: config.description,
         }),
     },
+    {
+        relativePath: 'proteum.config.ts',
+        content: createProteumConfigTemplate(),
+    },
     {
         relativePath: '.env',
         content: createEnvTemplate({

package/cli/scaffold/templates.ts

@@ -227,6 +227,8 @@ export const createServerTsconfigTemplate = () => `{
     },
     "include": [
         ".",
+        "../identity.config.ts",
+        "../proteum.config.ts",
         "../var/typings",
         "../node_modules/proteum/types/global",
         "../.proteum/server/services.d.ts",
@@ -236,11 +238,12 @@ export const createServerTsconfigTemplate = () => `{
 `;
 
 export const createGitignoreTemplate = () => `node_modules
-.proteum
-.cache
-bin
-dev
-var
+/.proteum
+/.cache
+/bin
+/dev
+/var
+/proteum.connected.json
 .env
 `;
 
@@ -248,6 +251,7 @@ export const createEnvTemplate = ({ port, url }: { port: number; url: string })
 ENV_PROFILE=dev
 PORT=${port}
 URL=${url}
+URL_INTERNAL=${url}
 
 # Optional trace settings
 # TRACE_ENABLE=true
@@ -306,28 +310,38 @@ export const createIdentityTemplate = ({
     appName: string;
     appIdentifier: string;
     appDescription: string;
-}) => `name: ${appName}
-identifier: ${appIdentifier}
-description: ${JSON.stringify(appDescription)}
-
-author:
-    name: ${appName}
-    url: localhost
-    email: team@example.com
-
-social:
-
-language: en
-locale: en-US
-maincolor: white
-iconsPack: light
-
-web:
-    title: ${JSON.stringify(appName)}
-    titleSuffix: ${JSON.stringify(appName)}
-    fullTitle: ${JSON.stringify(appName)}
-    description: ${JSON.stringify(appDescription)}
-    version: 0.0.1
+}) => `import { Application } from 'proteum/config';
+
+export default Application.identity({
+    name: ${JSON.stringify(appName)},
+    identifier: ${JSON.stringify(appIdentifier)},
+    description: ${JSON.stringify(appDescription)},
+    author: {
+        name: ${JSON.stringify(appName)},
+        url: 'localhost',
+        email: 'team@example.com',
+    },
+    social: {},
+    language: 'en',
+    locale: 'en-US',
+    maincolor: 'white',
+    iconsPack: 'light',
+    web: {
+        title: ${JSON.stringify(appName)},
+        titleSuffix: ${JSON.stringify(appName)},
+        fullTitle: ${JSON.stringify(appName)},
+        description: ${JSON.stringify(appDescription)},
+        version: '0.0.1',
+    },
+});
+`;
+
+export const createProteumConfigTemplate = () => `import { Application } from 'proteum/config';
+
+export default Application.setup({
+    transpile: [],
+    connect: {},
+});
 `;
 
 export const createInitSummary = (result: TScaffoldResult, config: TScaffoldInitConfig) => ({

package/cli/utils/agents.ts

@@ -19,10 +19,12 @@ type TAgentLinkDefinition = { projectPath: string; sourcePath: string; ensurePar
 - CONSTANTS
 ----------------------------------*/
 
-// Project-local AGENTS entrypoints mapped to their framework-owned source files.
+// Project-local instruction entrypoints mapped to their canonical shipped source files.
 const projectAgentLinkDefinitions: TAgentLinkDefinition[] = [
     { projectPath: 'AGENTS.md', sourcePath: 'AGENTS.md' },
     { projectPath: 'CODING_STYLE.md', sourcePath: 'CODING_STYLE.md' },
+    { projectPath: 'diagnostics.md', sourcePath: 'diagnostics.md' },
+    { projectPath: 'optimizations.md', sourcePath: 'optimizations.md' },
     { projectPath: path.join('client', 'AGENTS.md'), sourcePath: path.join('client', 'AGENTS.md') },
     { projectPath: path.join('client', 'pages', 'AGENTS.md'), sourcePath: path.join('client', 'pages', 'AGENTS.md') },
     {
@@ -81,7 +83,7 @@ function ensureSymlinks(appRoot: string, linkDefinitions: TAgentLinkDefinition[]
 
         const sourceFilepath = linkDefinition.sourcePath;
         if (!fs.existsSync(sourceFilepath)) {
-            throw new Error(`Missing framework asset: ${sourceFilepath}`);
+            throw new Error(`Missing project instruction asset: ${sourceFilepath}`);
         }
 
         const symlinkTarget = path.relative(projectParentDir, sourceFilepath);

package/cli/utils/keyboard.ts

@@ -23,7 +23,15 @@ class KeyboardCommands {
     }
 
     private listen() {
+        if (!process.stdin) return;
+
         readline.emitKeypressEvents(process.stdin);
+
+        if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
+            logVerbose('Keyboard shortcuts disabled because stdin is not an interactive TTY.');
+            return;
+        }
+
         process.stdin.setRawMode(true);
         process.stdin.on('keypress', async (chunk: string, key: Key) => {
             let str = key.name;

package/client/dev/profiler/ApexChart.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import type { ApexOptions } from 'apexcharts';
+
+const readErrorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
+
+export default function ApexChart({
+    emptyLabel = 'No chart data available.',
+    options,
+}: {
+    emptyLabel?: string;
+    options?: ApexOptions;
+}) {
+    const mountRef = React.useRef<HTMLDivElement | null>(null);
+    const [errorMessage, setErrorMessage] = React.useState<string>();
+
+    React.useEffect(() => {
+        const target = mountRef.current;
+        if (!target || !options) return;
+
+        let disposed = false;
+        let chart: { destroy: () => void } | undefined;
+
+        target.innerHTML = '';
+        setErrorMessage(undefined);
+
+        void (async () => {
+            try {
+                const module = await import('apexcharts');
+                if (disposed || !mountRef.current) return;
+
+                const ApexCharts = module.default;
+                chart = new ApexCharts(mountRef.current, options);
+                await chart.render();
+            } catch (error) {
+                if (!disposed) setErrorMessage(readErrorMessage(error));
+            }
+        })();
+
+        return () => {
+            disposed = true;
+            chart?.destroy();
+            target.innerHTML = '';
+        };
+    }, [options]);
+
+    if (!options) return <div className="proteum-profiler__empty">{emptyLabel}</div>;
+
+    if (errorMessage) {
+        return (
+            <div className="proteum-profiler__chartMount">
+                <div className="proteum-profiler__row">
+                    <div className="proteum-profiler__rowHeader">
+                        <strong>Chart error</strong>
+                    </div>
+                    <div className="proteum-profiler__mono">{errorMessage}</div>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="proteum-profiler__chartMount">
+            <div ref={mountRef} />
+        </div>
+    );
+}