@pikku/cli 0.12.125 → 0.12.126

package/surface.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.12.125",
+  "version": "0.12.126",
   "entryPoints": [
     {
       "id": "app",
@@ -2132,17 +2132,20 @@
                   "doc": "Hosts this secret may be sent to, e.g. `['api.notion.com']` or `'*.notion.com'`. Omitted means unrestricted unless `config.secrets.requireAllowedHosts` is set."
                 },
                 {
-                  "line": "description?: string"
+                  "line": "description?: string",
+                  "doc": "What this secret is for, shown beside the field someone has to fill in."
                 },
                 {
-                  "line": "displayName: string"
+                  "line": "displayName: string",
+                  "doc": "How the secret is labelled wherever a person is asked to supply it."
                 },
                 {
                   "line": "docsUrl?: string",
                   "doc": "Where a user goes to obtain this value, surfaced beside a missing one."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE."
                 },
                 {
                   "line": "optional?: boolean",
@@ -2153,10 +2156,12 @@
                   "doc": "Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`."
                 },
                 {
-                  "line": "schema: T"
+                  "line": "schema: T",
+                  "doc": "The shape of the value, as a schema. This is what types `getSecret`'s result — pass the schema itself, not an instance of it."
                 },
                 {
-                  "line": "secretId: string"
+                  "line": "secretId: string",
+                  "doc": "The id under the backing store, which is where the value actually lives."
                 }
               ],
               "examples": [
@@ -2614,21 +2619,24 @@
               "docs": "What a gateway integration implements: parse an incoming event into a\nmessage, send one back, and open and close the connection.",
               "members": [
                 {
-                  "line": "close: () => Promise<void>"
+                  "line": "close: () => Promise<void>",
+                  "doc": "Called by GatewayService.stop(); release the connection init() opened."
                 },
                 {
                   "line": "init: (onMessage: (data: unknown) => Promise<void>) => Promise<void>",
                   "doc": "Called by GatewayService.start(); must call onMessage per incoming event."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "Identifies the gateway in wirings and logs, e.g. `'slack'`."
                 },
                 {
                   "line": "parse: (data: unknown) => GatewayInboundMessage | null",
                   "doc": "Return null to ignore the event, e.g. a delivery receipt."
                 },
                 {
-                  "line": "send: (senderId: string, message: GatewayOutboundMessage) => Promise<void>"
+                  "line": "send: (senderId: string, message: GatewayOutboundMessage) => Promise<void>",
+                  "doc": "Deliver a reply back to the sender the message came from."
                 },
                 {
                   "line": "verifyWebhook?: ((data: unknown, request?: PikkuHTTPRequest) => WebhookVerificationResult | Promise<WebhookVerificationResult>)",
@@ -2647,20 +2655,24 @@
               "docs": "One message arriving from a gateway, normalised: who sent it, in which\nconversation, and what they said.",
               "members": [
                 {
-                  "line": "attachments?: GatewayAttachment[]"
+                  "line": "attachments?: GatewayAttachment[]",
+                  "doc": "Files and media that came with the message."
                 },
                 {
-                  "line": "metadata?: Record<string, unknown>"
+                  "line": "metadata?: Record<string, unknown>",
+                  "doc": "Anything else the adapter wants to carry through to the wiring."
                 },
                 {
-                  "line": "raw: unknown"
+                  "line": "raw: unknown",
+                  "doc": "The provider's own event, untouched, for anything this shape drops."
                 },
                 {
                   "line": "senderId: string",
                   "doc": "Platform-specific: a phone number, a Slack user id, and so on."
                 },
                 {
-                  "line": "text: string"
+                  "line": "text: string",
+                  "doc": "What they said, as plain text, with the provider's markup stripped."
                 }
               ]
             },
@@ -2675,13 +2687,16 @@
               "docs": "One message to send back through a gateway — plain text, or the provider's\nown rich content.",
               "members": [
                 {
-                  "line": "attachments?: GatewayAttachment[]"
+                  "line": "attachments?: GatewayAttachment[]",
+                  "doc": "Files and media to send alongside."
                 },
                 {
-                  "line": "richContent?: Record<string, unknown>"
+                  "line": "richContent?: Record<string, unknown>",
+                  "doc": "The provider's own rich payload, e.g. Slack blocks. Passed through as-is."
                 },
                 {
-                  "line": "text?: string"
+                  "line": "text?: string",
+                  "doc": "The reply as plain text. Every provider can render this."
                 }
               ]
             },
@@ -2778,7 +2793,8 @@
               "docs": "What a gateway's `verifyWebhook` returns — verified, with the response the\nprovider expects back, or not.",
               "members": [
                 {
-                  "line": "verified: boolean"
+                  "line": "verified: boolean",
+                  "doc": "True when the request really came from the provider. False when the signature or challenge did not check out."
                 }
               ]
             },
