@pikku/cli 0.12.82 → 0.12.85

package/skills/pikku-software-archaeology/references/pikku-mapping.md

@@ -0,0 +1,49 @@
+# How Pikku Consumes a Product Blueprint
+
+The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pikku primitive. A generator (or an agent following `pikku-feature`) walks the JSON files in this order:
+
+| Blueprint source | Pikku target |
+|---|---|
+| `entities.json` attributes + relationships + constraints | Kysely migrations + generated `DB` types; Zod schemas per entity |
+| `entities.json` states/transitions | a `status` column + transition guards inside the owning commands (or a state-machine helper) |
+| `commands.json` | `pikkuFunc` / `pikkuSessionlessFunc` with `input:` Zod schema built from `input[]`; `preconditions` become guard clauses; name is the camelCased command name (`SendInvoice` → `sendInvoice`) |
+| `queries.json` | `pikkuFunc` reads; `scoping` becomes the mandatory `WHERE` / session filter |
+| `events.json` | EventHub topics (realtime) or queue messages; `consumedBy` become `wireQueueWorker` handlers — implicit events (`explicit: false`) get promoted to real emissions |
+| `policies.json` (authorization) | Pikku `permissions` / middleware; one policy = one named permission function, wired everywhere `enforcedAt` listed — this collapses duplicated legacy checks into a single definition |
+| `policies.json` (validation) | Zod schema refinements on the command's `input` |
+| `workflows.json` kind=user | frontend flows + the commands they chain |
+| `workflows.json` kind=system, with `schedule` | `wireScheduler` entries |
+| `workflows.json` multi-step / checkpointing | `pikkuWorkflowFunc` with one `workflow.do(...)` step per blueprint step |
+| `workflows.json` `scenarios[]` | **`pikkuUserFlow` stories — this is the canonical target.** Each scenario's given/when/outcome maps 1:1 onto a user-flow step sequence; group scenarios by their workflow into one flow per journey. Only scenarios with no user-facing surface (pure system workflows: cron sweeps, webhook ingest) fall back to API/e2e tests |
+| `api.json` | `wireHTTP` routes: keep `path`+`method` for compatibility, point at the mapped command/query func; `auth: none`/capability-URL surfaces get `auth: false` |
+| `api.json` kind=webhook-in | `wireHTTP` with `auth: false` + signature-verification middleware from the integration |
+| `integrations.json` | services in `services.ts` (constructor-injected classes); `configVia` env vars become `wireSecret` / config; per-user credentials become `wireCredential` |
+| `architecture.json` notes | deployment config (ports, raw-body routes, proxy expectations) |
+| `invariants.json` enforcedBy=db-constraint | migration constraints (UNIQUE, CHECK, FK) |
+| `invariants.json` enforcedBy=code-guard/nothing | guard clauses + a test each; `atRiskBecause` entries get a hardening task |
+| `gaps.json` | excluded from generation; `open-product-decision` + `migration.json.decisionsNeeded` go to a human BEFORE generation starts |
+| `migration.json.mappings` | the work plan: one mapping = one migration slice |
+| `interfaces.json` kind=cli | `wireCLI` entrypoints — the CLI commands are the same funcs the routes expose |
+| `interfaces.json` kind=mcp | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates) |
+| `interfaces.json` kind=openapi-rest / sdk | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen |
+| `interfaces.json` kind=websocket-realtime | `pikku-realtime` EventHub topics / channels |
+| `frontend.json` | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react-query` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto |
+| `frontend-routes.json` | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views |
+| `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk |
+| `frontend-components.json` rebuild=`custom-logic` | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items |
+| `frontend-components.json` rebuild=`custom-style` | normalize to Mantine/theme tokens; usually deleted-and-recomposed, not ported |
+
+## Order of generation
+
+1. Human resolves `decisionsNeeded`.
+2. Entities → migrations + types.
+3. Policies → permission functions (before commands, so commands can reference them).
+4. Commands + queries → funcs; api.json → wirings.
+5. Events → topics/queues; system workflows → schedulers/workers/workflows.
+6. Scenarios → tests. Run them against the new implementation; they encode the legacy behavior worth preserving.
+
+## Uncertainty handling
+
+- `confidence: high` concepts generate directly.
+- `confidence: medium` concepts generate, but are listed for review in the pre-generation report — id, evidence summary, and what is uncertain — rather than carrying a marker comment in the generated code. The report is the review surface; the generated code stays clean.
+- `confidence: low` concepts are NOT generated automatically — they surface in the pre-generation review along with `decisionsNeeded`.

