@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-service-backends/references/aws.md

@@ -0,0 +1,106 @@
+# AWS (`@pikku/aws-services`)
+
+```bash
+yarn add @pikku/aws-services
+```
+
+AWS-backed implementations of the content, queue, and secret interfaces.
+
+## `S3Content` — ContentService
+
+```typescript
+import { S3Content } from '@pikku/aws-services'
+
+const content = new S3Content(
+  config: { bucketName: string; region: string; endpoint?: string },
+  logger: Logger,
+  signConfig: { keyPairId: string; privateKey: string }
+)
+```
+
+`endpoint` is what points the client at LocalStack or an S3-compatible store.
+
+Every method takes a single **args object**, matching the shared `ContentService`
+interface. None of them are positional:
+
+- `signURL({ url, dateLessThan, dateGreaterThan? }): Promise<string>` — CloudFront-sign an absolute URL
+- `signContentKey({ bucket, contentKey, dateLessThan, dateGreaterThan? }): Promise<string>`
+- `getUploadURL({ bucket, fileKey, contentType, visibility? }): Promise<{ uploadUrl, assetKey }>` — `visibility` is ignored
+- `readFile({ bucket, key }): Promise<ReadableStream | NodeJS.ReadableStream>`
+- `readFileAsBuffer({ bucket, key }): Promise<Buffer>`
+- `writeFile({ bucket, key, stream }): Promise<boolean>`
+- `copyFile({ bucket, key, fromAbsolutePath }): Promise<boolean>`
+- `deleteFile({ bucket, key }): Promise<boolean>`
+
+`signContentKey` builds `https://<bucketName>/<bucket>/<contentKey>` — it uses
+`bucketName` as the **host**. For signed content that value must therefore be
+your CloudFront domain, not a plain bucket name, which means the same config
+field is doing two jobs.
+
+Presigned upload URLs expire after a fixed **3600s**, not configurable through
+the service.
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const content = new S3Content(
+    { bucketName: config.s3Bucket, region: config.awsRegion },
+    logger,
+    { keyPairId: config.cfKeyPairId, privateKey: config.cfPrivateKey }
+  )
+  return { config, logger, content }
+})
+```
+
+## `SQSQueueService` — QueueService
+
+```typescript
+import { SQSQueueService } from '@pikku/aws-services'
+
+const queue = new SQSQueueService({
+  region: string,
+  queueUrlPrefix: string, // e.g. 'https://sqs.us-east-1.amazonaws.com/123456789/'
+  endpoint?: string,      // LocalStack or a custom SQS endpoint
+})
+```
+
+- `add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>` — returns SQS's `MessageId`
+- `getJob()` — always **throws**
+
+The queue URL is `queueUrlPrefix + queueName`, so the name in `wireQueueWorker`
+has to match the SQS queue exactly.
+
+Constraints inherited from SQS, enforced in `add`:
+
+- `options.delay` is in **milliseconds**, floored to whole seconds. Over
+  900_000ms (15 minutes) or negative throws before the message is sent.
+- Standard queues only — no FIFO, so no `MessageGroupId` and no ordering
+  guarantee.
+- `data` is `JSON.stringify`d, which is where a `Date` or a `Map` quietly
+  degrades.
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const queue = new SQSQueueService({
+    region: config.awsRegion,
+    queueUrlPrefix: config.sqsUrlPrefix,
+  })
+  return { config, queue }
+})
+```
+
+## `AWSSecrets` — SecretService
+
+```typescript
+import { AWSSecrets } from '@pikku/aws-services'
+
+const secrets = new AWSSecrets({ awsRegion: 'eu-west-2' })
+```
+
+`AWSConfig` has one field, `awsRegion` — there is no credentials option; the
+SDK's default provider chain (instance role, env, profile) supplies those.
+
+- `getSecret<T = string>(SecretId: string): Promise<SecretValue<T>>` — a JSON secret is parsed automatically, so pass a shape as `T` (a non-JSON value comes back as the raw string). The result is a branded `SecretValue`, not a bare value — reveal it where it is used rather than passing it through logs
+- `getSecrets<T>(SecretIds: (keyof T & string)[]): Promise<Partial<T>>` — missing keys are omitted rather than thrown
+- `hasSecret(SecretId: string): Promise<boolean>` — performs a full fetch
+- `setSecret` / `deleteSecret` — **not implemented**; they throw

