@pikku/cli 0.12.90 → 0.12.92

package/dist/src/functions/wirings/scenarios/serialize-scenario-functions.js

@@ -1,104 +0,0 @@
-/**
- * Generate the scenario instrumentation functions (`pikku scenario` coverage
- * snapshots and stub-call inspection) into the project scaffold, so scenario
- * runs work against any server without requiring the console addon.
- */
-export const serializeScenarioFunctions = (pathToPikkuTypes, requireAuth = true) => {
-    const authFlag = requireAuth ? 'true' : 'false';
-    const schemas = `/**
- * Auto-generated scenario instrumentation schemas
- * Do not edit manually - regenerate with 'npx pikku'
- */
-import { z } from 'zod'
-
-export const StubCallsQuery = z.object({
-  service: z.string().optional(),
-})
-
-export const Enabled = z.object({ enabled: z.boolean() })
-`;
-    const functions = `/**
- * Auto-generated scenario instrumentation functions
- * Do not edit manually - regenerate with 'npx pikku'
- */
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { pikkuFunc } from '${pathToPikkuTypes}'
-import {
-  getStubTracker,
-  isTestRun,
-  type CoverageFunctionMeta,
-} from '@pikku/core/services'
-import { StubCallsQuery, Enabled } from './scenarios.schemas.gen.js'
-
-export const pikkuScenarioTakeLiveCoverage = pikkuFunc({
-  tags: ['pikku'],
-  title: 'Take Live Coverage',
-  description:
-    'Snapshots the live coverage collected since the server started (or since the last reset) — V8 precise coverage on Node, istanbul instrumentation on Bun — and maps it onto function body spans. Returns null unless the server was started with coverage enabled (pikku dev --coverage).',
-  expose: true,
-  auth: ${authFlag},
-  func: async ({ coverageService, metaService }) => {
-    if (!coverageService?.takeReport || !metaService?.basePath) return null
-    let functionsMeta: Record<string, CoverageFunctionMeta>
-    try {
-      const content = await readFile(
-        join(
-          metaService.basePath,
-          'function',
-          'pikku-functions-meta-verbose.gen.json'
-        ),
-        'utf-8'
-      )
-      functionsMeta = JSON.parse(content)
-    } catch {
-      return null
-    }
-    return await coverageService.takeReport(functionsMeta)
-  },
-})
-
-export const pikkuScenarioResetLiveCoverage = pikkuFunc({
-  tags: ['pikku'],
-  title: 'Reset Live Coverage',
-  description:
-    'Clears V8 precise-coverage call counts so the next takeLiveCoverage snapshot is attributable to a single scenario run. Reports enabled: false when the server was not started with coverage enabled.',
-  expose: true,
-  auth: ${authFlag},
-  output: Enabled,
-  func: async ({ coverageService }) => {
-    if (!coverageService) return { enabled: false }
-    await coverageService.reset()
-    return { enabled: true }
-  },
-})
-
-export const pikkuScenarioResetStubs = pikkuFunc({
-  tags: ['pikku'],
-  title: 'Reset Stubs',
-  description:
-    'Clears recorded stub calls so the next getStubCalls result is attributable to a single scenario run. Reports enabled: false when the server was not started in test mode.',
-  expose: true,
-  auth: ${authFlag},
-  output: Enabled,
-  func: async () => {
-    getStubTracker().reset()
-    return { enabled: isTestRun() }
-  },
-})
-
-export const pikkuScenarioGetStubCalls = pikkuFunc({
-  tags: ['pikku'],
-  title: 'Get Stub Calls',
-  description:
-    'Returns calls recorded against stubbed/spied services (via the stub()/spy() core utils). Empty unless the server records service calls (pikku dev --test).',
-  expose: true,
-  auth: ${authFlag},
-  input: StubCallsQuery,
-  func: async (_services, data) => {
-    return getStubTracker().getCalls(data?.service ?? undefined)
-  },
-})
-`;
-    return { schemas, functions };
-};