package/skills/pikku-software-archaeology/scripts/validate.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Validates a .knowledge/ blueprint directory against references/blueprint.schema.json,
+// then runs cross-file referential checks (does every command's domain exist, does every
+// api surface map to a real command/query, ...). Exit 0 = valid, 1 = errors.
+//
+// Usage: node validate.mjs <path-to-.knowledge-dir>
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const schemaDoc = JSON.parse(readFileSync(join(here, '..', 'references', 'blueprint.schema.json'), 'utf8'));
+
+const dir = process.argv[2];
+if (!dir) { console.error('usage: node validate.mjs <.knowledge dir>'); process.exit(2); }
+
+const errors = [];
+const warnings = [];
+
+// --- minimal JSON-Schema-subset validator (type, required, properties, items, enum, minItems, pattern, $ref -> $defs) ---
+function resolveRef(ref) {
+  const m = /^#\/\$defs\/(\w+)$/.exec(ref);
+  if (!m || !schemaDoc.$defs[m[1]]) throw new Error(`unresolvable $ref ${ref}`);
+  return schemaDoc.$defs[m[1]];
+}
+
+function check(value, schema, path) {
+  if (schema.$ref) schema = { ...resolveRef(schema.$ref), ...schema, $ref: undefined };
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${path}: expected one of [${schema.enum.join(', ')}], got ${JSON.stringify(value)}`);
+    return;
+  }
+  const t = schema.type;
+  if (t === 'object') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      errors.push(`${path}: expected object`); return;
+    }
+    for (const req of schema.required || []) {
+      if (!(req in value)) errors.push(`${path}: missing required field "${req}"`);
+    }
+    for (const [k, v] of Object.entries(value)) {
+      if (schema.properties?.[k]) check(v, schema.properties[k], `${path}.${k}`);
+    }
+  } else if (t === 'array') {
+    if (!Array.isArray(value)) { errors.push(`${path}: expected array`); return; }
+    if (schema.minItems && value.length < schema.minItems) {
+      errors.push(`${path}: needs at least ${schema.minItems} item(s), has ${value.length}`);
+    }
+    if (schema.items) value.forEach((v, i) => check(v, schema.items, `${path}[${i}]`));
+  } else if (t === 'string') {
+    if (typeof value !== 'string') { errors.push(`${path}: expected string`); return; }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${path}: "${value}" does not match ${schema.pattern}`);
+    }
+  } else if (t === 'boolean' && typeof value !== 'boolean') {
+    errors.push(`${path}: expected boolean`);
+  } else if (t === 'number' && typeof value !== 'number') {
+    errors.push(`${path}: expected number`);
+  }
+}
+
+// --- load + per-file validation ---
+// Files marked `x-optional` (the frontend layer) only validate when present, so a
+// backend-only repo does not fail for lacking them.
+const docs = {};
+for (const [filename, fileSchema] of Object.entries(schemaDoc.files)) {
+  const p = join(dir, filename);
+  if (!existsSync(p)) {
+    if (!fileSchema['x-optional']) errors.push(`${filename}: missing`);
+    continue;
+  }
+  try {
+    docs[filename] = JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    errors.push(`${filename}: invalid JSON (${e.message})`); continue;
+  }
+  check(docs[filename], fileSchema, filename);
+}
+if (!existsSync(join(dir, 'blueprint.md'))) errors.push('blueprint.md: missing');
+
+// --- cross-file referential checks ---
+if (docs['domains.json'] && docs['commands.json']) {
+  const domains = new Set((docs['domains.json'].domains || []).map((d) => d.name));
+  const commandNames = new Set((docs['commands.json'].commands || []).map((c) => c.name));
+  const queryNames = new Set((docs['queries.json']?.queries || []).map((q) => q.name));
+  const eventNames = new Set((docs['events.json']?.events || []).map((e) => e.name));
+
+  const wantDomain = (owner, d) => {
+    if (d && !domains.has(d)) errors.push(`${owner}: domain "${d}" not defined in domains.json`);
+  };
+  for (const c of docs['commands.json'].commands || []) {
+    wantDomain(`commands.json:${c.name}`, c.domain);
+    for (const ev of c.eventsProduced || []) {
+      if (!eventNames.has(ev)) warnings.push(`commands.json:${c.name} produces "${ev}" which is not in events.json`);
+    }
+  }
+  for (const q of docs['queries.json']?.queries || []) wantDomain(`queries.json:${q.name}`, q.domain);
+  for (const e of docs['entities.json']?.entities || []) wantDomain(`entities.json:${e.name}`, e.domain);
+  for (const ev of docs['events.json']?.events || []) wantDomain(`events.json:${ev.name}`, ev.domain);
+
+  for (const s of docs['api.json']?.surfaces || []) {
+    const { type, name } = s.mapsTo || {};
+    if (type === 'command' && !commandNames.has(name)) errors.push(`api.json:${s.method || ''} ${s.path}: maps to unknown command "${name}"`);
+    if (type === 'query' && !queryNames.has(name)) errors.push(`api.json:${s.method || ''} ${s.path}: maps to unknown query "${name}"`);
+    if (type === 'event-ingress' && !eventNames.has(name)) errors.push(`api.json:${s.method || ''} ${s.path}: event-ingress maps to unknown event "${name}" (state-changing webhooks should map to a command instead)`);
+  }
+  // every domain's listed concepts should exist
+  for (const d of docs['domains.json'].domains || []) {
+    for (const c of d.commands || []) if (!commandNames.has(c)) warnings.push(`domains.json:${d.name}: lists command "${c}" not in commands.json`);
+    for (const q of d.queries || []) if (!queryNames.has(q)) warnings.push(`domains.json:${d.name}: lists query "${q}" not in queries.json`);
+    for (const e of d.events || []) if (!eventNames.has(e)) warnings.push(`domains.json:${d.name}: lists event "${e}" not in events.json`);
+    const policyNames = new Set((docs['policies.json']?.policies || []).map((p) => p.name));
+    for (const p of d.policies || []) if (!policyNames.has(p)) warnings.push(`domains.json:${d.name}: lists policy "${p}" not in policies.json`);
+  }
+  // commands with no policies and no preconditions are suspicious for mutating ops
+  for (const c of docs['commands.json'].commands || []) {
+    if (!(c.policies || []).length && !(c.preconditions || []).length) {
+      warnings.push(`commands.json:${c.name}: no policies or preconditions — really unguarded, or missed extraction?`);
+    }
+  }
+}
+
+// --- frontend layer cross-checks (only when the optional frontend files exist) ---
+if (docs['frontend-components.json']) {
+  const componentNames = new Set(
+    (docs['frontend-components.json'].components || []).map((c) => c.name),
+  );
+  // routes should reference components that were actually inventoried
+  for (const r of docs['frontend-routes.json']?.routes || []) {
+    for (const c of r.usesComponents || []) {
+      if (!componentNames.has(c)) {
+        warnings.push(`frontend-routes.json:${r.path}: uses component "${c}" not in frontend-components.json`);
+      }
+    }
+  }
+  // a component flagged as needing a port must say WHY (the custom logic), or the
+  // port-risk is unactionable
+  for (const c of docs['frontend-components.json'].components || []) {
+    if (c.rebuild === 'custom-logic' && !c.customLogic) {
+      warnings.push(`frontend-components.json:${c.name}: rebuild=custom-logic but no customLogic description — port risk is unactionable`);
+    }
+  }
+  // data-fetching queries named on routes should resolve to a real query/command
+  if (docs['queries.json'] || docs['commands.json']) {
+    const known = new Set([
+      ...(docs['queries.json']?.queries || []).map((q) => q.name),
+      ...(docs['commands.json']?.commands || []).map((c) => c.name),
+    ]);
+    for (const r of docs['frontend-routes.json']?.routes || []) {
+      for (const d of r.dataFrom || []) {
+        if (!known.has(d)) {
+          warnings.push(`frontend-routes.json:${r.path}: reads "${d}" which is not a known query/command`);
+        }
+      }
+    }
+  }
+}
+
+// an inconsistent UI with no specific design findings = under-extraction
+// (guarded on frontend.json alone — independent of the component inventory)
+if (docs['frontend.json']) {
+  const consistency = docs['frontend.json'].designSystemConsistency;
+  const findingCount = (docs['frontend.json'].designFindings || []).length;
+  if ((consistency === 'mixed' || consistency === 'ad-hoc') && findingCount === 0) {
+    warnings.push(`frontend.json: designSystemConsistency="${consistency}" but designFindings is empty — name the specific broken patterns (interaction/theming/cross-page/…)`);
+  }
+}
+
+for (const w of warnings) console.log(`WARN  ${w}`);
+for (const e of errors) console.log(`ERROR ${e}`);
+console.log(`\n${errors.length} error(s), ${warnings.length} warning(s) across ${Object.keys(docs).length} files`);
+process.exit(errors.length ? 1 : 0);

