@pikku/skills 0.12.13 → 0.12.14

package/skills/pikku-schedule/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: pikku-schedule
 description: >-
-  Use when setting up in-memory cron scheduling in a Pikku app. Covers InMemorySchedulerService
-  for running scheduled tasks. TRIGGER when: code uses InMemorySchedulerService,
-  PikkuTaskScheduler, or user asks about in-memory scheduling, cron jobs without external
-  dependencies, or @pikku/schedule. DO NOT TRIGGER when: user asks about cron wiring (use
-  pikku-cron) or queue-based scheduling with BullMQ/PgBoss (use pikku-queue).
+  Use when adding scheduled tasks, recurring jobs, or cron-based automation to a Pikku app. Covers
+  wireScheduler, cron expressions, the scheduled task wire object, and scheduler middleware.
+  TRIGGER when: code uses wireScheduler, user asks about cron, scheduled tasks, recurring jobs, or
+  "run every X minutes/hours". DO NOT TRIGGER when: user asks about background jobs with retries
+  (use pikku-queue) or event-driven triggers (use pikku-trigger).
 installGroups: [core]
 ---
 
-# Pikku Schedule (In-Memory Scheduler)
+# Pikku Scheduled Tasks
 
 ## Agent Operating Procedure
 
@@ -21,75 +21,203 @@ Use this skill as an execution checklist, not reference material.
 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/schedule` provides an in-memory cron scheduler for running Pikku scheduled functions without external dependencies like Redis or PostgreSQL.
+Wire Pikku functions to run on a schedule using cron expressions. Uses `pikkuVoidFunc` (no input/output).
 
-## Installation
+`pikku dev`, `pikku serve` and the standalone deploy adapter each register a scheduler service for you, so a wired task runs without any setup. Only register one yourself when deploying somewhere those do not reach, and then take it off the queue factory (`bullFactory.getSchedulerService()`, `pgBossFactory.getSchedulerService()` — see `pikku-queue`) so it survives a restart and is shared between instances.
+
+## Before You Start
 
 ```bash
-yarn add @pikku/schedule
+pikku info functions --verbose   # See existing functions and their types
+pikku info tags --verbose        # Understand project organization
 ```
 
+See `pikku-concepts` for the core mental model.
+
 ## API Reference
 
-### `InMemorySchedulerService`
+### `wireScheduler(config)`
 
 ```typescript
-import { InMemorySchedulerService } from '@pikku/schedule'
-
-const schedulerService = new InMemorySchedulerService()
-await schedulerService.start() // registers a CronJob per wired scheduled task
+import { wireScheduler } from '@pikku/core/scheduler'
+
+wireScheduler({
+  name: string,            // Unique scheduler name
+  schedule: string,        // Cron expression
+  func: PikkuVoidFunc,     // Must be pikkuVoidFunc (no input/output)
+  tags?: string[],         // Targets tag middleware — see pikku-middleware
+  middleware?: PikkuMiddleware[],
+})
 ```
 
-It implements core's `SchedulerService` on two mechanisms: `cron` for the
-recurring tasks you declared with `wireScheduler` (see `pikku-cron`), and
-`setTimeout` for one-off delayed RPCs. Both live in process memory, so nothing
-survives a restart and nothing is shared between instances — fine for
-development and a single-instance deployment, wrong for anything else.
-
-`PikkuTaskScheduler` is a deprecated alias for the same class.
+### Wire Object (`wire.scheduledTask`)
 
-### Scheduling a one-off RPC
+Inside scheduled functions:
 
 ```typescript
-const taskId = await schedulerService.scheduleRPC(
-  '5m',
-  'sendReminder',
-  data,
-  session
-)
-await schedulerService.getTask(taskId) // { rpcName, scheduledFor, status, … } | null
-await schedulerService.getAllTasks() // pending one-offs only
-await schedulerService.unschedule(taskId) // true when it was still pending
+wire.scheduledTask.name // Scheduler name
+wire.scheduledTask.schedule // Cron expression string
+wire.scheduledTask.executionTime // Date this execution was triggered
+wire.scheduledTask.skip(reason?) // Abort this execution — THROWS, never returns
+```
+
+**`skip()` aborts by throwing.** It reads like an early return but it is not:
+nothing after the call runs, so there is no need to `return` afterwards. The
+consequence that bites is in middleware — a `try/catch` around `await next()`
+will catch a skip and report it as a failure. If your middleware distinguishes
+success from failure, let the skip pass through rather than logging it as an
+error.
+
+### Cron Expression Reference
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
 ```
 
