proteum 2.1.2 → 2.1.6

package/common/connectedProjects.ts

@@ -0,0 +1,113 @@
+export const connectedProjectContractVersion = 1 as const;
+export const connectedProjectHealthPath = '/api/__proteum/connected/ping';
+export const connectedProjectProxyPathPrefix = '/api/__proteum/connected';
+
+export const connectedProjectSourceKinds = ['file', 'github'] as const;
+
+export type TConnectedProjectSourceKind = (typeof connectedProjectSourceKinds)[number];
+
+export type TConnectedProjectTypingMode = 'local-typed' | 'runtime-only';
+
+export type TConnectedProjectConfig = {
+    source?: string;
+    urlInternal?: string;
+};
+
+export type TConnectedProjectsConfig = Record<string, TConnectedProjectConfig>;
+
+export type TConnectedProjectContractController = {
+    className: string;
+    methodName: string;
+    routeBasePath: string;
+    routePath: string;
+    httpPath: string;
+    clientAccessor: string;
+    hasInput: boolean;
+    inputCallsCount: number;
+    importPath: string;
+    relativeFilepath: string;
+    sourceLocation: { line: number; column: number };
+};
+
+export type TConnectedProjectContract = {
+    version: typeof connectedProjectContractVersion;
+    packageName?: string;
+    identity: {
+        name: string;
+        identifier: string;
+    };
+    controllers: TConnectedProjectContractController[];
+};
+
+export type TConnectedProjectEnvConfig = {
+    namespace: string;
+    urlInternal: string;
+};
+
+export type TConnectedFetcherTarget = {
+    namespace: string;
+    controllerAccessor: string;
+    httpPath: string;
+};
+
+const normalizeNamespace = (value: string) => value.trim();
+
+export const normalizeConnectedProjectsConfig = (value: unknown): TConnectedProjectsConfig => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+
+    const output: TConnectedProjectsConfig = {};
+
+    for (const [rawNamespace, rawConfig] of Object.entries(value)) {
+        const namespace = normalizeNamespace(rawNamespace);
+        if (!namespace) continue;
+        if (!rawConfig || typeof rawConfig !== 'object' || Array.isArray(rawConfig)) continue;
+
+        if ('source' in rawConfig && rawConfig.source !== undefined && rawConfig.source !== null && typeof rawConfig.source !== 'string') {
+            throw new Error(`Invalid connect.${namespace}.source. Expected a string.`);
+        }
+        if ('urlInternal' in rawConfig && rawConfig.urlInternal !== undefined && rawConfig.urlInternal !== null && typeof rawConfig.urlInternal !== 'string') {
+            throw new Error(`Invalid connect.${namespace}.urlInternal. Expected a string.`);
+        }
+        const source =
+            'source' in rawConfig && rawConfig.source !== undefined && rawConfig.source !== null
+                ? String(rawConfig.source).trim() || undefined
+                : undefined;
+        const urlInternal =
+            'urlInternal' in rawConfig && rawConfig.urlInternal !== undefined && rawConfig.urlInternal !== null
+                ? String(rawConfig.urlInternal).trim() || undefined
+                : undefined;
+
+        output[namespace] = {
+            ...(source ? { source } : {}),
+            ...(urlInternal ? { urlInternal } : {}),
+        };
+    }
+
+    return output;
+};
+
+export const getConnectedProjectSlug = (namespace: string) =>
+    normalizeNamespace(namespace)
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toUpperCase();
+
+export const buildConnectedProjectProxyPath = (namespace: string, httpPath: string) => {
+    const normalizedHttpPath = httpPath.startsWith('/') ? httpPath : `/${httpPath}`;
+    return `${connectedProjectProxyPathPrefix}/${encodeURIComponent(normalizeNamespace(namespace))}${normalizedHttpPath}`;
+};
+
+export const parseConnectedProjectProxyPath = (pathname: string) => {
+    if (!pathname.startsWith(`${connectedProjectProxyPathPrefix}/`)) return undefined;
+
+    const remainder = pathname.slice(connectedProjectProxyPathPrefix.length + 1);
+    const separatorIndex = remainder.indexOf('/');
+    if (separatorIndex === -1) return undefined;
+
+    const namespace = decodeURIComponent(remainder.slice(0, separatorIndex)).trim();
+    const httpPath = `/${remainder.slice(separatorIndex + 1)}`;
+    if (!namespace || httpPath === '/') return undefined;
+
+    return { namespace, httpPath };
+};