package/skills/pikku-template-clone/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-template-clone
-description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `pikku create`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
+description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `npm create pikku`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
 allowed-tools: Bash(git status *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *)
 ---
 

package/skills/pikku-trigger/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-trigger
-description: 'Use when adding event-driven functions that respond to system events like Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or custom event sources. Covers wireTrigger, wireTriggerSource, and pikkuTriggerFunc.
-TRIGGER when: code uses wireTrigger/wireTriggerSource/pikkuTriggerFunc, user asks about event-driven functions, Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or reacting to external events.
-DO NOT TRIGGER when: user asks about scheduled tasks (use pikku-cron) or background job queues (use pikku-queue).'
+description: >-
+  Use when adding event-driven functions that respond to system events like Redis pub/sub,
+  PostgreSQL LISTEN/NOTIFY, or custom event sources. Covers wireTrigger, wireTriggerSource, and
+  pikkuTriggerFunc. TRIGGER when: code uses wireTrigger/wireTriggerSource/pikkuTriggerFunc, user
+  asks about event-driven functions, Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or reacting to
+  external events. DO NOT TRIGGER when: user asks about scheduled tasks (use pikku-cron) or
+  background job queues (use pikku-queue).
 installGroups: [core]
 ---
 

package/skills/pikku-versioning/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-versioning
-description: 'Use when versioning Pikku function contracts, detecting breaking changes, or managing API backward compatibility. Covers the version property, versions.pikku.json manifest, contract hashing, and CI integration.
-TRIGGER when: code uses version: on a pikkuFunc, user asks about API versioning, breaking changes, contract hashes, backward compatibility, or "pikku versions" CLI commands.
-DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config) or general function definitions (use pikku-concepts).'
+description: >-
+  Use when versioning Pikku function contracts, detecting breaking changes, or managing API
+  backward compatibility. Covers the version property, versions.pikku.json manifest, contract
+  hashing, and CI integration. TRIGGER when: code uses version: on a pikkuFunc, user asks about
+  API versioning, breaking changes, contract hashes, backward compatibility, or "pikku versions"
+  CLI commands. DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config)
+  or general function definitions (use pikku-concepts).
 installGroups: [core]
 ---
 

