@pikku/skills 0.12.10 → 0.12.11

package/skills/pikku-services/references/audit-wire-service.md

@@ -9,13 +9,15 @@ Pair with `createAuditedKysely` to auto-capture every Kysely query as an audit e
 import { createInvocationAudit } from '@pikku/core/services'
 import { createAuditedKysely } from '@pikku/kysely'
 
-export const createWireServices = pikkuWireServices(async (singletonServices, wire) => {
-  const audit = createInvocationAudit(singletonServices.audit, wire)
-  const kysely = singletonServices.kysely
-    ? createAuditedKysely(singletonServices.kysely, { audit })
-    : undefined
-  return { audit, ...(kysely ? { kysely } : {}) }
-})
+export const createWireServices = pikkuWireServices(
+  async (singletonServices, wire) => {
+    const audit = createInvocationAudit(singletonServices.audit, wire)
+    const kysely = singletonServices.kysely
+      ? createAuditedKysely(singletonServices.kysely, { audit })
+      : undefined
+    return { audit, ...(kysely ? { kysely } : {}) }
+  }
+)
 ```
 
 The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions that emit custom events use it directly:
@@ -24,7 +26,11 @@ The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions
 const deleteUser = pikkuFunc({
   func: async ({ audit }, { userId }) => {
     // The user identity comes from the wire session — the payload is metadata.
-    await audit.write({ type: 'user.deleted', source: 'explicit', metadata: { userId } })
+    await audit.write({
+      type: 'user.deleted',
+      source: 'explicit',
+      metadata: { userId },
+    })
     // ...
   },
 })

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

@@ -5,118 +5,182 @@
 //
 // 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';
+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 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 dir = process.argv[2]
+if (!dir) {
+  console.error('usage: node validate.mjs <.knowledge dir>')
+  process.exit(2)
+}
 
-const errors = [];
-const warnings = [];
+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]];
+  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.$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;
+    errors.push(
+      `${path}: expected one of [${schema.enum.join(', ')}], got ${JSON.stringify(value)}`
+    )
+    return
   }
-  const t = schema.type;
+  const t = schema.type
   if (t === 'object') {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-      errors.push(`${path}: expected object`); return;
+      errors.push(`${path}: expected object`)
+      return
     }
     for (const req of schema.required || []) {
-      if (!(req in value)) errors.push(`${path}: missing required field "${req}"`);
+      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}`);
+      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 (!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}`);
+      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}]`));
+    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 (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}`);
+      errors.push(`${path}: "${value}" does not match ${schema.pattern}`)
     }
   } else if (t === 'boolean' && typeof value !== 'boolean') {
-    errors.push(`${path}: expected boolean`);
+    errors.push(`${path}: expected boolean`)
   } else if (t === 'number' && typeof value !== 'number') {
-    errors.push(`${path}: expected 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 = {};
+const docs = {}
 for (const [filename, fileSchema] of Object.entries(schemaDoc.files)) {
-  const p = join(dir, filename);
+  const p = join(dir, filename)
   if (!existsSync(p)) {
-    if (!fileSchema['x-optional']) errors.push(`${filename}: missing`);
-    continue;
+    if (!fileSchema['x-optional']) errors.push(`${filename}: missing`)
+    continue
   }
   try {
-    docs[filename] = JSON.parse(readFileSync(p, 'utf8'));
+    docs[filename] = JSON.parse(readFileSync(p, 'utf8'))
   } catch (e) {
-    errors.push(`${filename}: invalid JSON (${e.message})`); continue;
+    errors.push(`${filename}: invalid JSON (${e.message})`)
+    continue
   }
-  check(docs[filename], fileSchema, filename);
+  check(docs[filename], fileSchema, filename)
 }
-if (!existsSync(join(dir, 'blueprint.md'))) errors.push('blueprint.md: missing');
+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 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`);
-  };
+    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);
+    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`);
+      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 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)`);
+    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`);
+    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?`);
+      warnings.push(
+        `commands.json:${c.name}: no policies or preconditions — really unguarded, or missed extraction?`
+      )
     }
   }
 }
@@ -124,13 +188,15 @@ if (docs['domains.json'] && docs['commands.json']) {
 // --- 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),
-  );
+    (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`);
+        warnings.push(
+          `frontend-routes.json:${r.path}: uses component "${c}" not in frontend-components.json`
+        )
       }
     }
   }
@@ -138,7 +204,9 @@ if (docs['frontend-components.json']) {
   // 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`);
+      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
@@ -146,11 +214,13 @@ if (docs['frontend-components.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`);
+          warnings.push(
+            `frontend-routes.json:${r.path}: reads "${d}" which is not a known query/command`
+          )
         }
       }
     }
@@ -160,14 +230,21 @@ if (docs['frontend-components.json']) {
 // 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/…)`);
+  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);
+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-tag-middleware/SKILL.md

@@ -6,6 +6,7 @@ description: 'Deprecated — use pikku-middleware instead. Tag middleware (addTa
 # Deprecated: use `pikku-middleware`
 
 Tag middleware is covered in the **`pikku-middleware`** skill, which also covers:
+
 - `addHTTPMiddleware` (global / prefix-based)
 - `addTagMiddleware` (tag-scoped)
 - Middleware execution order and priority

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

@@ -26,8 +26,9 @@ commit, separate from any feature work.
 
    `create-pikku` keeps only the chosen package manager's lockfile and deletes
    the other, and for yarn it may have written an **empty** `yarn.lock` as a
-   marker. Commit the lockfile *after* the first install has filled it in —
+   marker. Commit the lockfile _after_ the first install has filled it in —
    committing the empty placeholder pins nothing.
