@pikku/cli 0.12.118 → 0.12.119

package/dist/src/functions/validate/auth-plugin-checks.js

@@ -0,0 +1,165 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const lines = (...parts) => parts.join('\n');
+/** Local rather than imported from shared-checks, which imports this module. */
+const readTextSafe = async (path) => {
+    if (!existsSync(path))
+        return null;
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const stringArray = (value) => Array.isArray(value)
+    ? value.filter((v) => typeof v === 'string')
+    : [];
+/**
+ * Source files under one directory, generated files included — better-auth is
+ * routinely configured in a file the auth scaffold wrote.
+ */
+const listSourceFiles = async (dir) => {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return (await readdir(dir, { recursive: true }))
+            .filter((f) => typeof f === 'string' &&
+            (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+            !f.includes('node_modules'))
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * The text inside every `plugins: [...]` array in the file.
+ *
+ * Bracket-counted rather than parsed: `pikku validate` runs without a TypeScript
+ * program, and a `]` inside a string literal in a plugin's options is the only
+ * way this misreads an array — at which point the check under-reports rather
+ * than inventing a finding.
+ */
+const pluginArrays = (text) => {
+    const arrays = [];
+    const opener = /plugins\s*:\s*\[/g;
+    let match;
+    while ((match = opener.exec(text))) {
+        const start = match.index + match[0].length;
+        let depth = 1;
+        let i = start;
+        while (i < text.length && depth > 0) {
+            if (text[i] === '[')
+                depth++;
+            else if (text[i] === ']')
+                depth--;
+            i++;
+        }
+        if (depth === 0)
+            arrays.push(text.slice(start, i - 1));
+    }
+    return arrays;
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * How `exported` from `module` can be called in this file: the local name a
+ * named import bound it to, or `<namespace>.<exported>` for a namespace import.
+ * Empty when the file never imports it, so a local helper of the same name is
+ * not mistaken for the package's.
+ */
+const importedCallees = (text, module, exported) => {
+    const callees = [];
+    const imports = /import\s+([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = imports.exec(text))) {
+        if (match[2] !== module)
+            continue;
+        const clause = match[1];
+        const namespace = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
+        if (namespace) {
+            callees.push(`${namespace[1]}.${exported}`);
+            continue;
+        }
+        const named = clause.match(/\{([\s\S]*?)\}/);
+        if (!named)
+            continue;
+        for (const entry of named[1].split(',')) {
+            const [imported, alias] = entry.split(/\s+as\s+/).map((v) => v.trim());
+            if (imported === exported)
+                callees.push(alias || imported);
+        }
+    }
+    return callees;
+};
+/**
+ * Whether `exported` from `module` is wired as a plugin — imported from that
+ * package *and* called inside a `plugins: [...]` array. An import left behind
+ * after the call was removed configures nothing, and a call somewhere else in
+ * the file is not a plugin.
+ */
+const configuresPlugin = (text, module, exported) => {
+    const callees = importedCallees(text, module, exported);
+    if (callees.length === 0)
+        return false;
+    return pluginArrays(text).some((array) => callees.some((callee) => new RegExp(`(^|[^\\w$.])${escapeRegExp(callee)}\\s*\\(`).test(array)));
+};
+/**
+ * Whether better-auth is configured the way pikku supports.
+ *
+ * Pikku authorizes on scopes, so better-auth's `admin()` — which authorizes its
+ * endpoints against a `user.role` column — is unsupported: wiring it means
+ * running two authorization models and projecting one onto the other. The
+ * inspector refuses it outright at prebuild; this reports the same thing
+ * without one, and additionally catches the quieter half of the migration, an
+ * app that dropped `admin()` and never wired `ban()`, which keeps its ban
+ * columns and its ban UI while silently enforcing nothing.
+ */
+export const runAuthPluginChecks = async (root, config) => {
+    const findings = [];
+    const srcDirectories = stringArray(config?.srcDirectories);
+    const searchDirs = srcDirectories.length
+        ? srcDirectories
+        : [join('packages', 'functions', 'src')];
+    const sourceFiles = (await Promise.all(searchDirs.map((dir) => listSourceFiles(join(root, dir))))).flat();
+    let bansAnywhere = false;
+    const adminFiles = [];
+    for (const file of sourceFiles) {
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        if (configuresPlugin(text, 'better-auth/plugins', 'admin'))
+            adminFiles.push(file);
+        if (configuresPlugin(text, '@pikku/better-auth', 'ban'))
+            bansAnywhere = true;
+    }
+    for (const file of adminFiles) {
+        findings.push({
+            id: 'better-auth-admin-plugin',
+            severity: 'error',
+            message: "better-auth's admin() plugin is not supported — it authorizes against a user.role column while pikku authorizes on scopes, so one has to be projected onto the other",
+            path: file,
+            fixHint: lines('Replace it with ban(), which keeps the one capability admin() had that', 'pikku cannot supply from outside better-auth — refusing a banned user a', 'session:', "  import { ban } from '@pikku/better-auth'", '  betterAuth({ plugins: [ban()] })', 'User management is already scoped RPCs in @pikku/addon-admin: list,', 'create, ban, remove, revoke sessions and set password.'),
+        });
+    }
+    if (!bansAnywhere && adminFiles.length === 0) {
+        const configuresAuth = sourceFiles.length > 0;
+        if (configuresAuth) {
+            for (const file of sourceFiles) {
+                const text = await readTextSafe(file);
+                if (!text || !/\bpikkuBetterAuth\s*\(/.test(text))
+                    continue;
+                findings.push({
+                    id: 'better-auth-no-ban-plugin',
+                    severity: 'warn',
+                    message: 'better-auth is configured without ban() — the banned/banReason/banExpires columns do not exist, so banning a user through @pikku/addon-admin has nothing to write and nothing refuses their next sign-in',
+                    path: file,
+                    fixHint: lines("  import { ban } from '@pikku/better-auth'", '  betterAuth({ plugins: [ban()] })', 'Wire it wherever the rest of your plugins are, then run', '`pikku db migrate` to add the columns.'),
+                });
+                break;
+            }
+        }
+    }
+    return findings;
+};

package/dist/src/functions/validate/persona-checks.js

@@ -123,7 +123,7 @@ export const runPersonaChecks = async (root, config) => {
         return findings;
     }
     if (!(await hasActorSignIn(sourceFiles))) {
-        w('personas-no-actor-sign-in', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but nothing wires actor sign-in — a scenario run signs in over POST /auth/sign-in/actor, so every persona fails to acquire a session`, pikkuConfigPath, lines('Wire the actor plugin where better-auth is configured:', "  import { actor } from '@pikku/better-auth'", '  plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]', 'The plugin refuses every sign-in while the secret is unset, so a stage', 'that must not run scenarios simply leaves SCENARIO_ACTOR_SECRET out.'));
+        w('personas-no-actor-sign-in', `${personas} persona${personas === 1 ? ' is' : 's are'} declared, but nothing wires actor sign-in — a scenario run signs in over POST /auth/sign-in/actor, so every persona fails to acquire a session`, pikkuConfigPath, lines('Wire the actor plugin where better-auth is configured:', "  import { actor } from '@pikku/better-auth'", '  plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]', '`pikku dev` turns the endpoint on and mints the secret itself, so there', 'is nothing to configure locally. A deployed stage that must run', 'scenarios opts in with', 'PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in; everywhere else', 'the endpoint stays off whatever the environment happens to contain.'));
     }
     const environments = config?.environments;
     const hasEnvironment = typeof environments === 'object' &&

package/dist/src/functions/validate/shared-checks.js

@@ -4,7 +4,10 @@ import { join } from 'node:path';
 import { runKnowledgeValidate } from '@pikku/knowledge';
 import { runBootstrapChecks } from './bootstrap-checks.js';
 import { runPersonaChecks } from './persona-checks.js';
+import { runAuthPluginChecks } from './auth-plugin-checks.js';
 import { runScenarioFileChecks } from './scenario-file-checks.js';
+import { projectWiresChannels, runWebsocketDepsChecks, } from './websocket-deps-checks.js';
+import { resolveFromProject } from '../../utils/resolve-from-project.js';
 /**
  * A malformed config is named, never reported as absent.
  *
@@ -311,8 +314,17 @@ export async function runSharedProjectChecks(root) {
     }
     // ── server bootstrap ───────────────────────────────────────────────────
     findings.push(...(await runBootstrapChecks(root, rootPkg, pikkuConfig)));
+    findings.push(...runWebsocketDepsChecks({
+        root,
+        runtime: typeof globalThis.Bun !== 'undefined'
+            ? 'bun'
+            : 'node',
+        hasChannels: await projectWiresChannels(root, typeof pikkuConfig?.outDir === 'string' ? pikkuConfig.outDir : '.pikku'),
+        resolve: (specifier) => resolveFromProject(root, specifier),
+    }));
     // ── personas, scenario files and the knowledge base ────────────────────
     findings.push(...(await runPersonaChecks(root, pikkuConfig)));
+    findings.push(...(await runAuthPluginChecks(root, pikkuConfig)));
     const srcDirectories = Array.isArray(pikkuConfig?.srcDirectories)
         ? pikkuConfig.srcDirectories.filter((d) => typeof d === 'string')
         : [];

package/dist/src/functions/validate/websocket-deps-checks.d.ts

@@ -0,0 +1,30 @@
+import type { ValidateFinding } from './persona-checks.js';
+/**
+ * The packages the Node dev/serve path needs to speak WebSocket. Both are
+ * optional peers of `@pikku/cli`, because Bun serves WebSockets natively
+ * through `@pikku/bun-server` and a Bun project has no use for either.
+ */
+export declare const NODE_WEBSOCKET_PACKAGES: readonly ["@pikku/ws", "ws"];
+export type WebsocketDepsInput = {
+    root: string;
+    /** The runtime the CLI is running on. Bun needs neither package. */
+    runtime: 'node' | 'bun';
+    /** Whether the project wires any channels. Nothing is reported when not. */
+    hasChannels: boolean;
+    /** Resolves a specifier from the project. `undefined` when not installed. */
+    resolve: (specifier: string) => string | undefined;
+};
+/**
+ * Reports the optional WebSocket peers when a Node-hosted project that wires
+ * channels is missing them.
+ *
+ * `pikku dev` / `pikku serve` under Node start over plain HTTP when the
+ * packages are absent, rather than failing: a project with no channels does not
+ * need them, and making them hard dependencies of the CLI is what put a second
+ * `@pikku/core` in the tree. That leaves a project that *does* wire channels
+ * with sockets that never connect and nothing pointing at the cause — which is
+ * this check.
+ */
+export declare function runWebsocketDepsChecks(input: WebsocketDepsInput): ValidateFinding[];
+/** True when codegen produced at least one channel for this project. */
+export declare function projectWiresChannels(root: string, outDir: string): Promise<boolean>;

package/dist/src/functions/validate/websocket-deps-checks.js

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+import { readJsonSafe } from './shared-checks.js';
+/**
+ * The packages the Node dev/serve path needs to speak WebSocket. Both are
+ * optional peers of `@pikku/cli`, because Bun serves WebSockets natively
+ * through `@pikku/bun-server` and a Bun project has no use for either.
+ */
+export const NODE_WEBSOCKET_PACKAGES = ['@pikku/ws', 'ws'];
+/**
+ * Reports the optional WebSocket peers when a Node-hosted project that wires
+ * channels is missing them.
+ *
+ * `pikku dev` / `pikku serve` under Node start over plain HTTP when the
+ * packages are absent, rather than failing: a project with no channels does not
+ * need them, and making them hard dependencies of the CLI is what put a second
+ * `@pikku/core` in the tree. That leaves a project that *does* wire channels
+ * with sockets that never connect and nothing pointing at the cause — which is
+ * this check.
+ */
+export function runWebsocketDepsChecks(input) {
+    const { root, runtime, hasChannels, resolve } = input;
+    if (runtime === 'bun' || !hasChannels)
+        return [];
+    const missing = NODE_WEBSOCKET_PACKAGES.filter((name) => !resolve(name));
+    if (missing.length === 0)
+        return [];
+    const named = missing.join(' and ');
+    return [
+        {
+            id: 'websocket-deps-missing',
+            severity: 'error',
+            message: `${named} ${missing.length > 1 ? 'are' : 'is'} not installed, but this project wires channels — \`pikku dev\` and \`pikku serve\` will start without WebSocket support and every channel connection will fail`,
+            path: join(root, 'package.json'),
+            fixHint: `Install ${NODE_WEBSOCKET_PACKAGES.join(' ')} in this project. They are optional peer dependencies of @pikku/cli so that Bun projects, which serve WebSockets natively, do not pull them in`,
+        },
+    ];
+}
+/** True when codegen produced at least one channel for this project. */
+export async function projectWiresChannels(root, outDir) {
+    const meta = await readJsonSafe(join(root, outDir, 'channel', 'pikku-channels-meta.gen.json'));
+    return !!meta && Object.keys(meta).length > 0;
+}

package/dist/src/functions/wirings/personas/serialize-personas-secrets.d.ts

@@ -3,7 +3,7 @@
  *
  * `SCENARIO_ACTOR_SECRET` is the platform's, not the application's: nothing in
  * app code reads it. It is consumed by the scenario service when it signs an
- * actor in, by `pikku scenario` / `pikku persona` / `pikku persona sync`, and by
+ * actor in, by `pikku scenario` / `pikku persona`, and by
  * the Playwright provider. Declaring it here — rather than leaving every project
  * to hand-write the same `defineSecret` — is the same reasoning that puts
  * `BETTER_AUTH_SECRET` in the auth scaffold: a value the framework requires

package/dist/src/functions/wirings/personas/serialize-personas-secrets.js

@@ -3,7 +3,7 @@
  *
  * `SCENARIO_ACTOR_SECRET` is the platform's, not the application's: nothing in
  * app code reads it. It is consumed by the scenario service when it signs an
- * actor in, by `pikku scenario` / `pikku persona` / `pikku persona sync`, and by
+ * actor in, by `pikku scenario` / `pikku persona`, and by
  * the Playwright provider. Declaring it here — rather than leaving every project
  * to hand-write the same `defineSecret` — is the same reasoning that puts
  * `BETTER_AUTH_SECRET` in the auth scaffold: a value the framework requires

package/dist/src/functions/wirings/scopes/pikku-command-scopes.d.ts

@@ -1,3 +1,13 @@
+import type { PersonaDefinitions } from '@pikku/core/persona';
+import type { ScopeDefinitions } from '@pikku/core/scope';
+/**
+ * The declared scopes, plus the `app` tree derived from the personas.
+ *
+ * Appended here rather than in the inspector because it is not a declaration
+ * the AST can find: it is the personas' `app` field read as a scope, and this
+ * is the one place the two states are both in hand.
+ */
+export declare const withAppScopes: (scopes: ScopeDefinitions, personas: PersonaDefinitions) => ScopeDefinitions;
 export declare const pikkuScopes: import("#pikku/function").PikkuFunctionConfig<{
     bootstrap?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{

package/dist/src/functions/wirings/scopes/pikku-command-scopes.js

@@ -4,6 +4,22 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { serializeScopesTypes } from './serialize-scopes-types.js';
 import { serializeScopesClient } from './serialize-scopes-client.js';
 import { validateAndBuildScopeDefinitionsMeta } from '@pikku/core/scope';
+import { APP_SCOPE_ROOT, buildAppScopeDefinition } from '@pikku/core/persona';
+/**
+ * The declared scopes, plus the `app` tree derived from the personas.
+ *
+ * Appended here rather than in the inspector because it is not a declaration
+ * the AST can find: it is the personas' `app` field read as a scope, and this
+ * is the one place the two states are both in hand.
+ */
+export const withAppScopes = (scopes, personas) => {
+    const declared = scopes.find((scope) => scope.name === APP_SCOPE_ROOT);
+    if (declared) {
+        throw new Error(`'${APP_SCOPE_ROOT}' is reserved: it is derived from the apps your personas name, and ${declared.sourceFile ?? 'a defineScope call'} declares it too. Rename that scope root — two trees answering to one name make a grant ambiguous.`);
+    }
+    const appScopes = buildAppScopeDefinition(personas);
+    return appScopes ? [...scopes, appScopes] : scopes;
+};
 export const pikkuScopes = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }, data) => {
         const { scopesFile, scopesMetaJsonFile } = config;
@@ -19,15 +35,16 @@ export const pikkuScopes = pikkuSessionlessFunc({
         // Scopes step regenerates it with the declarations once setup has run.
         const bootstrap = data?.bootstrap ?? false;
         const state = await getInspectorState(false, bootstrap, bootstrap);
+        const definitions = withAppScopes(state.scopes.definitions, state.personas.definitions);
         const content = serializeScopesTypes({
-            definitions: state.scopes.definitions,
+            definitions,
         });
         await writeFileInDir(logger, scopesFile, content);
         if (scopesClientFile) {
-            await writeFileInDir(logger, scopesClientFile, serializeScopesClient({ definitions: state.scopes.definitions }));
+            await writeFileInDir(logger, scopesClientFile, serializeScopesClient({ definitions }));
         }
         if (scopesMetaJsonFile) {
-            const meta = validateAndBuildScopeDefinitionsMeta(state.scopes.definitions);
+            const meta = validateAndBuildScopeDefinitionsMeta(definitions);
             await writeFileInDir(logger, scopesMetaJsonFile, JSON.stringify(meta, null, 2));
         }
     },

package/dist/src/functions/wirings/workflow/pikku-command-workflow.js

@@ -103,7 +103,7 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         {
             const agentMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.agentMapDeclarationFile, packageMappings);
             const exposedRpcMapImportPath = getFileImportRelativePath(config.personasWiringFile, config.rpcMapDeclarationFile, packageMappings);
-            await writeFileInDir(logger, config.personasWiringFile, serializePersonas(personas, agentMapImportPath, exposedRpcMapImportPath));
+            await writeFileInDir(logger, config.personasWiringFile, serializePersonas(personas, agentMapImportPath, exposedRpcMapImportPath, config.environments ?? {}));
             // Same reason as the scenario meta above: a project generated before this
             // moved to `scenarios/` still has a copy under `workflow/`, and tsc
             // compiles every file in the output tree whether anything imports it.

package/dist/src/functions/wirings/workflow/serialize-personas.d.ts

@@ -1,3 +1,4 @@
+import type { PersonaEnvironment } from '@pikku/core/persona';
 import type { ResolvedPersona } from '@pikku/core/services';
 /**
  * The runtime half of `definePersonas()`.
@@ -7,4 +8,4 @@ import type { ResolvedPersona } from '@pikku/core/services';
  * to arrive at the same one. Baking them here is what makes that a single fact
  * rather than three implementations of the same rule.
  */
-export declare const serializePersonas: (personas: Record<string, ResolvedPersona>, agentMapImportPath: string, rpcMapImportPath: string) => string;
+export declare const serializePersonas: (personas: Record<string, ResolvedPersona>, agentMapImportPath: string, rpcMapImportPath: string, environments?: Readonly<Record<string, PersonaEnvironment>>) => string;

package/dist/src/functions/wirings/workflow/serialize-personas.js

@@ -6,7 +6,14 @@
  * to arrive at the same one. Baking them here is what makes that a single fact
  * rather than three implementations of the same rule.
  */
-export const serializePersonas = (personas, agentMapImportPath, rpcMapImportPath) => {
+export const serializePersonas = (personas, agentMapImportPath, rpcMapImportPath, environments = {}) => {
+    // Only the flag the rule reads. The rest of an environment entry is its
+    // apiUrl and paths, which belong to the machine running `pikku scenario` and
+    // have no business inside the deployed bundle.
+    const projected = Object.fromEntries(Object.entries(environments).map(([name, environment]) => [
+        name,
+        environment.production ? { production: true } : {},
+    ]));
     return `/** Personas declared with definePersonas() */
 import { createHttpPersonas } from '@pikku/core/persona'
 import type { HttpPersonasConfig } from '@pikku/core/persona'
@@ -27,6 +34,18 @@ export type PersonaName = keyof typeof personaConfigs
  */
 export const personaList: ResolvedPersona[] = Object.values(personaConfigs)
 
+/**
+ * The \`environments\` block of pikku.config.json, carried into the runtime.
+ *
+ * A persona's environments are checked twice: at build time against the config,
+ * and again wherever a persona is signed in or provisioned, against the
+ * environment the running process says it is (\`PIKKU_ENV\`). The second check
+ * is not the first one repeated — the build check trusts the file, and the run
+ * check does not trust which artifact got deployed — so the rule needs the
+ * config on both sides of the build.
+ */
+export const personaEnvironments = ${JSON.stringify(projected, null, 2)} as const satisfies Record<string, { production?: boolean }>
+
 export type AgentName = keyof AgentMap & string
 /**
  * The personas this project declares, keyed by name — the \`actors\` a scenario

package/dist/src/server/actor-sign-in.d.ts

@@ -0,0 +1,5 @@
+import type { Logger } from '@pikku/core/services';
+export declare const ACTOR_SECRET_ENV = "SCENARIO_ACTOR_SECRET";
+export declare const VITE_ACTOR_SECRET_ENV = "VITE_SCENARIO_ACTOR_SECRET";
+export declare const enableDevActorSignIn: (logger: Logger) => void;
+export declare const disableDevActorSignIn: (logger: Logger) => void;

package/dist/src/server/actor-sign-in.js

@@ -0,0 +1,27 @@
+import { randomBytes } from 'node:crypto';
+import { ACTOR_SIGN_IN_OPT_IN_ENV, DEV_ACTOR_SIGN_IN_ENV, } from '@pikku/better-auth';
+export const ACTOR_SECRET_ENV = 'SCENARIO_ACTOR_SECRET';
+export const VITE_ACTOR_SECRET_ENV = 'VITE_SCENARIO_ACTOR_SECRET';
+const mintEphemeralSecret = () => randomBytes(32).toString('base64url');
+export const enableDevActorSignIn = (logger) => {
+    process.env[DEV_ACTOR_SIGN_IN_ENV] = 'true';
+    const configured = process.env[ACTOR_SECRET_ENV] || undefined;
+    const configuredForFrontend = process.env[VITE_ACTOR_SECRET_ENV] || undefined;
+    if (configured &&
+        configuredForFrontend &&
+        configured !== configuredForFrontend) {
+        logger.warn(`${ACTOR_SECRET_ENV} and ${VITE_ACTOR_SECRET_ENV} are set to different values — using ${ACTOR_SECRET_ENV}, since that is the one the server compares against`);
+    }
+    const secret = configured ?? configuredForFrontend ?? mintEphemeralSecret();
+    process.env[ACTOR_SECRET_ENV] = secret;
+    process.env[VITE_ACTOR_SECRET_ENV] = secret;
+    logger.info((configured ?? configuredForFrontend)
+        ? `Actor quick login enabled, using the ${configured ? ACTOR_SECRET_ENV : VITE_ACTOR_SECRET_ENV} already in this environment`
+        : 'Actor quick login enabled with a secret minted for this run — nothing to configure, and it is gone when the server stops');
+};
+export const disableDevActorSignIn = (logger) => {
+    if (process.env[DEV_ACTOR_SIGN_IN_ENV] !== undefined) {
+        logger.warn(`${DEV_ACTOR_SIGN_IN_ENV} was set in this environment and has been cleared — \`pikku serve\` never enables actor sign-in. Set ${ACTOR_SIGN_IN_OPT_IN_ENV} if this stage is meant to run scenarios.`);
+    }
+    delete process.env[DEV_ACTOR_SIGN_IN_ENV];
+};

package/dist/src/server/node-server-runner.d.ts

@@ -2,11 +2,22 @@
  * Node dev server runner — `@pikku/node-http-server` + the `ws` WebSocketServer.
  * Used when the CLI runs under Node. Owns the WebSocketServer so teardown
  * (close ws then the http server) is encapsulated in the returned instance.
+ *
+ * `@pikku/ws` and `ws` are optional peers of the CLI, so they are imported
+ * dynamically and resolved from the *project* rather than from the CLI: both
+ * peer on `@pikku/core`, and a copy loaded out of the CLI's own tree is paired
+ * with the CLI's core instead of the project's. A project without them served
+ * over plain HTTP — `pikku validate` reports the missing packages.
  */
 import type { EventHubService } from '@pikku/core/channel';
 import type { Logger } from '@pikku/core/services';
 import type { DevServerRunner, DevServerInstance, DevServerConfig, DevServerOptions } from './dev-server-runner.interface.js';
+export declare const WEBSOCKET_PACKAGES_MISSING = "WebSocket support is disabled: @pikku/ws and ws are not installed in this project. Install them (npm install @pikku/ws ws) to serve channels over Node.";
 export declare class NodeServerRunner implements DevServerRunner {
+    private readonly rootDir;
+    private pikkuWs?;
+    private ws?;
+    constructor(rootDir: string);
     createEventHub(): Promise<EventHubService<any>>;
     createServer(config: DevServerConfig, logger: Logger, options?: DevServerOptions): DevServerInstance;
 }

package/dist/src/server/node-server-runner.js

@@ -2,23 +2,46 @@
  * Node dev server runner — `@pikku/node-http-server` + the `ws` WebSocketServer.
  * Used when the CLI runs under Node. Owns the WebSocketServer so teardown
  * (close ws then the http server) is encapsulated in the returned instance.
+ *
+ * `@pikku/ws` and `ws` are optional peers of the CLI, so they are imported
+ * dynamically and resolved from the *project* rather than from the CLI: both
+ * peer on `@pikku/core`, and a copy loaded out of the CLI's own tree is paired
+ * with the CLI's core instead of the project's. A project without them served
+ * over plain HTTP — `pikku validate` reports the missing packages.
  */
 import { LocalEventHubService } from '@pikku/core/channel/local';
 import { PikkuNodeHTTPServer } from '@pikku/node-http-server';
-import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws';
-import { WebSocketServer } from 'ws';
+import { cjsInterop, importFromProject } from '../utils/resolve-from-project.js';
+export const WEBSOCKET_PACKAGES_MISSING = 'WebSocket support is disabled: @pikku/ws and ws are not installed in this project. Install them (npm install @pikku/ws ws) to serve channels over Node.';
 export class NodeServerRunner {
+    rootDir;
+    pikkuWs;
+    ws;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
     async createEventHub() {
+        this.pikkuWs = await importFromProject(this.rootDir, '@pikku/ws');
+        const ws = await importFromProject(this.rootDir, 'ws');
+        this.ws = ws && cjsInterop(ws, 'WebSocketServer');
         return new LocalEventHubService();
     }
     createServer(config, logger, options = {}) {
-        const wss = new WebSocketServer({
-            noServer: true,
-            maxPayload: DEFAULT_WS_MAX_PAYLOAD,
-        });
+        const { pikkuWs, ws } = this;
+        if (!pikkuWs || !ws) {
+            logger.warn(WEBSOCKET_PACKAGES_MISSING);
+        }
+        const wss = pikkuWs && ws
+            ? new ws.WebSocketServer({
+                noServer: true,
+                maxPayload: pikkuWs.DEFAULT_WS_MAX_PAYLOAD,
+            })
+            : undefined;
         const server = new PikkuNodeHTTPServer(config, logger, {
             configureServer: (httpServer) => {
-                pikkuWebsocketHandler({ server: httpServer, wss, logger });
+                if (pikkuWs && wss) {
+                    pikkuWs.pikkuWebsocketHandler({ server: httpServer, wss, logger });
+                }
             },
             contentSigningJWT: options.contentSigningJWT,
             // Read off this options object by the transport, not off `config` — so it
@@ -29,7 +52,9 @@ export class NodeServerRunner {
             init: () => server.init(),
             start: () => server.start(),
             stop: async () => {
-                await new Promise((resolve, reject) => wss.close((err) => (err ? reject(err) : resolve())));
+                if (wss) {
+                    await new Promise((resolve, reject) => wss.close((err) => (err ? reject(err) : resolve())));
+                }
                 await server.stop();
             },
         };

package/dist/src/services.js

@@ -353,7 +353,9 @@ export const createSingletonServices = async (config) => {
         invalidateInspectorState,
         workflowService,
         bundler: isBun ? new BunBundler() : new NodeBundler(),
-        devServerRunner: isBun ? new BunServerRunner() : new NodeServerRunner(),
+        devServerRunner: isBun
+            ? new BunServerRunner()
+            : new NodeServerRunner(rootDir),
     };
 };
 export const createWireServices = async ({ logger }, { cli, channel }) => {

package/dist/src/utils/resolve-from-project.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolves a package as the *project* would, not as the CLI would.
+ *
+ * The CLI is frequently run from somewhere that is not the project — `npx`
+ * unpacks it into `~/.npm/_npx/<hash>`, a monorepo hoists it to the workspace
+ * root — so a bare `import('pkg')` from CLI code finds the copy sitting next to
+ * the CLI. For a package that peers on `@pikku/core` that is the wrong copy:
+ * it gets paired with the CLI's core rather than the project's, and the version
+ * skew surfaces as a missing subpath export from a package the project never
+ * imported. Resolving against the project's own package.json keeps one core in
+ * play.
+ */
+export declare const resolveFromProject: (rootDir: string, specifier: string) => string | undefined;
+/**
+ * Recovers a CommonJS package's exports from an import by path.
+ *
+ * Node reconstructs a CJS module's named exports only when it is imported by
+ * bare specifier. Imported by absolute path — which is the whole point of
+ * resolving from the project — the namespace carries `default` and nothing
+ * else, so a package like `ws`, which hangs `WebSocketServer` off
+ * `module.exports`, arrives with the constructor apparently missing. `probe` is
+ * the export that decides which of the two shapes came back.
+ */
+export declare const cjsInterop: <T>(mod: T, probe: string) => T;
+/**
+ * Imports a package resolved from the project, or `undefined` when it is not
+ * installed there. Callers decide whether absence is fatal.
+ */
+export declare const importFromProject: <T>(rootDir: string, specifier: string) => Promise<T | undefined>;

package/dist/src/utils/resolve-from-project.js

@@ -0,0 +1,45 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+/**
+ * Resolves a package as the *project* would, not as the CLI would.
+ *
+ * The CLI is frequently run from somewhere that is not the project — `npx`
+ * unpacks it into `~/.npm/_npx/<hash>`, a monorepo hoists it to the workspace
+ * root — so a bare `import('pkg')` from CLI code finds the copy sitting next to
+ * the CLI. For a package that peers on `@pikku/core` that is the wrong copy:
+ * it gets paired with the CLI's core rather than the project's, and the version
+ * skew surfaces as a missing subpath export from a package the project never
+ * imported. Resolving against the project's own package.json keeps one core in
+ * play.
+ */
+export const resolveFromProject = (rootDir, specifier) => {
+    try {
+        return createRequire(join(rootDir, 'package.json')).resolve(specifier);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Recovers a CommonJS package's exports from an import by path.
+ *
+ * Node reconstructs a CJS module's named exports only when it is imported by
+ * bare specifier. Imported by absolute path — which is the whole point of
+ * resolving from the project — the namespace carries `default` and nothing
+ * else, so a package like `ws`, which hangs `WebSocketServer` off
+ * `module.exports`, arrives with the constructor apparently missing. `probe` is
+ * the export that decides which of the two shapes came back.
+ */
+export const cjsInterop = (mod, probe) => probe in mod
+    ? mod
+    : (mod.default ?? mod);
+/**
+ * Imports a package resolved from the project, or `undefined` when it is not
+ * installed there. Callers decide whether absence is fatal.
+ */
+export const importFromProject = async (rootDir, specifier) => {
+    const resolved = resolveFromProject(rootDir, specifier);
+    if (!resolved)
+        return undefined;
+    return (await import(resolved));
+};