package/skills/pikku-websocket/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-websocket
-description: 'Use when adding real-time features, WebSocket channels, live updates, chat, or pub/sub to a Pikku app. Covers wireChannel, action routing, auth, EventHub pub/sub, channel middleware, and generated WebSocket client.
-TRIGGER when: code uses wireChannel, user asks about WebSocket, real-time, live updates, chat, pub/sub, or the generated WebSocket client.
-DO NOT TRIGGER when: user asks about HTTP/REST (use pikku-http), SSE (use pikku-http with sse: true), or WebSocket deployment specifics (use pikku-deploy-uws).'
+description: >-
+  Use when adding real-time features, WebSocket channels, live updates, chat, or pub/sub to a
+  Pikku app. Covers wireChannel, action routing, auth, EventHub pub/sub, channel middleware, and
+  generated WebSocket client. TRIGGER when: code uses wireChannel, user asks about WebSocket,
+  real-time, live updates, chat, pub/sub, or the generated WebSocket client. DO NOT TRIGGER when:
+  user asks about HTTP/REST (use pikku-http), SSE (use pikku-http with sse: true), or WebSocket
+  deployment specifics (use pikku-deploy-uws).
 ---
 
 # Pikku WebSocket Wiring
@@ -172,7 +176,7 @@ wireChannel({
 
 ### Generated WebSocket Client
 
-After `npx pikku prebuild`:
+After `npx pikku all`:
 
 ```typescript
 import { PikkuWebSocket } from '.pikku/pikku-websocket.gen.js'

package/skills/pikku-workflow/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-workflow
-description: 'Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku. Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
-TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows, multi-step processes, durable execution, suspend/resume, or DAG orchestration.
-DO NOT TRIGGER when: user asks about simple background jobs (use pikku-queue) or scheduled tasks (use pikku-cron).'
+description: >-
+  Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku.
+  Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
+  TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows,
+  multi-step processes, durable execution, suspend/resume, or DAG orchestration. DO NOT TRIGGER
+  when: user asks about simple background jobs (use pikku-queue) or scheduled tasks (use
+  pikku-cron).
 installGroups: [core]
 ---
 

package/skills/pikku-ws/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: pikku-ws
-description: 'Use when setting up a WebSocket server with the ws library in a Pikku app. Covers the ws runtime adapter for Pikku channels.
-TRIGGER when: code uses @pikku/ws, user asks about ws library WebSocket server, or Node.js WebSocket runtime.
-DO NOT TRIGGER when: user asks about WebSocket wiring/channels (use pikku-websocket) or uWebSockets (use pikku-deploy-uws).'
+description: >-
+  Use when setting up a WebSocket server with the ws library in a Pikku app. Covers the ws runtime
+  adapter for Pikku channels. TRIGGER when: code uses @pikku/ws, user asks about ws library
+  WebSocket server, or Node.js WebSocket runtime. DO NOT TRIGGER when: user asks about WebSocket
+  wiring/channels (use pikku-websocket) or uWebSockets (use pikku-deploy-uws).
 ---
 
 # Pikku WS (WebSocket Server Runtime)