@pikku/cli 0.12.152 → 0.12.154

package/dist/.pikku/scopes/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/scopes` resolves here.

package/dist/.pikku/scopes/pikku-flags.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * This file was generated by the @pikku/cli

package/dist/.pikku/scopes/pikku-personas.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * This file was generated by the @pikku/cli

package/dist/.pikku/scopes/pikku-roles.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * This file was generated by the @pikku/cli

package/dist/.pikku/scopes/pikku-scope-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 export { defineScope } from '@pikku/core/scope';
 export { defineSystemRole } from '@pikku/core/role';

package/dist/.pikku/scopes/pikku-scope-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 export { defineScope } from '@pikku/core/scope';
 export { defineSystemRole } from '@pikku/core/role';

package/dist/.pikku/scopes/pikku-scopes.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * This file was generated by the @pikku/cli

package/dist/.pikku/secrets/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/secrets` resolves here.

package/dist/.pikku/secrets/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/secrets` resolves here.

package/dist/.pikku/secrets/pikku-secret-types.gen.d.ts

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 export { defineSecret } from '@pikku/core/secret';

package/dist/.pikku/secrets/pikku-secret-types.gen.js

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 export { defineSecret } from '@pikku/core/secret';

package/dist/.pikku/secrets/pikku-secrets.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { TypedSecretService as CoreTypedSecretService } from '@pikku/core/services';
 import type { SecretService } from '@pikku/core/services';

package/dist/.pikku/secrets/pikku-secrets.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { TypedSecretService as CoreTypedSecretService } from '@pikku/core/services';
 /**

package/dist/.pikku/services/pikku-meta-service.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 export declare class PikkuMetaService extends LocalMetaService {

package/dist/.pikku/services/pikku-meta-service.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 export class PikkuMetaService extends LocalMetaService {

package/dist/.pikku/setup/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/setup` resolves here.

package/dist/.pikku/setup/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/setup` resolves here.

package/dist/.pikku/setup/pikku-setup-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Config and service factory definitions, declared once per application

package/dist/.pikku/setup/pikku-setup-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Config and service factory definitions, declared once per application

package/dist/.pikku/trigger/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/trigger` resolves here.

package/dist/.pikku/trigger/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/trigger` resolves here.

package/dist/.pikku/trigger/pikku-trigger-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/trigger/pikku-trigger-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/variables/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/variables` resolves here.

package/dist/.pikku/variables/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/variables` resolves here.

package/dist/.pikku/variables/pikku-variable-types.gen.d.ts

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 export { defineVariable } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variable-types.gen.js

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 export { defineVariable } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variables.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { TypedVariablesService as CoreTypedVariablesService } from '@pikku/core/services';
 import type { VariablesService } from '@pikku/core/services';

package/dist/.pikku/variables/pikku-variables.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { TypedVariablesService as CoreTypedVariablesService, } from '@pikku/core/services';
 /**

package/dist/.pikku/workflow/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/workflow` resolves here.

