@pikku/cli 0.12.90 → 0.12.92

package/skills/pikku-security/SKILL.md

@@ -1,108 +0,0 @@
----
-name: pikku-security
-description: >-
-  Use when adding authentication or session management to a Pikku app — pikkuAuth, session
-  lifecycle (setSession/clearSession), built-in auth strategies (authBearer, authCookie,
-  authAPIKey), or JWT setup. TRIGGER when: user asks about login, logout, session, bearer tokens,
-  cookie auth, API keys, or JWT. DO NOT TRIGGER when: user asks about middleware (use
-  pikku-middleware), permissions/authorization checks (use pikku-permissions), or secrets/env vars
-  (use pikku-config).
-installGroups: [core]
----
-
-# Pikku Security (Authentication & Sessions)
-
-## Agent Operating Procedure
-
-1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info functions --verbose` to understand existing auth setup.
-2. Auth strategies live in wirings files — do not put `addHTTPMiddleware` calls inside function bodies.
-3. Validate with `pikku all --tsc` after changes — it regenerates and then type-checks in one pass, and fails on type errors. Use `--tsc-summary` for a compact one-line-per-error report.
-
-For **middleware** (including tag middleware and service-to-service bearer auth) see `pikku-middleware`.
-For **permissions** (pikkuPermission, pikkuAuth, per-function authorization) see `pikku-permissions`.
-
-## Session Management
-
-```typescript
-// Read session in pikkuFunc (session guaranteed to exist)
-const getProfile = pikkuFunc({
-  func: async ({ db }, _data, { session }) => {
-    return await db.getUser(session.userId)
-  },
-})
-
-// Set session (e.g., after login)
-const login = pikkuFunc({
-  auth: false,
-  func: async ({ jwt, db }, { email, password }, { setSession }) => {
-    const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id })
-    return { token: jwt.sign({ userId: user.id }) }
-  },
-})
-
-// Clear session (logout)
-const logout = pikkuFunc({
-  func: async ({}, _data, { clearSession }) => {
-    clearSession()
-  },
-})
-```
-
-## Built-in Auth Strategies
-
-Apply these via `addHTTPMiddleware` in a wirings file:
-
-```typescript
-import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '@pikku/core/http'
-
-// JWT bearer token — reads Authorization header
-addHTTPMiddleware('*', [authBearer()])
-
-// Cookie-based sessions — auto-refreshes JWT
-addHTTPMiddleware('*', [
-  authCookie({
-    name: 'session',
-    expiresIn: { value: 30, unit: 'day' },
-    options: { httpOnly: true, secure: true },
-  }),
-])
-
-// API key — from x-api-key header or ?apiKey= query param
-addHTTPMiddleware('*', [authAPIKey({ source: 'all' })])
-```
-
-## Complete Example
-
-```typescript
-// permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku'
-
-export const isAuthenticated = pikkuAuth(async (_services, session) => !!session)
-export const isVerified = pikkuAuth(async (_services, session) => !!session?.emailVerified)
-
-// wirings/auth.wiring.ts
-import { authCookie } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '@pikku/core/http'
-
-addHTTPMiddleware('*', [
-  authCookie({ name: 'session', expiresIn: { value: 30, unit: 'day' } }),
-])
-
-// functions/auth.functions.ts
-export const login = pikkuFunc({
-  auth: false,
-  func: async ({ jwt, db }, { email, password }, { setSession }) => {
-    const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id })
-    return { token: jwt.sign({ userId: user.id }) }
-  },
-})
-
-export const logout = pikkuFunc({
-  func: async ({}, _data, { clearSession }) => {
-    clearSession()
-  },
-})
-```

package/skills/pikku-services/SKILL.md

@@ -1,248 +0,0 @@
----
-name: pikku-services
-description: >-
-  Use when setting up dependency injection, creating custom services, or configuring the service
-  layer in a Pikku app. Covers pikkuServices (singleton), pikkuWireServices (per-request), service
-  typing, built-in services, and tree-shaking. TRIGGER when: code uses
-  pikkuServices/pikkuWireServices, user asks about services.ts, dependency injection, service
-  factories, or built-in services (ConsoleLogger, JoseJWTService). DO NOT TRIGGER when: user asks
-  about auth middleware (use pikku-security) or secrets/variables (use pikku-config).
-installGroups: [core]
----
-
-# Pikku Services (Dependency Injection)
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Pikku uses factory functions for dependency injection. Singleton services are created once at startup; wire services are created fresh per request/job/command. See `pikku-concepts` for the core mental model.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See which services existing functions use
-pikku info tags --verbose        # Understand project organization
-```
-
-## API Reference
-
-### `pikkuServices(factory)` — singleton services (created once at startup)
-
-```typescript
-import { pikkuServices } from '#pikku'
-import { ConsoleLogger } from '@pikku/core/services'
-import { JoseJWTService } from '@pikku/jose'
-
-export const createSingletonServices = pikkuServices(
-  async (config, existingServices?) => {
-    // config: your CoreConfig object
-    // existingServices: optional, for chaining factories
-    const logger = new ConsoleLogger()
-    const database = new DatabasePool(config.database)
-    await database.connect()
-    const jwt = new JoseJWTService(
-      async () => [{ id: 'my-key', value: config.jwtSecret }],
-      logger
-    )
-    return { config, logger, database, jwt, books: new BookService() }
-  }
-)
-```
-
-### `pikkuWireServices(factory)` — per-request services (fresh per HTTP request, queue job, CLI command, etc.)
-
-```typescript
-import { pikkuWireServices } from '#pikku'
-
-export const createWireServices = pikkuWireServices(
-  async (singletonServices, wire) => {
-    // singletonServices: all singleton services
-    // wire: transport context (session, channel, etc.)
-    // Pikku merges these with singleton services automatically
-    return {
-      userSession: createUserSessionService(wire),
-      dbTransaction: new DatabaseTransaction(singletonServices.database),
-    }
-  }
-)
-```
-
-### Auto-Generated Service Manifest
-
-After `npx pikku all`, Pikku generates `.pikku/pikku-services.gen.ts`, a manifest of which services are actually used by wired functions:
-
-```typescript
-export const requiredSingletonServices = {
-  database: true, // used by getUser, deleteUser
-  audit: true, // used by deleteUser
-  cache: false, // not used by any wired function
-  jwt: true, // used by auth middleware
-} as const
-
-export type RequiredSingletonServices = Pick<
-  SingletonServices,
-  'database' | 'audit' | 'jwt'
-> &
-  Partial<Omit<SingletonServices, 'database' | 'audit' | 'jwt'>>
-```
-
-## Usage Patterns
-
-### Using Services in Functions
-
-**Every service must be declared in `SingletonServices` (or `Services`) in `application-types.d.ts`.** Never access a service via a body-level cast (`services as typeof services & { myService: MyService }`) — that means the type is missing. Add the import and the field to `SingletonServices`, then destructure inline in the function signature. The inspector emits `SERVICES_NOT_DESTRUCTURED` and tree-shaking breaks when the first param is a plain identifier rather than an object pattern. Never `new` a service inside a function — services arrive only via injection.
-
-```typescript
-// ✅ Correct — inline destructure, no cast
-const getUser = pikkuFunc({
-  title: 'Get User',
-  func: async ({ db, logger, jwt }, { userId }) => {
-    logger.info('Fetching user', { userId })
-    return { user: await db.getUser(userId) }
-  },
-})
-
-// ❌ Wrong — named param + body cast; inspector warns + tree-shaking breaks
-const getUser = pikkuFunc({
-  func: async (services, { userId }) => {
-    const { db } = services as typeof services & { db: DbService }
-    // ...
-  },
-})
-```
-
-### Services Are Never Optional Inside a Function
-
-**Never write a `if (!service) throw ...` existence guard in a function body.** It is dead code, and it defeats the platform.
-
-Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means *"this may not be created"*, not *"this may be missing at call time"*. A service is optional precisely because **nothing destructures it**, and `requireSingletonServices` therefore never creates it. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
-
-The types enforce this rather than merely documenting it. The inspector records the services destructured by every wired `func`, `permissions` **and** `middleware`, and emits them as `RequiredSingletonServices`. The generated function types then default their service parameter to:
-
-```typescript
-export type WiredSingletonServices = RequiredSingletonServices & SingletonServices
-export type WiredServices = RequiredSingletonServices & Services
-```
-
-so a service that is `foo?: Foo` in `SingletonServices` arrives as a non-optional `Foo` in every function, permission and middleware that uses it. There is nothing to guard against.
-
-```typescript
-// ✅ Correct — destructure and use; creation is guaranteed by the manifest
-const listThreads = pikkuFunc({
-  func: async ({ agentRunService }, { threadId }) => {
-    return await agentRunService.getThreadMessages(threadId)
-  },
-})
-
-// ❌ Wrong — unreachable guard; signals a misunderstanding of service wiring
-const listThreads = pikkuFunc({
-  func: async ({ agentRunService }, { threadId }) => {
-    if (!agentRunService) throw new MissingServiceError('agentRunService')
-    return await agentRunService.getThreadMessages(threadId)
-  },
-})
-```
-
-If a service really is conditional at runtime (e.g. an optional integration a deployment may not configure), that is a **configuration** concern: branch on config, or fail fast at startup in `services.ts` — not per-request in every function.
-
-### Dynamic Import Optimization
-
-Use the generated manifest to conditionally import heavy dependencies — only the services actually wired get instantiated:
-
-```typescript
-import { requiredSingletonServices } from '.pikku/pikku-services.gen.js'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new ConsoleLogger()
-
-  let jwt: JWTService | undefined
-  if (requiredSingletonServices.jwt) {
-    const { JoseJWTService } = await import('@pikku/jose')
-    jwt = new JoseJWTService(keys, logger)
-  }
-
-  let database: Database | undefined
-  if (requiredSingletonServices.database) {
-    database = await createDatabase(config.databaseUrl)
-  }
-
-  return { config, logger, jwt, database }
-})
-```
-
-### Audit Wire Service
-
-`createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and Fabric notes, read `references/audit-wire-service.md`.
-
-### Built-in Services
-
-| Service                    | Package                | Purpose                          |
-| -------------------------- | ---------------------- | -------------------------------- |
-| `ConsoleLogger`            | `@pikku/core/services` | Console-based logging            |
-| `JoseJWTService`           | `@pikku/jose`          | JWT sign/verify via jose         |
-| `LocalSecretService`       | `@pikku/core/services` | Local development secrets        |
-| `LocalVariablesService`    | `@pikku/core/services` | Local environment variables      |
-| `PinoLogger`               | `@pikku/pino`          | Structured logging via Pino      |
-| `createInvocationAudit`    | `@pikku/core/services` | Per-request audit buffer         |
-| `createAuditedKysely`      | `@pikku/kysely`        | Auto-capture DB queries as audit events |
-
-## Complete Example
-
-```typescript
-// services.ts
-import { pikkuServices, pikkuWireServices } from '#pikku'
-import { ConsoleLogger } from '@pikku/core/services'
-import { JoseJWTService } from '@pikku/jose'
-
-// Custom service
-class TodoStore {
-  private todos: Map<string, Todo> = new Map()
-  async create(title: string, priority: string) {
-    const todo = { id: crypto.randomUUID(), title, priority, completed: false }
-    this.todos.set(todo.id, todo)
-    return todo
-  }
-  async get(id: string) { return this.todos.get(id) }
-  async list() { return [...this.todos.values()] }
-  async delete(id: string) { this.todos.delete(id) }
-}
-
-export const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new ConsoleLogger()
-  const jwt = new JoseJWTService(
-    async () => [{ id: 'my-key', value: config.jwtSecret }],
-    logger
-  )
-  return {
-    config,
-    logger,
-    jwt,
-    secrets: new LocalSecretService(),
-    variables: new LocalVariablesService(),
-    todoStore: new TodoStore(),
-  }
-})
-
-export const createWireServices = pikkuWireServices(
-  async (singletonServices, wire) => ({
-    scopedLogger: new ScopedLogger(wire.session?.initial?.userId),
-  })
-)
-
-// functions/todos.functions.ts — services are auto-injected
-export const createTodo = pikkuFunc({
-  title: 'Create Todo',
-  func: async ({ todoStore, logger }, { title, priority }) => {
-    const todo = await todoStore.create(title, priority)
-    logger.info('Created todo', { id: todo.id })
-    return { todo }
-  },
-})
-```

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

@@ -1,34 +0,0 @@
-# Audit Wire Service
-
-`createInvocationAudit` creates a per-request `InvocationAuditLog` that buffers audit events in memory and flushes them as a batch when the function-runner calls `closeWireServices` at the end of the request. If `singletonServices.audit` is not configured (local dev without Fabric), it returns a no-op `DisabledInvocationAudit` — no crash, events are silently dropped.
-
-Pair with `createAuditedKysely` to auto-capture every Kysely query as an audit event.
-
-```typescript
-// services.ts
-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 } : {}) }
-})
-```
-
-The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions that emit custom events use it directly:
-
-```typescript
-const deleteUser = pikkuFunc({
-  func: async ({ audit }, { userId }) => {
-    await audit.audit({ type: 'user.deleted', actor_user_id: userId })
-    // ...
-  },
-})
-```
-
-`closeWireServices` (called automatically by the function-runner) invokes `audit.close()` → `singletonServices.audit.write(batch)` → platform-specific flush (e.g. CF Queue, libsql INSERT). No manual flushing needed.
-
-> **Fabric note:** Fabric provisions the audit queue and consumer worker automatically. The audit table schema is in `db/sqlite/0003-audit.sql` (starter-template). Run `pikku fabric validate` to confirm the migration is in place.

package/skills/pikku-software-archaeology/README.md

@@ -1,70 +0,0 @@
-# pikku-software-archaeology
-
-Reverse-engineers an existing repository into a **Product Blueprint**: the product intelligence hidden inside an implementation (domains, entities, commands, queries, events, policies, workflows, invariants, integrations, gaps), extracted as schema-validated JSON that a generator — in our case Pikku — can rebuild from.
-
-```
-Existing Repository → pikku-software-archaeology → .knowledge/ blueprint → new Pikku application
-```
-
-This is **not** a code indexer or doc generator. It extracts *intent over implementation*: `POST /api/users/:id/status` becomes the command `ActivateUser`; three scattered `if (inv.user_id !== req.user.id)` checks become one `InvoiceOwnerOnly` policy with three `enforcedAt` citations.
-
-## Design decision: the AI is the parser
-
-There is deliberately **no scanner/AST tooling** in this skill. Static extraction is brittle and per-language (the first prototype's regex scanner broke before it ran once); the analyzing model already reads every language — JS, TS, Ruby, Python, PHP, Go — follows indirection, and understands intent. Determinism lives in the **output contract** instead: fixed file names, schema-validated shapes, sorted unordered collections (sequence-bearing arrays keep their observed order), and stable concept names, all enforced by a dumb JSON validator (`scripts/validate.mjs`). The audit is expensive; that's the trade we chose.
-
-## How to run it
-
-In Claude Code, from (or pointing at) the target repo:
-
-> Use the pikku-software-archaeology skill to extract a product blueprint from /path/to/repo
-
-The agent then:
-1. **Surveys** the repo (manifests, entry points, routes, jobs, webhooks, schema, config, TODO/HACK markers) — facts only.
-2. **Excavates the test suite** — `describe`/`it` names become workflow scenarios; assertions confirm policies and upgrade confidence; rules that exist *only* in tests are captured.
-3. **Extracts** through twelve lenses (domains, entities, commands, …) per the pipeline in `SKILL.md`. Large repos fan out subagents per lens and merge.
-4. **Cross-checks and validates**:
-   ```bash
-   node .claude/skills/pikku-software-archaeology/scripts/validate.mjs <repo>/.knowledge
-   ```
-   The validator checks every file against `references/blueprint.schema.json` plus referential integrity across files (commands reference defined domains, api surfaces map to defined commands/queries, events have producers, …).
-5. Writes `blueprint.md`, the human synthesis.
-
-Output lands in `<repo>/.knowledge/` — 14 core JSON files + `blueprint.md` (see `SKILL.md` for the full listing). Repos with a frontend and/or non-HTTP consumer channels also get an **optional consumer-surface layer**: `interfaces.json` (every way the product is used — web UI, CLI, MCP server for AI agents, OpenAPI/REST, SDK, realtime, webhooks) plus `frontend.json` / `frontend-routes.json` / `frontend-components.json`. The frontend component inventory's `rebuild` field is the key output: it separates trivially-rebuildable standard components from the **custom-logic** pieces (charts, complex tables, editors) that must be carefully ported. Backend-only repos omit these and the validator does not complain.
-
-### Incremental re-analysis
-
-Concept names are the stable IDs. On re-run after code changes, re-extract only the affected lens/domain, diff against the existing `.knowledge/`, and leave unrelated entries verbatim. Unordered collections are sorted so diffs stay reviewable; sequence-bearing arrays stay in observed order.
-
-## How Pikku consumes the blueprint
-
-Full mapping table in `references/pikku-mapping.md`. Summary: entities → Kysely migrations + Zod schemas; commands/queries → `pikkuFunc`s; api surfaces → `wireHTTP`; policies → shared permission functions (collapsing duplicated legacy checks); system workflows → `wireScheduler`/`wireQueueWorker`/`pikkuWorkflowFunc`; integrations → injected services with `wireSecret`/`wireCredential`; test-derived scenarios → `pikkuUserFlow` stories / e2e tests. Humans resolve `migration.json.decisionsNeeded` before any generation starts.
-
-## How uncertainty is represented
-
-Every extracted concept carries:
-
-```json
-{ "evidence": [{ "file": "controllers/invoices.js", "lines": "52", "note": "guard: only drafts editable" }],
-  "confidence": "high" }
-```
-
-- **high** — the behavior itself is in the cited code/schema/test. Generates directly.
-- **medium** — inferred from converging signals. Generates with a review marker.
-- **low** — plausible reconstruction. Never auto-generated; surfaced for human review.
-
-Two further distinctions keep facts and guesses separate:
-- `events[].explicit: false` — the event was *reconstructed* from side-effect clusters (email + status flip), not emitted by the code.
-- Comments/docs vs code: comments describe intent, code describes behavior. Disagreements are recorded as the code's behavior plus a `gaps.json` entry.
-
-## Repo layout
-
-```
-pikku-software-archaeology/
-├── SKILL.md                          # skill definition + extraction pipeline
-├── README.md                         # this file
-├── references/
-│   ├── blueprint.schema.json         # the output contract (JSON Schema)
-│   └── pikku-mapping.md              # blueprint → Pikku primitives
-└── scripts/
-    └── validate.mjs                  # schema + cross-file validation (node, no deps)
-```