proteum 2.1.9 → 2.2.0

package/cli/commands/configure.ts

@@ -0,0 +1,226 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import fs from 'fs';
+import path from 'path';
+import prompts from 'prompts';
+import { UsageError } from 'clipanion';
+
+// Configs
+import cli from '..';
+import { renderRows } from '../presentation/layout';
+import { isLikelyProteumAppRoot } from '../presentation/commands';
+import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
+import { configureProjectAgentSymlinks, type TConfigureProjectAgentSymlinksResult } from '../utils/agents';
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const findLikelyRepoRoot = (startPath: string) => {
+    let currentPath = path.resolve(startPath);
+
+    while (true) {
+        if (fs.existsSync(path.join(currentPath, '.git'))) return currentPath;
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return undefined;
+        currentPath = parentPath;
+    }
+};
+
+const resolveCanonicalPath = (inputPath: string) => {
+    const resolvedPath = path.resolve(inputPath);
+
+    try {
+        return fs.realpathSync(resolvedPath);
+    } catch {
+        return resolvedPath;
+    }
+};
+
+const isInsideDirectory = ({ child, parent }: { child: string; parent: string }) => {
+    const relativePath = path.relative(parent, child);
+    return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+};
+
+const assertProteumAppRoot = (appRoot: string) => {
+    if (isLikelyProteumAppRoot(appRoot)) return;
+
+    throw new UsageError(
+        `This command expects a Proteum app root. Missing one or more required entries in ${appRoot}.`,
+    );
+};
+
+const promptMonorepoRoot = async ({
+    appRoot,
+    defaultRoot,
+}: {
+    appRoot: string;
+    defaultRoot?: string;
+}) => {
+    const response = await prompts(
+        {
+            type: 'text',
+            name: 'value',
+            message: 'Monorepo root path',
+            initial: defaultRoot,
+            validate: (input) => {
+                const resolvedRoot = resolveCanonicalPath(String(input || defaultRoot || ''));
+
+                if (!input && !defaultRoot) return 'A monorepo root path is required.';
+                if (!fs.existsSync(resolvedRoot) || !fs.statSync(resolvedRoot).isDirectory())
+                    return `Directory not found: ${resolvedRoot}`;
+                if (!isInsideDirectory({ child: appRoot, parent: resolvedRoot }))
+                    return `The Proteum app root must be inside the monorepo root: ${resolvedRoot}`;
+
+                return true;
+            },
+        },
+        {
+            onCancel: () => {
+                throw new UsageError('Cancelled `proteum configure agents`.');
+            },
+        },
+    );
+
+    return resolveCanonicalPath(String(response.value || defaultRoot || ''));
+};
+
+const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
+    if (blockedPaths.length === 0) return [];
+
+    console.info(await renderWarning('Proteum found existing non-managed instruction paths.'));
+    console.info(['Choose whether to overwrite each path with a Proteum-managed symlink:', ...blockedPaths.map((entry) => `- ${entry}`)].join('\n'));
+
+    const overwriteBlockedPaths: string[] = [];
+
+    for (const blockedPath of blockedPaths) {
+        const response = await prompts(
+            {
+                type: 'confirm',
+                name: 'value',
+                message: `Overwrite ${blockedPath}?`,
+                initial: false,
+            },
+            {
+                onCancel: () => {
+                    throw new UsageError('Cancelled `proteum configure agents`.');
+                },
+            },
+        );
+
+        if (response.value === true) overwriteBlockedPaths.push(blockedPath);
+    }
+
+    return overwriteBlockedPaths;
+};
+
+const renderConfigureResultSections = (result: TConfigureProjectAgentSymlinksResult) => {
+    const sections: string[] = [];
+
+    sections.push(
+        renderRows(
+            [
+                { label: 'mode', value: result.mode },
+                ...(result.monorepoRoot ? [{ label: 'monorepo root', value: result.monorepoRoot }] : []),
+            ],
+            { minLabelWidth: 16, maxLabelWidth: 16 },
+        ),
+    );
+
+    if (result.created.length > 0) sections.push(['Created:', ...result.created.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.updated.length > 0) sections.push(['Updated:', ...result.updated.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.overwritten.length > 0)
+        sections.push(['Overwritten:', ...result.overwritten.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.updatedGitignores.length > 0)
+        sections.push(['Updated .gitignore:', ...result.updatedGitignores.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.blocked.length > 0)
+        sections.push(
+            [
+                'Skipped existing non-managed paths:',
+                ...result.blocked.map((entry) => `- ${entry}`),
+            ].join('\n'),
+        );
+
+    return sections;
+};
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+
+export const run = async (): Promise<void> => {
+    if (cli.args.action !== 'agents') throw new UsageError('Usage: `proteum configure agents`');
+
+    const appRoot = resolveCanonicalPath(cli.paths.appRoot);
+    assertProteumAppRoot(appRoot);
+
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new UsageError('`proteum configure agents` is interactive and requires a TTY.');
+    }
+
+    const likelyRepoRoot = findLikelyRepoRoot(appRoot);
+    const defaultMonorepoRoot =
+        likelyRepoRoot && likelyRepoRoot !== appRoot && isInsideDirectory({ child: appRoot, parent: likelyRepoRoot })
+            ? likelyRepoRoot
+            : undefined;
+    console.info(
+        [
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure Proteum-managed instruction symlinks.'),
+            renderRows([{ label: 'app', value: appRoot === process.cwd() ? '.' : appRoot }]),
+        ].join('\n\n'),
+    );
+
+    const monorepoResponse = await prompts(
+        {
+            type: 'confirm',
+            name: 'value',
+            message: 'Is this Proteum app part of a monorepo?',
+            initial: defaultMonorepoRoot !== undefined,
+        },
+        {
+            onCancel: () => {
+                throw new UsageError('Cancelled `proteum configure agents`.');
+            },
+        },
+    );
+    const isMonorepo = monorepoResponse.value === true;
+    const monorepoRoot = isMonorepo
+        ? await promptMonorepoRoot({
+              appRoot,
+              defaultRoot: defaultMonorepoRoot,
+          })
+        : undefined;
+
+    const preview = configureProjectAgentSymlinks({
+        appRoot,
+        coreRoot: cli.paths.core.root,
+        dryRun: true,
+        monorepoRoot,
+    });
+    const overwriteBlockedPaths = await promptBlockedOverwritePaths(preview.blocked);
+
+    console.info(
+        await renderStep(
+            '[1/1]',
+            isMonorepo
+                ? `Writing monorepo-aware instruction symlinks using ${monorepoRoot}.`
+                : 'Writing standalone instruction symlinks.',
+        ),
+    );
+
+    const result = configureProjectAgentSymlinks({
+        appRoot,
+        coreRoot: cli.paths.core.root,
+        monorepoRoot,
+        overwriteBlockedPaths,
+    });
+    const sections = renderConfigureResultSections(result);
+
+    console.info(await renderSuccess('Proteum-managed instruction symlinks are configured.'));
+
+    if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
+};

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');