@pikku/cli 0.12.104 → 0.12.107

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

@@ -1,8 +1,10 @@
 import { existsSync } from 'fs';
+import { unresolvedSchemaReferences } from '@pikku/inspector';
 import { pikkuWorkflowComplexFunc } from '#pikku/workflow/pikku-workflow-types.gen.js';
 import { assertSingleCoreVersion } from '../../utils/assert-single-core-version.js';
 import { warnOnSplitTypeIdentity } from '../validate/type-identity-checks.js';
-import { pruneLegacyScaffoldFiles, removeRetiredScaffoldFiles, } from '../../utils/remove-legacy-scaffold-file.js';
+import { pruneLegacyScaffoldFiles, refreshScaffoldsImportingRemovedEntryPoints, removeRetiredScaffoldFiles, } from '../../utils/remove-legacy-scaffold-file.js';
+import { writeSurfaceUsage } from '../surface/write-surface-usage.js';
 import { PikkuTypecheckFailedError, renderTscFull, renderTscSummary, runProjectTypecheck, } from '../../utils/tsc-check.js';
 const scaffoldFiles = (config) => {
     const files = [];
@@ -51,9 +53,10 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         // it. Say it now or never.
         await warnOnSplitTypeIdentity(config.rootDir, logger);
         await pruneLegacyScaffoldFiles(config);
+        await refreshScaffoldsImportingRemovedEntryPoints(config);
         await removeRetiredScaffoldFiles(config);
         const allImports = [];
-        let typesDeclarationFileExists = true;
+        let functionTypesFileExists = true;
         if (!existsSync(config.outDir)) {
             logger.debug(`• .pikku directory not found, running bootstrap first...`);
             // Every `getInspectorState` step below discards its result on purpose. A
@@ -67,11 +70,12 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             await workflow.do('Bootstrap inspect', async () => {
                 await getInspectorState(false, true, true);
             });
-            // Both before function types: pikku-types.gen.ts re-exports the scope
-            // definition types and imports ScopeId from the scopes codegen, so any
-            // later import of '#pikku' — the inspector reading a project's zod
-            // schemas, for one — fails until these two files exist.
+            // Both before the function types: the function leaf imports ScopeId from
+            // the scopes codegen, so any later import of '#pikku/function' — the
+            // inspector reading a project's zod schemas, for one — fails until these
+            // two files exist.
             await workflow.do('Bootstrap scope definition types', 'pikkuScopeDefinitionTypes', null);
+            await workflow.do('Bootstrap error types', 'pikkuErrorTypes', null);
             await workflow.do('Bootstrap scopes', 'pikkuScopes', { bootstrap: true });
             await workflow.do('Bootstrap roles', 'pikkuRoles', { bootstrap: true });
             await workflow.do('Bootstrap personas', 'pikkuPersonas', {
@@ -83,17 +87,12 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             await workflow.do('Bootstrap auth types', 'pikkuAuth', {
                 bootstrap: true,
             });
-            await workflow.do('Bootstrap function types', 'pikkuFunctionTypes', {
-                bootstrap: true,
-            });
             await workflow.do('Bootstrap addon types', 'pikkuAddonTypes', {
                 bootstrap: true,
             });
             await Promise.all([
                 workflow.do('Bootstrap HTTP types', 'pikkuHTTPTypes', null),
                 workflow.do('Bootstrap channel types', 'pikkuChannelTypes', null),
-                workflow.do('Bootstrap scheduler types', 'pikkuSchedulerTypes', null),
-                workflow.do('Bootstrap queue types', 'pikkuQueueTypes', null),
                 workflow.do('Bootstrap workflow', 'pikkuWorkflow', {
                     bootstrap: true,
                 }),
@@ -101,21 +100,35 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
                     bootstrap: true,
                 }),
                 workflow.do('Bootstrap MCP types', 'pikkuMCPTypes', null),
-                workflow.do('Bootstrap AI agent types', 'pikkuAIAgentTypes', null),
+                workflow.do('Bootstrap AI agent types', 'pikkuAgentTypes', null),
+                ...(config.addon
+                    ? []
+                    : [
+                        workflow.do('Bootstrap scheduler types', 'pikkuSchedulerTypes', null),
+                        workflow.do('Bootstrap queue types', 'pikkuQueueTypes', null),
+                        workflow.do('Bootstrap gateway types', 'pikkuGatewayTypes', {
+                            bootstrap: true,
+                        }),
+                    ]),
             ]);
-            await workflow.do('Bootstrap Node types', 'pikkuNodeTypes', null);
             await workflow.do('Bootstrap Secret definition types', 'pikkuSecretDefinitionTypes', null);
+            await workflow.do('Bootstrap Variable definition types', 'pikkuVariableDefinitionTypes', null);
             if (!config.addon) {
                 await workflow.do('Bootstrap CLI types', 'pikkuCLITypes', {
                     bootstrap: true,
                 });
             }
+            // Before the re-inspect, not after: the inspector builds its own TS
+            // program, and every user file reaches the wirings through
+            // `#pikku/<leaf>`. Without the indexes those specifiers do not resolve,
+            // and an unresolved factory leaves the function's input silently `any`.
+            await workflow.do('Bootstrap leaf subpath entries', 'pikkuLeafIndexes', null);
             await workflow.do('Bootstrap re-inspect', async () => {
                 await getInspectorState(true, true);
             });
         }
-        if (!existsSync(config.typesDeclarationFile)) {
-            typesDeclarationFileExists = false;
+        if (!existsSync(config.functionTypesFile)) {
+            functionTypesFileExists = false;
         }
         const missingScaffolds = scaffoldFiles(config).filter((s) => !existsSync(s.file));
         if (missingScaffolds.length > 0) {
@@ -123,24 +136,41 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
                 await workflow.do(`Scaffold ${generator}`, generator, null);
             }
         }
-        await workflow.do('Generate function types', 'pikkuFunctionTypes', {});
-        if (!typesDeclarationFileExists || missingScaffolds.length > 0) {
+        // Before the leaf indexes, because an index only re-exports entry files that
+        // exist when it is written. These three are pure — they read `config` and
+        // nothing else — so nothing holds them back to the inspected pass below, and
+        // running them there would leave the first run after an upgrade with a
+        // `#pikku/secrets` that resolves but is missing `defineSecret`.
+        await Promise.all([
+            workflow.do('Secret definition types', 'pikkuSecretDefinitionTypes', null),
+            workflow.do('Scope definition types', 'pikkuScopeDefinitionTypes', null),
+            workflow.do('Variable definition types', 'pikkuVariableDefinitionTypes', null),
+        ]);
+        await workflow.do('Function types split', 'pikkuFunctionTypesSplit', {});
+        await workflow.do('Leaf subpath entries', 'pikkuLeafIndexes', null);
+        if (!functionTypesFileExists || missingScaffolds.length > 0) {
             logger.debug(`• Type file or scaffolds first created, inspecting again...`);
             await workflow.do('Re-inspect after types', async () => {
                 await getInspectorState(true);
             });
         }
         // Type generators are independent of each other
+        // These write the addon-safe subset of their leaf when the project is an
+        // addon, so they run either way. Skipping them for an addon only meant the
+        // bootstrap pass's copy was never rewritten, and an addon generated by an
+        // older CLI kept wiring leaves that no longer compiled against the current
+        // function leaf.
         const typeGenerators = [
-            workflow.do('Function types split', 'pikkuFunctionTypesSplit', {}),
             workflow.do('Trigger types', 'pikkuTriggerTypes', {}),
-            workflow.do('AI agent types', 'pikkuAIAgentTypes', null),
+            workflow.do('AI agent types', 'pikkuAgentTypes', null),
+            workflow.do('HTTP types', 'pikkuHTTPTypes', null),
+            workflow.do('Channel types', 'pikkuChannelTypes', null),
+            workflow.do('MCP types', 'pikkuMCPTypes', null),
         ];
         if (!config.addon) {
-            typeGenerators.push(workflow.do('HTTP types', 'pikkuHTTPTypes', null), workflow.do('Channel types', 'pikkuChannelTypes', null), workflow.do('Scheduler types', 'pikkuSchedulerTypes', null), workflow.do('Queue types', 'pikkuQueueTypes', null), workflow.do('MCP types', 'pikkuMCPTypes', null));
+            typeGenerators.push(workflow.do('Gateway types', 'pikkuGatewayTypes', {}), workflow.do('Scheduler types', 'pikkuSchedulerTypes', null), workflow.do('Queue types', 'pikkuQueueTypes', null));
         }
         await Promise.all(typeGenerators);
-        await workflow.do('Node types', 'pikkuNodeTypes', null);
         if (!config.addon) {
             await workflow.do('CLI types', 'pikkuCLITypes', null);
         }
@@ -161,8 +191,8 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         }
         const [hasInternalRPCs, agents, scorers] = await Promise.all([
             workflow.do('RPC', 'pikkuRPC', null),
-            workflow.do('AI agent', 'pikkuAIAgent', null),
-            workflow.do('AI scorer', 'pikkuAIScorer', null),
+            workflow.do('AI agent', 'pikkuAgent', null),
+            workflow.do('AI scorer', 'pikkuAgentScorer', null),
         ]);
         allImports.push(config.modelAliasesFile);
         if (agents) {
@@ -183,15 +213,13 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             workflow.do('Virtual user functions', 'pikkuVirtualUserFunctions', null),
             workflow.do('Events scaffold', 'pikkuEventsScaffold', null),
             workflow.do('Emails', 'pikkuEmails', null),
-            workflow.do('Secret definition types', 'pikkuSecretDefinitionTypes', null),
+            workflow.do('Error types', 'pikkuErrorTypes', null),
             workflow.do('Auth', 'pikkuAuth', {}),
             workflow.do('Secrets', 'pikkuSecrets', null),
             workflow.do('Credentials', 'pikkuCredentials', null),
-            workflow.do('Scope definition types', 'pikkuScopeDefinitionTypes', null),
             workflow.do('Scopes', 'pikkuScopes', {}),
             workflow.do('Roles', 'pikkuRoles', {}),
             workflow.do('Personas', 'pikkuPersonas', {}),
-            workflow.do('Variable definition types', 'pikkuVariableDefinitionTypes', null),
             workflow.do('Variables', 'pikkuVariables', null),
             workflow.do('Addon types', 'pikkuAddonTypes', null),
         ]);