-The delay is milliseconds or a duration string (`'30s'`, `'5m'`, `'2h'`). This is
-also the mechanism a workflow's delayed steps use, which is why a workflow that
-sleeps needs a `schedulerService` registered.
+Common patterns:
+
+| Expression    | Meaning                    |
+| ------------- | -------------------------- |
+| `*/5 * * * *` | Every 5 minutes            |
+| `0 9 * * *`   | Daily at 9:00 AM           |
+| `0 9 * * 1`   | Every Monday at 9:00 AM    |
+| `0 0 1 * *`   | First of month at midnight |
+| `0 */6 * * *` | Every 6 hours              |
+| `30 2 * * 0`  | Sundays at 2:30 AM         |
 
 ## Usage Patterns
 
-### Basic Setup
+### Basic Scheduled Task
+
+```typescript
+const dailySummary = pikkuVoidFunc({
+  title: 'Daily Summary',
+  func: async ({ db, emailService, logger }) => {
+    logger.info('Generating daily summary')
+    const stats = await db.getDailyStats()
+    await emailService.sendSummary(stats)
+  },
+})
+
+wireScheduler({
+  name: 'dailySummary',
+  schedule: '0 9 * * *',
+  func: dailySummary,
+})
+```
 
-The scheduler is a singleton service under the name **`schedulerService`**, and
-it is started in your server bootstrap — declaring it without calling `start()`
-registers no cron jobs, so nothing ever fires:
+### Using the Wire Object
 
 ```typescript
-// start.ts
-import { InMemorySchedulerService } from '@pikku/schedule'
+const weeklyCleanup = pikkuVoidFunc({
+  title: 'Weekly Cleanup',
+  func: async ({ db, logger }, _input, wire) => {
+    logger.info(`Running: ${wire.scheduledTask.name}`)
+    logger.info(`Schedule: ${wire.scheduledTask.schedule}`)
+    logger.info(`Execution time: ${wire.scheduledTask.executionTime}`)
+
+    const staleCount = await db.countStaleTodos()
+    if (staleCount === 0) {
+      wire.scheduledTask.skip('No stale todos found') // throws — nothing below runs
+    }
+
+    await db.deleteCompletedTodos({ olderThan: '30d' })
+    logger.info(`Cleaned ${staleCount} stale todos`)
+  },
+})
 
-const schedulerService = new InMemorySchedulerService()
-const singletonServices = await createSingletonServices(config, {
-  schedulerService,
+wireScheduler({
+  name: 'weeklyCleanup',
+  schedule: '0 0 * * 0',
+  func: weeklyCleanup,
 })
+```
+
+### Scheduler Middleware
 
-await appServer.start()
-await schedulerService.start()
+```typescript
+const schedulerMetrics = pikkuMiddleware(
+  async ({ logger }, { scheduledTask }, next) => {
+    const start = Date.now()
+    logger.info(`Task started: ${scheduledTask.name}`)
+
+    try {
+      await next()
+      logger.info(`Task completed: ${scheduledTask.name}`, {
+        duration: Date.now() - start,
+      })
+    } catch (error) {
+      logger.error(`Task failed: ${scheduledTask.name}`, {
+        error: error.message,
+        duration: Date.now() - start,
+      })
+      throw error
+    }
+  }
+)
+
+wireScheduler({
+  name: 'dailySummary',
+  schedule: '0 9 * * *',
+  func: dailySummary,
+  middleware: [schedulerMetrics],
+})
 ```
 