package/skills/pikku-addon/SKILL.md

@@ -1,243 +0,0 @@
----
-name: pikku-addon
-description: >-
-  Use when creating or consuming reusable function packages (addons) in Pikku. Covers wireAddon,
-  addon(), pikkuAddonServices, pikkuAddonWireServices, addon package structure, and cross-project
-  function sharing. TRIGGER when: code uses wireAddon/addon()/pikkuAddonServices, user asks about
-  addons, reusable function packages, cross-project sharing, or addon package structure. DO NOT
-  TRIGGER when: user asks about internal function composition (use pikku-rpc) or general function
-  definitions (use pikku-concepts).
-installGroups: [core]
----
-
-# Pikku Addons
-
-## 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.
-
-Addons are reusable Pikku function packages that can be shared across projects. They bundle functions, services, secrets, and variables into a self-contained NPM package.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and addons
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### `wireAddon(config)`
-
-Register an addon in the consuming project:
-
-```typescript
-import { wireAddon } from '#pikku'
-
-wireAddon({
-  name: string,                    // Namespace for addon functions (e.g. 'todos')
-  package: string,                 // NPM package name (e.g. '@pikku/addon-todos')
-  rpcEndpoint?: string,            // Optional remote RPC endpoint for distributed execution
-  auth?: boolean,                  // Whether addon functions require authentication
-  tags?: string[],                 // Tags applied to all addon functions
-  secretOverrides?: Record<string, string>,    // Remap secret names
-  variableOverrides?: Record<string, string>,  // Remap variable names
-})
-```
-
-### `addon(name)`
-
-Type-safe reference to an addon function — use when wiring to HTTP, agents, etc.:
-
-```typescript
-import { addon } from '#pikku'
-
-addon('todos:addTodo') // Returns a typed function config
-addon('emails:sendEmail') // Namespace:functionName format
-```
-
-### `pikkuAddonServices(factory)`
-
-Define singleton services for an addon package (created once at startup):
-
-```typescript
-import { pikkuAddonServices } from '#pikku'
-
-export const createSingletonServices = pikkuAddonServices(
-  async (config, parentServices?) => {
-    // parentServices: logger, variables, secrets from the consuming app
-    return {
-      myStore: new MyStore(),
-    }
-  }
-)
-```
-
-### `pikkuAddonWireServices(factory)`
-
-Define per-request services for an addon package (created fresh per HTTP request, queue job, etc.):
-
-```typescript
-import { pikkuAddonWireServices } from '#pikku'
-
-export const createWireServices = pikkuAddonWireServices(
-  async (singletonServices, wire) => {
-    // wire: transport context (http, channel, session, etc.)
-    const authHeader = wire.http?.request?.header('authorization')
-    return {
-      myService: new MyService(authHeader),
-    }
-  }
-)
-```
-
-## Creating an Addon
-
-### Scaffold
-
-```bash
-npx pikku new addon
-```
-
-This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json` (`addon: true`), `tsconfig.json` (`#pikku` path mapping), `src/services.ts`, `src/functions/`, and `types/application-types.d.ts`. For the full file contents/exports you rarely hand-edit, read `references/addon-package-manifest.md`.
-
-### Services
-
-```typescript
-// src/services.ts
-import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku'
-import { TodoStore } from './todo-store.service.js'
-
-export const createSingletonServices = pikkuAddonServices(async () => {
-  const todoStore = new TodoStore()
-  return { todoStore }
-})
-
-// Optional — only needed if addon functions require per-request services
-export const createWireServices = pikkuAddonWireServices(
-  async (singletonServices, wire) => {
-    return {}
-  }
-)
-```
-
-### Functions
-
-```typescript
-// src/functions/addTodo.function.ts
-import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku'
-
-const AddTodoInput = z.object({ title: z.string() })
-const AddTodoOutput = z.object({ id: z.string(), title: z.string() })
-
-export const addTodo = pikkuSessionlessFunc({
-  description: 'Adds a new todo',
-  input: AddTodoInput,
-  output: AddTodoOutput,
-  func: async ({ todoStore }, { title }) => {
-    return todoStore.add(title)
-  },
-})
-```
-
-Optional approval gating (e.g. for agent tools) — add `approvalRequired: true` plus an `approvalDescription` resolver:
-
-```typescript
-approvalRequired: true,
-approvalDescription: async (_services, { title }) => `Add a todo called "${title}"`,
-```
-
-### Build
-
-```bash
-npx pikku all    # Generate types
-yarn tsc         # Compile TypeScript
-cp -r .pikku dist/  # Include generated files in dist
-```
-
-## Consuming an Addon
-
-### Install & Register
-
-```bash
-yarn add @my-org/addon-todos
-```
-
-```typescript
-// wirings/todos.wirings.ts
-import { wireAddon } from '#pikku'
-
-wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
-```
-
-After registration, run `npx pikku all` to generate types for the addon's functions.
-
-### Call via RPC
-
-```typescript
-export const myFunc = pikkuFunc({
-  func: async (_services, data, { rpc }) => {
-    const todo = await rpc.invoke('todos:addTodo', { title: 'Buy milk' })
-    return todo
-  },
-})
-```
-
-### Wire to HTTP
-
-```typescript
-import { wireHTTP, addon } from '#pikku'
-
-wireHTTP({
-  method: 'get',
-  route: '/todos',
-  func: addon('todos:listTodos'),
-  auth: false,
-})
-```
-
-Or batch multiple addon routes with `defineHTTPRoutes` + `wireHTTPRoutes`:
-
-```typescript
-import { wireHTTPRoutes, defineHTTPRoutes, addon } from '#pikku'
-
-const todoRoutes = defineHTTPRoutes({
-  tags: ['todos'],
-  auth: false,
-  routes: {
-    list: { method: 'get', route: '/todos', func: addon('todos:listTodos') },
-    add: { method: 'post', route: '/todos', func: addon('todos:addTodo') },
-  },
-})
-
-wireHTTPRoutes({ basePath: '/api', routes: { todos: todoRoutes } })
-```
-
-### Use in AI Agents
-
-```typescript
-import { pikkuAIAgent } from '#pikku'
-import { addon } from '#pikku'
-
-export const todoAgent = pikkuAIAgent({
-  name: 'todo-agent',
-  description: 'Manages a todo list',
-  instructions: 'You help users manage their todos.',
-  model: 'openai/gpt-4o',
-  tools: [
-    addon('todos:listTodos'),
-    addon('todos:addTodo'),
-    addon('todos:deleteTodo'),
-  ],
-  maxSteps: 5,
-})
-```

