@pikku/cli 0.12.152 → 0.12.153

package/dist/src/functions/examples/run.js

@@ -0,0 +1,242 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { EXAMPLES } from '../../examples.gen.js';
+import { entityNames, extractExampleApi, extractTeaching, renameActorsInCode, renameEntityInCode, renameEntityInPath, requiredChain, reservedEntityCollision, resolveExamplePath, scenarioRpcNames, splitExampleFiles, stripTeaching, } from './corpus.js';
+import { entityWriteCoverage, generatedTables, nearestTable, personaCast, registeredRpcs, resolveAppBase, } from './project.js';
+const summary = (example) => ({
+    name: example.name,
+    title: example.title,
+    when: example.when,
+    lang: example.lang,
+    entity: example.entity,
+    deferUntil: example.deferUntil,
+});
+export function runExamplesList(group) {
+    const examples = group
+        ? EXAMPLES.filter((e) => e.name.startsWith(group))
+        : [...EXAMPLES];
+    return { examples: examples.map(summary) };
+}
+/** The project's own source directory a backend recipe's files are rebased onto. */
+function functionsDirOf(project) {
+    const first = project.srcDirectories[0];
+    if (!first)
+        return 'src';
+    const rel = first.startsWith(project.rootDir)
+        ? first.slice(project.rootDir.length).replace(/^[/\\]/, '')
+        : first;
+    return rel.replace(/\\/g, '/').replace(/^\.\//, '') || 'src';
+}
+export function runExamplesShow(project, name, entity) {
+    const empty = {
+        name,
+        title: '',
+        when: '',
+        source: '',
+        steps: '',
+        code: '',
+        notes: [],
+        available: EXAMPLES.map((e) => e.name),
+    };
+    const found = EXAMPLES.find((e) => e.name === name);
+    if (!found)
+        return { found: false, ...empty };
+    const from = found.entity ? entityNames(found.entity) : null;
+    const to = entity ? entityNames(entity) : null;
+    const cast = personaCast(project.srcDirectories);
+    const applyRename = (body) => renameActorsInCode(from && to ? renameEntityInCode(body, from, to) : body, cast);
+    return {
+        found: true,
+        ...empty,
+        title: found.title,
+        when: found.when,
+        source: found.source,
+        steps: found.steps ? applyRename(found.steps) : '',
+        code: applyRename(stripTeaching(found.content)),
+        notes: extractTeaching(found.content).map((note) => ({
+            anchor: note.anchor ? applyRename(note.anchor) : null,
+            lines: note.lines.map(applyRename),
+        })),
+    };
+}
+/** `ProductsComment` → `products_comment`, the name its migration has to declare. */
+function snakeTable(pascal) {
+    return pascal.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+}
+/**
+ * The tables a file needs but this project has not generated zod for.
+ *
+ * The entity gate covers the table the example was asked for. A recipe may also reach for
+ * a CHILD of it, and that table exists in no project until someone writes its migration.
+ * Written anyway, both its imports resolve to `any` and codegen dies naming the file.
+ */
+function missingTables(body, tables) {
+    if (!tables || tables.length === 0)
+        return [];
+    const imported = /import\s*\{([^}]+)\}\s*from\s*'#pikku\/db\/zod\.gen\.js'/.exec(body)?.[1];
+    if (!imported)
+        return [];
+    const wanted = new Set(imported
+        .split(',')
+        .map((name) => name
+        .trim()
+        .split(/\s+as\s+/)[0]
+        .replace(/(InsertZ|PatchZ|Z)$/, ''))
+        .filter(Boolean));
+    return [...wanted].filter((table) => !tables.includes(table));
+}
+const blank = (name, entity) => ({
+    ok: false,
+    name,
+    entity,
+    refusal: '',
+    written: [],
+    kept: [],
+    failed: [],
+    deferred: [],
+    manual: [],
+    api: [],
+    when: '',
+    steps: '',
+    notes: [],
+});
+const refuse = (name, entity, refusal) => ({
+    ...blank(name, entity),
+    refusal,
+});
+export function runExamplesAdd(project, name, entity, app) {
+    const found = EXAMPLES.find((e) => e.name === name);
+    if (!found) {
+        return refuse(name, entity ?? '', `No example named "${name}". Run \`pikku examples\` to see what there is.`);
+    }
+    // A pacing precondition, declared by the recipe rather than configured here: an app
+    // whose schema promises tables nobody can create or edit yet does not need an AI
+    // surface on top of it. Fails open when there is no schema to measure against.
+    if (found.deferUntil === 'entity-write') {
+        const { required, uncovered } = entityWriteCoverage(project.rootDir, project.srcDirectories);
+        if (required.length > 0 && uncovered.length === required.length) {
+            return refuse(name, entity ?? '', `"${name}" declares \`deferUntil: entity-write\`, and none of the ${required.length} table(s) this app's own migrations declare (${required.join(', ')}) has a create or edit path yet. Build one vertical's list + create + edit against a real \`insertInto\`/\`updateTable\` first, then run this again.`);
+        }
+    }
+    if (found.entity && !entity) {
+        return refuse(name, '', `"${name}" is written for an example \`${found.entity}\`, and is useless until it is renamed. Run it again with the domain word you mean: \`pikku examples add --name ${name} --entity <name>\`. It then writes its files already named for that entity.`);
+    }
+    const collision = entity ? reservedEntityCollision(entity) : null;
+    if (collision) {
+        return refuse(name, entity ?? '', `"${entity}" is reserved — it collides with ${collision}, and the rename would write a table that clobbers it. Use the domain word you actually mean.`);
+    }
+    const target = resolveAppBase(project.rootDir, app);
+    if (!target) {
+        return refuse(name, entity ?? '', `There is no app called "${app}" under apps/. Drop --app to write into the primary one.`);
+    }
+    const from = found.entity ? entityNames(found.entity) : null;
+    const to = entity ? entityNames(entity) : null;
+    const cast = personaCast(project.srcDirectories);
+    const renameCode = (body) => renameActorsInCode(from && to ? renameEntityInCode(body, from, to) : body, cast);
+    const renamePath = (path) => from && to ? renameEntityInPath(path, from, to) : path;
+    const code = stripTeaching(found.content);
+    const tables = code.includes('zod.gen')
+        ? generatedTables(project.outDir)
+        : null;
+    if (to && tables && tables.length > 0 && !tables.includes(to.pascal)) {
+        const near = nearestTable(to.pascal, tables);
+        const shown = tables
+            .slice(0, 25)
+            .map((t) => t[0].toLowerCase() + t.slice(1));
+        return refuse(name, entity ?? '', `"${name}" builds its schemas from the \`${to.pascal}\` table zod, and this project has no such table — every one of its imports would resolve to \`any\` and fail codegen.\n` +
+            (near
+                ? `Did you mean \`--entity ${near[0].toLowerCase() + near.slice(1)}\`?`
+                : `Tables it does have: ${shown.join(', ')}${tables.length > shown.length ? `, +${tables.length - shown.length} more` : ''}.\nUse one of those, or write the migration for "${to.camel}" first and run \`pikku db migrate\`.`));
+    }
+    // A scenario is the one family that is a FORWARD reference: its steps name RPCs at the
+    // type level, so a step naming one nobody has written is a type error the instant the
+    // file lands — and while codegen is red nothing written afterwards registers.
+    const wantedRpcs = scenarioRpcNames(renameCode(code));
+    if (wantedRpcs.length > 0) {
+        const registered = registeredRpcs(project.outDir);
+        const missing = wantedRpcs.filter((rpc) => !registered.includes(rpc));
+        if (registered.length > 0 && missing.length > 0) {
+            const shown = registered.slice(0, 25);
+            return refuse(name, entity ?? '', `"${name}" writes steps that call ${missing.map((r) => `\`${r}\``).join(', ')}, and this project has no such rpc. A scenario names its rpcs at the TYPE level, so the file would fail codegen the moment it lands.\n` +
+                `Build the journey first, then come back for the scenario that proves it.\n` +
+                `Rpcs it has today: ${shown.join(', ')}${registered.length > shown.length ? `, +${registered.length - shown.length} more` : ''}.`);
+        }
+    }
+    const functionsDir = functionsDirOf(project);
+    const { install: requiredNames, manual } = requiredChain(found.name, EXAMPLES);
+    const requiredEntries = requiredNames
+        .map((n) => EXAMPLES.find((e) => e.name === n))
+        .filter((e) => e !== undefined);
+    // Renamed AFTER the split, never before: a marker line and a body line want opposite
+    // precedence for a one-word example, and renaming the whole blob first settles that the
+    // wrong way for every destination path.
+    const ownFiles = splitExampleFiles(code).map((f) => ({
+        ...f,
+        path: renamePath(f.path),
+        body: renameCode(f.body),
+    }));
+    // A recipe with no `// ===== FILE:` marker has no ONE true destination — where a config
+    // block or an auth hook belongs depends on the app. Those are read, not written.
+    if (ownFiles.length === 0) {
+        return refuse(name, entity ?? '', `"${name}" names no destination file — where it goes depends on how this app is laid out, so writing it would be a guess. Read it with \`pikku examples show --name ${name}${entity ? ` --entity ${entity}` : ''}\` and put it where it belongs.`);
+    }
+    const result = blank(name, entity ?? '');
+    const install = (files) => {
+        for (const file of files) {
+            const absent = missingTables(file.body, tables);
+            if (absent.length > 0) {
+                result.deferred.push({
+                    path: file.path,
+                    tables: absent.map(snakeTable),
+                });
+                continue;
+            }
+            const relative = resolveExamplePath(file.path, target.base, functionsDir);
+            const destination = join(project.rootDir, relative);
+            // Never clobber: a file the caller has since customised stays theirs, which is what
+            // makes it safe to run this twice.
+            if (existsSync(destination) && !file.overwrite) {
+                if (!result.kept.includes(relative) &&
+                    !result.written.includes(relative)) {
+                    result.kept.push(relative);
+                }
+                continue;
+            }
+            try {
+                mkdirSync(dirname(destination), { recursive: true });
+                writeFileSync(destination, file.body);
+                result.written.push(relative);
+            }
+            catch (err) {
+                result.failed.push(`${relative} (${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
+    };
+    const requiredFiles = requiredEntries.flatMap((e) => splitExampleFiles(stripTeaching(e.content)));
+    install(requiredFiles);
+    install(ownFiles);
+    const usable = new Set([...result.written, ...result.kept]);
+    result.api = [
+        ...requiredEntries.flatMap((e) => splitExampleFiles(e.content)),
+        ...splitExampleFiles(found.content).map((f) => ({
+            path: renamePath(f.path),
+            body: renameCode(f.body),
+        })),
+    ]
+        .map((f) => ({
+        path: resolveExamplePath(f.path, target.base, functionsDir),
+        body: f.body,
+    }))
+        .filter((f) => usable.has(f.path) && !f.path.includes('.stories.'))
+        .map((f) => ({ path: f.path, ...extractExampleApi(f.body) }))
+        .filter((f) => f.exports.length > 0);
+    result.manual = manual;
+    result.when = found.when;
+    result.steps = found.steps ? renameCode(found.steps) : '';
+    result.notes = extractTeaching(found.content).map((note) => ({
+        anchor: note.anchor ? renameCode(note.anchor) : null,
+        lines: note.lines.map(renameCode),
+    }));
+    result.ok = result.failed.length === 0;
+    return result;
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export declare const ExamplesListInput: z.ZodObject<{
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ExamplesListOutput: z.ZodObject<{
+    examples: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodString;
+        when: z.ZodString;
+        lang: z.ZodString;
+        entity: z.ZodString;
+        deferUntil: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ExamplesShowInput: z.ZodObject<{
+    name: z.ZodString;
+    entity: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ExamplesShowOutput: z.ZodObject<{
+    found: z.ZodBoolean;
+    name: z.ZodString;
+    title: z.ZodString;
+    when: z.ZodString;
+    source: z.ZodString;
+    steps: z.ZodString;
+    code: z.ZodString;
+    notes: z.ZodArray<z.ZodObject<{
+        anchor: z.ZodNullable<z.ZodString>;
+        lines: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    available: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const ExamplesAddInput: z.ZodObject<{
+    name: z.ZodString;
+    entity: z.ZodOptional<z.ZodString>;
+    app: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ExamplesAddOutput: z.ZodObject<{
+    ok: z.ZodBoolean;
+    name: z.ZodString;
+    entity: z.ZodString;
+    refusal: z.ZodString;
+    written: z.ZodArray<z.ZodString>;
+    kept: z.ZodArray<z.ZodString>;
+    failed: z.ZodArray<z.ZodString>;
+    deferred: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        tables: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    manual: z.ZodArray<z.ZodString>;
+    api: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        exports: z.ZodArray<z.ZodString>;
+        declarations: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    when: z.ZodString;
+    steps: z.ZodString;
+    notes: z.ZodArray<z.ZodObject<{
+        anchor: z.ZodNullable<z.ZodString>;
+        lines: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExamplesListResult = z.infer<typeof ExamplesListOutput>;
+export type ExamplesShowResult = z.infer<typeof ExamplesShowOutput>;
+export type ExamplesAddResult = z.infer<typeof ExamplesAddOutput>;

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

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+/**
+ * The `pikku examples` schemas, declared here rather than beside the wired functions.
+ *
+ * The CLI bootstraps with the PUBLISHED inspector, which has to be able to IMPORT the
+ * schema a command declares. A command file imports `#pikku`, which points at build
+ * output that does not exist yet while the bootstrap is running — so a schema the
+ * inspector must read cannot live in one. Same reason the knowledge schemas sit in their
+ * own file.
+ */
+const ExampleSummary = z.object({
+    name: z.string(),
+    title: z.string(),
+    when: z.string(),
+    lang: z.string(),
+    entity: z.string(),
+    deferUntil: z.string(),
+});
+export const ExamplesListInput = z.object({
+    group: z
+        .string()
+        .optional()
+        .describe('Only the examples whose name starts with this, e.g. `scenario`'),
+});
+export const ExamplesListOutput = z.object({
+    examples: z.array(ExampleSummary),
+});
+export const ExamplesShowInput = z.object({
+    name: z.string(),
+    entity: z
+        .string()
+        .optional()
+        .describe("Rewrite the example's domain symbol into this one before printing"),
+});
+export const ExamplesShowOutput = z.object({
+    found: z.boolean(),
+    name: z.string(),
+    title: z.string(),
+    when: z.string(),
+    source: z.string(),
+    steps: z.string(),
+    code: z.string(),
+    notes: z.array(z.object({ anchor: z.string().nullable(), lines: z.array(z.string()) })),
+    available: z.array(z.string()),
+});
+export const ExamplesAddInput = z.object({
+    name: z.string(),
+    entity: z
+        .string()
+        .optional()
+        .describe("The domain symbol to rename the example's own onto"),
+    app: z
+        .string()
+        .optional()
+        .describe('Which frontend a screen belongs to, for a project with more than one'),
+});
+export const ExamplesAddOutput = z.object({
+    ok: z.boolean(),
+    name: z.string(),
+    entity: z.string(),
+    /** Why nothing was written. A refusal is the whole answer; every other field is empty. */
+    refusal: z.string(),
+    written: z.array(z.string()),
+    kept: z.array(z.string()),
+    failed: z.array(z.string()),
+    deferred: z.array(z.object({ path: z.string(), tables: z.array(z.string()) })),
+    manual: z.array(z.string()),
+    api: z.array(z.object({
+        path: z.string(),
+        exports: z.array(z.string()),
+        declarations: z.array(z.string()),
+    })),
+    when: z.string(),
+    steps: z.string(),
+    notes: z.array(z.object({ anchor: z.string().nullable(), lines: z.array(z.string()) })),
+});

package/dist/src/functions/surface/render-surface-doc.js

@@ -172,11 +172,41 @@ const renderSymbol = (symbol, leaf, home, ai) => {
     }
     return lines.join('\n').trimEnd();
 };
+/**
+ * Words in an identifier, however it was spelled: `PikkuScenarioWire` and
+ * `pikku-scenario-wire` both come back as pikku, scenario, wire.
+ */
+const words = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+/**
+ * A guessed name is almost never a substring of a real one — `PikkuScenarioWire`
+ * is contained in nothing, so whole-string matching offered no suggestion in the
+ * one case a suggestion is worth anything. Rank by shared words instead, which
+ * puts `PikkuBrowserWire` and `TypedScenario` in front of that guess.
+ */
 const near = (target, candidates) => {
     const needle = target.toLowerCase();
+    const wanted = new Set(words(target));
     return candidates
-        .filter((candidate) => candidate.toLowerCase().includes(needle))
-        .slice(0, 5);
+        .map((candidate) => {
+        const own = words(candidate);
+        const shared = own.filter((word) => wanted.has(word)).length;
+        const contains = candidate.toLowerCase().includes(needle);
+        return {
+            candidate,
+            score: shared + (contains ? wanted.size : 0),
+            extra: own.length - shared,
+        };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score ||
+        a.extra - b.extra ||
+        a.candidate.localeCompare(b.candidate))
+        .slice(0, 5)
+        .map((entry) => entry.candidate);
 };
 export const renderSurfaceDoc = (doc, { target, ai = false, entryPoint = 'app' } = {}) => {
     const leaves = appEntryPoint(doc, entryPoint).leaves;