@@ -224,6 +252,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         if (schemas) {
             allImports.push(`${config.schemaDirectory}/register.gen.ts`);
         }
+        const hadRPCInternalMap = existsSync(config.rpcInternalMapDeclarationFile);
         const [, , , workflows] = await Promise.all([
             workflow.do('RPC internal map', 'pikkuRPCInternalMap', null),
             workflow.do('RPC exposed map', 'pikkuRPCExposedMap', null),
@@ -240,7 +269,24 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
                 workflowRoutes = await workflow.do('Workflow routes', 'pikkuWorkflowRoutes', null);
             }
         }
-        if (workflows || remoteRPC || webhook || workflowRoutes) {
+        // A contract type reaches the schema generator only through a file that
+        // imports it, and for a type exported by nothing but its own function file
+        // that file is the RPC internal map — written just above, after schemas.
+        // A first build has no map to read yet, so those schemas come out missing
+        // from a run that otherwise succeeds and the RPC dies with
+        // MissingSchemaError on its first call. The map exists now, so
+        // re-inspecting resolves them.
+        //
+        // Only on the build that created the map: a project whose references are
+        // unresolved for some other reason would otherwise pay a second inspection
+        // on every run for a re-generation that cannot help it.
+        const unresolvedSchemas = !hadRPCInternalMap &&
+            unresolvedSchemaReferences(await getInspectorState()).length > 0;
+        if (workflows ||
+            remoteRPC ||
+            webhook ||
+            workflowRoutes ||
+            unresolvedSchemas) {
             await workflow.do('Re-inspect after workflows', async () => {
                 await getInspectorState(true);
             });
@@ -349,6 +395,16 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             await workflow.do('OpenAPI', 'pikkuOpenAPI', null);
         }
         await workflow.do('Versions update', 'pikkuVersionsUpdate', null);
+        // Last, because a leaf index only exists for an entry file that was
+        // actually generated — that absence is what makes `#pikku/http` fail to
+        // resolve in an addon rather than resolve to a module missing the export.
+        await workflow.do('Leaf subpath entries', 'pikkuLeafIndexes', null);
+        // Reads the counters the inspector accumulated during the sweep it already
+        // makes — no second pass over the project's source, and nothing retained.
+        await workflow.do('Surface usage', async () => {
+            const { surfaceUsage } = await getInspectorState();
+            await writeSurfaceUsage(logger, config, surfaceUsage ?? {});
+        });
         await workflow.do('Bootstrap', 'pikkuBootstrap', { allImports });
         await workflow.do('Summary', 'pikkuSummary', null);
         // Opt-in type-check gate (--tsc / --tsc-summary). Runs last, over the

package/dist/src/middleware/log-command-info-and-time.d.ts

@@ -1,5 +1,5 @@
 import type { Services } from '../../types/application-types.js';
-import type { PikkuWire } from '@pikku/core';
+import type { PikkuWire } from '@pikku/core/types';
 type PikkuMiddleware = (services: Services, wire: PikkuWire, next: () => Promise<void>) => Promise<void>;
 export interface LogCommandInfoOptions {
     commandStart: string;

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

@@ -6,7 +6,7 @@
  * shared with singleton services so function-side broadcasts reach the sockets
  * the transport holds.
  */
-import type { EventHubService } from '@pikku/core';
+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 class BunServerRunner implements DevServerRunner {

package/dist/src/server/content-signing-jwt.js

@@ -10,7 +10,7 @@
  * waving through requests when no key is configured.
  */
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
-import { getRelativeTimeOffsetFromNow } from '@pikku/core';
+import { getRelativeTimeOffsetFromNow } from '@pikku/core/utils';
 export const createEphemeralContentSigningJWT = () => {
     const key = randomBytes(32);
     const sign = (body) => createHmac('sha256', key).update(body).digest('base64url');

package/dist/src/server/dev-server-runner.interface.d.ts

@@ -8,7 +8,7 @@
  * reach the transport's sockets. The right runner is resolved once in
  * `services.ts` and injected — no `typeof Bun` checks in the dev command.
  */
-import type { EventHubService } from '@pikku/core';
+import type { EventHubService } from '@pikku/core/channel';
 import type { JWTService, Logger } from '@pikku/core/services';
 import type { NodeHTTPServerConfig } from '@pikku/node-http-server';
 export interface DevServerInstance {

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

@@ -3,7 +3,7 @@
  * Used when the CLI runs under Node. Owns the WebSocketServer so teardown
  * (close ws then the http server) is encapsulated in the returned instance.
  */
-import type { EventHubService } from '@pikku/core';
+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 class NodeServerRunner implements DevServerRunner {

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

@@ -5,14 +5,17 @@
  */
 import { LocalEventHubService } from '@pikku/core/channel/local';
 import { PikkuNodeHTTPServer } from '@pikku/node-http-server';
-import { pikkuWebsocketHandler } from '@pikku/ws';
+import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws';
 import { WebSocketServer } from 'ws';
 export class NodeServerRunner {
     async createEventHub() {
         return new LocalEventHubService();
     }
     createServer(config, logger, options = {}) {
-        const wss = new WebSocketServer({ noServer: true });
+        const wss = new WebSocketServer({
+            noServer: true,
+            maxPayload: DEFAULT_WS_MAX_PAYLOAD,
+        });
         const server = new PikkuNodeHTTPServer(config, logger, {
             configureServer: (httpServer) => {
                 pikkuWebsocketHandler({ server: httpServer, wss, logger });

package/dist/src/services/cli-logger.service.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '@pikku/core/services';
-import type { Safe } from '@pikku/core';
+import type { Safe } from '@pikku/core/classification';
 import { LogLevel } from '@pikku/core/services';
 import type { ErrorCode, DiagnosticSeverity, CodedDiagnostic } from '@pikku/inspector';
 export type CLIOutputMode = 'text' | 'json';

package/dist/src/services/cli-logger.service.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { LogLevel } from '@pikku/core/services';
-import { isExpectedError } from '@pikku/core';
+import { isExpectedError } from '@pikku/core/errors';
 // Compact one-line wordmark — the old multi-line ASCII art got cropped in
 // short/narrow AI-agent panes. Coloured directly (not via the blue `info`
 // path) so the cyan/bold render correctly.

package/dist/src/services.d.ts

@@ -1,6 +1,6 @@
 import type { Config, Services, SingletonServices, UserSession } from '../types/application-types.js';
-import type { CreateConfig } from '@pikku/core';
-import type { CreateWireServices, CreateSingletonServices } from '@pikku/core/ecosystem';
+import type { CreateConfig } from '@pikku/core/types';
+import type { CreateWireServices, CreateSingletonServices } from '@pikku/core/types';
 import { LogLevel } from '@pikku/core/services';
 import { CLILogger } from './services/cli-logger.service.js';
 import type { InspectorDiagnostic } from '@pikku/inspector';
@@ -10,16 +10,19 @@ export declare function processDiagnostics(diagnostics: InspectorDiagnostic[], l
 /**
  * Default CLI renderer that logs output using the logger
  */
-export declare const defaultCLIRenderer: import("@pikku/core/cli").CorePikkuCLIRender<ForwardedLogMessage, import("@pikku/core").CoreSingletonServices<{
+export declare const defaultCLIRenderer: import("@pikku/core/cli").CorePikkuCLIRender<ForwardedLogMessage, import("@pikku/core/types").CoreSingletonServices<{
     logLevel?: LogLevel;
     secrets?: {
         requireAllowedHosts?: boolean;
     };
     workflow?: import("@pikku/core/workflow").WorkflowServiceConfig;
     webhook?: import("@pikku/core/services").WebhookServiceConfig;
-    postgres?: import("@pikku/core").PostgresConfig;
-}>, import("@pikku/core").CoreUserSession>;
-export declare const createConfig: CreateConfig<Config, [PikkuCLIConfig]>;
+    postgres?: import("@pikku/core/types").PostgresConfig;
+}>, import("@pikku/core/types").CoreUserSession>;
+export declare const createConfig: CreateConfig<Config, [
+    PikkuCLIConfig,
+    string[]?
+]>;
 /**
  * Singleton services factory for the Pikku CLI
  * This function creates the singleton services used by the CLI and is created once on start.

package/dist/src/services.js

@@ -1,8 +1,8 @@
 import { pikkuCLIRender } from '@pikku/core/cli';
-import { LocalVariablesService, LocalSecretService, LogLevel, InMemoryWorkflowService, } from '@pikku/core/services';
-import { NoopAuditService } from '@pikku/core';
+import { LocalVariablesService, LocalSecretService, LogLevel, NoopAuditService, } from '@pikku/core/services';
+import { InMemoryWorkflowService } from '@pikku/core/services';
 import { CLILogger } from './services/cli-logger.service.js';
-import { getPikkuCLIConfig } from './utils/pikku-cli-config.js';
+import { getPikkuCLIConfig, tryGetPikkuCLIConfig, } from './utils/pikku-cli-config.js';
 import { inspect, serializeInspectorState, deserializeInspectorState, filterInspectorState, getInitialInspectorState, ErrorCode, } from '@pikku/inspector';
 import { glob } from 'tinyglobby';
 import path from 'path';
@@ -66,7 +66,17 @@ export const defaultCLIRenderer = pikkuCLIRender((_services, data) => {
         return;
     logger[data.level]({ message: data.message, type: data.type });
 });
-export const createConfig = async (_variablesService, data) => {
+/**
+ * Commands that must work in a directory that is not a Pikku project.
+ * `skills install` writes agent skills into a repo that has no pikku.config.json
+ * yet — that is the whole point of it — so it cannot require one to start.
+ */
+const CONFIG_FREE_COMMANDS = new Set([
+    'skills',
+    'skills.list',
+    'skills.install',
+]);
+export const createConfig = async (_variablesService, data, commandPath = []) => {
     // Determine log level based on CLI flags with precedence:
     // --silent > --loglevel > --verbose > --info > default (info)
     let logLevel = LogLevel.info; // default
@@ -110,7 +120,13 @@ export const createConfig = async (_variablesService, data) => {
     if (!isSilent && outputMode !== 'json') {
         logger.logLogo();
     }
-    const cliConfig = await getPikkuCLIConfig(logger, data.configFile, [], true, data.outDir);
+    // A config-free command still uses the project config when one is there, so
+    // it behaves the same inside a project; it just does not demand one.
+    const configFree = CONFIG_FREE_COMMANDS.has(commandPath.join('.'));
+    const cliConfig = configFree
+        ? ((await tryGetPikkuCLIConfig(logger, data.configFile, [], data.outDir)) ??
+            {})
+        : await getPikkuCLIConfig(logger, data.configFile, [], true, data.outDir);
     // Load inspector state from file if stateInput is provided
     let preloadedInspectorState = undefined;
     if (data.stateInput) {
@@ -161,7 +177,7 @@ export const createSingletonServices = async (config) => {
         // In bootstrap mode, return a minimal "zero state" with core types
         // This allows bootstrap to run immediately without inspecting the codebase
         if (bootstrapMode) {
-            const corePackagePath = '@pikku/core';
+            const corePackagePath = '@pikku/core/types';
             const initialState = getInitialInspectorState(rootDir);
             // Populate filesAndMethods with core types from @pikku/core
             initialState.filesAndMethods = {

package/dist/src/utils/file-writer.d.ts

@@ -1,5 +1,7 @@
 import type { CLILogger } from '../services/cli-logger.service.js';
 export declare const DO_NOT_MODIFY_COMMENT: string;
+export declare const setScaffoldWriteGuard: (dir: string | undefined) => void;
+export declare const isScaffoldWriteGuarded: (path: string) => boolean;
 export declare const getTsWriteGeneration: () => number;
 export declare const writeFileInDir: (logger: CLILogger, path: string, content: string, { ignoreModifyComment, logWrite, }?: {
     ignoreModifyComment?: boolean;

package/dist/src/utils/file-writer.js

@@ -1,4 +1,4 @@
-import { dirname, join } from 'path';
+import { dirname, join, relative, resolve } from 'path';
 import { mkdir, readFile, rename, writeFile, rm } from 'fs/promises';
 import { existsSync } from 'fs';
 import { getCLIVersion } from './get-cli-version.js';
@@ -6,10 +6,39 @@ export const DO_NOT_MODIFY_COMMENT = `/**
  * This file was generated by @pikku/cli@${getCLIVersion()}
  */
 `;
+/**
+ * While set, writes and removals under this directory are skipped.
+ *
+ * Deploy plan runs a full `pikku all` per unit with `--outDir` redirected to
+ * that unit's `.pikku`. Scaffold files are project *source* — generated once,
+ * then owned and edited by the developer — and their imports are computed
+ * against `config.outDir`, so regenerating them under a redirected outDir
+ * rewrites the developer's tree to point at
+ * `.deploy/<provider>/units/<unit>/.pikku` and leaves it failing to typecheck
+ * until the next ordinary `pikku all`.
+ *
+ * Guarding the writer rather than each generator is deliberate: generators are
+ * added regularly, several write both scaffold source and `.pikku` artifacts in
+ * one pass (so an all-or-nothing early return would skip too much), and a new
+ * one that forgets the check is silently correct here.
+ */
+let scaffoldWriteGuardDir;
+export const setScaffoldWriteGuard = (dir) => {
+    scaffoldWriteGuardDir = dir ? resolve(dir) : undefined;
+};
+export const isScaffoldWriteGuarded = (path) => scaffoldWriteGuardDir !== undefined &&
+    !relative(scaffoldWriteGuardDir, resolve(path)).startsWith('..');
 let tsWriteGeneration = 0;
 const TS_FILE_REGEX = /\.[mc]?tsx?$/;
 export const getTsWriteGeneration = () => tsWriteGeneration;
 export const writeFileInDir = async (logger, path, content, { ignoreModifyComment = false, logWrite = true, } = {}) => {
+    if (isScaffoldWriteGuarded(path)) {
+        logger.debug({
+            message: `↷ Skipped scaffold write to ${path} (per-unit deploy codegen)`,
+            type: 'info',
+        });
+        return;
+    }
     if (path.includes('.json')) {
         ignoreModifyComment = true;
     }
@@ -71,6 +100,13 @@ export function scaffoldFilePath(config, subdir, name, suffix, overrideDir) {
     return join(config.rootDir, config.srcDirectories[0], subdir, `${fileName}${suffix}`);
 }
 export const removeFileInDir = async (logger, path, { logRemove = true } = {}) => {
+    if (isScaffoldWriteGuarded(path)) {
+        logger.debug({
+            message: `↷ Skipped scaffold removal of ${path} (per-unit deploy codegen)`,
+            type: 'info',
+        });
+        return;
+    }
     // Check if file exists before attempting removal
     if (existsSync(path)) {
         await rm(path, { force: true });

package/dist/src/utils/is-deploy-codegen.d.ts

@@ -0,0 +1,21 @@
+import type { VariablesService } from '@pikku/core/services';
+/**
+ * Is this process a per-unit deploy codegen run?
+ *
+ * Deploy plan runs a full `pikku all` once per unit with `--outDir` pointed at
+ * that unit's `.pikku`. Scaffold files are *project source* — written once and
+ * then owned by the developer — and their import paths are computed against
+ * `config.outDir`, so regenerating them under a redirected outDir rewrites the
+ * developer's tree to point at `.deploy/<provider>/units/<unit>/.pikku`. The
+ * source then no longer typechecks until `pikku all` is run again.
+ *
+ * Every generator that writes into the scaffold directory has to ask this
+ * before writing.
+ *
+ * Note the coercion. `LocalVariablesService.get` runs the raw value through
+ * `JSON.parse`, so the string `'1'` arrives as the *number* `1` and a
+ * `=== '1'` check silently never matches — which is exactly how this guard came
+ * to exist while having no effect. Compare on the stringified value so the
+ * check holds whichever way the variable is supplied.
+ */
+export declare const isDeployCodegen: (variables: VariablesService) => Promise<boolean>;

package/dist/src/utils/is-deploy-codegen.js

@@ -0,0 +1,23 @@
+/**
+ * Is this process a per-unit deploy codegen run?
+ *
+ * Deploy plan runs a full `pikku all` once per unit with `--outDir` pointed at
+ * that unit's `.pikku`. Scaffold files are *project source* — written once and
+ * then owned by the developer — and their import paths are computed against
+ * `config.outDir`, so regenerating them under a redirected outDir rewrites the
+ * developer's tree to point at `.deploy/<provider>/units/<unit>/.pikku`. The
+ * source then no longer typechecks until `pikku all` is run again.
+ *
+ * Every generator that writes into the scaffold directory has to ask this
+ * before writing.
+ *
+ * Note the coercion. `LocalVariablesService.get` runs the raw value through
+ * `JSON.parse`, so the string `'1'` arrives as the *number* `1` and a
+ * `=== '1'` check silently never matches — which is exactly how this guard came
+ * to exist while having no effect. Compare on the stringified value so the
+ * check holds whichever way the variable is supplied.
+ */
+export const isDeployCodegen = async (variables) => {
+    const flag = await variables.get('PIKKU_DEPLOY_CODEGEN');
+    return flag !== undefined && flag !== null && String(flag) === '1';
+};

package/dist/src/utils/leaf-import-path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The import path a generated file uses to reach one wiring's leaf.
+ *
+ * Scaffolds used to reach `pikku-types.gen.ts`, which re-exported every leaf —
+ * so a project with one scaffold pulled every wiring's core dependencies into
+ * its module graph whether it wired them or not. Naming the leaf keeps a
+ * scaffold's imports to the wirings it actually uses.
+ *
+ * Relative rather than `#pikku/<leaf>`: a scaffold can be written into a
+ * different package to the one that declares the alias, and `#` specifiers are
+ * private to the package that declares them.
+ */
+export declare const getLeafImportPath: (from: string, leaf: string, config: {
+    outDir: string;
+    packageMappings: Record<string, string>;
+}) => string;

package/dist/src/utils/leaf-import-path.js

@@ -0,0 +1,15 @@
+import { join } from 'path';
+import { getFileImportRelativePath } from './file-import-path.js';
+/**
+ * The import path a generated file uses to reach one wiring's leaf.
+ *
+ * Scaffolds used to reach `pikku-types.gen.ts`, which re-exported every leaf —
+ * so a project with one scaffold pulled every wiring's core dependencies into
+ * its module graph whether it wired them or not. Naming the leaf keeps a
+ * scaffold's imports to the wirings it actually uses.
+ *
+ * Relative rather than `#pikku/<leaf>`: a scaffold can be written into a
+ * different package to the one that declares the alias, and `#` specifiers are
+ * private to the package that declares them.
+ */
+export const getLeafImportPath = (from, leaf, config) => getFileImportRelativePath(from, join(config.outDir, leaf, 'index.ts'), config.packageMappings);

package/dist/src/utils/parse-cli-filters.js

@@ -1,23 +1,3 @@
-/**
- * Parse a comma-separated string or array into an array of trimmed, non-empty strings
- * Returns undefined if the input is empty/undefined or results in an empty array
- */
-function parseCommaSeparated(value) {
-    if (!value)
-        return undefined;
-    if (Array.isArray(value)) {
-        const flattened = value
-            .flatMap((item) => item.split(','))
-            .map((item) => item.trim())
-            .filter((item) => item.length > 0);
-        return flattened.length > 0 ? flattened : undefined;
-    }
-    const parsed = value
-        .split(',')
-        .map((item) => item.trim())
-        .filter((item) => item.length > 0);
-    return parsed.length > 0 ? parsed : undefined;
-}
 /**
  * Parse CLI filter arguments into InspectorFilters format
  */
@@ -52,7 +32,7 @@ export function parseCLIFilters(data, cliConfig) {
         append('excludeTarget', source.excludeTarget);
     };
     const namedFilters = cliConfig?.namedFilters ?? {};
-    const requestedNamedFilters = parseCommaSeparated(data.filter ?? data.filters);
+    const requestedNamedFilters = data.filter ?? (data.filters ? [data.filters] : undefined);
     if (requestedNamedFilters && requestedNamedFilters.length > 0) {
         for (const name of requestedNamedFilters) {
             const preset = namedFilters[name];
@@ -66,20 +46,20 @@ export function parseCLIFilters(data, cliConfig) {
         }
     }
     mergeFilter({
-        names: parseCommaSeparated(data.names),
-        tags: parseCommaSeparated(data.tags),
-        wires: parseCommaSeparated(data.wires),
-        directories: parseCommaSeparated(data.directories),
-        httpRoutes: parseCommaSeparated(data.httpRoutes),
-        httpMethods: parseCommaSeparated(data.httpMethods),
-        target: parseCommaSeparated(data.target),
-        excludeNames: parseCommaSeparated(data.excludeNames),
-        excludeTags: parseCommaSeparated(data.excludeTags),
-        excludeWires: parseCommaSeparated(data.excludeWires),
-        excludeDirectories: parseCommaSeparated(data.excludeDirectories),
-        excludeHttpRoutes: parseCommaSeparated(data.excludeHttpRoutes),
-        excludeHttpMethods: parseCommaSeparated(data.excludeHttpMethods),
-        excludeTarget: parseCommaSeparated(data.excludeTarget),
+        names: data.names,
+        tags: data.tags,
+        wires: data.wires,
+        directories: data.directories,
+        httpRoutes: data.httpRoutes,
+        httpMethods: data.httpMethods,
+        target: data.target,
+        excludeNames: data.excludeNames,
+        excludeTags: data.excludeTags,
+        excludeWires: data.excludeWires,
+        excludeDirectories: data.excludeDirectories,
+        excludeHttpRoutes: data.excludeHttpRoutes,
+        excludeHttpMethods: data.excludeHttpMethods,
+        excludeTarget: data.excludeTarget,
     });
     const validateTargetList = (values, argName) => {
         if (!values || values.length === 0)

package/dist/src/utils/pikku-cli-config.d.ts

@@ -1,6 +1,17 @@
 import type { PikkuCLIConfig } from '../../types/config.js';
 import type { CLILogger } from '../services/cli-logger.service.js';
 export declare const getPikkuCLIConfig: (logger: CLILogger, configFile: string | undefined, requiredFields: Array<keyof PikkuCLIConfig>, exitProcess?: boolean, outDirOverride?: string) => Promise<PikkuCLIConfig>;
+/**
+ * Like `getPikkuCLIConfig`, but returns null when the project has no config at
+ * all rather than throwing.
+ *
+ * Some commands are meant to run *outside* a Pikku project: `pikku skills
+ * install` seeds a repo's agent skills, which is something you do before there
+ * is a pikku.config.json to read. Requiring one to find out there isn't one is
+ * a chicken-and-egg. A config that exists but is broken still throws — that is
+ * a real error, and staying quiet about it would hide it.
+ */
+export declare const tryGetPikkuCLIConfig: (logger: CLILogger, configFile: string | undefined, requiredFields: Array<keyof PikkuCLIConfig>, outDirOverride?: string) => Promise<PikkuCLIConfig | null>;
 /** A config that was found and parsed, but says something impossible. */
 export declare class PikkuCLIConfigError extends Error {
 }