@pikku/cli 0.12.153 → 0.12.155

package/dist/src/fabric/lib/report-environment.js

@@ -1,6 +1,6 @@
-import { readFile, lstat, readdir } from 'node:fs/promises';
+import { readFile, lstat, readdir, realpath } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 /**
  * Walk up from `startDir` for the first `node_modules/@pikku` that holds
  * packages. A monorepo hoists to the root, an app installs locally, and either
@@ -26,6 +26,21 @@ export async function findPikkuScope(startDir) {
         dir = parent;
     }
 }
+/**
+ * A symlink on its own proves nothing: bun and pnpm install every registry
+ * package as a link into a store that itself lives under `node_modules`, so
+ * reading the link alone marks a whole ordinary install as modified framework
+ * code. Only a target outside `node_modules` is a checkout someone can edit.
+ */
+async function resolvesToCheckout(packageDir) {
+    const stats = await lstat(packageDir).catch(() => null);
+    if (!stats?.isSymbolicLink())
+        return false;
+    const target = await realpath(packageDir).catch(() => null);
+    if (!target)
+        return false;
+    return !`${target}${sep}`.includes(`${sep}node_modules${sep}`);
+}
 /**
  * Versions read off the installed tree rather than out of `package.json`. A
  * range like `^0.12.35` says nothing about what ran, and the version that ran
@@ -51,11 +66,10 @@ export async function readPikkuPackages(scopeDir) {
         }
         if (typeof version !== 'string')
             continue;
-        const stats = await lstat(packageDir).catch(() => null);
         packages.push({
             name: `@pikku/${entry}`,
             version,
-            linked: stats?.isSymbolicLink() ?? false,
+            linked: await resolvesToCheckout(packageDir),
         });
     }
     return packages;

package/dist/src/fabric/lib/sealed-box.js

@@ -16,6 +16,7 @@
  * business having one; opening a value happens in the worker.
  */
 import { createCipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from 'node:crypto';
+import { FabricPreconditionError } from './errors.js';
 /** Algorithm tag carried by every sealed value. Must match fabric's. */
 export const SEALED_BOX_ALGORITHM = 'sealed-x25519-v1';
 /** HKDF domain separator. Must match fabric's byte for byte. */
@@ -60,13 +61,13 @@ function importPublicKey(publicKey) {
         });
     }
     catch (error) {
-        throw new Error(`Not a valid X25519 public key (${error instanceof Error ? error.message : String(error)})`);
+        throw new FabricPreconditionError(`Not a valid X25519 public key (${error instanceof Error ? error.message : String(error)})`);
     }
     // A public key of the wrong curve would still ECDH, just against a key the
     // stage's worker cannot match — the failure would surface as an unopenable
     // secret much later, so refuse it at the point the type is still knowable.
     if (key.asymmetricKeyType !== 'x25519') {
-        throw new Error(`Stage sealing key is ${key.asymmetricKeyType}, expected x25519 — this CLI is too old for it, run \`npm i -g @pikku/cli\``);
+        throw new FabricPreconditionError(`Stage sealing key is ${key.asymmetricKeyType}, expected x25519 — this CLI is too old for it, run \`npm i -g @pikku/cli\``);
     }
     return key;
 }

package/dist/src/fabric/lib/stage.js

