proteum 2.2.2 → 2.2.6

package/cli/commands/e2e.ts

@@ -0,0 +1,204 @@
+import { spawn } from 'child_process';
+import dotenv from 'dotenv';
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '../../common/dev/session';
+
+type TPlaywrightInvocation = {
+    command: string;
+    args: string[];
+};
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+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 manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
+
+    return '';
+};
+
+const getBaseUrlCandidates = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    if (!port) return [];
+
+    return [...new Set([`http://localhost:${port}`, `http://127.0.0.1:${port}`, `http://[::1]:${port}`])];
+};
+
+const getSessionErrorMessage = (body: TDevSessionErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Session request failed with status ${statusCode}.`;
+};
+
+const hasStructuredSessionError = (body: TDevSessionErrorResponse | object | string | undefined): body is TDevSessionErrorResponse =>
+    typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string';
+
+const requestSession = async ({ email, role }: { email: string; role: string }) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getBaseUrlCandidates()) {
+        try {
+            const response = await got(`${baseUrl}/__proteum/session/start`, {
+                method: 'POST',
+                json: role ? { email, role } : { email },
+                responseType: 'json',
+                throwHttpErrors: false,
+                retry: { limit: 0 },
+            });
+
+            if (response.statusCode >= 400) {
+                if (response.statusCode === 404 && !hasStructuredSessionError(response.body as TDevSessionErrorResponse | object | string | undefined)) {
+                    attempts.push(`${baseUrl}/__proteum/session/start: returned 404`);
+                    continue;
+                }
+
+                throw new UsageError(
+                    getSessionErrorMessage(response.body as TDevSessionErrorResponse | object | string | undefined, response.statusCode),
+                );
+            }
+
+            return {
+                baseUrl,
+                token: (response.body as TDevSessionStartResponse).session.token,
+            };
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}/__proteum/session/start: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum session server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Start the app with `proteum dev`, then pass --port or --url to `proteum e2e`.',
+        ].join('\n'),
+    );
+};
+
+const resolveBaseUrl = (sessionBaseUrl?: string) => {
+    if (sessionBaseUrl) return sessionBaseUrl;
+
+    const [baseUrl] = getBaseUrlCandidates();
+    if (baseUrl) return baseUrl;
+
+    throw new UsageError('Could not determine E2E_BASE_URL. Pass --port or --url to `proteum e2e`.');
+};
+
+const parseEnvPair = (value: string) => {
+    const separatorIndex = value.indexOf('=');
+    if (separatorIndex <= 0) {
+        throw new UsageError(`Invalid --env value "${value}". Expected KEY=value.`);
+    }
+
+    const key = value.slice(0, separatorIndex).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        throw new UsageError(`Invalid --env key "${key}".`);
+    }
+
+    return { key, value: value.slice(separatorIndex + 1) };
+};
+
+const readEnvFiles = (filepaths: string[]) => {
+    const env: Record<string, string> = {};
+
+    for (const filepath of filepaths) {
+        const absoluteFilepath = path.resolve(cli.args.workdir as string, filepath);
+
+        if (!fs.existsSync(absoluteFilepath)) {
+            throw new UsageError(`Env file does not exist: ${absoluteFilepath}`);
+        }
+
+        Object.assign(env, dotenv.parse(fs.readFileSync(absoluteFilepath)));
+    }
+
+    return env;
+};
+
+const resolvePlaywrightInvocation = (appRoot: string): TPlaywrightInvocation => {
+    const binaryName = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
+    const localBinary = path.join(appRoot, 'node_modules', '.bin', binaryName);
+
+    if (fs.existsSync(localBinary)) {
+        return { command: localBinary, args: ['test'] };
+    }
+
+    return { command: 'npx', args: ['playwright', 'test'] };
+};
+
+const runPlaywright = async ({ env, playwrightArgs }: { env: Record<string, string>; playwrightArgs: string[] }) => {
+    const appRoot = cli.args.workdir as string;
+    const invocation = resolvePlaywrightInvocation(appRoot);
+
+    return await new Promise<number | null>((resolve, reject) => {
+        const child = spawn(invocation.command, [...invocation.args, ...playwrightArgs], {
+            cwd: appRoot,
+            env: {
+                ...process.env,
+                ...env,
+            },
+            stdio: 'inherit',
+        });
+
+        child.once('error', reject);
+        child.once('close', (exitCode) => resolve(exitCode));
+    });
+};
+
+export const run = async () => {
+    const sessionEmail = typeof cli.args.sessionEmail === 'string' ? cli.args.sessionEmail.trim() : '';
+    const sessionRole = typeof cli.args.sessionRole === 'string' ? cli.args.sessionRole.trim() : '';
+    const envFilepaths = Array.isArray(cli.args.envFile) ? cli.args.envFile : [];
+    const envPairs = Array.isArray(cli.args.env) ? cli.args.env : [];
+    const playwrightArgs = Array.isArray(cli.args.playwrightArgs) ? cli.args.playwrightArgs : [];
+    const explicitPort = getRouterPort();
+
+    const explicitEnv = readEnvFiles(envFilepaths);
+    for (const pair of envPairs) {
+        const parsed = parseEnvPair(pair);
+        explicitEnv[parsed.key] = parsed.value;
+    }
+
+    const session = sessionEmail ? await requestSession({ email: sessionEmail, role: sessionRole }) : undefined;
+    const baseUrl = resolveBaseUrl(session?.baseUrl);
+    const exitCode = await runPlaywright({
+        env: {
+            ...explicitEnv,
+            E2E_BASE_URL: baseUrl,
+            ...(explicitPort ? { E2E_PORT: explicitPort } : {}),
+            ...(session?.token ? { E2E_AUTH_TOKEN: session.token } : {}),
+        },
+        playwrightArgs,
+    });
+
+    return exitCode ?? 1;
+};

package/cli/commands/typecheck.ts

@@ -1,5 +1,5 @@
 import cli from '..';
-import { refreshGeneratedTypings, runAppTypecheck } from '../utils/check';
+import { hasAppConfig, refreshGeneratedTypings, runAppTypecheck } from '../utils/check';
 import { renderRows } from '../presentation/layout';
 import { renderStep, renderSuccess, renderTitle } from '../presentation/ink';
 
@@ -23,8 +23,12 @@ export const run = async (): Promise<void> => {
             renderRows([{ label: 'app', value: cli.paths.appRoot === process.cwd() ? '.' : cli.paths.appRoot }]),
         ].join('\n\n'),
     );
-    console.info(await renderStep('[1/2]', 'Refreshing generated typings.'));
-    await refreshGeneratedTypings();
+    if (hasAppConfig()) {
+        console.info(await renderStep('[1/2]', 'Refreshing generated typings.'));
+        await refreshGeneratedTypings();
+    } else {
+        console.info(await renderStep('[1/2]', 'Skipping generated typings: no Proteum app config found.'));
+    }
     console.info(await renderStep('[2/2]', 'Running TypeScript typechecking.'));
     await runAppTypecheck();
     console.info(await renderSuccess('Typecheck passed.'));

package/cli/presentation/commands.ts

@@ -14,6 +14,7 @@ export const proteumCommandNames = [
     'typecheck',
     'lint',
     'check',
+    'e2e',
     'connect',
     'doctor',
     'explain',
@@ -55,7 +56,7 @@ export const proteumRecommendedFlow: TRow[] = [
 
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
-    { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
+    { title: 'Quality gates', names: ['typecheck', 'lint', 'check', 'e2e'] },
     { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'trace', 'command', 'session', 'verify'] },
     { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
 ];
@@ -112,22 +113,22 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure Proteum-managed instruction symlinks for a standalone app or monorepo app root.',
+        summary: 'Interactively configure Proteum-managed instruction stubs for a standalone app or monorepo app root.',
         usage: 'proteum configure agents',
         bestFor:
-            'Creating or switching the managed `AGENTS.md` instruction layout intentionally instead of having `init` or `dev` write symlinks implicitly.',
+            'Creating or switching the managed `AGENTS.md` instruction layout intentionally instead of having `init` or `dev` write instruction files implicitly.',
         examples: [
             {
-                description: 'Configure instruction symlinks for the current standalone app',
+                description: 'Configure instruction stubs for the current standalone app',
                 command: 'proteum configure agents',
             },
         ],
         notes: [
-            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` symlink.',
+            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` stub.',
             'Standalone mode writes the full app-root instruction set into the current Proteum app root.',
             'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and switches the current app root `AGENTS.md` to the app-root addendum.',
-            'If a target path already contains a non-managed file or foreign symlink, the interactive flow asks whether to overwrite it with the Proteum-managed symlink.',
-            'Declined non-managed paths are left untouched; Proteum still creates missing symlinks and updates symlinks it already manages.',
+            'If a target path already contains a non-managed file or foreign symlink, the interactive flow asks whether to overwrite it with the Proteum-managed stub.',
+            'Declined non-managed paths are left untouched; Proteum still creates missing stubs and updates stubs or symlinks it already manages.',
         ],
         status: 'experimental',
     },
@@ -276,6 +277,35 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: ['This command executes refresh, typecheck, then lint in that order.'],
         status: 'stable',
     },
+    e2e: {
+        name: 'e2e',
+        category: 'Quality gates',
+        summary: 'Run app Playwright tests with Proteum-managed E2E environment values.',
+        usage:
+            'proteum e2e [--cwd <path>] [--port <port>|--url <url>] [--session-email <email>] [--session-role <role>] [--env KEY=value] [--env-file <path>] [--grep <text>] [--project <name>] [specs...]',
+        bestFor:
+            'Running targeted or full Playwright suites without shell-leading environment assignments for base URLs, auth tokens, or per-run values.',
+        examples: [
+            {
+                description: 'Run the full suite against a local dev server',
+                command: 'proteum e2e --port 3101',
+            },
+            {
+                description: 'Run one spec with a dev auth token minted internally',
+                command: 'proteum e2e --port 3101 --session-email admin@example.com --session-role ADMIN tests/e2e/features/admin.spec.ts',
+            },
+            {
+                description: 'Load extra dotenv values before Playwright starts',
+                command: 'proteum e2e --url http://localhost:3101 --env-file .proteum/e2e.env --grep smoke',
+            },
+        ],
+        notes: [
+            '`proteum e2e` spawns Playwright with `E2E_BASE_URL`, optional `E2E_PORT`, optional `E2E_AUTH_TOKEN`, and any `--env`/`--env-file` values in the child process environment.',
+            'Common Playwright flags are exposed directly: `--config`, `--debug`, `--grep`, `--headed`, `--list`, `--project`, `--reporter`, `--retries`, `--timeout`, `--ui`, and `--workers`.',
+            'The shell command itself stays `proteum e2e ...`, so Codex does not need to run `FOO=bar npx playwright test ...`.',
+        ],
+        status: 'experimental',
+    },
     connect: {
         name: 'connect',
         category: 'Manifest and contracts',

package/cli/runtime/command.ts

@@ -4,11 +4,11 @@ import cli, { type TArgsObject } from '../context';
 import { createClipanionUsage, proteumCommands, type TProteumCommandName } from '../presentation/commands';
 import { createArgs } from './argv';
 
-type TRunModule = { run: () => Promise<void> };
+type TRunModule = { run: () => Promise<number | void> };
 
 export const runCommandModule = async (loader: () => Promise<TRunModule>) => {
     const module = await loader();
-    await module.run();
+    return await module.run();
 };
 
 export abstract class ProteumCommand extends Command {

package/cli/runtime/commands.ts

@@ -259,6 +259,63 @@ class CheckCommand extends ProteumCommand {
     }
 }
 
+class E2eCommand extends ProteumCommand {
+    public static paths = [['e2e']];
+
+    public static usage = buildUsage('e2e');
+
+    public cwd = Option.String('--cwd', { description: 'Run Playwright against another Proteum app root.' });
+    public port = Option.String('--port', { description: 'Set E2E_BASE_URL from a local router port.' });
+    public url = Option.String('--url', { description: 'Set E2E_BASE_URL from an explicit base URL.' });
+    public sessionEmail = Option.String('--session-email', {
+        description: 'Mint a dev session before Playwright starts and pass it as E2E_AUTH_TOKEN.',
+    });
+    public sessionRole = Option.String('--session-role', { description: 'Require the dev session user to have this role.' });
+    public env = Option.Array('--env', [], { description: 'Pass an environment value to Playwright as KEY=value.' });
+    public envFile = Option.Array('--env-file', [], { description: 'Load environment values from a dotenv file before Playwright starts.' });
+    public config = Option.String('--config', { description: 'Playwright config file.' });
+    public debug = Option.Boolean('--debug', false, { description: 'Run Playwright in debug mode.' });
+    public grep = Option.String('--grep', { description: 'Playwright grep filter.' });
+    public headed = Option.Boolean('--headed', false, { description: 'Run browsers in headed mode.' });
+    public list = Option.Boolean('--list', false, { description: 'List Playwright tests without running them.' });
+    public project = Option.Array('--project', [], { description: 'Playwright project name. Can be repeated.' });
+    public reporter = Option.String('--reporter', { description: 'Playwright reporter.' });
+    public retries = Option.String('--retries', { description: 'Playwright retry count.' });
+    public timeout = Option.String('--timeout', { description: 'Playwright per-test timeout.' });
+    public ui = Option.Boolean('--ui', false, { description: 'Run Playwright in UI mode.' });
+    public workers = Option.String('--workers', { description: 'Playwright worker count.' });
+    public specs = Option.Rest();
+
+    public async execute() {
+        const playwrightArgs = [
+            ...(this.config ? ['--config', this.config] : []),
+            ...(this.debug ? ['--debug'] : []),
+            ...(this.grep ? ['--grep', this.grep] : []),
+            ...(this.headed ? ['--headed'] : []),
+            ...(this.list ? ['--list'] : []),
+            ...this.project.flatMap((project) => ['--project', project]),
+            ...(this.reporter ? ['--reporter', this.reporter] : []),
+            ...(this.retries ? ['--retries', this.retries] : []),
+            ...(this.timeout ? ['--timeout', this.timeout] : []),
+            ...(this.ui ? ['--ui'] : []),
+            ...(this.workers ? ['--workers', this.workers] : []),
+            ...this.specs,
+        ];
+
+        this.setCliArgs({
+            env: this.env,
+            envFile: this.envFile,
+            playwrightArgs,
+            port: this.port ?? '',
+            sessionEmail: this.sessionEmail ?? '',
+            sessionRole: this.sessionRole ?? '',
+            url: this.url ?? '',
+            workdir: this.cwd ?? '',
+        });
+        return await runCommandModule(() => import('../commands/e2e'));
+    }
+}
+
 class ConnectCommand extends ProteumCommand {
     public static paths = [['connect']];
 
@@ -608,6 +665,7 @@ export const registeredCommands = {
     typecheck: TypecheckCommand,
     lint: LintCommand,
     check: CheckCommand,
+    e2e: E2eCommand,
     connect: ConnectCommand,
     doctor: DoctorCommand,
     explain: ExplainCommand,
@@ -640,6 +698,7 @@ export const createCli = (version: string) => {
     clipanion.register(TypecheckCommand);
     clipanion.register(LintCommand);
     clipanion.register(CheckCommand);
+    clipanion.register(E2eCommand);
     clipanion.register(ConnectCommand);
     clipanion.register(DoctorCommand);
     clipanion.register(ExplainCommand);

package/cli/scaffold/index.ts

@@ -727,7 +727,7 @@ export const runInitScaffold = async () => {
               ? 'Run `npm run dev` in the new app directory.'
               : 'Run `npm install`, then `npm run dev` in the new app directory.',
     );
-    result.nextSteps.push('Run `proteum configure agents` when you want Proteum-managed instruction symlinks.');
+    result.nextSteps.push('Run `proteum configure agents` when you want Proteum-managed instruction stubs.');
     result.nextSteps.push('Use `proteum create page|controller|command|route|service ...` to add app artifacts.');
 
     printResult(result, createInitSummary(result, config));