@pikku/cli 0.12.67 → 0.12.69

package/dist/src/functions/commands/{user-flow.js → scenario.js}

@@ -1,23 +1,23 @@
 import { resolve } from 'path';
 import { pikkuSessionlessFunc } from '#pikku';
-import { InMemoryWorkflowService, createHttpUserFlowActors, } from '@pikku/core/services';
+import { InMemoryWorkflowService, createHttpScenarioActors, } from '@pikku/core/services';
 import { pikkuState } from '@pikku/core/internal';
 import { loadUserBootstrap } from './load-user-project.js';
-const isUserFlow = (wf) => wf?.userFlow === true;
-const listUserFlows = (state) => Object.entries(state.workflows?.meta ?? {})
-    .filter(([, wf]) => isUserFlow(wf))
+const isScenario = (wf) => wf?.scenario === true;
+const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
+    .filter(([, wf]) => isScenario(wf))
     .map(([id, wf]) => ({
     id,
     name: wf.name ?? id,
     description: wf.description ?? wf.summary ?? wf.title ?? null,
     tags: wf.tags ?? [],
 }));
-export const userFlowList = pikkuSessionlessFunc({
+export const scenarioList = pikkuSessionlessFunc({
     func: async ({ logger, getInspectorState }) => {
         const state = await getInspectorState();
-        const flows = listUserFlows(state);
+        const flows = listScenarios(state);
         if (flows.length === 0) {
-            logger.info('No user flows found (pikkuUserFlow exports).');
+            logger.info('No scenarios found (pikkuScenario exports).');
             return;
         }
         for (const flow of flows) {
@@ -29,26 +29,26 @@ export const userFlowList = pikkuSessionlessFunc({
         }
     },
 });
-export const userFlowRun = pikkuSessionlessFunc({
+export const scenarioRun = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState, variables }, { environment, flows, tags }) => {
         const state = await getInspectorState(true);
         // --- resolve the target environment ---
-        const environments = config.userFlows?.environments ?? {};
+        const environments = config.scenarios?.environments ?? {};
         const env = environments[environment];
         if (!env) {
             const known = Object.keys(environments);
-            throw new Error(`Unknown user-flow environment '${environment}'. ` +
+            throw new Error(`Unknown scenario environment '${environment}'. ` +
                 (known.length
                     ? `Configured environments: ${known.join(', ')}`
-                    : `Add userFlows.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
+                    : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
         }
         // --- select flows ---
-        let selected = listUserFlows(state);
+        let selected = listScenarios(state);
         if (flows) {
             const names = new Set(flows.split(',').map((f) => f.trim()));
             const unknown = [...names].filter((n) => !selected.some((f) => f.name === n));
             if (unknown.length) {
-                throw new Error(`Unknown user flow(s): ${unknown.join(', ')}. Available: ${selected.map((f) => f.name).join(', ')}`);
+                throw new Error(`Unknown scenario(s): ${unknown.join(', ')}. Available: ${selected.map((f) => f.name).join(', ')}`);
             }
             selected = selected.filter((f) => names.has(f.name));
         }
@@ -57,20 +57,20 @@ export const userFlowRun = pikkuSessionlessFunc({
             selected = selected.filter((f) => wanted.some((t) => f.tags.includes(t)));
         }
         if (selected.length === 0) {
-            logger.error('No user flows matched.');
+            logger.error('No scenarios matched.');
             process.exitCode = 1;
             return;
         }
         // --- actors: registry from config, secret STRICTLY from env ---
-        const secret = await variables.get('USER_FLOW_ACTOR_SECRET');
+        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
         if (!secret) {
-            throw new Error('USER_FLOW_ACTOR_SECRET is not set — user-flow actors cannot sign in. ' +
+            throw new Error('SCENARIO_ACTOR_SECRET is not set — scenario actors cannot sign in. ' +
                 'Export it in the environment running this command (never put it in pikku.config.json).');
         }
-        const actors = createHttpUserFlowActors({
+        const actors = createHttpScenarioActors({
             apiUrl: env.apiUrl,
             secret,
-            actors: config.userFlows?.actors ?? {},
+            actors: config.scenarios?.actors ?? {},
             signInPath: env.signInPath,
             rpcPath: env.rpcPath,
         });
@@ -87,8 +87,8 @@ export const userFlowRun = pikkuSessionlessFunc({
         });
         const guardRpc = {
             rpcWithWire: async (rpcName) => {
-                throw new Error(`User flow tried to run '${rpcName}' as an internal step. Every workflow.do ` +
-                    `in a user flow must carry { actor: actors.x } so it executes against ` +
+                throw new Error(`Scenario tried to run '${rpcName}' as an internal step. Every workflow.do ` +
+                    `in a scenario must carry { actor: actors.x } so it executes against ` +
                     `'${environment}' (${env.apiUrl}), not local services.`);
             },
         };
@@ -135,7 +135,7 @@ export const userFlowRun = pikkuSessionlessFunc({
                 logger.error(`FAIL ${r.name} (${r.durationMs}ms): ${r.error}`);
             }
         }
-        logger.info(`${results.length - failed.length}/${results.length} user flows passed against '${environment}'`);
+        logger.info(`${results.length - failed.length}/${results.length} scenarios passed against '${environment}'`);
         if (failed.length > 0) {
             process.exitCode = 1;
         }

package/dist/src/functions/commands/serve-console.d.ts

@@ -1,4 +1,3 @@
-import { createServer } from 'http';
-import type { Logger } from '@pikku/core/services';
+import type { StaticMount } from '@pikku/node-http-server';
 export declare function resolveConsoleDir(): string;
-export declare function startConsoleServer(consoleFlag: string | boolean, hostname: string, logger: Logger): Promise<ReturnType<typeof createServer> | undefined>;
+export declare function resolveConsoleMount(): Promise<StaticMount | undefined>;

package/dist/src/functions/commands/serve-console.js

@@ -1,62 +1,16 @@
-import { createServer } from 'http';
-import { readFile, stat } from 'fs/promises';
-import { join, extname } from 'path';
+import { stat } from 'fs/promises';
+import { join } from 'path';
 import { fileURLToPath } from 'url';
-const MIME_TYPES = {
-    '.html': 'text/html',
-    '.js': 'application/javascript',
-    '.css': 'text/css',
-    '.json': 'application/json',
-    '.png': 'image/png',
-    '.svg': 'image/svg+xml',
-    '.ico': 'image/x-icon',
-    '.webmanifest': 'application/manifest+json',
-    '.woff': 'font/woff',
-    '.woff2': 'font/woff2',
-    '.ttf': 'font/ttf',
-    '.map': 'application/json',
-};
 export function resolveConsoleDir() {
     return join(fileURLToPath(import.meta.url), '..', '..', '..', '..', '..', 'console-app');
 }
-export async function startConsoleServer(consoleFlag, hostname, logger) {
+export async function resolveConsoleMount() {
     const consoleDir = resolveConsoleDir();
-    const consolePort = typeof consoleFlag === 'string' ? parseInt(consoleFlag, 10) : 51442;
     try {
-        await stat(consoleDir);
+        await stat(join(consoleDir, 'index.html'));
     }
     catch {
-        logger.error('Console app not found. Please rebuild @pikku/cli with the console app bundled.');
         return undefined;
     }
-    const server = createServer(async (req, res) => {
-        const url = new URL(req.url || '/', `http://localhost:${consolePort}`);
-        let filePath = join(consoleDir, url.pathname);
-        try {
-            const s = await stat(filePath);
-            if (s.isDirectory())
-                filePath = join(filePath, 'index.html');
-        }
-        catch {
-            filePath = join(consoleDir, 'index.html');
-        }
-        try {
-            const content = await readFile(filePath);
-            const contentType = MIME_TYPES[extname(filePath)] || 'application/octet-stream';
-            res.writeHead(200, { 'Content-Type': contentType });
-            res.end(content);
-        }
-        catch {
-            res.writeHead(404, { 'Content-Type': 'text/plain' });
-            res.end('Not Found');
-        }
-    });
-    await new Promise((resolve, reject) => {
-        server.listen(consolePort, () => {
-            logger.info(`Pikku Console running at http://${hostname}:${consolePort}`);
-            resolve();
-        });
-        server.on('error', reject);
-    });
-    return server;
+    return { urlPrefix: '/console', directory: consoleDir, spaFallback: true };
 }

package/dist/src/functions/commands/serve.d.ts

@@ -1,10 +1,10 @@
 export declare const serve: import("#pikku").PikkuFunctionConfig<{
     port?: string;
-    console?: string | boolean;
+    console?: boolean;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     port?: string;
-    console?: string | boolean;
+    console?: boolean;
 }, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<{
     port?: string;
-    console?: string | boolean;
+    console?: boolean;
 }, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/commands/serve.js

@@ -10,10 +10,11 @@ import { InMemorySchedulerService } from '@pikku/schedule';
 import { resolveDb, createKysely, parseDatabaseUrl, } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
-import { startConsoleServer } from './serve-console.js';
+import { resolveConsoleMount } from './serve-console.js';
 export const serve = pikkuSessionlessFunc({
     remote: true,
-    func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: consoleFlag }) => {
+    func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole }) => {
+        process.env.PIKKU_DEV_QUICK_LOGIN ??= 'true';
         const resolvedPort = parseInt(port || '3000', 10);
         const hostname = 'localhost';
         const bindHostname = '127.0.0.1';
@@ -111,27 +112,31 @@ export const serve = pikkuSessionlessFunc({
             const m = await loadUserModule(serverLifecycleFactory.file);
             return m[serverLifecycleFactory.variable];
         };
+        const consoleMount = serveConsole ? await resolveConsoleMount() : undefined;
+        if (serveConsole && !consoleMount) {
+            logger.warn('Console app not found. Please rebuild @pikku/cli with the console app bundled.');
+        }
         const pikkuServer = devServerRunner.createServer({
             ...userConfig,
             hostname: bindHostname,
             port: resolvedPort,
             content: localContentConfig,
+            ...(consoleMount ? { staticMounts: [consoleMount] } : {}),
         }, logger);
         const lifecycle = await loadLifecycle();
         await pikkuServer.init();
         await lifecycle?.beforeStart?.(resolvedServices);
         await pikkuServer.start();
         await lifecycle?.afterStart?.(resolvedServices);
-        const consoleServer = consoleFlag
-            ? await startConsoleServer(consoleFlag, hostname, logger)
-            : undefined;
+        if (consoleMount) {
+            logger.info(`Pikku Console available at http://${hostname}:${resolvedPort}${consoleMount.urlPrefix}`);
+        }
         process.once('SIGINT', async () => {
             logger.info('Stopping server...');
             try {
                 await lifecycle?.beforeStop?.(resolvedServices);
                 await stopSingletonServices();
                 await pikkuServer.stop();
-                consoleServer?.close();
                 await lifecycle?.afterStop?.(resolvedServices);
             }
             finally {

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

@@ -3,7 +3,7 @@ import { ErrorCode } from '@pikku/inspector';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeWorkflowTypes } from './serialize-workflow-types.js';
-import { serializeUserFlowActors } from './serialize-user-flow-actors.js';
+import { serializeScenarioActors } from './serialize-scenario-actors.js';
 import { serializeWorkflowRegistration } from './serialize-workflow-registration.js';
 import { serializeWorkflowMap } from './serialize-workflow-map.js';
 import { serializeWorkflowBootstrapMap } from './serialize-workflow-bootstrap-map.js';
@@ -63,13 +63,14 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
         const rpcMapImportPath = getFileImportRelativePath(workflowTypesFile, config.rpcInternalMapDeclarationFile, packageMappings);
         const workflowMapImportPath = getFileImportRelativePath(workflowTypesFile, workflowMapDeclarationFile, packageMappings);
         await writeFileInDir(logger, workflowTypesFile, serializeWorkflowTypes(functionTypesImportPath, rpcMapImportPath, workflowMapImportPath));
-        const userFlowActors = config.userFlows?.actors;
-        if (userFlowActors && Object.keys(userFlowActors).length > 0) {
-            await writeFileInDir(logger, config.userFlowActorsFile, serializeUserFlowActors(userFlowActors));
+        const scenarioActors = config.scenarios?.actors;
+        if (scenarioActors && Object.keys(scenarioActors).length > 0) {
+            const agentMapImportPath = getFileImportRelativePath(config.scenarioActorsFile, config.agentMapDeclarationFile, packageMappings);
+            await writeFileInDir(logger, config.scenarioActorsFile, serializeScenarioActors(scenarioActors, agentMapImportPath));
             // JSON twin for the runtime meta service (console personas view). Lives
             // next to workflow/meta but NOT inside it — getWorkflowMeta() treats
             // every workflow/meta/*.gen.json as a workflow.
-            await writeFileInDir(logger, join(dirname(config.userFlowActorsFile), 'user-flow-actors.gen.json'), JSON.stringify(userFlowActors, null, 2));
+            await writeFileInDir(logger, join(dirname(config.scenarioActorsFile), 'scenario-actors.gen.json'), JSON.stringify(scenarioActors, null, 2));
         }
         await writeFileInDir(logger, workflowMapDeclarationFile, bootstrap
             ? serializeWorkflowBootstrapMap(workflows.meta, workflows.graphMeta)

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

@@ -0,0 +1,8 @@
+import type { PikkuCLIConfig } from '../../../../types/config.js';
+/**
+ * Generate the typed scenario actor registry from pikku.config.json's
+ * `scenarios.actors`. Apps wire the result as the `actors` singleton service:
+ *
+ *   actors: createScenarioActors({ apiUrl, secret })
+ */
+export declare const serializeScenarioActors: (actors: NonNullable<NonNullable<PikkuCLIConfig["scenarios"]>["actors"]>, agentMapImportPath: string) => string;

package/dist/src/functions/wirings/workflow/serialize-scenario-actors.js

@@ -0,0 +1,43 @@
+/**
+ * Generate the typed scenario actor registry from pikku.config.json's
+ * `scenarios.actors`. Apps wire the result as the `actors` singleton service:
+ *
+ *   actors: createScenarioActors({ apiUrl, secret })
+ */
+export const serializeScenarioActors = (actors, agentMapImportPath) => {
+    return `/**
+ * Scenario actors declared in pikku.config.json (\`scenarios.actors\`).
+ * Any scenario can impersonate any actor.
+ */
+import {
+  createHttpScenarioActors,
+  type HttpScenarioActorsConfig,
+  type ScenarioActor,
+  type ScenarioActorConfig,
+} from '@pikku/core/services'
+import type { AgentMap } from '${agentMapImportPath}'
+
+export const scenarioActorConfigs = ${JSON.stringify(actors, null, 2)} as const satisfies Record<string, ScenarioActorConfig>
+
+export type ScenarioActorName = keyof typeof scenarioActorConfigs
+
+/** \`actor.converse({ agent })\` is constrained to the project's agent names. */
+export type AgentName = keyof AgentMap & string
+export type TypedScenarioActors = Record<
+  ScenarioActorName,
+  ScenarioActor<AgentName>
+>
+
+/**
+ * Build the injected \`actors\` service: one lazy HTTP actor per registry
+ * entry, signing in via the Better Auth actor plugin on first invoke.
+ */
+export const createScenarioActors = (
+  options: Omit<HttpScenarioActorsConfig, 'actors'>
+): TypedScenarioActors =>
+  createHttpScenarioActors({
+    ...options,
+    actors: scenarioActorConfigs,
+  }) as TypedScenarioActors
+`;
+};

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

@@ -108,23 +108,23 @@ export function pikkuWorkflowComplexFunc(func: any) {
 }
 
 /**
- * A user flow: a complex workflow that drives the app the way users do.
+ * A scenario: a complex workflow that drives the app the way users do.
  * Steps run as actors over the REAL transport — \`workflow.do(step, rpc,
  * data, { actor: actors.yasser })\` — so flows double as e2e tests and
  * staged/production health checks (no state reset; scope what you create).
  */
-export function pikkuUserFlow<
+export function pikkuScenario<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
 >(
   config: PikkuWorkflowConfigWithSchema<InputSchema, OutputSchema>
 ): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'workflow', PikkuFunctionWorkflow<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>, InputSchema, OutputSchema>
-export function pikkuUserFlow<In, Out = unknown>(
+export function pikkuScenario<In, Out = unknown>(
   func:
     | PikkuFunctionWorkflow<In, Out>
     | PikkuFunctionConfig<In, Out, 'workflow', PikkuFunctionWorkflow<In, Out>>
 ): PikkuFunctionConfig<In, Out, 'workflow'>
-export function pikkuUserFlow(func: any) {
+export function pikkuScenario(func: any) {
   return typeof func === 'function' ? { func } : func
 }
 

package/dist/src/functions/workflows/all.workflow.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'fs';
 import { pikkuWorkflowComplexFunc } from '#pikku/workflow/pikku-workflow-types.gen.js';
 import { assertSingleCoreVersion } from '../../utils/assert-single-core-version.js';
+import { PikkuTypecheckFailedError, renderTscFull, renderTscSummary, runProjectTypecheck, } from '../../utils/tsc-check.js';
 const scaffoldFiles = (config) => {
     const files = [];
     if (config.scaffold?.rpc && config.publicRpcFile)
@@ -272,5 +273,21 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         await workflow.do('Versions update', 'pikkuVersionsUpdate', null);
         await workflow.do('Bootstrap', 'pikkuBootstrap', { allImports });
         await workflow.do('Summary', 'pikkuSummary', null);
+        // Opt-in type-check gate (--tsc / --tsc-summary). Runs last, over the
+        // post-codegen project, so generated .pikku files are included — matching a
+        // real build. Printed inside the step; the throw lives in the workflow body
+        // (like assertSingleCoreVersion) so it reliably fails the run.
+        if (config.tsc || config.tscSummary) {
+            const errorCount = await workflow.do('Type check', async () => {
+                const { result, diagnostics, formatHost } = runProjectTypecheck(config.tsconfig, config.rootDir);
+                logger.info(config.tsc
+                    ? renderTscFull(diagnostics, config.rootDir, formatHost)
+                    : renderTscSummary(result));
+                return result.errorCount;
+            });
+            if (errorCount > 0) {
+                throw new PikkuTypecheckFailedError(`Type check failed: ${errorCount} error${errorCount === 1 ? '' : 's'}`);
+            }
+        }
     },
 });

package/dist/src/utils/pikku-cli-config.js

@@ -306,8 +306,8 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (!result.workflowMetaDir) {
             result.workflowMetaDir = join(workflowDir, 'meta');
         }
-        if (!result.userFlowActorsFile) {
-            result.userFlowActorsFile = join(workflowDir, 'pikku-user-flow-actors.gen.ts');
+        if (!result.scenarioActorsFile) {
+            result.scenarioActorsFile = join(workflowDir, 'pikku-scenario-actors.gen.ts');
         }
         // Services
         if (!result.servicesFile) {

package/dist/src/utils/tsc-check.d.ts

@@ -0,0 +1,46 @@
+import ts from 'typescript';
+import { PikkuError } from '@pikku/core';
+export declare class PikkuTypecheckFailedError extends PikkuError {
+}
+export interface TscDiagnostic {
+    file: string;
+    line: number;
+    column: number;
+    code: number;
+    category: 'error' | 'warning' | 'suggestion' | 'message';
+    message: string;
+}
+export interface TscCheckResult {
+    errorCount: number;
+    warningCount: number;
+    fileCount: number;
+    diagnostics: TscDiagnostic[];
+}
+/**
+ * Turn raw tsc diagnostics into a filtered, structured result. Pure — it takes
+ * already-computed diagnostics so it can be unit-tested without a program.
+ * Anything under node_modules or outside the project root is dropped so the
+ * output stays focused on the user's own code (and not lib .d.ts noise).
+ */
+export declare const collectTscDiagnostics: (diagnostics: readonly ts.Diagnostic[], rootDir: string) => TscCheckResult;
+/**
+ * Compact, token-frugal render of a type-check result: a one-line header plus
+ * one line per diagnostic (no code frames), capped. Used by `--tsc-summary` so
+ * AI agents and CI logs get the signal without the flood.
+ */
+export declare const renderTscSummary: (result: TscCheckResult, maxLines?: number) => string;
+/**
+ * Full render: tsc's own formatter with code frames, filtered to project files.
+ */
+export declare const renderTscFull: (diagnostics: readonly ts.Diagnostic[], rootDir: string, formatHost: ts.FormatDiagnosticsHost) => string;
+/**
+ * Run a real `tsc --noEmit` over the project's own tsconfig — the correct
+ * source of truth (lib, paths, strict), unlike the inspector's stripped-down
+ * traversal program. Returns both a structured result and the raw diagnostics
+ * so the caller can pick the compact (`--tsc-summary`) or full (`--tsc`) render.
+ */
+export declare const runProjectTypecheck: (tsconfigPath: string, rootDir: string) => {
+    result: TscCheckResult;
+    diagnostics: ts.Diagnostic[];
+    formatHost: ts.FormatDiagnosticsHost;
+};

package/dist/src/utils/tsc-check.js

@@ -0,0 +1,141 @@
+import ts from 'typescript';
+import { dirname, isAbsolute, relative } from 'node:path';
+import { PikkuError } from '@pikku/core';
+// A type-check failure is expected (the --tsc gate did its job) — throw a
+// PikkuError so the runner logs the message alone, not a stack trace.
+export class PikkuTypecheckFailedError extends PikkuError {
+}
+const CATEGORY = {
+    [ts.DiagnosticCategory.Error]: 'error',
+    [ts.DiagnosticCategory.Warning]: 'warning',
+    [ts.DiagnosticCategory.Suggestion]: 'suggestion',
+    [ts.DiagnosticCategory.Message]: 'message',
+};
+const MAX_MESSAGE_LENGTH = 200;
+const DEFAULT_MAX_LINES = 50;
+const NO_FILE = '(project)';
+const isProjectFile = (fileName, rootDir) => {
+    if (fileName.includes('/node_modules/'))
+        return false;
+    const rel = relative(rootDir, fileName);
+    return !rel.startsWith('..') && !isAbsolute(rel);
+};
+/**
+ * Turn raw tsc diagnostics into a filtered, structured result. Pure — it takes
+ * already-computed diagnostics so it can be unit-tested without a program.
+ * Anything under node_modules or outside the project root is dropped so the
+ * output stays focused on the user's own code (and not lib .d.ts noise).
+ */
+export const collectTscDiagnostics = (diagnostics, rootDir) => {
+    const files = new Set();
+    const collected = [];
+    let errorCount = 0;
+    let warningCount = 0;
+    for (const d of diagnostics) {
+        let file = NO_FILE;
+        let line = 0;
+        let column = 0;
+        if (d.file) {
+            if (!isProjectFile(d.file.fileName, rootDir))
+                continue;
+            file = relative(rootDir, d.file.fileName);
+            const lc = d.file.getLineAndCharacterOfPosition(d.start ?? 0);
+            line = lc.line + 1;
+            column = lc.character + 1;
+        }
+        const category = CATEGORY[d.category];
+        if (category === 'error')
+            errorCount++;
+        else if (category === 'warning')
+            warningCount++;
+        let message = ts.flattenDiagnosticMessageText(d.messageText, ' ');
+        if (message.length > MAX_MESSAGE_LENGTH) {
+            message = `${message.slice(0, MAX_MESSAGE_LENGTH - 1)}…`;
+        }
+        files.add(file);
+        collected.push({ file, line, column, code: d.code, category, message });
+    }
+    collected.sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
+    return {
+        errorCount,
+        warningCount,
+        fileCount: files.size,
+        diagnostics: collected,
+    };
+};
+/**
+ * Compact, token-frugal render of a type-check result: a one-line header plus
+ * one line per diagnostic (no code frames), capped. Used by `--tsc-summary` so
+ * AI agents and CI logs get the signal without the flood.
+ */
+export const renderTscSummary = (result, maxLines = DEFAULT_MAX_LINES) => {
+    if (result.errorCount === 0 && result.warningCount === 0) {
+        return 'Type check passed — no errors.';
+    }
+    const counts = [];
+    if (result.errorCount > 0) {
+        counts.push(`${result.errorCount} error${result.errorCount === 1 ? '' : 's'}`);
+    }
+    if (result.warningCount > 0) {
+        counts.push(`${result.warningCount} warning${result.warningCount === 1 ? '' : 's'}`);
+    }
+    const fileLabel = `${result.fileCount} file${result.fileCount === 1 ? '' : 's'}`;
+    const lines = [`Type check: ${counts.join(', ')} in ${fileLabel}`];
+    const shown = result.diagnostics.slice(0, maxLines);
+    for (const d of shown) {
+        const at = d.line > 0 ? `${d.file}:${d.line}:${d.column}` : d.file;
+        lines.push(`  ${at}  TS${d.code}  ${d.message}`);
+    }
+    const remaining = result.diagnostics.length - shown.length;
+    if (remaining > 0) {
+        lines.push(`  … and ${remaining} more (run \`pikku all --tsc\` for full output)`);
+    }
+    return lines.join('\n');
+};
+/**
+ * Full render: tsc's own formatter with code frames, filtered to project files.
+ */
+export const renderTscFull = (diagnostics, rootDir, formatHost) => {
+    const filtered = diagnostics.filter((d) => !d.file || isProjectFile(d.file.fileName, rootDir));
+    if (filtered.length === 0)
+        return 'Type check passed — no errors.';
+    return ts.formatDiagnosticsWithColorAndContext(filtered, formatHost);
+};
+/**
+ * Run a real `tsc --noEmit` over the project's own tsconfig — the correct
+ * source of truth (lib, paths, strict), unlike the inspector's stripped-down
+ * traversal program. Returns both a structured result and the raw diagnostics
+ * so the caller can pick the compact (`--tsc-summary`) or full (`--tsc`) render.
+ */
+export const runProjectTypecheck = (tsconfigPath, rootDir) => {
+    const formatHost = {
+        getCanonicalFileName: (f) => f,
+        getCurrentDirectory: () => rootDir,
+        getNewLine: () => ts.sys.newLine,
+    };
+    const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (configFile.error) {
+        const diagnostics = [configFile.error];
+        return {
+            result: collectTscDiagnostics(diagnostics, rootDir),
+            diagnostics,
+            formatHost,
+        };
+    }
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, dirname(tsconfigPath));
+    const program = ts.createProgram({
+        rootNames: parsed.fileNames,
+        options: {
+            ...parsed.options,
+            noEmit: true,
+            incremental: false,
+            tsBuildInfoFile: undefined,
+        },
+    });
+    const diagnostics = [...parsed.errors, ...ts.getPreEmitDiagnostics(program)];
+    return {
+        result: collectTscDiagnostics(diagnostics, rootDir),
+        diagnostics,
+        formatHost,
+    };
+};