-Call `close()` on shutdown — it stops every cron job and clears pending timers.
+## Complete Example
+
+```typescript
+// functions/scheduled.functions.ts
+export const dailySummary = pikkuVoidFunc({
+  title: 'Daily Summary',
+  func: async ({ db, emailService, logger }) => {
+    const stats = await db.getDailyStats()
+    await emailService.sendSummary(stats)
+    logger.info('Daily summary sent', { stats })
+  },
+})
+
+export const cleanupExpired = pikkuVoidFunc({
+  title: 'Cleanup Expired',
+  func: async ({ db, logger }, _input, wire) => {
+    const count = await db.countExpiredSessions()
+    if (count === 0) {
+      wire.scheduledTask.skip('No expired sessions') // throws — nothing below runs
+    }
+    await db.deleteExpiredSessions()
+    logger.info(`Cleaned ${count} expired sessions`)
+  },
+})
+
+export const syncInventory = pikkuVoidFunc({
+  title: 'Sync Inventory',
+  func: async ({ inventoryApi, db, logger }) => {
+    const updates = await inventoryApi.getChanges()
+    await db.applyInventoryUpdates(updates)
+    logger.info(`Synced ${updates.length} inventory changes`)
+  },
+})
 
-For distributed or persistent scheduling, take the scheduler service off the
-queue factory instead (`bullFactory.getSchedulerService()`,
-`pgBossFactory.getSchedulerService()`) and register it under the same name. See
-`pikku-queue`.
+// wirings/scheduler.wiring.ts
+wireScheduler({
+  name: 'dailySummary',
+  schedule: '0 9 * * *',
+  func: dailySummary,
+})
+wireScheduler({
+  name: 'cleanupExpired',
+  schedule: '0 */6 * * *',
+  func: cleanupExpired,
+})
+wireScheduler({
+  name: 'syncInventory',
+  schedule: '*/15 * * * *',
+  func: syncInventory,
+})
+```

package/skills/pikku-schema-ajv/SKILL.md

@@ -5,7 +5,6 @@ description: >-
   request/response validation. TRIGGER when: code uses AjvSchemaService, user asks about AJV, JSON
   schema validation, or @pikku/schema-ajv. DO NOT TRIGGER when: user asks about Cloudflare Workers
   schema validation (use pikku-schema-cfworker).
-installGroups: [core]
 ---
 
 # Pikku Schema AJV (JSON Schema Validation)

package/skills/pikku-schema-cfworker/SKILL.md

@@ -6,7 +6,6 @@ description: >-
   CFWorkerSchemaService, user asks about schema validation on Cloudflare Workers, or
   @pikku/schema-cfworker. DO NOT TRIGGER when: user asks about AJV schema validation (use
   pikku-schema-ajv).
-installGroups: [core, fabric]
 ---
 
 # Pikku Schema CFWorker (Cloudflare Workers Validation)

package/skills/pikku-security/SKILL.md

@@ -61,7 +61,7 @@ with the default `auth` would be rejected before its body ever ran.
 Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
-import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
+import { authBearer, authCookie, authAPIKey } from '#pikku/middleware'
 import { addHTTPMiddleware } from '#pikku/http'
 
 // JWT bearer token — reads Authorization header
@@ -128,7 +128,7 @@ export const isVerified = pikkuAuth(
 )
 
 // wirings/auth.wiring.ts