package/skills/pikku-addon/references/addon-package-manifest.md

@@ -1,63 +0,0 @@
-# Addon Package Manifest Reference
-
-`npx pikku new addon` scaffolds these files. You rarely hand-edit them — consult this when wiring exports or config by hand.
-
-## Package Structure
-
-```text
-my-addon/
-├── package.json               # Exports .pikku/* and dist/
-├── pikku.config.json          # addon: true + metadata
-├── tsconfig.json              # #pikku path mapping
-├── src/
-│   ├── services.ts            # createSingletonServices (required)
-│   └── functions/
-│       └── *.function.ts      # Function definitions
-├── types/
-│   └── application-types.d.ts # SingletonServices interface
-└── .pikku/                    # Generated (gitignored)
-```
-
-## pikku.config.json
-
-```json
-{
-  "tsconfig": "./tsconfig.json",
-  "srcDirectories": ["src", "types"],
-  "outDir": "./.pikku",
-  "addon": true,
-  "node": {
-    "displayName": "My Addon",
-    "description": "What this addon does",
-    "categories": ["General"]
-  }
-}
-```
-
-## package.json (key fields)
-
-```json
-{
-  "name": "@my-org/addon-todos",
-  "imports": {
-    "#pikku": "./.pikku/pikku-types.gen.ts",
-    "#pikku/*": "./.pikku/*"
-  },
-  "exports": {
-    ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },
-    "./.pikku/*": "./.pikku/*",
-    "./.pikku/pikku-metadata.gen.json": "./.pikku/pikku-metadata.gen.json",
-    "./.pikku/rpc/pikku-rpc-wirings-map.internal.gen.js": {
-      "types": "./.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts"
-    }
-  },
-  "files": ["dist", ".pikku"],
-  "peerDependencies": {
-    "@pikku/core": "*"
-  },
-  "scripts": {
-    "pikku": "pikku all",
-    "build": "tsc && cp -r .pikku dist/"
-  }
-}
-```