package/skills/pikku-service-backends/references/backblaze.md

@@ -0,0 +1,57 @@
+# Backblaze B2 (`@pikku/backblaze`)
+
+```bash
+yarn add @pikku/backblaze
+```
+
+`B2Content` implements `ContentService` over Backblaze B2.
+
+```typescript
+import { B2Content } from '@pikku/backblaze'
+
+const content = new B2Content(config: B2ContentConfig, logger: Logger)
+```
+
+`B2ContentConfig` has exactly three fields — `applicationKeyId`, `applicationKey`
+and `bucketId`. There is no `cdnUrl`: downloads are served from the `downloadUrl`
+B2 returns at authorization.
+
+Every method takes a single **args object**, matching the shared `ContentService`
+interface. None of them are positional:
+
+- `signContentKey({ bucket, contentKey, dateLessThan }): Promise<string>` — a full download URL with an `Authorization` query param
+- `signURL({ url, dateLessThan }): Promise<string>` — re-signs an existing `/file/` URL; a URL with no `/file/` segment is returned untouched
+- `getUploadURL({ bucket, fileKey, contentType, visibility? }): Promise<UploadURLResult>` — `visibility` is ignored
+- `writeFile({ bucket, key, stream }): Promise<boolean>`
+- `copyFile({ bucket, key, fromAbsolutePath }): Promise<boolean>`
+- `readFile({ bucket, key }): Promise<ReadableStream | NodeJS.ReadableStream>`
+- `readFileAsBuffer({ bucket, key }): Promise<Buffer>`
+- `deleteFile({ bucket, key }): Promise<boolean>`
+
+Because `writeFile` drains the whole stream into a `Buffer` before uploading
+(B2's upload endpoint needs a SHA-1 and a content length up front), large uploads
+should go through `getUploadURL` and be sent by the client directly.
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const content = new B2Content(
+    {
+      applicationKeyId: config.b2KeyId,
+      applicationKey: config.b2AppKey,
+      bucketId: config.b2BucketId,
+    },
+    logger
+  )
+  return { config, logger, content }
+})
+```
+
+```typescript
+await content.writeFile({ bucket: 'avatars', key: `${userId}.png`, stream })
+const url = await content.signContentKey({
+  bucket: 'avatars',
+  contentKey: `${userId}.png`,
+  dateLessThan: new Date(Date.now() + 60_000),
+})
+```

package/skills/pikku-service-backends/references/mongodb.md

@@ -0,0 +1,90 @@
+# MongoDB (`@pikku/mongodb`)
+
+```bash
+yarn add @pikku/mongodb
+```
+
+## `PikkuMongoDB` — connection wrapper
+
+Every service below takes a `Db`, so the wrapper is constructed and initialised
+first.
+
+```typescript
+import { PikkuMongoDB } from '@pikku/mongodb'
+
+const mongo = new PikkuMongoDB(
+  logger: Logger,
+  clientOrUri: MongoClient | string,
+  dbName: string,
+  options?: MongoClientOptions
+)
+
+await mongo.init()
+mongo.db  // Db instance for queries
+await mongo.close()
+```
+
+## Available services
+
+| Service | Interface | Purpose |
+| --- | --- | --- |
+| `MongoDBChannelStore` | `ChannelStore` | WebSocket channel state persistence |
+| `MongoDBEventHubStore` | `EventHubStore` | Event hub state persistence |
+| `MongoDBWorkflowService` | `PikkuWorkflowService` | Workflow definition storage |
+| `MongoDBWorkflowRunService` | `WorkflowRunService` | Workflow execution tracking |
+| `MongoDBDeploymentService` | `DeploymentService` | Deployment state management |
+| `MongoDBAgentStorageService` | `AgentStorageService`, `AgentRunStateService` | AI conversation/run storage |
+| `MongoDBAgentRunService` | `AgentRunService` | Agent execution tracking |
+| `MongoDBSecretService` | `SecretService` | Encrypted secret storage (envelope encryption) |
+| `MongoDBSessionStore` | `SessionStore` | Persisted user sessions |
+
+All of them take a `Db` in the constructor and have an `init()` method that
+creates the collections and indexes. **Await it** — a service used without it
+behaves like an unindexed collection.
+
+## `MongoDBSecretService`
+
+Envelope encryption: `key` derives the KEK that wraps each secret's own DEK.
+Keeping `previousKey` set is what makes `rotateKEK()` possible — it re-wraps
+every secret onto the current key and returns the new version.
+
+```typescript
+import { MongoDBSecretService } from '@pikku/mongodb'
+
+const secrets = new MongoDBSecretService(mongo.db, {
+  key: 'your-key-encryption-passphrase',
+  keyVersion: 2, // defaults to 1
+  previousKey: 'the-passphrase-you-are-rotating-away-from',
+  audit: true, // log write/delete/rotate through the audit sink
+  auditReads: false, // reads too — noisy, off by default
+})
+await secrets.init()
+
+await secrets.setSecret('api-key', { key: 'sk-...' })
+const value = await secrets.getSecret<{ key: string }>('api-key')
+await secrets.rotateKEK()
+```
+
+## Full setup
+
+```typescript
+import {
+  PikkuMongoDB,
+  MongoDBChannelStore,
+  MongoDBWorkflowService,
+} from '@pikku/mongodb'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const mongo = new PikkuMongoDB(logger, config.mongoUri, 'myapp')
+  await mongo.init()
+
+  const channelStore = new MongoDBChannelStore(mongo.db)
+  await channelStore.init()
+
+  const workflowService = new MongoDBWorkflowService(mongo.db)
+  await workflowService.init()
+
+  return { config, logger, database: mongo, channelStore, workflowService }
+})
+```

package/skills/pikku-service-backends/references/redis.md

@@ -0,0 +1,75 @@
+# Redis (`@pikku/redis`)
+
+```bash
+yarn add @pikku/redis
+```
+
+Redis-backed implementations of Pikku's core service interfaces, using
+[ioredis](https://github.com/redis/ioredis). Every service accepts a Redis
+connection — an ioredis `Redis` instance, `RedisOptions`, or a connection
+string — in its constructor. None of them need an `init()` call.
+
+| Service | Interface | Purpose |
+| --- | --- | --- |
+| `RedisChannelStore` | `ChannelStore` | WebSocket channel state persistence |
+| `RedisEventHubStore` | `EventHubStore` | Event hub state persistence |
+| `RedisWorkflowService` | `PikkuWorkflowService` | Workflow definition storage |
+| `RedisWorkflowRunService` | `WorkflowRunService` | Workflow execution tracking |
+| `RedisDeploymentService` | `DeploymentService` | Deployment state management |
+| `RedisAgentRunService` | `AgentRunService` | Agent execution tracking |
+| `RedisSecretService` | `SecretService` | Encrypted secret storage (envelope encryption) |
+| `RedisSessionStore` | `SessionStore` | Persisted user sessions |
+
+There is no Redis implementation of `AgentStorageService` — AI conversation
+storage is MongoDB-only.
+
+## `RedisSecretService`
+
+Envelope encryption: `key` derives the KEK that wraps each secret's own DEK.
+Keeping `previousKey` set is what makes `rotateKEK()` possible — it re-wraps
+every secret onto the current key and returns the new version.
+
+```typescript
+import { RedisSecretService } from '@pikku/redis'
+
+const secrets = new RedisSecretService(
+  connectionOrConfig: Redis | RedisOptions | string,
+  config: {
+    key: string          // the KEK passphrase
+    keyVersion?: number  // defaults to 1
+    previousKey?: string // required to rotate
+    keyPrefix?: string   // namespaces the redis keys
+  }
+)
+
+await secrets.getSecret<T = string>(key: string): Promise<T>
+await secrets.getSecrets<T>(keys: (keyof T & string)[]): Promise<Partial<T>>
+await secrets.hasSecret(key: string): Promise<boolean>
+await secrets.setSecret(key: string, value: unknown): Promise<void>
+await secrets.deleteSecret(key: string): Promise<void>
+await secrets.rotateKEK(): Promise<number>
+await secrets.close(): Promise<void>
+```
+
+## Full setup
+
+```typescript
+import {
+  RedisChannelStore,
+  RedisWorkflowService,
+  RedisSecretService,
+} from '@pikku/redis'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+
+  const channelStore = new RedisChannelStore(config.redisUrl)
+  const workflowService = new RedisWorkflowService(config.redisUrl)
+
+  const secrets = new RedisSecretService(config.redisUrl, {
+    key: config.kekPassphrase,
+  })
+
+  return { config, logger, channelStore, workflowService, secrets }
+})
+```

package/skills/pikku-service-backends/references/schema.md

@@ -0,0 +1,63 @@
+# Schema validation (`@pikku/schema-ajv`, `@pikku/schema-cfworker`)
+
+Two implementations of `SchemaService` from `@pikku/core`. Pikku uses whichever
+one is wired to validate function inputs and outputs against the schemas codegen
+derives from your function definitions.
+
+```bash
+yarn add @pikku/schema-ajv       # default for Node.js
+yarn add @pikku/schema-cfworker  # Cloudflare Workers
+```
+
+Both expose the same four methods:
+
+- `compileSchema(name: string, schema: any): void` — compile and register under `name`
+- `validateSchema(schemaName: string, json: any): void` — throws on failure
+- `getSchemaNames(): Set<string>`
+- `getSchemaKeys(schemaName: string): string[]` — top-level property keys, or `[]` if the schema has no `properties`
+
+On `compileSchema` the first argument is the **name** and the second the schema —
+the parameter is called `schema` in the source, which reads backwards.
+
+## `AjvSchemaService`
+
+```typescript
+import { AjvSchemaService } from '@pikku/schema-ajv'
+
+const schema = new AjvSchemaService(logger: Logger)
+```
+
+Backed by [AJV](https://ajv.js.org/).
+
+- **AJV is a module-level singleton**, shared by every `AjvSchemaService` you
+  construct, so compiled schema names are global to the process.
+- **`useDefaults: true` mutates the validated object**, filling in schema
+  defaults in place.
+- `ajv-formats` is registered, so `format` keywords (`email`, `uuid`,
+  `date-time`) are enforced.
+
+## `CFWorkerSchemaService`
+
+```typescript
+import { CFWorkerSchemaService } from '@pikku/schema-cfworker'
+
+const schema = new CFWorkerSchemaService(logger: Logger)
+```
+
+Backed by [@cfworker/json-schema](https://github.com/cfworker/cfworker), which
+uses no `eval` or `new Function` and so runs where AJV cannot.
+
+- Each validator gets a **deep clone** of the schema (`@cfworker/json-schema`
+  mutates what it is given, which throws on a frozen generated object).
+- A compile failure throws `Error('Failed to compile schema: <name>')` with the
+  underlying cause swallowed — check the schema by hand when you see it.
+
+## Wiring either one
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new ConsoleLogger()
+  const schema = new AjvSchemaService(logger)
+  return { config, logger, schema }
+})
+```