package/dist/.pikku/workflow/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 /**
  * Subpath entry — `#pikku/workflow` resolves here.

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import type { PikkuWorkflowGraphConfig, PikkuWorkflowGraphResult } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { pikkuWorkflowGraph as corePikkuWorkflowGraph } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { pikkuState } from '@pikku/core/state';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.152
+ * This file was generated by @pikku/cli@0.12.154
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.152') {
-      process.stderr.write(`\n  Update available  0.12.152 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.154') {
+      process.stderr.write(`\n  Update available  0.12.154 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/cli.wiring.js

@@ -33,6 +33,7 @@ import { pikkuAudit } from './functions/commands/audit.js';
 import { pikkuSemver } from './functions/commands/semver.js';
 import { renderSemver } from './functions/commands/semver-render.js';
 import { validate, renderValidate } from './functions/commands/validate.js';
+import { examplesAdd, examplesList, examplesShow, renderExamplesAdd, renderExamplesList, renderExamplesShow, } from './functions/commands/examples.js';
 import { knowledgeValidate, renderKnowledgeValidate, } from './functions/commands/knowledge-validate.js';
 import { knowledgeIndex, renderKnowledgeIndex, } from './functions/commands/knowledge-index.js';
 import { knowledgeReconcile, renderKnowledgeReconcile, } from './functions/commands/knowledge-reconcile.js';
@@ -507,6 +508,56 @@ wireCLI({
                 }),
             },
         },
+        examples: {
+            description: 'Worked examples of the things that are easy to get wrong and hard to discover — read one, or write it into this project already named for your own entity',
+            subcommands: {
+                list: pikkuCLICommand({
+                    func: examplesList,
+                    render: renderExamplesList,
+                    description: 'List every example, with what each one is for',
+                    options: {
+                        group: {
+                            description: 'Only the examples whose name starts with this, e.g. `scenario`',
+                            short: 'g',
+                        },
+                    },
+                }),
+                show: pikkuCLICommand({
+                    func: examplesShow,
+                    render: renderExamplesShow,
+                    description: 'Print one example, renamed onto your own entity, with everything the recipe says about itself',
+                    options: {
+                        name: {
+                            description: 'Which example',
+                            short: 'n',
+                        },
+                        entity: {
+                            description: "The domain symbol to rewrite the example's own onto",
+                            short: 'e',
+                        },
+                    },
+                }),
+                add: pikkuCLICommand({
+                    func: examplesAdd,
+                    render: renderExamplesAdd,
+                    description: 'Write one example into this project, or say what is in the way and write nothing',
+                    options: {
+                        name: {
+                            description: 'Which example',
+                            short: 'n',
+                        },
+                        entity: {
+                            description: "The domain symbol to rename the example's own onto",
+                            short: 'e',
+                        },
+                        app: {
+                            description: 'Which frontend a screen belongs to, for a project with more than one',
+                            short: 'a',
+                        },
+                    },
+                }),
+            },
+        },
         knowledge: {
             description: 'Inspect and maintain the knowledge base — what this app is, in the language its users use',
             subcommands: {

package/dist/src/deploy/build-pipeline.d.ts

@@ -44,6 +44,44 @@ export declare class PikkuDeployBuildFailedError extends PikkuError {
  * when every unit was generated and bundled.
  */
 export declare function describeBuildFailure(result: Pick<BuildPipelineResult, 'bundleErrors' | 'codegenErrors'>): string | null;