package/skills/pikku-ai-agent/SKILL.md

@@ -1,231 +0,0 @@
----
-name: pikku-ai-agent
-description: >-
-  Use when building AI agents, chatbots, or LLM-powered assistants with Pikku. Covers
-  pikkuAIAgent, tool registration, memory, streaming, and agent invocation. TRIGGER when: code
-  uses pikkuAIAgent/runAIAgent/streamAIAgent, user asks about AI agents, chatbots, LLM assistants,
-  tool-calling agents, or agent memory/streaming. DO NOT TRIGGER when: user asks about MCP tool
-  exposure (use pikku-mcp) or general function definitions (use pikku-concepts).
-installGroups: [core]
----
-
-# Pikku AI Agent Wiring
-
-## 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.
-
-Build AI agents that use Pikku functions as tools. Agents support conversation memory, streaming, and multi-step tool execution.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions that can be used as agent tools
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### `pikkuAIAgent(config)`
-
-```typescript
-import { pikkuAIAgent } from '#pikku'
-
-pikkuAIAgent({
-  name: string,                  // Unique agent identifier
-  description: string,           // What the agent does
-  instructions: string | string[],  // System prompt / behavior instructions
-  model: string,                 // LLM model (e.g. 'openai/gpt-5-mini')
-  tools?: PikkuFunc[],           // Pikku functions the agent can call
-  agents?: AIAgentConfig[],      // Sub-agents this agent can delegate to
-  memory?: {
-    storage?: string,            // Service name for persistence (e.g. 'aiStorage')
-    vector?: string,             // Vector store service name
-    embedder?: string,           // Embedding service name
-    lastMessages?: number,       // How many messages to retain in context
-    workingMemory?: ZodSchema,   // Schema for structured working memory
-  },
-  maxSteps?: number,             // Max tool-call rounds per invocation
-  temperature?: number,          // LLM temperature (0-1)
-  toolChoice?: 'auto' | 'required' | 'none',
-  input?: ZodSchema,             // Input validation schema
-  output?: ZodSchema,            // Output validation schema
-  tags?: string[],               // For grouping and middleware targeting
-  aiMiddleware?: PikkuAIMiddlewareHooks[],  // AI-specific middleware
-  middleware?: PikkuMiddleware[],
-  permissions?: PermissionGroup,
-})
-```
-
-### `runAIAgent(name, input, options)` — Non-streaming
-
-```typescript
-const result = await runAIAgent(
-  agentName,
-  {
-    message: string, // User message
-    threadId: string, // Conversation thread ID
-    resourceId: string, // User/resource identifier
-  },
-  { singletonServices }
-)
-
-result.text // Agent's text response
-result.steps // Array of tool calls made
-result.usage // Token usage { inputTokens, outputTokens }
-```
-
-### `streamAIAgent(name, input, channel, options)` — Streaming
-
-```typescript
-await streamAIAgent(
-  agentName,
-  {
-    message: string,
-    threadId: string,
-    resourceId: string,
-  },
-  channel,
-  { singletonServices }
-)
-
-// Channel receives events:
-// { type: 'step-start', stepNumber: 1 }
-// { type: 'text-delta', text: '...' }
-// { type: 'reasoning-delta', text: '...' }
-// { type: 'tool-call', toolCallId, toolName, args }
-// { type: 'tool-result', toolCallId, toolName, result }
-// { type: 'agent-call', agentName, session, input }
-// { type: 'agent-result', agentName, session, result }
-// { type: 'approval-request', toolCallId, toolName, args, reason? }
-// { type: 'usage', tokens: { input, output }, model }
-// { type: 'error', message }
-// { type: 'done' }
-```
-
-## Usage Patterns
-
-### Define an Agent
-
-```typescript
-const todoAssistant = pikkuAIAgent({
-  name: 'todo-assistant',
-  description: 'A helpful assistant that manages todos',
-  instructions:
-    'You help users manage their todo lists. Be concise and helpful.',
-  model: 'openai/gpt-5-mini',
-  tools: [listTodos, createTodo, completeTodo],
-  memory: {
-    storage: 'aiStorage',
-    lastMessages: 20,
-  },
-  maxSteps: 5,
-  temperature: 0.7,
-})
-```
-
-### Invoke Non-Streaming
-
-```typescript
-const result = await runAIAgent(
-  'todo-assistant',
-  {
-    message: 'Create a task for tomorrow: buy groceries',
-    threadId: 'thread-123',
-    resourceId: 'user-456',
-  },
-  { singletonServices }
-)
-
-console.log(result.text) // "I've created a task 'buy groceries' for tomorrow."
-console.log(result.steps) // [{ tool: 'createTodo', args: {...}, result: {...} }]
-console.log(result.usage) // { inputTokens: 150, outputTokens: 42 }
-```
-
-### Stream Responses
-
-```typescript
-await streamAIAgent(
-  'todo-assistant',
-  {
-    message: 'Create a task for tomorrow',
-    threadId: 'thread-123',
-    resourceId: 'user-456',
-  },
-  channel,
-  { singletonServices }
-)
-```
-
-## Complete Example
-
-```typescript
-// functions/todos.functions.ts
-export const listTodos = pikkuSessionlessFunc({
-  description: 'List all todo items',
-  func: async ({ db }, { status }) => {
-    return { todos: await db.listTodos(status) }
-  },
-})
-
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  func: async ({ db }, { text, priority, dueDate }) => {
-    return await db.createTodo({ text, priority, dueDate })
-  },
-})
-
-export const completeTodo = pikkuFunc({
-  description: 'Mark a todo as complete',
-  func: async ({ db }, { todoId }) => {
-    return await db.completeTodo(todoId)
-  },
-})
-
-// agents/todo-assistant.ts
-const todoAssistant = pikkuAIAgent({
-  name: 'todo-assistant',
-  description: 'A helpful assistant that manages todos',
-  instructions: `You help users manage their todo lists.
-    - Be concise and helpful
-    - When creating todos, infer priority if not specified
-    - When listing todos, summarize the results`,
-  model: 'openai/gpt-5-mini',
-  tools: [listTodos, createTodo, completeTodo],
-  memory: {
-    storage: 'aiStorage',
-    lastMessages: 20,
-  },
-  maxSteps: 5,
-  temperature: 0.7,
-})
-
-// Wire to HTTP for chat endpoint
-wireHTTP({
-  method: 'post',
-  route: '/chat',
-  func: pikkuFunc({
-    title: 'Chat',
-    func: async (services, { message, threadId }, wire) => {
-      const { session } = wire
-      return await runAIAgent(
-        'todo-assistant',
-        {
-          message,
-          threadId,
-          resourceId: session.userId,
-        },
-        { singletonServices: services }
-      )
-    },
-  }),
-})
-```