@pikku/cli 0.12.127 → 0.12.133

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/commands/new-addon.d.ts

@@ -28,6 +28,33 @@ export declare function getAddonFiles(vars: AddonVars, flags: {
     delegated?: boolean;
 }): Record<string, string>;
 export declare function getTestFiles(vars: AddonVars): Record<string, string>;
+/**
+ * Does `root`'s `workspaces` field cover `dir`?
+ *
+ * Declaring workspaces is not enough — a root with `packages/*` does not own an
+ * addon written to `addons/crm`, and yarn, npm and pnpm all skip a nested
+ * package they were never told about.
+ */
+export declare function workspaceCovers(root: string, dir: string): boolean;
+/**
+ * An addon that has not been built is dead at runtime.
+ *
+ * The generated package exports `./dist/...` — that is what an installed
+ * consumer resolves, and what the app's own `pikku-bootstrap.gen.ts` imports.
+ * Until `build` has run, every `ref('<addon>:...')` resolves to nothing and the
+ * app fails at boot with PKU340 plus an ERR_MODULE_NOT_FOUND on a dist path
+ * nobody wrote. Nothing about the generated files shows the problem, so the
+ * generator finishes the job: install at the root that owns the lockfile, then
+ * run the addon's own `build` script (whose `prebuild` is `pikku all`).
+ */
+export type AddonBuildRunner = (command: string, args: string[], cwd: string) => {
+    status: number | null;
+    error?: Error;
+};
+export declare const buildGeneratedAddon: (addonDir: string, logger: {
+    info: (message: string) => void;
+    error: (message: string) => void;
+}, run?: AddonBuildRunner) => boolean;
 export declare const pikkuNewAddon: import("#pikku/function").PikkuFunctionConfig<{
     name: string;
     displayName?: string;
@@ -43,6 +70,7 @@ export declare const pikkuNewAddon: import("#pikku/function").PikkuFunctionConfi
     authConfig?: string;
     mcp?: boolean;
     camelCase?: boolean;
+    build?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
     name: string;
     displayName?: string;
@@ -58,6 +86,7 @@ export declare const pikkuNewAddon: import("#pikku/function").PikkuFunctionConfi
     authConfig?: string;
     mcp?: boolean;
     camelCase?: boolean;
+    build?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
     name: string;
     displayName?: string;
@@ -73,4 +102,5 @@ export declare const pikkuNewAddon: import("#pikku/function").PikkuFunctionConfi
     authConfig?: string;
     mcp?: boolean;
     camelCase?: boolean;
+    build?: boolean;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/new-addon.js

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from 'fs';
-import { dirname, join } from 'path';
+import { dirname, join, relative as relativePath, sep } from 'path';
 import { mkdir, writeFile } from 'fs/promises';
+import { spawnSync } from 'node:child_process';
+import { findInstallRoot } from './update.js';
 import { createEmptyManifest, saveManifest, } from '../../utils/contract-versions.js';
 import { pikkuSessionlessFunc } from '#pikku/function';
 import { parseOpenAPISpec, computeContractHash, generateAddonFromOpenAPI, loadAuthConfig, } from '@pikku/openapi-parser';
@@ -159,7 +161,7 @@ export function getAddonFiles(vars, flags) {
         scripts: {
             prepublishOnly: 'yarn build',
             prebuild: 'pikku all',
-            build: 'tsc && cp -r .pikku types dist/',
+            build: 'tsc && pikku dist',
             pikku: 'pikku all',
         },
         peerDependencies: {
@@ -851,8 +853,81 @@ async function writeFiles(baseDir, files) {
     }
     return written;
 }
+/**
+ * Does `root`'s `workspaces` field cover `dir`?
+ *
+ * Declaring workspaces is not enough — a root with `packages/*` does not own an
+ * addon written to `addons/crm`, and yarn, npm and pnpm all skip a nested
+ * package they were never told about.
+ */
+export function workspaceCovers(root, dir) {
+    const relative = relativePath(root, dir).split(sep).join('/');
+    if (relative === '' || relative.startsWith('..')) {
+        return false;
+    }
+    let patterns;
+    try {
+        const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+        patterns = Array.isArray(manifest.workspaces)
+            ? manifest.workspaces
+            : manifest.workspaces?.packages;
+    }
+    catch {
+        return false;
+    }
+    if (!Array.isArray(patterns)) {
+        return false;
+    }
+    return patterns.some((pattern) => {
+        if (typeof pattern !== 'string') {
+            return false;
+        }
+        const source = pattern
+            .split('/')
+            .map((segment) => segment === '**'
+            ? '.*'
+            : segment.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*'))
+            .join('/');
+        return new RegExp(`^${source}$`).test(relative);
+    });
+}
+const spawnAddonBuildStep = (command, args, cwd) => {
+    const { status, error } = spawnSync(command, args, {
+        cwd,
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+    });
+    return { status, error };
+};
+export const buildGeneratedAddon = (addonDir, logger, run = spawnAddonBuildStep) => {
+    const { dir: installDir, packageManager } = findInstallRoot(addonDir);
+    if (packageManager === 'unknown') {
+        logger.error(`Could not tell which package manager owns ${addonDir} — the addon is generated but NOT built. Run install, then the addon's build script, in ${addonDir} before using it.`);
+        return false;
+    }
+    // A root install only reaches the addon when the root's workspace patterns
+    // cover it. A root that owns the lockfile but not this package installs
+    // nothing for it, so its devDependencies — `@pikku/cli` and `typescript`,
+    // which the build script needs — would never arrive.
+    const installIn = workspaceCovers(installDir, addonDir)
+        ? installDir
+        : addonDir;
+    const steps = [
+        [installIn, ['install']],
+        [addonDir, ['run', 'build']],
+    ];
+    for (const [cwd, args] of steps) {
+        logger.info(`${packageManager} ${args.join(' ')} (${cwd})`);
+        const result = run(packageManager, args, cwd);
+        if (result.status !== 0) {
+            logger.error(`${packageManager} ${args.join(' ')} failed in ${cwd}: ${result.error?.message ?? `exit ${result.status}`}`);
+            return false;
+        }
+    }
+    return true;
+};
 export const pikkuNewAddon = pikkuSessionlessFunc({
-    func: async ({ logger, config }, { name, displayName, description, category = 'General', dir, secret = false, variable = false, oauth = false, credential, test = true, openapi, authConfig, mcp = false, camelCase = false, }) => {
+    func: async ({ logger, config }, { name, displayName, description, category = 'General', dir, secret = false, variable = false, oauth = false, credential, test = true, openapi, authConfig, mcp = false, camelCase = false, build = true, }) => {
         name = sanitizeAddonName(name);
         if (!/^[a-z][a-z0-9_-]*$/.test(name)) {
             logger.error(`Invalid addon name "${name}": must start with a lowercase letter and contain only lowercase alphanumerics, hyphens, and underscores`);
@@ -949,6 +1024,9 @@ export const pikkuNewAddon = pikkuSessionlessFunc({
         for (const f of written) {
             logger.debug({ message: `  ${f}`, type: 'success' });
         }
+        if (build && !buildGeneratedAddon(addonDir, logger)) {
+            process.exit(1);
+        }
         console.log(addonDir);
     },
 });

package/dist/src/functions/commands/persona-sync.d.ts

@@ -9,10 +9,11 @@
  * config and write through it, which provisioned a local stage correctly and
  * silently provisioned the wrong database for every other environment.
  *
- * So the deployment provisions itself: an app calls `provisionPersonas` from
- * `@pikku/better-auth` in its server lifecycle, where the database connection
- * and better-auth's own adapter are both already open, and a deploy carries its
- * personas with it. What is left here is the half that needs no database — the
+ * So the deployment provisions itself: an app hands its personas to
+ * `pikkuFabric` from `@pikku/better-auth`, and the plugin creates a missing one
+ * on the operator handshake that asks for it, where the database connection and
+ * better-auth's own adapter are both already open. What is left here is the
+ * half that needs no database — the
  * declaration, and the environment rule applied to it — which is what tells you
  * before a deploy whether the accounts you expect will appear.
  */

package/dist/src/functions/commands/persona-sync.js

@@ -12,10 +12,11 @@ import { resolvePersonas } from '../../utils/resolve-personas.js';
  * config and write through it, which provisioned a local stage correctly and
  * silently provisioned the wrong database for every other environment.
  *
- * So the deployment provisions itself: an app calls `provisionPersonas` from
- * `@pikku/better-auth` in its server lifecycle, where the database connection
- * and better-auth's own adapter are both already open, and a deploy carries its
- * personas with it. What is left here is the half that needs no database — the
+ * So the deployment provisions itself: an app hands its personas to
+ * `pikkuFabric` from `@pikku/better-auth`, and the plugin creates a missing one
+ * on the operator handshake that asks for it, where the database connection and
+ * better-auth's own adapter are both already open. What is left here is the
+ * half that needs no database — the
  * declaration, and the environment rule applied to it — which is what tells you
  * before a deploy whether the accounts you expect will appear.
  */
@@ -65,6 +66,6 @@ export const personaSync = pikkuSessionlessFunc({
         for (const refusal of skipped) {
             logger.info(`  skipped: ${refusal}`);
         }
-        logger.info("  Provisioning runs in the deployment: call `provisionPersonas` from '@pikku/better-auth' in your server lifecycle, passing `personaConfigs` and `personaEnvironments` from the generated personas file.");
+        logger.info("  Provisioning runs in the deployment: pass `personas: { personas: personaConfigs, environments: personaEnvironments }` from the generated personas file to `pikkuFabric` from '@pikku/better-auth'.");
     },
 });

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

@@ -4,6 +4,7 @@ import { pikkuSessionlessFunc } from '#pikku/function';
 import { createHttpPersonas, deriveActorSecret, personaEnvironmentRefusal, roleMismatchMessage, verifyPersonaRoles, } from '@pikku/core/persona';
 import { personaVirtualUserTarget, runVirtualUser, catalogueClassification, DISPOSITIONS, prepareVirtualUserRun, } from '@pikku/core/virtual-user';
 import { getSingletonServices, setSingletonServices } from '@pikku/core/state';
+import { PikkuError } from '@pikku/core/errors';
 import { resolvePersonas } from '../../utils/resolve-personas.js';
 import { ACTOR_SECRET_VARIABLE, PERSONA_SECRETS_VARIABLE, resolvePersonaCredentials, } from '../../utils/persona-credentials.js';
 import { resolveEnvironment } from './environment.js';
@@ -108,7 +109,7 @@ export const personaRun = pikkuSessionlessFunc({
             agentsMeta: state.agents?.agentsMeta ?? {},
         });
         if (catalogue.length === 0) {
-            throw new Error('This project exposes no RPCs, so there is nothing for a virtual user to do.');
+            throw new PikkuError('This project exposes no RPCs, so there is nothing for a virtual user to do.');
         }
         const signedIn = createHttpPersonas({
             apiUrl: env.apiUrl,
@@ -132,7 +133,10 @@ export const personaRun = pikkuSessionlessFunc({
             else {
                 const message = roleMismatchMessage(verifyPersonaRoles(personaId, persona.roles, actual));
                 if (message) {
-                    throw new Error(message);
+                    // A refusal, not a crash: `PikkuError` is what tells the CLI to print
+                    // the message on its own, since the seed drift it names is the whole
+                    // finding and the frames underneath it are noise.
+                    throw new PikkuError(message);
                 }
             }
         }

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;