@@ -1,3 +1,4 @@
+import { FabricPreconditionError } from './errors.js';
 /**
  * Resolve a stage from (projectId, branch) via the `listStages` RPC. The
  * stageId-based read RPCs (listDeployments, listDeploymentWorkers,
@@ -22,13 +23,13 @@ export async function resolveStage(rpc, projectId, branch) {
         if (stages.length === 1 && only) {
             return { stageId: only.stageId, branch: only.branch };
         }
-        throw new Error(stages.length === 0
+        throw new FabricPreconditionError(stages.length === 0
             ? 'No stages deployed for this project yet — run `pikku fabric deploy apply <branch>` first.'
             : `--branch is required — this project has ${stages.length} stages: ${known.join(', ')}`);
     }
     const stage = stages.find((s) => s.branch === branch);
     if (!stage) {
-        throw new Error(`No stage for branch "${branch}".${known.length ? ` Existing: ${known.join(', ')}` : ''}`);
+        throw new FabricPreconditionError(`No stage for branch "${branch}".${known.length ? ` Existing: ${known.join(', ')}` : ''}`);
     }
     return { stageId: stage.stageId, branch: stage.branch };
 }

package/dist/src/functions/commands/deploy-apply.js

@@ -254,6 +254,7 @@ export const deployApply = pikkuSessionlessFunc({
             getEntryContext,
             frontend: config.frontend,
             outDir: config.outDir,
+            srcDirectories: config.srcDirectories,
             debugArtifacts: data?.debugArtifacts ?? false,
             logger,
             bundler,

package/dist/src/functions/commands/deploy-plan.js

@@ -63,6 +63,7 @@ export const deployPlan = pikkuSessionlessFunc({
             getEntryContext,
             frontend: config.frontend,
             outDir: config.outDir,
+            srcDirectories: config.srcDirectories,
             debugArtifacts: data?.debugArtifacts ?? false,
             logger,
             bundler,

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

@@ -30,8 +30,11 @@ export const watch = pikkuSessionlessFunc({
                     });
                 }
                 catch (err) {
-                    console.error(err);
-                    logger.error('Error running watch');
+                    // Through the logger, so it obeys --log-level and the dev server's
+                    // formatting. `console.error(err)` printed a bare stack over the top
+                    // of the watch output no matter what verbosity was asked for.
+                    logger.error(`Error running watch: ${err instanceof Error ? err.message : String(err)}`);
+                    logger.debug(err instanceof Error ? (err.stack ?? '') : String(err));
                 }
             };
             // A codegen pass holds a whole ts.Program, so two overlapping passes double

package/dist/src/functions/db/sqlite/scenario-baseline.js

@@ -6,6 +6,11 @@ export async function captureSqliteScenarioBaseline(resolved, { keep = [] }) {
     const shouldKeep = keepMatcher(keep);
     const withDb = (run) => {
         const db = runtime.open(resolved.dbFile);
+        // The app under test is still connected to this file. A rollback-journal
+        // database gives a writer an exclusive lock, so without a timeout the first
+        // statement that overlaps one of the app's reads fails outright with
+        // SQLITE_BUSY and takes the scenario with it.
+        db.exec('PRAGMA busy_timeout = 10000');
         try {
             return run(db);
         }

package/dist/src/functions/wirings/agent/serialize-public-agent.js

@@ -203,6 +203,7 @@ export const agentRoutes = defineHTTPRoutes({
       route: '${globalHTTPPrefix}/rpc/agent/:agentName/stream',
       method: 'post',
       sse: true,
+      streamProtocol: 'agui',
       func: agentStreamCaller,
     },
     agentApprove: {
@@ -214,6 +215,7 @@ export const agentRoutes = defineHTTPRoutes({
       route: '${globalHTTPPrefix}/rpc/agent/:agentName/resume',
       method: 'post',
       sse: true,
+      streamProtocol: 'agui',
       func: agentResumeCaller,
     },
   },

package/dist/src/functions/wirings/cli/serialize-channel-cli-client.js

@@ -112,6 +112,7 @@ export function serializeChannelCLIClient(programName, programMeta, clientFile,
         : '';
     return `
 import { executeRawCLIViaChannel } from '@pikku/core/cli/channel'
+import { formatCLIError, wantsStackTrace } from '@pikku/core/cli'
 import type { CorePikkuCLIClientRender } from '@pikku/core/cli/channel'
 import type { Capabilities } from '@pikku/core/channel'
 import { CorePikkuWebsocket } from '@pikku/websocket'
@@ -218,12 +219,25 @@ if (isDirectExecution) {
     ws = new WebSocket(url)
   }
 
+  // Whatever comes back is printed the way the rest of the CLI prints errors:
+  // a deliberate error as its message, anything unexpected with its stack, and
+  // either with a stack under --verbose / PIKKU_DEBUG.
+  const reportFatal = (error: unknown): void => {
+    // stderr is asynchronous when it is a pipe, so exiting on the next line can
+    // truncate the diagnostic. Exit from the write callback, with exitCode set
+    // first in case the stream is already gone and the callback never fires.
+    process.exitCode = 1
+    process.stderr.write(
+      formatCLIError(error, { verbose: wantsStackTrace(process.argv.slice(2)) }) + '\\n',
+      () => process.exit(1)
+    )
+  }
+  process.on('uncaughtException', reportFatal)
+  process.on('unhandledRejection', reportFatal)
+
   ${capitalizedName}CLIClient(ws, process.argv.slice(2))
     .then((exitCode) => process.exit(exitCode))
-    .catch(error => {
-      console.error('Fatal channel CLI error:', error)
-      process.exit(1)
-    })
+    .catch(reportFatal)
 }
 `;
 }

package/dist/src/functions/wirings/cli/serialize-local-cli-bootstrap.js

@@ -14,7 +14,7 @@ export function serializeLocalCLIBootstrap(programName, _programMeta, bootstrapF
         : null;
     const cliBootstrapPath = getFileImportRelativePath(bootstrapFile, config.bootstrapFile, config.packageMappings);
     return `
-import { executeCLI, CLIError } from '@pikku/core/cli'
+import { executeCLI, CLIError, formatCLIError, wantsStackTrace } from '@pikku/core/cli'
 ${pikkuConfigFactory ? `import { ${pikkuConfigFactory.variable} as createConfig } from '${pikkuConfigPath}'` : ''}
 import { ${singletonServicesFactory.variable} as createSingletonServices } from '${singletonServicesPath}'
 ${wireServicesFactory ? `import { ${wireServicesFactory.variable} as createWireServices } from '${wireServicesPath}'` : ''}
@@ -44,10 +44,21 @@ export default ${capitalizedName}CLI
 ${DIRECT_EXECUTION_GUARD}
 
 if (isDirectExecution) {
-  ${capitalizedName}CLI(process.argv.slice(2)).catch(error => {
-    console.error('Fatal error:', error.message)
-    process.exit(1)
-  })
+  const reportFatal = (error: unknown): void => {
+    // executeCLI already printed a CLIError; it carries the exit code, not text.
+    if (error instanceof CLIError) process.exit(error.exitCode)
+    // stderr is asynchronous when it is a pipe, so exiting on the next line can
+    // truncate the diagnostic. Exit from the write callback, with exitCode set
+    // first in case the stream is already gone and the callback never fires.
+    process.exitCode = 1
+    process.stderr.write(
+      formatCLIError(error, { verbose: wantsStackTrace(process.argv.slice(2)) }) + '\\n',
+      () => process.exit(1)
+    )
+  }
+  process.on('uncaughtException', reportFatal)
+  process.on('unhandledRejection', reportFatal)
+  ${capitalizedName}CLI(process.argv.slice(2)).catch(reportFatal)
 }
 `;
 }

package/dist/src/functions/wirings/functions/pikku-command-addon-types.js

@@ -5,6 +5,25 @@ import { checkRequiredTypes } from '../../../utils/check-required-types.js';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeAddonInstallTypes, serializeAddonTypes, } from './serialize-addon-types.js';
+/**
+ * The functions each installed addon publishes, by package — what `mcp` on a
+ * `wireAddon` is typed against. A package wired twice contributes the same
+ * names under both namespaces, and a remote addon contributes none: its
+ * functions run on the host, and it is `wireRemoteAddon` that installs it.
+ */
+const addonFunctionNames = (state) => {
+    const names = {};
+    for (const [namespace, decl] of state.rpc.wireAddonDeclarations) {
+        if (decl.remote) {
+            continue;
+        }
+        const meta = state.addonFunctions[namespace];
+        if (meta) {
+            names[decl.package] = Object.keys(meta);
+        }
+    }
+    return names;
+};
 export const pikkuAddonTypes = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }, input) => {
         const { addonTypesFile, addonSetupTypesFile, packageMappings, servicesFile, secretsFile, credentialsFile, variablesFile, } = config;
@@ -15,14 +34,16 @@ export const pikkuAddonTypes = pikkuSessionlessFunc({
         await rm(config.addon ? addonTypesFile : addonSetupTypesFile, {
             force: true,
         });
-        // An application installs addons; an addon package declares itself. Both
-        // halves are static, so the app half needs no inspector pass and is written
-        // on the bootstrap run as readily as on the full one.
+        const bootstrap = input?.bootstrap === true;
+        // An application installs addons; an addon package declares itself. The app
+        // half is written on the bootstrap run too — `wireAddon` has to resolve
+        // before the inspector can read the calls that say which addons are
+        // installed — but only the full run knows what each addon publishes, so
+        // that is when `mcp` gets its names.
         if (!config.addon) {
-            await writeFileInDir(logger, addonTypesFile, serializeAddonInstallTypes());
+            await writeFileInDir(logger, addonTypesFile, serializeAddonInstallTypes(bootstrap ? {} : addonFunctionNames(await getInspectorState())));
             return;
         }
-        const bootstrap = input?.bootstrap === true;
         if (bootstrap) {
             await writeFileInDir(logger, addonSetupTypesFile, 'export {}\n');
             return;

package/dist/src/functions/wirings/functions/serialize-addon-types.d.ts

@@ -10,5 +10,5 @@
  * `#pikku/addon/<leaf>` — a depth at which an application has nothing to match,
  * leaving the resolver to fall back to Node's per-package `imports`.
  */
-export declare const serializeAddonInstallTypes: () => string;
+export declare const serializeAddonInstallTypes: (addonFunctionNames?: Record<string, string[]>) => string;
 export declare const serializeAddonTypes: (singletonServicesTypeImport: string, singletonServicesTypeName: string, configTypeImport: string, requiredServicesTypeImport: string, typedSecretServiceImport: string, typedVariablesServiceImport: string, typedCredentialServiceImport?: string | null) => string;

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

@@ -10,12 +10,57 @@
  * `#pikku/addon/<leaf>` — a depth at which an application has nothing to match,
  * leaving the resolver to fall back to Node's per-package `imports`.
  */
-export const serializeAddonInstallTypes = () => `/**
+export const serializeAddonInstallTypes = (addonFunctionNames = {}) => {
+    const packages = Object.entries(addonFunctionNames).filter(([, names]) => names.length > 0);
+    // Nothing installed yet — the bootstrap run writes this before any addon's
+    // metadata has been read, and a project with no addons never gets more.
+    if (packages.length === 0) {
+        return `/**
  * Installing an addon into this application
  */
 
 export { wireAddon, wireRemoteAddon } from '@pikku/core/addon'
 `;
+    }
+    const entries = packages
+        .map(([pkg, names]) => `  ${JSON.stringify(pkg)}: ${names
+        .map((name) => JSON.stringify(name))
+        .join(' | ')}`)
+        .join('\n');
+    return `/**
+ * Installing an addon into this application
+ */
+
+import { wireAddon as wireAddonCore } from '@pikku/core/addon'
+import type { WireAddonConfig } from '@pikku/core/addon'
+
+export { wireRemoteAddon } from '@pikku/core/addon'
+
+/**
+ * The functions each installed addon publishes. \`mcp\` names them.
+ */
+type AddonFunctions = {
+${entries}
+}
+
+type AddonFunctionName<Package extends string> =
+  Package extends keyof AddonFunctions ? AddonFunctions[Package] : string
+
+/**
+ * Installs an addon into this project: its functions, wirings and scopes become
+ * part of the app, under the namespace and options given here.
+ *
+ * \`mcp: true\` offers every function the addon itself declared as a tool; a list
+ * names the functions to offer, checked against the ones the addon publishes.
+ */
+export const wireAddon = <Package extends string>(
+  config: Omit<WireAddonConfig, 'package' | 'mcp'> & {
+    package: Package
+    mcp?: boolean | AddonFunctionName<Package>[]
+  }
+): void => wireAddonCore(config)
+`;
+};
 export const serializeAddonTypes = (singletonServicesTypeImport, singletonServicesTypeName, configTypeImport, requiredServicesTypeImport, typedSecretServiceImport, typedVariablesServiceImport, typedCredentialServiceImport = null) => {
     return `/**
  * Addon package types for pikkuAddonConfig and pikkuAddonServices

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

@@ -44,7 +44,9 @@ const generateArgumentsFromSchema = async (inputSchema, schemaDirectory, typesMa
     }
     catch (e) {
         logger.warn(`Command MCP: Could not load schema for type: ${uniqueName} from ${schemaPath}`);
-        console.error(e);
+        // The warning above is the actionable half; the cause is detail, and detail
+        // belongs behind the verbosity control rather than on everyone's stderr.
+        logger.debug(e instanceof Error ? (e.stack ?? e.message) : String(e));
         return [];
     }
 };

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

@@ -13,10 +13,22 @@ export const pikkuMiddleware = pikkuSessionlessFunc({
         const hasDefinitions = Object.keys(state.middleware.definitions).length > 0;
         const hasChannelMiddleware = state.channelMiddleware.tagMiddleware.size > 0 ||
             Object.keys(state.channelMiddleware.definitions).length > 0;
+        // A project whose only middleware is `addGlobalMiddleware([...])` over
+        // middleware defined in a package (a session bridge, say) has no group and
+        // no local definition, and used to generate no middleware file at all — so
+        // the registration never ran.
+        // `globalFiles` is the current record, but the serializer also still reads
+        // `global:*` out of `instances` so that a state serialized by an older
+        // inspector keeps working. This gate decides whether the serializer runs at
+        // all, so it has to accept exactly what the serializer accepts — otherwise
+        // an older state is dropped here and the file it needed is never written.
+        const hasGlobalMiddleware = (state.middleware.globalFiles?.size ?? 0) > 0 ||
+            Object.keys(state.middleware.instances).some((id) => id.startsWith('global:'));
         if (hasHTTPGroups ||
             hasTagGroups ||
             hasDefinitions ||
-            hasChannelMiddleware) {
+            hasChannelMiddleware ||
+            hasGlobalMiddleware) {
             const metaData = state.middlewareGroupsMeta;
             await writeFileInDir(logger, config.middlewareGroupsMetaJsonFile, JSON.stringify(metaData, null, 2));
             await writeFileInDir(logger, middlewareFile, serializeMiddlewareImports(middlewareFile, middleware, state.http, packageMappings, state));

package/dist/src/functions/wirings/middleware/serialize-middleware-imports.d.ts

@@ -1,2 +1,15 @@
 import type { InspectorMiddlewareState, InspectorHTTPState, InspectorState } from '@pikku/inspector';
 export declare const serializeMiddlewareImports: (outputPath: string, middlewareState: InspectorMiddlewareState, httpState: InspectorHTTPState, packageMappings?: Record<string, string>, fullState?: InspectorState) => string;
+/**
+ * Fail the build if a file that calls `addGlobalMiddleware` has no side-effect
+ * import in the generated middleware file.
+ *
+ * Auth commonly lives in global middleware, and a deployed unit that misses its
+ * import does not fail to build — it serves every authenticated route a 401
+ * with a clean build log. Checking the emitted text (rather than the set it was
+ * built from) is what makes this a check and not a restatement: it fails if the
+ * emit is ever dropped, put behind a condition, or handed a path the import
+ * list does not actually carry. It cannot fire on a build that does emit the
+ * import.
+ */
+export declare const assertGlobalMiddlewareImported: (outputPath: string, output: string, globalImportPaths: Map<string, string>) => void;

package/dist/src/functions/wirings/middleware/serialize-middleware-imports.js

@@ -54,21 +54,34 @@ export const serializeMiddlewareImports = (outputPath, middlewareState, httpStat
     // Global middleware (addGlobalMiddleware) is registered by a top-level call
     // at module evaluation, so a side-effect import of its source file runs the
     // registration. Unlike tag/http middleware it has no associated wire group —
-    // it lives only in `instances` keyed `global:*` — so the per-unit `--names`
-    // filter leaves it out of every deployed unit (the `state.http.files`
-    // fallback that add-middleware adds gets stripped by that filter). Emitting
-    // it here, into the always-bootstrap-imported pikku-middleware.gen.ts,
-    // guarantees global middleware registers in every unit. A duplicate import
-    // in full builds is harmless — module bodies evaluate once.
+    // the inspector records it as a source file in `globalFiles` (and as
+    // `global:*` entries in `instances`) — so the per-unit `--names` filter
+    // leaves it out of every deployed unit (the `state.http.files` fallback that
+    // add-middleware adds gets stripped by that filter). Emitting it here, into
+    // the always-bootstrap-imported pikku-middleware.gen.ts, guarantees global
+    // middleware registers in every unit. A duplicate import in full builds is
+    // harmless — module bodies evaluate once.
     //
     // `isFactoryCall` is not consulted: it distinguishes `mw()` from `mw` as an
     // array element, not a deferred registration behind an exported factory, and
     // addGlobalMiddleware registers at module evaluation under either form.
+    //
+    // `globalFiles` is the primary source: it is a plain set of file names, where
+    // `instances` is a map whose keys an unrelated registration could once
+    // collide with. The `global:*` sweep stays as well, so a state serialized by
+    // an older inspector (no `globalFiles`) still emits its imports.
+    const globalSourceFiles = new Set(middlewareState.globalFiles ?? []);
     for (const [instanceId, instance] of Object.entries(middlewareState.instances)) {
         if (instanceId.startsWith('global:')) {
-            directImports.add(getFileImportRelativePath(outputPath, instance.sourceFile, packageMappings));
+            globalSourceFiles.add(instance.sourceFile);
         }
     }
+    const globalImportPaths = new Map();
+    for (const sourceFile of globalSourceFiles) {
+        const filePath = getFileImportRelativePath(outputPath, sourceFile, packageMappings);
+        globalImportPaths.set(sourceFile, filePath);
+        directImports.add(filePath);
+    }
     const allFactories = new Map([
         ...httpFactories,
         ...tagFactories,
@@ -90,5 +103,32 @@ export const serializeMiddlewareImports = (outputPath, middlewareState, httpStat
             serializedFactoryCalls.push(`${exportName}()`);
         }
     }
-    return [...serializedImports, ...serializedFactoryCalls].join('\n');
+    const output = [...serializedImports, ...serializedFactoryCalls].join('\n');
+    assertGlobalMiddlewareImported(outputPath, output, globalImportPaths);
+    return output;
+};
+/**
+ * Fail the build if a file that calls `addGlobalMiddleware` has no side-effect
+ * import in the generated middleware file.
+ *
+ * Auth commonly lives in global middleware, and a deployed unit that misses its
+ * import does not fail to build — it serves every authenticated route a 401
+ * with a clean build log. Checking the emitted text (rather than the set it was
+ * built from) is what makes this a check and not a restatement: it fails if the
+ * emit is ever dropped, put behind a condition, or handed a path the import
+ * list does not actually carry. It cannot fire on a build that does emit the
+ * import.
+ */
+export const assertGlobalMiddlewareImported = (outputPath, output, globalImportPaths) => {
+    const missing = [...globalImportPaths.entries()].filter(([, filePath]) => !output.includes(`import '${filePath}'`));
+    if (missing.length === 0) {
+        return;
+    }
+    throw new Error(`Global middleware would not be registered in ${outputPath}.\n` +
+        `These files call addGlobalMiddleware() but no side-effect import for them was emitted:\n` +
+        missing.map(([sourceFile]) => `  - ${sourceFile}`).join('\n') +
+        `\n\nGlobal middleware — auth gates included — only runs if its module is imported, so ` +
+        `this build would start up with it silently missing. Re-run \`pikku all\`; if it persists, ` +
+        `register the middleware from a file that also makes a wire registration ` +
+        `(e.g. addHTTPMiddleware) and report this as a pikku bug.`);
 };

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

@@ -1,9 +1,14 @@
+import { PikkuError } from '@pikku/core/errors';
 /**
- * A config that was found and parsed, but says something impossible.
+ * A config that was found and parsed, but says something impossible — or one
+ * that could not be found at all.
  *
  * Its message reaches the developer verbatim — every other error out of the
  * loader is reported as "failed to load", which sends the reader hunting for a
- * broken file rather than the line that is wrong.
+ * broken file rather than the line that is wrong. A `PikkuError`, so the CLI
+ * prints that message alone: a stack through the config loader is never the
+ * answer to "which line of my config is wrong", and `--verbose` / `PIKKU_DEBUG`
+ * still shows it for the times it is.
  */
-export declare class PikkuCLIConfigError extends Error {
+export declare class PikkuCLIConfigError extends PikkuError {
 }

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

@@ -1,9 +1,14 @@
+import { PikkuError } from '@pikku/core/errors';
 /**
- * A config that was found and parsed, but says something impossible.
+ * A config that was found and parsed, but says something impossible — or one
+ * that could not be found at all.
  *
  * Its message reaches the developer verbatim — every other error out of the
  * loader is reported as "failed to load", which sends the reader hunting for a
- * broken file rather than the line that is wrong.
+ * broken file rather than the line that is wrong. A `PikkuError`, so the CLI
+ * prints that message alone: a stack through the config loader is never the
+ * answer to "which line of my config is wrong", and `--verbose` / `PIKKU_DEBUG`
+ * still shows it for the times it is.
  */
-export class PikkuCLIConfigError extends Error {
+export class PikkuCLIConfigError extends PikkuError {
 }

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

@@ -56,7 +56,7 @@ async function findConfigFileOrNull() {
 async function findConfigFile() {
     const configFile = await findConfigFileOrNull();
     if (!configFile) {
-        throw new Error('Config file pikku.config.json not found');
+        throw new PikkuCLIConfigError('No Pikku config file (pikku.config.ts, .js or .json) found in this directory or any parent up to the repository root.\nRun this from inside a pikku project, or create one with `pikku init`.');
     }
     return configFile;
 }