package/common/dev/connect.ts

@@ -0,0 +1,267 @@
+import fs from 'fs';
+
+import {
+    formatManifestFilepath,
+    formatManifestLocation,
+    renderHumanBlock,
+    type THumanTextBlock,
+} from './diagnostics';
+import type {
+    TProteumManifest,
+    TProteumManifestController,
+    TProteumManifestDiagnostic,
+} from './proteumManifest';
+
+export type TConnectProjectController = {
+    clientAccessor: string;
+    filepath: string;
+    hasInput: boolean;
+    httpPath: string;
+    methodName: string;
+};
+
+export type TConnectProjectReport = {
+    namespace: string;
+    identityIdentifier?: string;
+    identityName?: string;
+    sourceKind?: string;
+    sourceValue?: string;
+    sourceConfigured: boolean;
+    cachedContractFilepath?: string;
+    cachedContractExists: boolean;
+    typingMode?: string;
+    urlInternalConfigured: boolean;
+    urlInternal?: string;
+    controllerCount: number;
+    controllers?: TConnectProjectController[];
+};
+
+export type TConnectResponse = {
+    app: {
+        identifier: string;
+        name: string;
+        root: string;
+    };
+    summary: {
+        connectedProjects: number;
+        errors: number;
+        importedControllers: number;
+        strictFailed: boolean;
+        warnings: number;
+    };
+    projects: TConnectProjectReport[];
+    diagnostics: TProteumManifestDiagnostic[];
+};
+
+const createDiagnostic = ({
+    code,
+    filepath,
+    level = 'error',
+    message,
+}: {
+    code: string;
+    filepath: string;
+    level?: TProteumManifestDiagnostic['level'];
+    message: string;
+}): TProteumManifestDiagnostic => ({
+    code,
+    filepath,
+    level,
+    message,
+});
+
+const sortDiagnostics = (diagnostics: TProteumManifestDiagnostic[]) =>
+    [...diagnostics].sort((left, right) => {
+        if (left.level !== right.level) return left.level === 'error' ? -1 : 1;
+        if (left.filepath !== right.filepath) return left.filepath.localeCompare(right.filepath);
+        return left.code.localeCompare(right.code);
+    });
+
+const toControllerSummary = (controller: TProteumManifestController): TConnectProjectController => ({
+    clientAccessor: controller.clientAccessor,
+    filepath: controller.filepath,
+    hasInput: controller.hasInput,
+    httpPath: controller.httpPath,
+    methodName: controller.methodName,
+});
+
+const formatControllerItem = (manifest: TProteumManifest, controller: TConnectProjectController) =>
+    `${controller.clientAccessor} -> POST ${controller.httpPath} input=${controller.hasInput ? 'yes' : 'no'} source=${formatManifestFilepath(manifest, controller.filepath)}#${controller.methodName}`;
+
+const formatProjectItem = (manifest: TProteumManifest, project: TConnectProjectReport) =>
+    `${project.namespace} -> ${project.identityIdentifier || project.identityName || 'unknown'} controllers=${project.controllerCount} sourceConfigured=${project.sourceConfigured ? 'yes' : 'no'} internal=${project.urlInternal || 'missing'} configured=${project.urlInternalConfigured ? 'yes' : 'no'}${project.sourceKind ? ` source=${project.sourceKind}` : ''}${project.sourceValue ? ` sourceValue=${project.sourceValue}` : ''}${project.typingMode ? ` typing=${project.typingMode}` : ''}${project.cachedContractFilepath ? ` contract=${formatManifestFilepath(manifest, project.cachedContractFilepath)}` : ''}${project.cachedContractFilepath ? ` cache=${project.cachedContractExists ? 'present' : 'missing'}` : ''}`;
+
+export const buildConnectResponse = (
+    manifest: TProteumManifest,
+    options: { includeControllers?: boolean; strict?: boolean } = {},
+): TConnectResponse => {
+    const diagnostics: TProteumManifestDiagnostic[] = [];
+    const projects: TConnectProjectReport[] = manifest.connectedProjects.map((project) => {
+        const controllers = manifest.controllers
+            .filter((controller) => controller.connectedProjectNamespace === project.namespace)
+            .sort((left, right) => left.clientAccessor.localeCompare(right.clientAccessor));
+        const sourceConfigured = typeof project.sourceValue === 'string' && project.sourceValue.trim() !== '';
+        const urlInternalConfigured = typeof project.urlInternal === 'string' && project.urlInternal.trim() !== '';
+        const cachedContractExists = project.cachedContractFilepath ? fs.existsSync(project.cachedContractFilepath) : false;
+
+        if (!sourceConfigured) {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.source-missing',
+                    filepath: manifest.app.setupFilepath,
+                    message: `Connected project "${project.namespace}" requires connect.${project.namespace}.source in proteum.config.ts during generation.`,
+                }),
+            );
+        }
+
+        if (sourceConfigured && !project.sourceKind) {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.contract-unresolved',
+                    filepath: manifest.app.setupFilepath,
+                    message: `Connected project "${project.namespace}" does not have a resolved contract source in the manifest.`,
+                }),
+            );
+        }
+
+        if (!project.cachedContractFilepath) {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.contract-cache-missing',
+                    filepath: manifest.app.setupFilepath,
+                    message: `Connected project "${project.namespace}" has no cached contract filepath in the manifest.`,
+                }),
+            );
+        } else if (!cachedContractExists) {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.contract-cache-missing-on-disk',
+                    filepath: project.cachedContractFilepath,
+                    message: `Cached connected contract "${project.cachedContractFilepath}" is missing from disk.`,
+                }),
+            );
+        }
+
+        if (!urlInternalConfigured) {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.url-internal-missing',
+                    filepath: manifest.app.setupFilepath,
+                    message: `Connected project "${project.namespace}" requires connect.${project.namespace}.urlInternal in proteum.config.ts for runtime calls.`,
+                }),
+            );
+        }
+
+        if (project.controllerCount === 0) {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.controllers-empty',
+                    filepath: manifest.app.setupFilepath,
+                    level: 'warning',
+                    message: `Connected project "${project.namespace}" imported zero controllers.`,
+                }),
+            );
+        }
+
+        if (project.sourceKind === 'file' && project.typingMode !== 'local-typed') {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.typing-mode-unexpected',
+                    filepath: manifest.app.setupFilepath,
+                    level: 'warning',
+                    message: `Connected project "${project.namespace}" uses a file source but typing mode is "${project.typingMode || 'unknown'}".`,
+                }),
+            );
+        }
+
+        if (project.sourceKind && project.sourceKind !== 'file' && project.typingMode === 'local-typed') {
+            diagnostics.push(
+                createDiagnostic({
+                    code: 'connect.typing-mode-unexpected',
+                    filepath: manifest.app.setupFilepath,
+                    level: 'warning',
+                    message: `Connected project "${project.namespace}" is non-local but typing mode is "${project.typingMode}".`,
+                }),
+            );
+        }
+
+        return {
+            namespace: project.namespace,
+            identityIdentifier: project.identityIdentifier,
+            identityName: project.identityName,
+            sourceKind: project.sourceKind,
+            sourceValue: project.sourceValue,
+            sourceConfigured,
+            cachedContractFilepath: project.cachedContractFilepath,
+            cachedContractExists,
+            typingMode: project.typingMode,
+            urlInternalConfigured,
+            urlInternal: project.urlInternal,
+            controllerCount: project.controllerCount,
+            ...(options.includeControllers === true ? { controllers: controllers.map(toControllerSummary) } : {}),
+        };
+    });
+
+    const sortedDiagnostics = sortDiagnostics(diagnostics);
+    const errors = sortedDiagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
+    const warnings = sortedDiagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+
+    return {
+        app: {
+            identifier: manifest.app.identity.identifier,
+            name: manifest.app.identity.name,
+            root: manifest.app.root,
+        },
+        summary: {
+            connectedProjects: projects.length,
+            errors,
+            importedControllers: projects.reduce((count, project) => count + project.controllerCount, 0),
+            strictFailed: options.strict === true && sortedDiagnostics.length > 0,
+            warnings,
+        },
+        projects,
+        diagnostics: sortedDiagnostics,
+    };
+};
+
+export const renderConnectHuman = (manifest: TProteumManifest, response: TConnectResponse) => {
+    const blocks: THumanTextBlock[] = [
+        {
+            title: 'Proteum Connect',
+            items: [
+                `app=${response.app.name} (${response.app.identifier})`,
+                `root=${formatManifestFilepath(manifest, response.app.root)}`,
+                `connectedProjects=${response.summary.connectedProjects}`,
+                `importedControllers=${response.summary.importedControllers}`,
+                `diagnostics=${response.summary.errors} errors, ${response.summary.warnings} warnings`,
+            ],
+        },
+        {
+            title: 'Connected Projects',
+            items: response.projects.map((project) => formatProjectItem(manifest, project)),
+            empty: 'No connected projects are configured.',
+        },
+    ];
+
+    const controllerItems = response.projects.flatMap((project) =>
+        (project.controllers || []).map((controller) => formatControllerItem(manifest, controller)),
+    );
+
+    if (controllerItems.length > 0) {
+        blocks.push({
+            title: 'Imported Controllers',
+            items: controllerItems,
+        });
+    }
+
+    blocks.push({
+        title: 'Diagnostics',
+        items: response.diagnostics.map(
+            (diagnostic) =>
+                `[${diagnostic.level}] ${diagnostic.code} ${diagnostic.message} source=${formatManifestFilepath(manifest, diagnostic.filepath)}${formatManifestLocation(diagnostic.sourceLocation?.line, diagnostic.sourceLocation?.column)}`,
+        ),
+        empty: 'No connect diagnostics were found.',
+    });
+
+    return blocks.map((block) => renderHumanBlock(block)).join('\n\n');
+};

