@pikku/cli 0.12.128 → 0.12.133

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

@@ -4,9 +4,9 @@
  * Runs: analyze → per-unit codegen → entry generation → bundle → configs
  * Outputs everything to .deploy/<provider>/ without deploying.
  */
-import { join } from 'node:path';
-import { existsSync } from 'node:fs';
-import { mkdir, writeFile, copyFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { cp, mkdir, writeFile, copyFile } from 'node:fs/promises';
 import { PikkuError } from '@pikku/core/errors';
 import { analyzeDeployment } from './analyzer/index.js';
 import { withoutScenarios } from '../functions/wirings/scenarios/scenario-partition.js';
@@ -61,6 +61,88 @@ function findLockfile(projectDir) {
     }
     return 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 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.
+ *
+ * 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.
+ *
+ * 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) {
+    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;
+    if (!engine)
+        return undefined;
+    await cp(join(projectDir, 'db', engine), 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');
+    if (!existsSync(coercionFile))
+        return { engine };
+    let rel = relative(unitDir, coercionFile).replace(/\\/g, '/');
+    if (!rel.startsWith('.'))
+        rel = `./${rel}`;
+    return { engine, coercionImportPath: rel.replace(/\.ts$/, '.js') };
+}
+/**
+ * The app's server lifecycle, for entries that can call it.
+ *
+ * The hooks are resolved to an import rather than read at build time because
+ * they are the app's own code and have to run in the app's own process, with
+ * the services that process built.
+ */
+function resolveLifecycle(unitDir, state) {
+    const factory = state.filesAndMethods.serverLifecycleFactory;
+    if (!factory)
+        return undefined;
+    let rel = relative(unitDir, factory.file).replace(/\\/g, '/');
+    if (!rel.startsWith('.'))
+        rel = `./${rel}`;
+    return {
+        importPath: rel.replace(/\.tsx?$/, '.js'),
+        variable: factory.variable,
+    };
+}
 export async function runBuildPipeline(options) {
     const { projectDir, projectId, provider, inspectorState, getEntryContext, debugArtifacts, logger, bundler, } = options;
     const deployDir = options.deployDir ?? join(projectDir, '.deploy');
@@ -115,6 +197,9 @@ export async function runBuildPipeline(options) {
         const ctx = {
             ...getEntryContext(unitDir, pikkuDir, singleUnit, inspectorState),
             frontend: frontendMount,
+            version: resolveProjectVersion(projectDir),
+            db: await resolveStandaloneDb(projectDir, pikkuDir, unitDir),
+            lifecycle: resolveLifecycle(unitDir, inspectorState),
         };
         const source = provider.generateEntrySource(ctx);
         const entryPath = join(unitDir, 'entry.ts');
@@ -228,7 +313,10 @@ export async function runBuildPipeline(options) {
             const unitDir = unit.target === 'server' ? containerDir : join(unitsDir, unit.name);
             const entryPath = join(unitDir, 'entry.ts');
             await mkdir(unitDir, { recursive: true });
-            const ctx = getEntryContext(unitDir, pikkuDir, unit, inspectorState);
+            const ctx = {
+                ...getEntryContext(unitDir, pikkuDir, unit, inspectorState),
+                lifecycle: resolveLifecycle(unitDir, inspectorState),
+            };
             const source = unit.target === 'server'
                 ? (provider.generateServerEntrySource?.(ctx) ??
                     generateServerEntrySource(ctx))

package/dist/src/deploy/codegen/per-unit-codegen.d.ts

@@ -42,6 +42,16 @@ export interface PerUnitCodegenResult {
         error: string;
     }>;
 }
+/**
+ * Collect the full set of filter names for a deployment unit.
+ *
+ * The --names filter matches against different identifier types depending
+ * on the metadata being filtered (function names, agent names, channel
+ * names, etc.).  For a unit to get its complete metadata, we need to
+ * include both the function IDs and any wiring-level names (e.g. agent
+ * names, channel names) that reference those functions.
+ */
+export declare function collectFilterNames(unit: DeploymentUnit, manifest: DeploymentManifest, inspectorState: InspectorState, workflowQueues: boolean): string[];
 /**
  * Runs filtered codegen for each deployment unit.
  *

package/dist/src/deploy/codegen/per-unit-codegen.js

@@ -34,7 +34,7 @@ function resolvePikkuBin() {
  * include both the function IDs and any wiring-level names (e.g. agent
  * names, channel names) that reference those functions.
  */
-function collectFilterNames(unit, manifest, inspectorState, workflowQueues) {
+export function collectFilterNames(unit, manifest, inspectorState, workflowQueues) {
     const names = new Set(unit.functionIds);
     // Include catch-all scaffold routes based on unit contents
     const functionsMeta = inspectorState.functions.meta;
@@ -103,6 +103,17 @@ function collectFilterNames(unit, manifest, inspectorState, workflowQueues) {
                 if (handler.type === 'scheduled')
                     names.add(handler.taskName);
             }
+            // `runAgent(...)` / `rpc.agent.run(...)` look the agent up in the
+            // in-process registry, so a function that calls one needs the agent's
+            // wiring — and its tools — bundled into its OWN unit, not just into
+            // the agent gateway unit.
+            for (const agentName of unit.invokedAgents ?? []) {
+                names.add(agentName);
+                const agentDef = manifest.agents.find((a) => a.name === agentName);
+                for (const id of agentDef?.toolFunctionIds ?? [])
+                    names.add(id);
+                names.add('/rpc/:rpcName');
+            }
             // Function units with workflow-state capability (workflow-starter,
             // workflow-runner, workflow-status-checker) call rpc.startWorkflow
             // and look workflows up by name in the registry. The registry is

package/dist/src/deploy/server-entry.js

@@ -18,6 +18,11 @@ export function generateServerEntrySource(ctx) {
         ctx.configImport,
         ctx.servicesImport,
         ctx.mcpImport,
+        ...(ctx.lifecycle
+            ? [
+                `import { ${ctx.lifecycle.variable} as __pikkuLifecycle } from '${ctx.lifecycle.importPath}'`,
+            ]
+            : []),
         `import '${ctx.bootstrapPath}'`,
         ``,
         `const PORT = Number(process.env.PORT ?? 8080)`,
@@ -33,9 +38,17 @@ export function generateServerEntrySource(ctx) {
         `    singletonServices.logger,`,
         `    { ${ctx.mcpServerOption}}`,
         `  )`,
-        `  server.enableExitOnSignals()`,
+        `  server.enableExitOnSignals(${ctx.lifecycle
+            ? `{ beforeStop: () => __pikkuLifecycle?.beforeStop?.(singletonServices), afterStop: () => __pikkuLifecycle?.afterStop?.(singletonServices) }`
+            : ''})`,
         `  await server.init()`,
+        ...(ctx.lifecycle
+            ? [`  await __pikkuLifecycle?.beforeStart?.(singletonServices)`]
+            : []),
         `  await server.start()`,
+        ...(ctx.lifecycle
+            ? [`  await __pikkuLifecycle?.afterStart?.(singletonServices)`]
+            : []),
         `}`,
         ``,
         `main().catch((err) => {`,

package/dist/src/functions/commands/knowledge-plan.d.ts

@@ -0,0 +1,112 @@
+import { renderKnowledgePlanDefer, renderKnowledgePlanProgress, renderKnowledgePlanSchema, renderKnowledgePlanSet, renderKnowledgePlanShow } from '../knowledge/render.js';
+export declare const knowledgePlanSchema: import("#pikku/function").PikkuFunctionConfig<Record<string, never>, {
+    schema: string;
+}, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<Record<string, never>, {
+    schema: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<Record<string, never>, {
+    schema: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const knowledgePlanShow: import("#pikku/function").PikkuFunctionConfig<{
+    milestone: string;
+    forBuild?: boolean | undefined;
+}, {
+    ok: boolean;
+    path: string;
+    body: string;
+}, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
+    milestone: string;
+    forBuild?: boolean | undefined;
+}, {
+    ok: boolean;
+    path: string;
+    body: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
+    milestone: string;
+    forBuild?: boolean | undefined;
+}, {
+    ok: boolean;
+    path: string;
+    body: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const knowledgePlanProgress: import("#pikku/function").PikkuFunctionConfig<{
+    milestone: string;
+}, {
+    ok: boolean;
+    path: string;
+    message: string;
+    done: string[];
+    missing: string[];
+    deferred: string[];
+    problems: string[];
+}, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
+    milestone: string;
+}, {
+    ok: boolean;
+    path: string;
+    message: string;
+    done: string[];
+    missing: string[];
+    deferred: string[];
+    problems: string[];
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
+    milestone: string;
+}, {
+    ok: boolean;
+    path: string;
+    message: string;
+    done: string[];
+    missing: string[];
+    deferred: string[];
+    problems: string[];
+}, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const knowledgePlanSet: import("#pikku/function").PikkuFunctionConfig<{
+    milestone: string;
+    file: string;
+}, {
+    ok: boolean;
+    path: string;
+    problems: string[];
+    schema?: string | undefined;
+}, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
+    milestone: string;
+    file: string;
+}, {
+    ok: boolean;
+    path: string;
+    problems: string[];
+    schema?: string | undefined;
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
+    milestone: string;
+    file: string;
+}, {
+    ok: boolean;
+    path: string;
+    problems: string[];
+    schema?: string | undefined;
+}, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const knowledgePlanDefer: import("#pikku/function").PikkuFunctionConfig<{
+    milestone: string;
+    item: string;
+    reason: string;
+}, {
+    ok: boolean;
+    path: string;
+    message: string;
+}, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
+    milestone: string;
+    item: string;
+    reason: string;
+}, {
+    ok: boolean;
+    path: string;
+    message: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
+    milestone: string;
+    item: string;
+    reason: string;
+}, {
+    ok: boolean;
+    path: string;
+    message: string;
+}, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export { renderKnowledgePlanDefer, renderKnowledgePlanProgress, renderKnowledgePlanSchema, renderKnowledgePlanSet, renderKnowledgePlanShow, };

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

@@ -0,0 +1,35 @@
+import { pikkuSessionlessFunc } from '#pikku/function';
+import { runKnowledgePlanDefer, runKnowledgePlanProgress, runKnowledgePlanSchema, runKnowledgePlanSet, runKnowledgePlanShow, } from '@pikku/knowledge';
+import { renderKnowledgePlanDefer, renderKnowledgePlanProgress, renderKnowledgePlanSchema, renderKnowledgePlanSet, renderKnowledgePlanShow, } from '../knowledge/render.js';
+import { KnowledgePlanDeferInputSchema, KnowledgePlanDeferOutputSchema, KnowledgePlanProgressInputSchema, KnowledgePlanProgressOutputSchema, KnowledgePlanSchemaInputSchema, KnowledgePlanSchemaOutputSchema, KnowledgePlanSetInputSchema, KnowledgePlanSetOutputSchema, KnowledgePlanShowInputSchema, KnowledgePlanShowOutputSchema, } from '../knowledge/schemas.js';
+export const knowledgePlanSchema = pikkuSessionlessFunc({
+    description: 'Print the plan schema, so a plan is written against what is actually enforced rather than guessed at.',
+    input: KnowledgePlanSchemaInputSchema,
+    output: KnowledgePlanSchemaOutputSchema,
+    func: async () => runKnowledgePlanSchema(),
+});
+export const knowledgePlanShow = pikkuSessionlessFunc({
+    description: "Print a milestone's plan, either as it is stored or as the ordered list of work a build follows.",
+    input: KnowledgePlanShowInputSchema,
+    output: KnowledgePlanShowOutputSchema,
+    func: async ({ config }, input) => runKnowledgePlanShow(config.rootDir, input),
+});
+export const knowledgePlanProgress = pikkuSessionlessFunc({
+    description: "Reconcile a milestone's plan against the generated meta and say what is still owed, so a milestone closes on what exists rather than on what was claimed.",
+    input: KnowledgePlanProgressInputSchema,
+    output: KnowledgePlanProgressOutputSchema,
+    func: async ({ config }, input) => runKnowledgePlanProgress(config.rootDir, input),
+});
+export const knowledgePlanSet = pikkuSessionlessFunc({
+    description: 'Validate a plan against its milestone note and write it, or write nothing and say what is wrong.',
+    input: KnowledgePlanSetInputSchema,
+    output: KnowledgePlanSetOutputSchema,
+    func: async ({ config }, input) => runKnowledgePlanSet(config.rootDir, input),
+});
+export const knowledgePlanDefer = pikkuSessionlessFunc({
+    description: 'Move one first-pass item to the next pass with the reason on the record, so it stops blocking the milestone.',
+    input: KnowledgePlanDeferInputSchema,
+    output: KnowledgePlanDeferOutputSchema,
+    func: async ({ config }, input) => runKnowledgePlanDefer(config.rootDir, input),
+});
+export { renderKnowledgePlanDefer, renderKnowledgePlanProgress, renderKnowledgePlanSchema, renderKnowledgePlanSet, renderKnowledgePlanShow, };

package/dist/src/functions/db/local-db.d.ts

@@ -1,5 +1,5 @@
 import { Kysely } from 'kysely';
-import { type MigrateResult } from './db-migrator.js';
+import { type MigrateResult } from '@pikku/migrator-sql';
 import type { ColumnInfo } from './db-introspector.js';
 import { type CodegenResult } from './db-codegen.js';
 import { type ZodCodegenResult } from './zod-codegen.js';

package/dist/src/functions/db/local-db.js

@@ -5,18 +5,18 @@ import { pathToFileURL } from 'node:url';
 import { runInNewContext } from 'node:vm';
 import { transformSync } from 'esbuild';
 import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely';
-import { migrate, baselineMigrations, } from './db-migrator.js';
+import { migrate, baselineMigrations, } from '@pikku/migrator-sql';
 import { applyPikkuSchemas, compilePikkuSchemas, pikkuSchemas, requiredPikkuSchemas, resolveRequirements, createCoercionPlugin, } from '@pikku/kysely';
 import { loadAuthOptions, getAuthMigrations } from './better-auth-schema.js';
 import { generateSchemaTypes } from './db-codegen.js';
 import { generateZodTypes } from './zod-codegen.js';
-import { tableCreationSql } from './schema-sql.js';
-import { SqliteMigrationExecutor } from './sqlite/sqlite-migrator.js';
+import { tableCreationSql } from '@pikku/migrator-sql';
+import { SqliteMigrationExecutor } from '@pikku/migrator-sql/sqlite';
 import { SqliteIntrospector } from './sqlite/sqlite-introspector.js';
 import { createSqliteKysely } from './sqlite/sqlite-kysely.js';
-import { loadSqliteRuntime } from './sqlite/sqlite-runtime.js';
+import { loadSqliteRuntime } from '@pikku/migrator-sql/sqlite';
 import { devSeed as runDevSeed } from './sqlite/dev-seed.js';
-import { PostgresMigrationExecutor } from './postgres/postgres-migrator.js';
+import { PostgresMigrationExecutor } from '@pikku/migrator-sql/postgres';
 import { createPGliteKysely } from './postgres/pglite-kysely.js';
 import { PostgresIntrospector } from './postgres/postgres-introspector.js';
 // ─── Resolution ───────────────────────────────────────────────────────────────

package/dist/src/functions/db/postgres/postgres-introspector.js

@@ -1,5 +1,5 @@
 import { Pool } from 'pg';
-import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
+import { MIGRATION_TRACKING_TABLE } from '@pikku/migrator-sql';
 import { parseCheckEnumValues } from '../check-enums.js';
 /** Table display name matching `listTables` (schema-qualified unless `public`). */
 function tableKey(schema, table) {

package/dist/src/functions/db/sqlite/dev-seed.d.ts

@@ -1,4 +1,4 @@
-import type { SyncSqliteDatabase } from './sqlite-runtime.js';
+import type { SyncSqliteDatabase } from '@pikku/migrator-sql/sqlite';
 export interface DevSeedResult {
     applied: boolean;
     bytes: number;

package/dist/src/functions/db/sqlite/sqlite-introspector.d.ts

@@ -1,5 +1,5 @@
 import type { DbIntrospector, ColumnInfo, ForeignKeyInfo, EnumInfo } from '../db-introspector.js';
-import type { SyncSqliteDatabase } from './sqlite-runtime.js';
+import type { SyncSqliteDatabase } from '@pikku/migrator-sql/sqlite';
 export declare class SqliteIntrospector implements DbIntrospector {
     private readonly db;
     constructor(db: SyncSqliteDatabase);

package/dist/src/functions/db/sqlite/sqlite-introspector.js

@@ -1,4 +1,4 @@
-import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
+import { MIGRATION_TRACKING_TABLE } from '@pikku/migrator-sql';
 import { parseCheckEnumsFromDdl } from '../check-enums.js';
 const SKIP_TABLES = new Set(['sqlite_sequence', MIGRATION_TRACKING_TABLE]);
 export class SqliteIntrospector {

package/dist/src/functions/db/sqlite/sqlite-kysely.d.ts

@@ -1,5 +1,5 @@
 import { Kysely, type KyselyPlugin } from 'kysely';
-import type { SyncSqliteDatabase } from './sqlite-runtime.js';
+import type { SyncSqliteDatabase } from '@pikku/migrator-sql/sqlite';
 export interface CreateSqliteKyselyOptions {
     db: SyncSqliteDatabase;
     camelCase?: boolean;

package/dist/src/functions/knowledge/render.d.ts

@@ -1,3 +1,8 @@
-import type { KnowledgeIndexResult, KnowledgeValidateResult } from '@pikku/knowledge';
+import type { KnowledgeIndexResult, KnowledgePlanDeferResult, KnowledgePlanProgressResult, KnowledgePlanSchemaResult, KnowledgePlanSetResult, KnowledgePlanShowResult, KnowledgeValidateResult } from '@pikku/knowledge';
 export declare const renderKnowledgeValidate: (_services: unknown, { ok, notes, findings }: KnowledgeValidateResult) => void;
 export declare const renderKnowledgeIndex: (_services: unknown, { ok, check, files }: KnowledgeIndexResult) => void;
+export declare const renderKnowledgePlanSchema: (_services: unknown, { schema }: KnowledgePlanSchemaResult) => void;
+export declare const renderKnowledgePlanShow: (_services: unknown, { ok, path, body }: KnowledgePlanShowResult) => void;
+export declare const renderKnowledgePlanProgress: (_services: unknown, { ok, path, message, done, missing, deferred, problems, }: KnowledgePlanProgressResult) => void;
+export declare const renderKnowledgePlanSet: (_services: unknown, { ok, path, problems, schema }: KnowledgePlanSetResult) => void;
+export declare const renderKnowledgePlanDefer: (_services: unknown, { ok, message }: KnowledgePlanDeferResult) => void;

package/dist/src/functions/knowledge/render.js

@@ -64,3 +64,77 @@ export const renderKnowledgeIndex = (_services, { ok, check, files }) => {
             process.exitCode = 1;
     }
 };
+export const renderKnowledgePlanSchema = (_services, { schema }) => {
+    console.log(schema);
+};
+export const renderKnowledgePlanShow = (_services, { ok, path, body }) => {
+    if (!ok) {
+        console.log(`${removed('✗')}  ${body}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(dim(path));
+    console.log(body);
+};
+const list = (label, entries, colour) => {
+    if (entries.length === 0)
+        return;
+    console.log(colour(`${label} (${entries.length})`));
+    for (const entry of entries)
+        console.log(`   ${entry}`);
+    console.log();
+};
+export const renderKnowledgePlanProgress = (_services, { ok, path, message, done, missing, deferred, problems, }) => {
+    if (message) {
+        console.log(`${removed('✗')}  ${message}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(dim(path));
+    console.log();
+    list('DONE', done, added);
+    list('MISSING', missing, removed);
+    list('DEFERRED to a later pass', deferred, dim);
+    list('PROBLEMS', problems, changed);
+    console.log('─'.repeat(40));
+    if (ok) {
+        console.log(`${added('✓')}  the plan's first pass is built`);
+        return;
+    }
+    if (missing.length > 0) {
+        console.log(`${removed('✗')}  the milestone is not built yet — build each missing item, or move it out with ` +
+            dim('pikku knowledge plan defer <milestone> <item> -r "<why>"'));
+    }
+    // A problem is something that EXISTS and does not do what was planned, so there is
+    // nothing to defer — saying "defer it" here sends the reader to a command that will
+    // refuse them.
+    if (problems.length > 0) {
+        console.log(`${removed('✗')}  the milestone is not built yet — fix what the problems above name. ` +
+            dim('A problem is never deferred; the thing exists, it just does something else.'));
+    }
+    // A build closes a milestone on this exit code, so it has to be readable by a shell
+    // and not only by whoever is reading the output.
+    process.exitCode = 1;
+};
+export const renderKnowledgePlanSet = (_services, { ok, path, problems, schema }) => {
+    if (ok) {
+        console.log(`${added('✓')}  plan written to ${path}`);
+        console.log(dim('the build is measured against it'));
+        return;
+    }
+    console.log(`${removed('✗')}  not written:`);
+    for (const problem of problems) {
+        console.log(`   ${problem}`);
+    }
+    if (schema) {
+        console.log();
+        console.log(dim('the schema, in full — build the plan to match it:'));
+        console.log(schema);
+    }
+    process.exitCode = 1;
+};
+export const renderKnowledgePlanDefer = (_services, { ok, message }) => {
+    console.log(`${ok ? added('✓') : removed('✗')}  ${message}`);
+    if (!ok)
+        process.exitCode = 1;
+};

package/dist/src/functions/knowledge/schemas.d.ts

@@ -49,3 +49,48 @@ export declare const KnowledgeValidateOutputSchema: import("zod").ZodObject<{
         fixHint: import("zod").ZodString;
     }, import("zod/v4/core").$strip>>;
 }, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanSchemaInputSchema: import("zod").ZodObject<{}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanSchemaOutputSchema: import("zod").ZodObject<{
+    schema: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanProgressInputSchema: import("zod").ZodObject<{
+    milestone: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanProgressOutputSchema: import("zod").ZodObject<{
+    ok: import("zod").ZodBoolean;
+    path: import("zod").ZodString;
+    message: import("zod").ZodString;
+    done: import("zod").ZodArray<import("zod").ZodString>;
+    missing: import("zod").ZodArray<import("zod").ZodString>;
+    deferred: import("zod").ZodArray<import("zod").ZodString>;
+    problems: import("zod").ZodArray<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanShowInputSchema: import("zod").ZodObject<{
+    milestone: import("zod").ZodString;
+    forBuild: import("zod").ZodOptional<import("zod").ZodBoolean>;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanShowOutputSchema: import("zod").ZodObject<{
+    ok: import("zod").ZodBoolean;
+    path: import("zod").ZodString;
+    body: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanSetInputSchema: import("zod").ZodObject<{
+    milestone: import("zod").ZodString;
+    file: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanSetOutputSchema: import("zod").ZodObject<{
+    ok: import("zod").ZodBoolean;
+    path: import("zod").ZodString;
+    problems: import("zod").ZodArray<import("zod").ZodString>;
+    schema: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanDeferInputSchema: import("zod").ZodObject<{
+    milestone: import("zod").ZodString;
+    item: import("zod").ZodString;
+    reason: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export declare const KnowledgePlanDeferOutputSchema: import("zod").ZodObject<{
+    ok: import("zod").ZodBoolean;
+    path: import("zod").ZodString;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;

package/dist/src/functions/knowledge/schemas.js

@@ -1,4 +1,4 @@
-import { KnowledgeIndexInput, KnowledgeIndexOutput, KnowledgeValidateInput, KnowledgeValidateOutput, } from '@pikku/knowledge';
+import { KnowledgeIndexInput, KnowledgeIndexOutput, KnowledgePlanDeferInput, KnowledgePlanDeferOutput, KnowledgePlanProgressInput, KnowledgePlanProgressOutput, KnowledgePlanSchemaInput, KnowledgePlanSchemaOutput, KnowledgePlanSetInput, KnowledgePlanSetOutput, KnowledgePlanShowInput, KnowledgePlanShowOutput, KnowledgeValidateInput, KnowledgeValidateOutput, } from '@pikku/knowledge';
 /**
  * The knowledge command schemas, re-bound to variables declared HERE rather than
  * imported straight into the command files.
@@ -23,3 +23,13 @@ export const KnowledgeIndexInputSchema = KnowledgeIndexInput;
 export const KnowledgeIndexOutputSchema = KnowledgeIndexOutput;
 export const KnowledgeValidateInputSchema = KnowledgeValidateInput;
 export const KnowledgeValidateOutputSchema = KnowledgeValidateOutput;
+export const KnowledgePlanSchemaInputSchema = KnowledgePlanSchemaInput;
+export const KnowledgePlanSchemaOutputSchema = KnowledgePlanSchemaOutput;
+export const KnowledgePlanProgressInputSchema = KnowledgePlanProgressInput;
+export const KnowledgePlanProgressOutputSchema = KnowledgePlanProgressOutput;
+export const KnowledgePlanShowInputSchema = KnowledgePlanShowInput;
+export const KnowledgePlanShowOutputSchema = KnowledgePlanShowOutput;
+export const KnowledgePlanSetInputSchema = KnowledgePlanSetInput;
+export const KnowledgePlanSetOutputSchema = KnowledgePlanSetOutput;
+export const KnowledgePlanDeferInputSchema = KnowledgePlanDeferInput;
+export const KnowledgePlanDeferOutputSchema = KnowledgePlanDeferOutput;