-import { authCookie } from '@pikku/core/middleware'
+import { authCookie } from '#pikku/middleware'
 import { addHTTPMiddleware } from '#pikku/http'
 
 addHTTPMiddleware('*', [

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

@@ -1,7 +1,6 @@
 ---
 name: pikku-software-archaeology
 description: 'Use when reverse-engineering an existing repository into a Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app). TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", or points at a legacy repo (any language — JS, TS, Ruby, Python, PHP, Go) and asks for its domains, workflows, business rules, or a rebuild plan. DO NOT TRIGGER for: documenting code structure, generating API docs from an already-clean codebase, or code review.'
-installGroups: [fabric]
 ---
 
 # Software Archaeology

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

@@ -2,7 +2,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 `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 *)
-installGroups: [core]
 ---
 
 # Pikku Template Post-Clone Cleanup

package/skills/pikku-trigger/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   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
+  external events. DO NOT TRIGGER when: user asks about scheduled tasks (use pikku-schedule) or
   background job queues (use pikku-queue).
 installGroups: [core]
 ---

package/skills/pikku-versioning/SKILL.md

@@ -11,7 +11,6 @@ description: >-
   CLI commands. DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config)
   or general function definitions (use pikku-concepts), or about updating dependency versions
   (use pikku-deps).
-installGroups: [core]
 ---
 
 # Pikku Function Versioning

package/skills/pikku-workflow/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   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).
+  pikku-schedule).
 installGroups: [core]
 ---
 

package/skills/pikku-workflows-client/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-workflows-client
 description: 'Run Pikku workflows from a React frontend and track their progress. Covers `useRunWorkflow` (run-and-wait), `useStartWorkflow` (fire-and-poll), and `useWorkflowStatus` (live status). TRIGGER when: a React component needs to invoke or display the status of a Pikku workflow, the user mentions long-running tasks / background jobs / progress UI tied to a workflow, or asks how to start/track a workflow from the client. DO NOT TRIGGER when: the user is wiring the workflow itself (use pikku-workflow) or only making regular RPC calls (use pikku-react-query).'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku Workflows — Client Hooks

package/skills/pikku-cron/SKILL.md

@@ -1,221 +0,0 @@
----
-name: pikku-cron
-description: >-
-  Use when adding scheduled tasks, recurring jobs, or cron-based automation to a Pikku app. Covers
-  wireScheduler, cron expressions, scheduled task wire object, and scheduler middleware. TRIGGER
-  when: code uses wireScheduler, user asks about cron, scheduled tasks, recurring jobs, or "run
-  every X minutes/hours". DO NOT TRIGGER when: user asks about background jobs with retries (use
-  pikku-queue) or event-driven triggers (use pikku-trigger).
-installGroups: [core]
----
-
-# Pikku Cron/Scheduler Wiring
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. 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.
-
-Wire Pikku functions to run on a schedule using cron expressions. Uses `pikkuVoidFunc` (no input/output).
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and their types
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### `wireScheduler(config)`
-
-```typescript
-import { wireScheduler } from '@pikku/core/scheduler'
-
-wireScheduler({
-  name: string,            // Unique scheduler name
-  schedule: string,        // Cron expression
-  func: PikkuVoidFunc,     // Must be pikkuVoidFunc (no input/output)
-  tags?: string[],         // Targets tag middleware — see pikku-middleware
-  middleware?: PikkuMiddleware[],
-})
-```
-
-### Wire Object (`wire.scheduledTask`)
-
-Inside scheduled functions:
-
-```typescript
-wire.scheduledTask.name // Scheduler name
-wire.scheduledTask.schedule // Cron expression string
-wire.scheduledTask.executionTime // Date this execution was triggered
-wire.scheduledTask.skip(reason?) // Abort this execution — THROWS, never returns
-```
-
-**`skip()` aborts by throwing.** It reads like an early return but it is not:
-nothing after the call runs, so there is no need to `return` afterwards. The
-consequence that bites is in middleware — a `try/catch` around `await next()`
-will catch a skip and report it as a failure. If your middleware distinguishes
-success from failure, let the skip pass through rather than logging it as an
-error.
-
-### Cron Expression Reference
-
-```
-┌───────────── minute (0-59)
-│ ┌───────────── hour (0-23)
-│ │ ┌───────────── day of month (1-31)
-│ │ │ ┌───────────── month (1-12)
-│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
-│ │ │ │ │
-* * * * *
-```
-
-Common patterns:
-
-| Expression    | Meaning                    |
-| ------------- | -------------------------- |
-| `*/5 * * * *` | Every 5 minutes            |
-| `0 9 * * *`   | Daily at 9:00 AM           |
-| `0 9 * * 1`   | Every Monday at 9:00 AM    |
-| `0 0 1 * *`   | First of month at midnight |
-| `0 */6 * * *` | Every 6 hours              |
-| `30 2 * * 0`  | Sundays at 2:30 AM         |
-
-## Usage Patterns
-
-### Basic Scheduled Task
-
-```typescript
-const dailySummary = pikkuVoidFunc({
-  title: 'Daily Summary',
-  func: async ({ db, emailService, logger }) => {
-    logger.info('Generating daily summary')
-    const stats = await db.getDailyStats()
-    await emailService.sendSummary(stats)
-  },
-})
-
-wireScheduler({
-  name: 'dailySummary',
-  schedule: '0 9 * * *',
-  func: dailySummary,
-})
-```
-
-### Using the Wire Object
-
-```typescript
-const weeklyCleanup = pikkuVoidFunc({
-  title: 'Weekly Cleanup',
-  func: async ({ db, logger }, _input, wire) => {
-    logger.info(`Running: ${wire.scheduledTask.name}`)
-    logger.info(`Schedule: ${wire.scheduledTask.schedule}`)
-    logger.info(`Execution time: ${wire.scheduledTask.executionTime}`)
-
-    const staleCount = await db.countStaleTodos()
-    if (staleCount === 0) {
-      wire.scheduledTask.skip('No stale todos found') // throws — nothing below runs
-    }
-
-    await db.deleteCompletedTodos({ olderThan: '30d' })
-    logger.info(`Cleaned ${staleCount} stale todos`)
-  },
-})
-
-wireScheduler({
-  name: 'weeklyCleanup',
-  schedule: '0 0 * * 0',
-  func: weeklyCleanup,
-})
-```
-
-### Scheduler Middleware
-
-```typescript
-const schedulerMetrics = pikkuMiddleware(
-  async ({ logger }, { scheduledTask }, next) => {
-    const start = Date.now()
-    logger.info(`Task started: ${scheduledTask.name}`)
-
-    try {
-      await next()
-      logger.info(`Task completed: ${scheduledTask.name}`, {
-        duration: Date.now() - start,
-      })
-    } catch (error) {
-      logger.error(`Task failed: ${scheduledTask.name}`, {
-        error: error.message,
-        duration: Date.now() - start,
-      })
-      throw error
-    }
-  }
-)
-
-wireScheduler({
-  name: 'dailySummary',
-  schedule: '0 9 * * *',
-  func: dailySummary,
-  middleware: [schedulerMetrics],
-})
-```
-
-## Complete Example
-
-```typescript
-// functions/scheduled.functions.ts
-export const dailySummary = pikkuVoidFunc({
-  title: 'Daily Summary',
-  func: async ({ db, emailService, logger }) => {
-    const stats = await db.getDailyStats()
-    await emailService.sendSummary(stats)
-    logger.info('Daily summary sent', { stats })
-  },
-})
-
-export const cleanupExpired = pikkuVoidFunc({
-  title: 'Cleanup Expired',
-  func: async ({ db, logger }, _input, wire) => {
-    const count = await db.countExpiredSessions()
-    if (count === 0) {
-      wire.scheduledTask.skip('No expired sessions') // throws — nothing below runs
-    }
-    await db.deleteExpiredSessions()
-    logger.info(`Cleaned ${count} expired sessions`)
-  },
-})
-
-export const syncInventory = pikkuVoidFunc({
-  title: 'Sync Inventory',
-  func: async ({ inventoryApi, db, logger }) => {
-    const updates = await inventoryApi.getChanges()
-    await db.applyInventoryUpdates(updates)
-    logger.info(`Synced ${updates.length} inventory changes`)
-  },
-})
-
-// wirings/scheduler.wiring.ts
-wireScheduler({
-  name: 'dailySummary',
-  schedule: '0 9 * * *',
-  func: dailySummary,
-})
-wireScheduler({
-  name: 'cleanupExpired',
-  schedule: '0 */6 * * *',
-  func: cleanupExpired,
-})
-wireScheduler({
-  name: 'syncInventory',
-  schedule: '*/15 * * * *',
-  func: syncInventory,
-})
-```

package/skills/pikku-tag-middleware/SKILL.md

@@ -1,14 +0,0 @@
----
-name: pikku-tag-middleware
-description: 'Deprecated — use pikku-middleware instead. Tag middleware (addTagMiddleware) is now documented as a section within the pikku-middleware skill, alongside global HTTP middleware, execution order, and the service-to-service bearer auth pattern.'
----
-
-# 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
-- Service-to-service bearer auth pattern
-- Session-setting middleware pattern