package/common/dev/console.ts

@@ -0,0 +1,31 @@
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+import type { TTraceCallOrigin, TTraceSqlQueryKind } from './requestTrace';
+
+export type TDevConsoleLogLevel = 'silly' | 'log' | 'info' | 'warn' | 'error';
+
+export type TDevConsoleLogChannel = {
+    channelType: 'cron' | 'master' | 'request' | 'socket';
+    channelId?: string;
+    method?: string;
+    path?: string;
+    user?: string;
+    traceCallId?: string;
+    traceCallOrigin?: TTraceCallOrigin;
+    traceCallLabel?: string;
+    traceCallFetcherId?: string;
+    prismaOperations?: Array<{ kind: TTraceSqlQueryKind; model?: string; operation: string }>;
+};
+
+export type TDevConsoleLogEntry = {
+    channel: TDevConsoleLogChannel;
+    level: TDevConsoleLogLevel;
+    text: string;
+    time: string;
+};
+
+export type TDevConsoleLogsResponse = {
+    logs: TDevConsoleLogEntry[];
+};

package/common/dev/contractsDoctor.ts

@@ -0,0 +1,128 @@
+import fs from 'fs';
+import path from 'path';
+
+import type { TDoctorResponse } from './diagnostics';
+import type {
+    TProteumManifest,
+    TProteumManifestDiagnostic,
+} from './proteumManifest';
+
+const buildGeneratedArtifactList = (manifest: TProteumManifest) => {
+    const appRoot = manifest.app.root;
+    const clientRouteModulesRoot = path.join(appRoot, '.proteum', 'client', 'route-modules');
+    const serverRouteModulesRoot = path.join(appRoot, '.proteum', 'server', 'route-modules');
+    const generated = new Set<string>([
+        path.join(appRoot, 'proteum.connected.json'),
+        path.join(appRoot, '.proteum', 'manifest.json'),
+        path.join(appRoot, '.proteum', 'proteum.connected.d.ts'),
+        path.join(appRoot, '.proteum', 'client', 'context.ts'),
+        path.join(appRoot, '.proteum', 'client', 'controllers.ts'),
+        path.join(appRoot, '.proteum', 'client', 'layouts.ts'),
+        path.join(appRoot, '.proteum', 'client', 'models.ts'),
+        path.join(appRoot, '.proteum', 'client', 'routes.ts'),
+        path.join(appRoot, '.proteum', 'client', 'services.d.ts'),
+        path.join(appRoot, '.proteum', 'common', 'controllers.ts'),
+        path.join(appRoot, '.proteum', 'common', 'models.ts'),
+        path.join(appRoot, '.proteum', 'common', 'services.d.ts'),
+        path.join(appRoot, '.proteum', 'server', 'commands.app.d.ts'),
+        path.join(appRoot, '.proteum', 'server', 'commands.d.ts'),
+        path.join(appRoot, '.proteum', 'server', 'commands.ts'),
+        path.join(appRoot, '.proteum', 'server', 'controllers.ts'),
+        path.join(appRoot, '.proteum', 'server', 'models.ts'),
+        path.join(appRoot, '.proteum', 'server', 'routes.ts'),
+        path.join(appRoot, '.proteum', 'server', 'services.d.ts'),
+    ]);
+
+    for (const route of manifest.routes.client) {
+        const sourceExtension = path.extname(route.filepath);
+        const chunkFilepath = route.chunkFilepath
+            ? `${route.chunkFilepath}${sourceExtension && route.chunkFilepath.endsWith(sourceExtension) ? '' : sourceExtension}`
+            : undefined;
+
+        if (chunkFilepath) generated.add(path.join(clientRouteModulesRoot, chunkFilepath));
+
+        const relativeSource = path.relative(appRoot, route.filepath);
+        generated.add(path.join(serverRouteModulesRoot, relativeSource));
+    }
+
+    for (const route of manifest.routes.server) {
+        const relativeSource = path.relative(appRoot, route.filepath);
+        generated.add(path.join(serverRouteModulesRoot, relativeSource));
+    }
+
+    return [...generated];
+};
+
+const createContractDiagnostic = ({
+    code,
+    filepath,
+    level = 'error',
+    message,
+    relatedFilepaths,
+}: {
+    code: string;
+    filepath: string;
+    level?: TProteumManifestDiagnostic['level'];
+    message: string;
+    relatedFilepaths?: string[];
+}): TProteumManifestDiagnostic => ({
+    code,
+    filepath,
+    level,
+    message,
+    ...(relatedFilepaths && relatedFilepaths.length > 0 ? { relatedFilepaths } : {}),
+});
+
+export const buildContractsDoctorResponse = (manifest: TProteumManifest, strict = false): TDoctorResponse => {
+    const diagnostics: TProteumManifestDiagnostic[] = [];
+    const sourceFilepaths = new Set<string>([
+        manifest.app.identityFilepath,
+        manifest.app.setupFilepath,
+        ...manifest.controllers.map((controller) => controller.filepath),
+        ...manifest.connectedProjects.flatMap((connectedProject) =>
+            connectedProject.cachedContractFilepath ? [connectedProject.cachedContractFilepath] : [],
+        ),
+        ...manifest.commands.map((command) => command.filepath),
+        ...manifest.routes.client.map((route) => route.filepath),
+        ...manifest.routes.server.map((route) => route.filepath),
+        ...manifest.layouts.map((layout) => layout.filepath),
+        ...manifest.services.app.flatMap((service) => (service.sourceFilepath ? [service.sourceFilepath] : [])),
+        ...manifest.services.routerPlugins.flatMap((service) => (service.sourceFilepath ? [service.sourceFilepath] : [])),
+    ]);
+
+    for (const filepath of sourceFilepaths) {
+        if (fs.existsSync(filepath)) continue;
+
+        diagnostics.push(
+            createContractDiagnostic({
+                code: 'contract.source-missing',
+                filepath,
+                message: `Referenced source file "${filepath}" is missing from disk.`,
+            }),
+        );
+    }
+
+    for (const filepath of buildGeneratedArtifactList(manifest)) {
+        if (fs.existsSync(filepath)) continue;
+
+        diagnostics.push(
+            createContractDiagnostic({
+                code: 'contract.generated-missing',
+                filepath,
+                message: `Expected generated artifact "${filepath}" is missing.`,
+            }),
+        );
+    }
+
+    const errors = diagnostics.filter((diagnostic) => diagnostic.level === 'error');
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
+
+    return {
+        diagnostics,
+        summary: {
+            errors: errors.length,
+            strictFailed: strict === true && diagnostics.length > 0,
+            warnings: warnings.length,
+        },
+    };
+};