@@ -3598,19 +3614,24 @@
               "signature": "(config: Parameters<typeof corePikkuAgentJudge<Services>>[0]) => PikkuAgentScorer<Services>",
               "members": [
                 {
-                  "line": "description: string"
+                  "line": "description: string",
+                  "doc": "What this judge grades, in one line, for whoever reads the score later."
                 },
                 {
-                  "line": "goal: string"
+                  "line": "goal: string",
+                  "doc": "The rubric: what a good answer looks like, phrased as the goal it should meet."
                 },
                 {
-                  "line": "model: string"
+                  "line": "model: string",
+                  "doc": "The model that grades, e.g. `'claude-sonnet-4-5'`. Not the model under test."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "Identifies the judge in results and in the Console. Unique per project."
                 },
                 {
-                  "line": "prompt?: ((input: ScorerInput) => string)"
+                  "line": "prompt?: ((input: ScorerInput) => string)",
+                  "doc": "Replaces the generated rubric prompt outright, for framing `goal` cannot express. The `{ score, reason }` response is still forced."
                 },
                 {
                   "line": "requiresReference?: boolean",
@@ -3640,10 +3661,12 @@
               "signature": "(config: Parameters<typeof corePikkuAgentScorer<Services>>[0]) => PikkuAgentScorer<Services>",
               "members": [
                 {
-                  "line": "description: string"
+                  "line": "description: string",
+                  "doc": "What this scorer grades, in one line, for whoever reads the score later."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "Identifies the scorer in results and in the Console. Unique per project."
                 },
                 {
                   "line": "requiresReference?: boolean",
@@ -3654,7 +3677,8 @@
                   "doc": "0..1 fraction of live runs to grade. Defaults to all of them."
                 },
                 {
-                  "line": "score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>"
+                  "line": "score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>",
+                  "doc": "The grade itself: read the finished run and return `{ score, reason }`. Runs in-process, so it may use your own services."
                 }
               ],
               "examples": [
@@ -8578,17 +8602,20 @@
                   "doc": "Hosts this secret may be sent to, e.g. `['api.notion.com']` or `'*.notion.com'`. Omitted means unrestricted unless `config.secrets.requireAllowedHosts` is set."
                 },
                 {
-                  "line": "description?: string"
+                  "line": "description?: string",
+                  "doc": "What this secret is for, shown beside the field someone has to fill in."
                 },
                 {
-                  "line": "displayName: string"
+                  "line": "displayName: string",
+                  "doc": "How the secret is labelled wherever a person is asked to supply it."
                 },
                 {
                   "line": "docsUrl?: string",
                   "doc": "Where a user goes to obtain this value, surfaced beside a missing one."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE."
                 },
                 {
                   "line": "optional?: boolean",
@@ -8599,10 +8626,12 @@
                   "doc": "Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`."
                 },
                 {
-                  "line": "schema: T"
+                  "line": "schema: T",
+                  "doc": "The shape of the value, as a schema. This is what types `getSecret`'s result — pass the schema itself, not an instance of it."
                 },
                 {
-                  "line": "secretId: string"
+                  "line": "secretId: string",
+                  "doc": "The id under the backing store, which is where the value actually lives."
                 }
               ],
               "examples": [
@@ -8689,17 +8718,20 @@
                   "doc": "Hosts this secret may be sent to, e.g. `['api.notion.com']` or `'*.notion.com'`. Omitted means unrestricted unless `config.secrets.requireAllowedHosts` is set."
                 },
                 {
-                  "line": "description?: string"
+                  "line": "description?: string",
+                  "doc": "What this secret is for, shown beside the field someone has to fill in."
                 },
                 {
-                  "line": "displayName: string"
+                  "line": "displayName: string",
+                  "doc": "How the secret is labelled wherever a person is asked to supply it."
                 },
                 {
                   "line": "docsUrl?: string",
                   "doc": "Where a user goes to obtain this value, surfaced beside a missing one."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE."
                 },
                 {
                   "line": "optional?: boolean",
@@ -8710,10 +8742,12 @@
                   "doc": "Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`."
                 },
                 {
-                  "line": "schema: T"
+                  "line": "schema: T",
+                  "doc": "The shape of the value, as a schema. This is what types `getSecret`'s result — pass the schema itself, not an instance of it."
                 },
                 {
-                  "line": "secretId: string"
+                  "line": "secretId: string",
+                  "doc": "The id under the backing store, which is where the value actually lives."
                 }
               ],
               "examples": [
@@ -9805,19 +9839,24 @@
               "signature": "(config: Parameters<typeof corePikkuAgentJudge<Services>>[0]) => PikkuAgentScorer<Services>",
               "members": [
                 {
-                  "line": "description: string"
+                  "line": "description: string",
+                  "doc": "What this judge grades, in one line, for whoever reads the score later."
                 },
                 {
-                  "line": "goal: string"
+                  "line": "goal: string",
+                  "doc": "The rubric: what a good answer looks like, phrased as the goal it should meet."
                 },
                 {
-                  "line": "model: string"
+                  "line": "model: string",
+                  "doc": "The model that grades, e.g. `'claude-sonnet-4-5'`. Not the model under test."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "Identifies the judge in results and in the Console. Unique per project."
                 },
                 {
-                  "line": "prompt?: ((input: ScorerInput) => string)"
+                  "line": "prompt?: ((input: ScorerInput) => string)",
+                  "doc": "Replaces the generated rubric prompt outright, for framing `goal` cannot express. The `{ score, reason }` response is still forced."
                 },
                 {
                   "line": "requiresReference?: boolean",
@@ -9847,10 +9886,12 @@
               "signature": "(config: Parameters<typeof corePikkuAgentScorer<Services>>[0]) => PikkuAgentScorer<Services>",
               "members": [
                 {
-                  "line": "description: string"
+                  "line": "description: string",
+                  "doc": "What this scorer grades, in one line, for whoever reads the score later."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "Identifies the scorer in results and in the Console. Unique per project."
                 },
                 {
                   "line": "requiresReference?: boolean",
@@ -9861,7 +9902,8 @@
                   "doc": "0..1 fraction of live runs to grade. Defaults to all of them."
                 },
                 {
-                  "line": "score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>"
+                  "line": "score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>",
+                  "doc": "The grade itself: read the finished run and return `{ score, reason }`. Runs in-process, so it may use your own services."
                 }
               ],
               "examples": [
@@ -10053,19 +10095,24 @@
               "signature": "(config: Parameters<typeof corePikkuAgentJudge<Services>>[0]) => PikkuAgentScorer<Services>",
               "members": [
                 {
-                  "line": "description: string"
+                  "line": "description: string",
+                  "doc": "What this judge grades, in one line, for whoever reads the score later."
                 },
                 {
-                  "line": "goal: string"
+                  "line": "goal: string",
+                  "doc": "The rubric: what a good answer looks like, phrased as the goal it should meet."
                 },
                 {
-                  "line": "model: string"
+                  "line": "model: string",
+                  "doc": "The model that grades, e.g. `'claude-sonnet-4-5'`. Not the model under test."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "Identifies the judge in results and in the Console. Unique per project."
                 },
                 {
-                  "line": "prompt?: ((input: ScorerInput) => string)"
+                  "line": "prompt?: ((input: ScorerInput) => string)",
+                  "doc": "Replaces the generated rubric prompt outright, for framing `goal` cannot express. The `{ score, reason }` response is still forced."
                 },
                 {
                   "line": "requiresReference?: boolean",
@@ -10096,10 +10143,12 @@
               "signature": "(config: Parameters<typeof corePikkuAgentScorer<Services>>[0]) => PikkuAgentScorer<Services>",
               "members": [
                 {
-                  "line": "description: string"
+                  "line": "description: string",
+                  "doc": "What this scorer grades, in one line, for whoever reads the score later."
                 },
                 {
-                  "line": "name: string"
+                  "line": "name: string",
+                  "doc": "Identifies the scorer in results and in the Console. Unique per project."
                 },
                 {
                   "line": "requiresReference?: boolean",
@@ -10110,7 +10159,8 @@
                   "doc": "0..1 fraction of live runs to grade. Defaults to all of them."
                 },
                 {
-                  "line": "score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>"
+                  "line": "score: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>",
+                  "doc": "The grade itself: read the finished run and return `{ score, reason }`. Runs in-process, so it may use your own services."
                 }
               ],
               "examples": [