+/**
+ * The database a standalone bundle has to open for itself.
+ *
+ * Every other provider deploys onto a host that supplies `kysely` — `pikku dev`
+ * builds one, a Cloudflare deploy binds one — so `createSingletonServices` is
+ * written expecting it. A standalone artifact has no host, and shipped one that
+ * never got a connection at all: the app booted straight into whatever its
+ * services factory does when the database is missing, which for the generated
+ * templates is a throw.
+ *
+ * Engine is resolved the way every other pikku host resolves it: `createConfig`
+ * first, through the same `loadUserConfigForDb` the db commands use, and the
+ * `db/sqlite` / `db/postgres` conventions only as the fallback. Reading the
+ * directory alone left an app that declares its database in config and keeps no
+ * migrations getting a connection under `pikku dev` and none in its artifact —
+ * the same crash, reached a different way. A config that cannot be loaded falls
+ * back to the directories rather than failing the build, because a project with
+ * no database at all must still bundle.
+ *
+ * Both at once is refused rather than resolved, whether the two arrive as two
+ * migration directories or as `sqliteDb` beside `postgresUrl`. Picking one would
+ * be picking which database the deployed app talks to on the strength of
+ * directory order, and the failure — an app running happily against the wrong,
+ * fully valid schema — is invisible until someone reads the data.
+ *
+ * Only the engine travels. A configured SQLite path is a developer's local file
+ * and has no meaning on the target host, which names its own through
+ * `PIKKU_DATA_DIR`.
+ *
+ * The migrations are copied in beside the bundle under the same `db/<engine>/`
+ * path they have in the project, which is also where Fabric's build container
+ * stages them. Two producers writing the artifact cannot disagree about where
+ * the SQL lives, and `bundle.js db migrate` finds it either way.
+ */
+export declare function resolveStandaloneDb(projectDir: string, pikkuDir: string, unitDir: string, srcDirectories: string[], logger: BuildLogger): Promise<{
+    engine: 'sqlite' | 'postgres';
+    coercionImportPath?: string;
+} | undefined>;
 export declare function runBuildPipeline(options: {
     projectDir: string;
     projectId: string;
@@ -66,6 +104,11 @@ export declare function runBuildPipeline(options: {
     };
     deployDir?: string;
     outDir?: string;
+    /**
+     * The project's source roots, for finding the `createConfig` that declares
+     * which database a standalone artifact has to open.
+     */
+    srcDirectories?: string[];
     /** Emit sourcemaps + per-unit `metafile.json` (debug-only). Default false. */
     debugArtifacts?: boolean;
     logger: BuildLogger;

package/dist/src/deploy/build-pipeline.js

@@ -13,6 +13,7 @@ import { withoutScenarios } from '../functions/wirings/scenarios/scenario-partit
 import { generatePerUnitCodegen } from './codegen/per-unit-codegen.js';
 import { materializeFrontend } from './frontend-assets.js';
 import { assertFrontendBuilt } from '../utils/frontend.js';
+import { loadUserConfigForDb, } from '../functions/commands/db-shared.js';
 import { generateServerEntrySource, SERVER_DOCKERFILE, SERVER_DOCKERIGNORE, } from './server-entry.js';
 /**
  * A unit that failed codegen or bundling is an expected build outcome (the
@@ -61,6 +62,44 @@ function findLockfile(projectDir) {
     }
     return null;
 }
+/**
+ * The project's declared version, or nothing.
+ *
+ * Absent is a real answer — a project need not version itself — and is better
+ * reported as unknown than as a number this made up.
+ */
+function resolveProjectVersion(projectDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The project's own database declaration, or nothing it could read.
+ *
+ * A config that throws, or names no `createConfig` at all, is reported as no
+ * declaration rather than as a build failure: it is only ever one of two
+ * signals here, and the directory conventions still answer for a project whose
+ * config needs an environment this build does not have.
+ */
+async function loadConfiguredDb(projectDir, srcDirectories, logger) {
+    try {
+        return await loadUserConfigForDb({
+            config: { rootDir: projectDir, srcDirectories },
+            logger: {
+                error: (msg) => logger.debug(msg),
+                warn: (msg) => logger.debug(msg),
+            },
+        });
+    }
+    catch (error) {
+        logger.debug(`Could not read createConfig to resolve the deploy database: ${error?.message ?? error}`);
+        return null;
+    }
+}
 /**
  * The database a standalone bundle has to open for itself.
  *
@@ -71,49 +110,59 @@ function findLockfile(projectDir) {
  * services factory does when the database is missing, which for the generated
  * templates is a throw.
  *
- * Engine comes from the migrations directory rather than the user config,
- * because that is the same signal `loadUserConfigForDb` falls back to and it
- * needs no module loading here. `db/sqlite` and `db/postgres` are the two
- * conventions the migrator already writes to, so a project declares its engine
- * by having written migrations for it.
+ * Engine is resolved the way every other pikku host resolves it: `createConfig`
+ * first, through the same `loadUserConfigForDb` the db commands use, and the
+ * `db/sqlite` / `db/postgres` conventions only as the fallback. Reading the
+ * directory alone left an app that declares its database in config and keeps no
+ * migrations getting a connection under `pikku dev` and none in its artifact —
+ * the same crash, reached a different way. A config that cannot be loaded falls
+ * back to the directories rather than failing the build, because a project with
+ * no database at all must still bundle.
+ *
+ * Both at once is refused rather than resolved, whether the two arrive as two
+ * migration directories or as `sqliteDb` beside `postgresUrl`. Picking one would
+ * be picking which database the deployed app talks to on the strength of
+ * directory order, and the failure — an app running happily against the wrong,
+ * fully valid schema — is invisible until someone reads the data.
  *
- * Both at once is refused rather than resolved. Picking one would be picking
- * which database the deployed app talks to on the strength of directory order,
- * and the failure — an app running happily against the wrong, fully valid
- * schema — is invisible until someone reads the data.
+ * Only the engine travels. A configured SQLite path is a developer's local file
+ * and has no meaning on the target host, which names its own through
+ * `PIKKU_DATA_DIR`.
  *
  * The migrations are copied in beside the bundle under the same `db/<engine>/`
  * path they have in the project, which is also where Fabric's build container
  * stages them. Two producers writing the artifact cannot disagree about where
  * the SQL lives, and `bundle.js db migrate` finds it either way.
  */
-/**
- * The project's declared version, or nothing.
- *
- * Absent is a real answer — a project need not version itself — and is better
- * reported as unknown than as a number this made up.
- */
-function resolveProjectVersion(projectDir) {
-    try {
-        const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
-        return typeof pkg.version === 'string' ? pkg.version : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function resolveStandaloneDb(projectDir, pikkuDir, unitDir) {
+export async function resolveStandaloneDb(projectDir, pikkuDir, unitDir, srcDirectories, logger) {
     const hasSqlite = existsSync(join(projectDir, 'db', 'sqlite'));
     const hasPostgres = existsSync(join(projectDir, 'db', 'postgres'));
     if (hasSqlite && hasPostgres) {
         throw new Error('This project has both db/sqlite and db/postgres migrations, so a standalone build cannot tell which database the app is meant to open. Keep the one this app deploys against.');
     }
-    const engine = hasSqlite ? 'sqlite' : hasPostgres ? 'postgres' : undefined;
+    const userConfig = await loadConfiguredDb(projectDir, srcDirectories, logger);
+    if (userConfig?.postgresUrl && userConfig?.sqliteDb) {
+        throw new Error('createConfig sets both postgresUrl and sqliteDb, so a standalone build cannot tell which database the app is meant to open. Configure exactly one database dialect.');
+    }
+    const engine = userConfig?.postgresUrl
+        ? 'postgres'
+        : userConfig?.sqliteDb
+            ? 'sqlite'
+            : hasSqlite
+                ? 'sqlite'
+                : hasPostgres
+                    ? 'postgres'
+                    : undefined;
     if (!engine)
         return undefined;
-    await cp(join(projectDir, 'db', engine), join(unitDir, 'db', engine), {
-        recursive: true,
-    });
+    // Absent for a database whose schema is created outside the migrator, which
+    // is a database to connect to rather than a reason to hand the app none.
+    const migrationsDir = join(projectDir, 'db', engine);
+    if (existsSync(migrationsDir)) {
+        await cp(migrationsDir, join(unitDir, 'db', engine), {
+            recursive: true,
+        });
+    }
     // Absent for an app that annotates no columns, which is a database with
     // nothing to coerce rather than a reason to hand the app no database.
     const coercionFile = join(pikkuDir, 'db', 'coercion.gen.ts');
@@ -199,7 +248,7 @@ export async function runBuildPipeline(options) {
             ...getEntryContext(unitDir, pikkuDir, singleUnit, inspectorState),
             frontend: frontendMount,
             version: resolveProjectVersion(projectDir),
-            db: await resolveStandaloneDb(projectDir, pikkuDir, unitDir),
+            db: await resolveStandaloneDb(projectDir, pikkuDir, unitDir, options.srcDirectories ?? ['src'], logger),
             lifecycle: resolveLifecycle(unitDir, inspectorState),
         };
         const source = provider.generateEntrySource(ctx);

package/dist/src/examples.gen.d.ts

@@ -0,0 +1,17 @@
+export interface PikkuExample {
+    name: string;
+    title: string;
+    when: string;
+    lang: string;
+    /** The example domain symbol this recipe spells, which `--entity` renames. */
+    entity: string;
+    /** A precondition the recipe declares, refusing `add` until it holds. */
+    deferUntil: string;
+    requires: string[];
+    /** The follow-up the recipe cannot perform itself, carried to the caller verbatim. */
+    steps: string;
+    /** Where the recipe lives, repo-relative. */
+    source: string;
+    content: string;
+}
+export declare const EXAMPLES: PikkuExample[];