proteum 2.5.9 → 2.5.11

package/cli/compiler/server/index.ts

@@ -10,6 +10,11 @@ import { type Configuration } from '@rspack/core';
 import cli from '@cli';
 import createCommonConfig, { TCompileMode, TCompileOutputTarget, regex } from '../common';
 import { toRspackAliases } from '../common/rspackAliases';
+import {
+    isUiSingletonRequest,
+    resolveUiSingletonAliases,
+    resolveUiSingletonServerExternalRequest,
+} from '../common/uiSingletons';
 import { resolveServerExternalRequest } from './externals';
 
 // Type
@@ -51,6 +56,9 @@ const getDevGeneratedRuntimeEntries = (app: App) => ({
     __proteum_dev_routes: [app.paths.server.generated + '/routes.ts'],
     __proteum_dev_controllers: [app.paths.server.generated + '/controllers.ts'],
 });
+const resolveFromAppOrCore = (request: string) => cli.paths.resolveRequest(request, { preferApp: true });
+const resolvePackageRootFromAppOrCore = (packageName: string) =>
+    cli.paths.resolvePackageRoot(packageName, { preferApp: true });
 const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
 const getFrameworkSourceRoot = () => {
     const installedCoreRoot = cli.paths.framework.installedRoot
@@ -120,6 +128,13 @@ export default function createCompiler(
     const rspackAliases = toRspackAliases(resolvedAliases);
     rspackAliases['proteum'] = frameworkSourceRoot;
     rspackAliases['@/client/router$'] = frameworkSourceRoot + '/client/router.ts';
+    Object.assign(
+        rspackAliases,
+        resolveUiSingletonAliases({
+            resolvePackageRoot: resolvePackageRootFromAppOrCore,
+            resolveRequest: resolveFromAppOrCore,
+        }),
+    );
 
     debug &&
         console.log(
@@ -160,20 +175,27 @@ export default function createCompiler(
 
             // node_modules
             function ({ context, request }, callback) {
+                if (request === undefined) return callback();
+
+                const uiSingletonExternalRequest = resolveUiSingletonServerExternalRequest(request, resolveFromAppOrCore);
+                if (uiSingletonExternalRequest !== undefined) {
+                    return callback(undefined, 'commonjs ' + uiSingletonExternalRequest);
+                }
+
                 const shouldCompile =
-                    request !== undefined &&
                     // Local files
-                    (request[0] === '.' ||
-                        request[0] === '/' ||
-                        // Aliased modules
-                        app.aliases.server.containsAlias(request) ||
-                        // TODO: proteum.conf: compile: include
-                        app.isTranspileModuleRequest(request) ||
-                        // Compile proteum modules
-                        request.startsWith('proteum') ||
-                        // React-based UI packages must pass through the alias layer on the server,
-                        // otherwise SSR can mix real React packages with the Preact compat runtime.
-                        serverReactCompatCompilePrefixes.some((prefix) => request.startsWith(prefix)));
+                    request[0] === '.' ||
+                    request[0] === '/' ||
+                    // Aliased modules
+                    app.aliases.server.containsAlias(request) ||
+                    // TODO: proteum.conf: compile: include
+                    app.isTranspileModuleRequest(request) ||
+                    // Compile proteum modules
+                    request.startsWith('proteum') ||
+                    // React/Preact singleton packages and React-based UI packages must pass through the alias layer on the server,
+                    // otherwise SSR can mix real React packages with the Preact compat runtime.
+                    isUiSingletonRequest(request) ||
+                    serverReactCompatCompilePrefixes.some((prefix) => request.startsWith(prefix));
 
                 //console.log('isNodeModule', request, isNodeModule);
 

package/cli/presentation/commands.ts

@@ -14,6 +14,7 @@ export const proteumCommandNames = [
     'typecheck',
     'lint',
     'check',
+    'docs',
     'e2e',
     'connect',
     'doctor',
@@ -301,6 +302,19 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: ['This command executes refresh, typecheck, then lint in that order.', 'From a monorepo wrapper root, check runs once per discovered Proteum app.'],
         status: 'stable',
     },
+    docs: {
+        name: 'docs',
+        category: 'Quality gates',
+        summary: 'Check that code and documentation still point at each other.',
+        usage: 'proteum docs check',
+        bestFor: 'Confirming doc anchors resolve and that fix notes and feature packs are reachable from code.',
+        examples: [{ description: 'Check every doc anchor in the repository', command: 'proteum docs check' }],
+        notes: [
+            'Only an anchor that no longer resolves fails the command; missing coverage is reported as a backlog.',
+            'Anchors are the `@docs`, `@adr`, `@fix`, and `@rule` tags described in `CODING_STYLE.md`.',
+        ],
+        status: 'stable',
+    },
     e2e: {
         name: 'e2e',
         category: 'Quality gates',
@@ -594,7 +608,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'session',
         category: 'Manifest and contracts',
         summary: 'Mint a dev-only auth session token and cookie payload for a known user.',
-        usage: 'proteum session <email> [--role <role>] [--port <port>|--url <baseUrl>] [--json]',
+        usage: 'proteum session <email> [--role <role>] [--redirect <path>] [--port <port>|--url <baseUrl>] [--json]',
         bestFor:
             'Starting browser or API automation from an authenticated state without driving the login UI, while still using the app-configured auth service.',
         examples: [
@@ -606,11 +620,16 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
                 description: 'Mint a GOD session for unique.domains and print machine-readable cookie data',
                 command: 'proteum session god@example.com --role GOD --json',
             },
+            {
+                description: 'Print a browser login URL that sets the cookie and opens a protected page',
+                command: 'proteum session admin@example.com --port 3101 --redirect /admin --json',
+            },
         ],
         notes: [
             'Sessions are available only in dev mode and use the auth service registered on the current app router.',
             'You must provide the target user email explicitly; Proteum does not guess your admin account universally across apps.',
             'The command returns a token plus Playwright-ready cookie JSON so agents can inject the session into a browser context directly.',
+            'The command also returns a browser login URL that works on localhost dev servers, sets the same session cookie, and redirects to a local path.',
             'Without `--port` or `--url`, Proteum refreshes generated artifacts, builds the dev output, starts a temporary local dev server, creates the session, prints the payload, and exits.',
         ],
         status: 'experimental',

package/cli/runtime/commands.ts

@@ -352,6 +352,22 @@ class CheckCommand extends ProteumCommand {
     }
 }
 
+class DocsCommand extends ProteumCommand {
+    public static paths = [['docs']];
+
+    public static usage = buildUsage('docs');
+
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = '', ...restArgs] = this.args;
+
+        assertNoLegacyArgs('docs', restArgs);
+        this.setCliArgs({ action });
+        await runCommandModule(() => import('../commands/docs'));
+    }
+}
+
 class E2eCommand extends ProteumCommand {
     public static paths = [['e2e']];
 
@@ -617,6 +633,7 @@ class SessionCommand extends ProteumCommand {
     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 redirect = Option.String('--redirect', { description: 'Local path used by the browser login URL.' });
     public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
     public args = Option.Rest();
 
@@ -628,6 +645,7 @@ class SessionCommand extends ProteumCommand {
             role: this.role ?? '',
             port: this.port ?? '',
             url: this.url ?? '',
+            redirect: this.redirect ?? '',
             json: this.json,
         });
 
@@ -917,6 +935,7 @@ export const registeredCommands = {
     typecheck: TypecheckCommand,
     lint: LintCommand,
     check: CheckCommand,
+    docs: DocsCommand,
     e2e: E2eCommand,
     connect: ConnectCommand,
     doctor: DoctorCommand,
@@ -953,6 +972,7 @@ export const createCli = (version: string) => {
     clipanion.register(TypecheckCommand);
     clipanion.register(LintCommand);
     clipanion.register(CheckCommand);
+    clipanion.register(DocsCommand);
     clipanion.register(E2eCommand);
     clipanion.register(ConnectCommand);
     clipanion.register(DoctorCommand);

package/cli/scaffold/index.ts

@@ -556,6 +556,9 @@ export const runCreateScaffold = async () => {
 
     result.notes.push(...plan.notes);
     result.nextSteps.push(...plan.nextSteps);
+    result.nextSteps.push(
+        'Adapt the generated code to the real feature and record non-obvious decisions as why-comments per `CODING_STYLE.md` (`Decision and context comments`).',
+    );
     printResult(result);
 };
 

package/cli/scaffold/templates.ts

@@ -22,7 +22,15 @@ export const createPageTemplate = ({
     routePath: string;
     heading: string;
     message: string;
-}) => `import { definePageRoute } from '@common/router/definitions';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { definePageRoute } from '@common/router/definitions';
+
+/*----------------------------------
+- PAGE
+----------------------------------*/
 
 export default definePageRoute({
     path: ${JSON.stringify(routePath)},
@@ -53,7 +61,15 @@ export const createControllerTemplate = ({
     appIdentifier: string;
     className: string;
     methodName: string;
-}) => `import { defineAction, defineController } from '@generated/server/controller';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { defineAction, defineController } from '@generated/server/controller';
+
+/*----------------------------------
+- CONTROLEUR
+----------------------------------*/
 
 export default defineController({
     actions: {
@@ -74,11 +90,23 @@ export const createCommandTemplate = ({
 }: {
     className: string;
     methodName: string;
-}) => `import { Commands } from '@server/app/commands';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { Commands } from '@server/app/commands';
 import type AppApplication from '@/server/index';
 
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
 type App = InstanceType<typeof AppApplication>;
 
+/*----------------------------------
+- COMMANDS
+----------------------------------*/
+
 export default class ${className} extends Commands<App> {
     public async ${methodName}() {
         return {
@@ -95,7 +123,15 @@ export const createRouteTemplate = ({
 }: {
     httpMethod: string;
     routePath: string;
-}) => `import { defineServerRoute } from '@common/router/definitions';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { defineServerRoute } from '@common/router/definitions';
+
+/*----------------------------------
+- ROUTES
+----------------------------------*/
 
 export default defineServerRoute({
     method: ${JSON.stringify(httpMethod.toUpperCase())},
@@ -115,12 +151,24 @@ export const createServiceTemplate = ({
 }: {
     appIdentifier: string;
     className: string;
-}) => `import Service from '@server/app/service';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import Service from '@server/app/service';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
 
 export type Config = {
     debug?: boolean;
 };
 
+/*----------------------------------
+- SERVICE
+----------------------------------*/
+
 export default class ${className} extends Service<Config, {}, ${appIdentifier}, ${appIdentifier}> {
     public async health() {
         return {
@@ -138,9 +186,17 @@ export const createServiceConfigTemplate = ({
     configExportName: string;
     serviceImportPath: string;
     serviceImportName: string;
-}) => `import { Services } from '@server/app';
+}) => `/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+import { Services } from '@server/app';
 import ${serviceImportName} from ${JSON.stringify(serviceImportPath)};
 
+/*----------------------------------
+- CONFIG
+----------------------------------*/
+
 export const ${configExportName} = Services.config(${serviceImportName}, {});
 `;
 

package/cli/utils/agents.ts

@@ -1053,11 +1053,11 @@ function renderEmbeddedProjectInstructions({
         '- Worktree Preflight (`cwd` inside `/.codex/worktrees/`, newly created Proteum worktree, or before editing in a Codex worktree): read Root contract fallback, run `npx proteum worktree init --source <source-app-root>` when the bootstrap marker is missing, run `npx proteum worktree init --source <source-app-root> --refresh` when Proteum reports stale bootstrap state, use `--skip-deps --reason "..."` only for intentional dependency skips, then run `npx proteum runtime status`; for runtime-visible work start or reuse one tracked `npx proteum dev` session using the Task Lifecycle launch workflow.',
         '- Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): read Root contract fallback before any git write.',
         '- Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change: read `DOCUMENTATION.md` and verify required docs, fix notes, or ADRs were updated or explicitly skipped with a reason.',
-        '- Before finishing production code changes: read Root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`.',
+        '- Before finishing production code changes: read Root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`. Run the `CODING_STYLE.md` self-check on the final diff; a non-obvious decision, workaround, or bug fix without a why-comment is a defect to fix before finishing.',
         '- Runtime-visible, request-time, router, SSR, browser, or controller behavior: read Root contract fallback and `diagnostics.md` for verification routing.',
         '- Bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes: read `DOCUMENTATION.md` before editing and update the relevant fix/regression docs when required.',
         '- Non-trivial feature, product, business-rule, UX, copy, or docs changes: read `DOCUMENTATION.md` before editing.',
-        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table.',
+        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table. While editing, record non-obvious decisions, workarounds, and constraints as why-comments per its `Decision and context comments` section.',
         '',
         '## Routing Table',
         '',

package/cli/verification/changed.ts

@@ -144,6 +144,13 @@ const isDocsOnlyFile = (filepath: string) =>
     filepath.startsWith('agents/') ||
     docsOnlyExtensions.has(path.extname(filepath));
 
+/**
+ * A change that can break the code-to-documentation link: either the corpus
+ * moved under the anchors, or a source file that may carry anchors changed.
+ */
+const isDocAnchorRelevantFile = (filepath: string) =>
+    filepath.startsWith('docs/') || isRelatedSourceFile(filepath);
+
 const normalizeGlob = (glob: string) => normalizePath(glob.trim());
 
 const escapeRegExp = (value: string) => value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
@@ -350,6 +357,20 @@ export const buildChangedVerificationPlan = ({
         if (check) addCheck({ check, selectedChecks });
     }
 
+    const docAnchorFiles = files.filter(isDocAnchorRelevantFile);
+    if (docAnchorFiles.length > 0) {
+        const check = createSuiteCheck({
+            configRoot: gitRoot,
+            files: docAnchorFiles,
+            id: 'builtin:doc-anchors',
+            reason: 'Changed docs or source files should keep doc anchors resolvable.',
+            scope: 'static',
+            source: 'builtin',
+            suite: 'npx proteum docs check',
+        });
+        if (check) addCheck({ check, selectedChecks });
+    }
+
     for (const rule of config.rules || []) {
         const matchedFiles = matchFiles(files, rule.match);
         if (matchedFiles.length === 0) continue;