proteum 2.1.9 → 2.2.1

package/cli/commands/dev.ts

@@ -21,7 +21,6 @@ import {
 // Configs
 import Compiler from '../compiler';
 import { createDevEventServer } from './devEvents';
-import { ensureProjectAgentSymlinks } from '../utils/agents';
 import { renderDevSession, renderServerReadyBanner, renderDevShutdownBanner } from '../presentation/devSession';
 import { clearInteractiveConsole } from '../presentation/welcome';
 import {
@@ -557,7 +556,6 @@ const createIndexedSourceWatching = ({
 const runDevLoop = async () => {
     devSessionStopping = false;
     clearInteractiveConsole();
-    ensureProjectAgentSymlinks({ appRoot: app.paths.root, coreRoot: cli.paths.core.root });
     await ensureDevSessionSlot();
     const proteumInstall = resolveFrameworkInstallInfo({
         appRoot: app.paths.root,

package/cli/commands/diagnose.ts

@@ -163,7 +163,35 @@ const renderOwners = (matches: TExplainOwnerMatch[]) =>
         ? ['Owner matches', '- none'].join('\n')
         : [
               'Owner matches',
-              ...matches.map((match) => `- [${match.kind}] ${match.label} score=${match.score} source=${formatSource(match)}`),
+              ...matches.map(
+                  (match) =>
+                      `- [${match.kind}] ${match.label} score=${match.score} scope=${match.scopeLabel} origin=${match.originHint} source=${formatSource(match)}`,
+              ),
+          ].join('\n');
+
+const renderChain = (response: TDiagnoseResponse) =>
+    !response.chain || response.chain.length === 0
+        ? ['Chain', '- none'].join('\n')
+        : [
+              'Chain',
+              ...response.chain.map(
+                  (item) =>
+                      `- [${item.kind}] ${item.label}${item.source?.filepath ? ` source=${item.source.filepath}${item.source.line ? `:${item.source.line}` : ''}${item.source.column ? `:${item.source.column}` : ''}` : ''}${item.details.length > 0 ? ` details=${item.details.join(', ')}` : ''}`,
+              ),
+          ].join('\n');
+
+const renderOrientation = (response: TDiagnoseResponse) =>
+    !response.orientation
+        ? ['Orientation', '- none'].join('\n')
+        : [
+              'Orientation',
+              `- agents=${response.orientation.guidance.agents}`,
+              `- diagnostics=${response.orientation.guidance.diagnostics}`,
+              `- optimizations=${response.orientation.guidance.optimizations}`,
+              `- codingStyle=${response.orientation.guidance.codingStyle}`,
+              `- areaAgents=${response.orientation.guidance.areaAgents.join(', ') || 'none'}`,
+              `- connected imports=${response.orientation.connected.imports.length} producers=${response.orientation.connected.producers.length}`,
+              ...response.orientation.nextSteps.map((step) => `- next=${step.command} (${step.reason})`),
           ].join('\n');
 
 const renderSuspects = (response: TDiagnoseResponse) =>
@@ -188,6 +216,10 @@ const renderHuman = (manifest: ReturnType<typeof readProteumManifest>, response:
         '',
         renderOwners(response.owner.matches.slice(0, 6)),
         '',
+        renderChain(response),
+        '',
+        renderOrientation(response),
+        '',
         renderDoctorResponseHuman({
             emptyMessage: 'No manifest diagnostics were found.',
             manifest,

package/cli/commands/explain.ts

@@ -55,7 +55,7 @@ export const run = async (): Promise<void> => {
                     ? ['- No matching manifest owners were found.']
                     : response.matches.map(
                           (match) =>
-                              `- [${match.kind}] ${match.label} score=${match.score} source=${match.source.filepath}${match.source.line ? `:${match.source.line}` : ''}${match.source.column ? `:${match.source.column}` : ''}`,
+                              `- [${match.kind}] ${match.label} score=${match.score} scope=${match.scopeLabel} origin=${match.originHint} source=${match.source.filepath}${match.source.line ? `:${match.source.line}` : ''}${match.source.column ? `:${match.source.column}` : ''}`,
                       )),
             ].join('\n'),
         );

package/cli/commands/migrate.ts

@@ -0,0 +1,51 @@
+import path from 'path';
+
+import cli from '..';
+import { runPageContractMigration } from '../migrate/pageContract';
+
+const printHuman = (summary: ReturnType<typeof runPageContractMigration>) => {
+    console.log(`Proteum migrate page-contract`);
+    console.log(`App root: ${summary.appRoot}`);
+    console.log(`Scanned files: ${summary.scannedFiles}`);
+    console.log(`Changed files: ${summary.changedFiles.length}${summary.dryRun ? ' (dry run)' : ''}`);
+
+    if (summary.changedFiles.length > 0) {
+        console.log('');
+        console.log('Rewritten files:');
+        for (const filepath of summary.changedFiles) {
+            console.log(`- ${path.relative(summary.appRoot, filepath)}`);
+        }
+    }
+
+    if (summary.manualFixes.length > 0) {
+        console.log('');
+        console.log('Manual fixes required:');
+        for (const fix of summary.manualFixes) {
+            console.log(
+                `- ${path.relative(summary.appRoot, fix.filepath)}:${fix.line}:${fix.column} ${fix.routeLabel} :: ${fix.reason}`,
+            );
+        }
+    }
+};
+
+export const run = async (): Promise<void> => {
+    const action = String(cli.args.action || '').trim();
+    if (action !== 'page-contract') {
+        throw new Error(`Unsupported migrate action "${action}". Expected "page-contract".`);
+    }
+
+    const summary = runPageContractMigration({
+        appRoot: String(cli.args.workdir || process.cwd()),
+        dryRun: cli.args.dryRun === true,
+    });
+
+    if (cli.args.json === true) {
+        console.log(JSON.stringify(summary, null, 2));
+    } else {
+        printHuman(summary);
+    }
+
+    if (summary.manualFixes.length > 0) {
+        throw new Error(`Page-contract migration requires manual fixes in ${summary.manualFixes.length} location(s).`);
+    }
+};

package/cli/commands/orient.ts

@@ -0,0 +1,169 @@
+import got from 'got';
+import path from 'path';
+import fs from 'fs-extra';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import Compiler from '../compiler';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
+import { buildOrientationResponse, type TOrientResponse } from '@common/dev/inspection';
+import type { TProteumManifest } from '@common/dev/proteumManifest';
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+const dedupe = <TValue>(values: TValue[]) => [...new Set(values)];
+
+const buildBaseUrlCandidates = (value: string) => {
+    const normalized = normalizeBaseUrl(value);
+
+    try {
+        const parsed = new URL(normalized);
+        const port = parsed.port;
+        const pathname = parsed.pathname === '/' ? '' : parsed.pathname;
+        const search = parsed.search;
+        const hash = parsed.hash;
+        const buildUrl = (hostname: string) => `${parsed.protocol}//${hostname}${port ? `:${port}` : ''}${pathname}${search}${hash}`;
+
+        if (parsed.hostname === '127.0.0.1') return dedupe([normalized, buildUrl('localhost'), buildUrl('[::1]')]);
+        if (parsed.hostname === 'localhost') return dedupe([normalized, buildUrl('127.0.0.1'), buildUrl('[::1]')]);
+        if (parsed.hostname === '[::1]' || parsed.hostname === '::1') return dedupe([normalized, buildUrl('localhost'), buildUrl('127.0.0.1')]);
+    } catch (_error) {}
+
+    return [normalized];
+};
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    const manifest = fs.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 buildBaseUrlCandidates(explicitUrl);
+
+    const port = getRouterPort();
+    return dedupe([`http://localhost:${port}`, `http://127.0.0.1:${port}`, `http://[::1]:${port}`]);
+};
+
+const requestJson = async <TResponse>(pathname: string) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                responseType: 'json',
+                retry: { limit: 0 },
+                throwHttpErrors: false,
+            });
+
+            if (response.statusCode >= 400) {
+                const body = response.body as { error?: string } | undefined;
+                throw new UsageError(body?.error || `Orient request failed with status ${response.statusCode}.`);
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+            attempts.push(`${baseUrl}${pathname}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum dev diagnostics server for orient.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or omit --port/--url to read the local manifest from disk.',
+        ].join('\n'),
+    );
+};
+
+const resolveManifest = async (): Promise<TProteumManifest> => {
+    const shouldUseRemoteServer =
+        (typeof cli.args.port === 'string' && cli.args.port.length > 0) ||
+        (typeof cli.args.url === 'string' && cli.args.url.length > 0);
+
+    if (shouldUseRemoteServer) {
+        return await requestJson<TProteumManifest>('/__proteum/explain');
+    }
+
+    const compiler = new Compiler('dev');
+    await compiler.refreshGeneratedTypings();
+    return readProteumManifest(cli.paths.appRoot);
+};
+
+const renderHuman = (response: TOrientResponse) =>
+    [
+        'Proteum orient',
+        `- query=${response.query}`,
+        `- appRoot=${response.app.appRoot}`,
+        `- repoRoot=${response.app.repoRoot}`,
+        `- identifier=${response.app.identifier}`,
+        ...(response.app.routerPort ? [`- routerPort=${response.app.routerPort}`] : []),
+        'Guidance',
+        `- agents=${response.guidance.agents}`,
+        `- diagnostics=${response.guidance.diagnostics}`,
+        `- optimizations=${response.guidance.optimizations}`,
+        `- codingStyle=${response.guidance.codingStyle}`,
+        `- areaAgents=${response.guidance.areaAgents.join(', ') || 'none'}`,
+        'Owner',
+        ...(response.owner.matches.length === 0
+            ? ['- none']
+            : response.owner.matches.slice(0, 6).map(
+                  (match) =>
+                      `- [${match.kind}] ${match.label} score=${match.score} scope=${match.scopeLabel} origin=${match.originHint} source=${match.source.filepath}${match.source.line ? `:${match.source.line}` : ''}${match.source.column ? `:${match.source.column}` : ''}`,
+              )),
+        'Connected',
+        ...(response.connected.imports.length === 0
+            ? ['- imports=none']
+            : response.connected.imports.map(
+                  (entry) => `- import ${entry.namespace}.${entry.clientAccessor} -> ${entry.httpPath} source=${entry.filepath}`,
+              )),
+        ...(response.connected.producers.length === 0
+            ? ['- producers=none']
+            : response.connected.producers.map(
+                  (project) =>
+                      `- producer ${project.namespace} identifier=${project.identityIdentifier || project.identityName || 'unknown'} source=${project.sourceKind || 'missing'} internal=${project.urlInternal || 'missing'}`,
+              )),
+        'Next',
+        ...response.nextSteps.map((step) => `- ${step.command} (${step.reason})`),
+        'Warnings',
+        ...(response.warnings.length === 0 ? ['- none'] : response.warnings.map((warning) => `- ${warning}`)),
+    ].join('\n');
+
+export const run = async () => {
+    const query = typeof cli.args.query === 'string' ? cli.args.query.trim() : '';
+    if (!query) throw new UsageError('A query is required. Example: proteum orient /api/Auth/CurrentUser');
+
+    const manifest = await resolveManifest();
+    const response = buildOrientationResponse(manifest, query);
+
+    if (cli.args.json === true) {
+        console.log(JSON.stringify(response, null, 2));
+        return;
+    }
+
+    console.log(renderHuman(response));
+};

package/cli/commands/perf.ts

@@ -164,12 +164,19 @@ const renderRequest = (response: TPerfRequestResponse) =>
                   (call) =>
                       `- ${call.label} | duration=${formatDuration(call.durationMs)} status=${call.statusCode ?? 'pending'} origin=${call.origin}${call.errorMessage ? ` error=${truncate(call.errorMessage, 96)}` : ''}`,
               )),
+        'Chain',
+        ...(!response.request.chain || response.request.chain.length === 0
+            ? ['- none']
+            : response.request.chain.map(
+                  (item) =>
+                      `- [${item.kind}] ${item.label}${item.source?.filepath ? ` | ${item.source.filepath}${item.source.line ? `:${item.source.line}` : ''}${item.source.column ? `:${item.source.column}` : ''}` : ''}${item.details.length > 0 ? ` | ${item.details.join(', ')}` : ''}`,
+              )),
         'Hot SQL',
         ...(response.request.hottestSqlQueries.length === 0
             ? ['- none']
             : response.request.hottestSqlQueries.map(
                   (query) =>
-                      `- ${query.callerLabel} | ${query.operation}${query.model ? ` ${query.model}` : ''} | duration=${formatDuration(query.durationMs)} | ${truncate(query.query, 104)}`,
+                      `- ${query.callerLabel} | ${query.operation}${query.model ? ` ${query.model}` : ''}${query.fingerprint ? ` | fp=${query.fingerprint}` : ''} | duration=${formatDuration(query.durationMs)} | ${truncate(query.query, 104)}`,
               )),
     ].join('\n');