+
 3. **Rename template identifiers.** Update `name` in the root `package.json`
    (and any `@project/*` or other placeholder names) to the real project.
 4. **Drop template-only artifacts.** Remove any `TEMPLATE.md`, demo docs, or

package/skills/pikku-trigger/SKILL.md

@@ -45,7 +45,7 @@ handler, and a handler can exist before any source is wired.
 Define the target function that handles trigger events:
 
 ```typescript
-import { wireTrigger } from '#pikku'
+import { wireTrigger } from '#pikku/trigger'
 
 wireTrigger({
   name: string, // Trigger name (matches source)
@@ -60,7 +60,7 @@ wireTrigger({
 Define the event source that fires triggers:
 
 ```typescript
-import { wireTriggerSource } from '#pikku'
+import { wireTriggerSource } from '#pikku/trigger'
 
 wireTriggerSource({
   name: string, // Must match a wireTrigger name
@@ -80,7 +80,7 @@ up a listener, calls `trigger.invoke(...)` for each event it sees, and returns a
 teardown function:
 
 ```typescript
-import { pikkuTriggerFunc } from '#pikku'
+import { pikkuTriggerFunc } from '#pikku/trigger'
 
 const source = pikkuTriggerFunc<
   InputType, // Configuration input

package/skills/pikku-websocket/SKILL.md

@@ -94,8 +94,9 @@ wireChannel({
   name: 'todos',
   route: '/todos',
   onMessageWiring: {
-    action: {                                  // ← the field to route on
-      create: { func: createTodo },            // ← its possible values
+    action: {
+      // ← the field to route on
+      create: { func: createTodo }, // ← its possible values
       list: { func: listTodos, auth: false },
     },
   },
@@ -129,7 +130,7 @@ wireChannel({
   onMessageWiring: {
     action: {
       authenticate: { func: authenticate, auth: false }, // No session required
-      subscribe: { func: subscribeTodos },               // Session required
+      subscribe: { func: subscribeTodos }, // Session required
       create: { func: createTodo },
     },
   },

package/skills/pikku-workflow/SKILL.md

@@ -64,8 +64,8 @@ import {
   pikkuWorkflowComplexFunc,
 } from '#pikku/workflow/pikku-workflow-types.gen.js'
 
-// WRONG — '#pikku' does not re-export them (TS2305)
-import { pikkuWorkflowFunc } from '#pikku'
+// WRONG — the function leaf does not re-export them (TS2305)
+import { pikkuWorkflowFunc } from '#pikku/function'
 ```
 
 ## Defining a workflow

package/skills/pikku-workflow/references/workflow-reference.md

@@ -6,15 +6,15 @@ Whether a step runs **inline** (same process/session, no queue round-trip) or is
 
 - **Steps default to inline.** Most steps don't need their own worker; running them inline avoids a queue round-trip per step, so a normally-started workflow executes its whole chain in one orchestrator pass.
 - **`workflowQueued: true` opts a function out.** Set it on the **function config** (`pikkuFunc` / `pikkuSessionlessFunc`, same level as `auth`/`expose`) to dispatch that step via the queue — for expensive/long-running steps that deserve their own worker, retry isolation, and concurrency limits. `workflowRetries` and `workflowTimeout` sit alongside it.
-- **Run-level `inline` is separate** and only controls whether the *whole run* executes in-process without queue infrastructure (set automatically when there is no `queueService`, or via `startWorkflow(..., { inline: true })`). It governs sleep handling, not per-step dispatch.
+- **Run-level `inline` is separate** and only controls whether the _whole run_ executes in-process without queue infrastructure (set automatically when there is no `queueService`, or via `startWorkflow(..., { inline: true })`). It governs sleep handling, not per-step dispatch.
 
 The rule (`dispatchStep`):
 
-| Function `workflowQueued` | `queueService` present? | Result |
-|---|---|---|
-| default / `false` | any | **inline** |
-| `true` | yes | **queued** (own worker) |
-| `true` | no | **throws** |
+| Function `workflowQueued` | `queueService` present? | Result                  |
+| ------------------------- | ----------------------- | ----------------------- |
+| default / `false`         | any                     | **inline**              |
+| `true`                    | yes                     | **queued** (own worker) |
+| `true`                    | no                      | **throws**              |
 
 ```typescript
 // Push this one expensive step onto the queue; every other step stays inline:
@@ -24,7 +24,9 @@ export const renderLargeReport = pikkuSessionlessFunc({
   workflowTimeout: '5m',
   input: ReportInput,
   output: ReportOutput,
-  func: async (services, data) => { /* ... */ },
+  func: async (services, data) => {
+    /* ... */
+  },
 })
 ```
 
@@ -39,13 +41,25 @@ Usually auto-scaffolded via `scaffold.workflow`. To wire by hand:
 
 ```typescript
 // Start a workflow
-wireHTTP({ method: 'post', route: '/onboard', func: workflowStart('onboardUser') })
+wireHTTP({
+  method: 'post',
+  route: '/onboard',
+  func: workflowStart('onboardUser'),
+})
 
 // Execute workflow steps (called by the orchestrator)
-wireHTTP({ method: 'post', route: '/onboard/run', func: workflow('onboardUser') })
+wireHTTP({
+  method: 'post',
+  route: '/onboard/run',
+  func: workflow('onboardUser'),
+})
 
 // Check workflow status
-wireHTTP({ method: 'get', route: '/onboard/status/:runId', func: workflowStatus('onboardUser') })
+wireHTTP({
+  method: 'get',
+  route: '/onboard/status/:runId',
+  func: workflowStatus('onboardUser'),
+})
 ```
 
 ## Suspend / resume example