@pikku/addon-console 0.12.45 → 0.12.47

package/dist/.pikku/addon/schemas/schemas/AddonPackageInfo.schema.json

@@ -1 +1 @@
-{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "author": { "type": "string" }, "repository": { "type": "string" }, "license": { "type": "string" }, "readme": { "type": "string" }, "icon": { "type": "string" }, "publishedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "functions": { "$ref": "#/definitions/FunctionsMeta" }, "agents": { "type": "object", "additionalProperties": {} }, "secrets": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "additionalProperties": {}, "description": "OAuth2 + wire credentials the addon declares (from its own `credentials/pikku-credentials-meta.gen.json`). Entries with an `oauth2` field are OAuth integrations to connect; the rest are wire credentials." }, "variables": { "type": "object", "additionalProperties": {} }, "httpRoutes": { "$ref": "#/definitions/HTTPWiringsMeta" }, "channels": { "$ref": "#/definitions/ChannelsMeta" }, "cli": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIProgramMeta" } }, "mcp": { "anyOf": [{ "$ref": "#/definitions/McpMeta" }, { "type": "null" }] }, "schemas": { "type": "object", "additionalProperties": {} } }, "required": ["id", "name", "displayName", "version", "description", "author", "publishedAt", "updatedAt", "tags", "categories", "functions", "agents", "secrets", "credentials", "variables", "httpRoutes", "channels", "cli", "mcp", "schemas"], "additionalProperties": false, "definitions": { "FunctionsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FunctionMeta" } }, "FunctionMeta": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "functionType": { "type": "string", "enum": ["user", "inline", "helper", "remote"], "description": "`remote`: a contract with no local body, answered by a connected client." }, "funcWrapper": { "type": "string" }, "services": { "$ref": "#/definitions/FunctionServicesMeta" }, "wires": { "$ref": "#/definitions/FunctionWiresMeta" }, "inputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "outputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "isDirectFunction": { "type": "boolean" }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "bodySourceFile": { "type": "string", "description": "File containing the handler body when it differs from sourceFile (imported handlers)" }, "bodyStart": { "type": "number", "description": "1-indexed first line of the handler body (verbose meta; coverage mapping)" }, "bodyEnd": { "type": "number", "description": "1-indexed last line of the handler body (verbose meta; coverage mapping)" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "inputSchemaName": { "type": ["string", "null"] }, "outputSchemaName": { "type": ["string", "null"] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this function. All are required (AND)." }, "expose": { "type": "boolean" }, "auth": { "type": "boolean", "description": "A sessionless function's own `auth: true`. `sessionless` carries the baseline — a `pikkuFunc` always requires a session — and this carries the tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to know whether a function is gated without running it." }, "permissionsInBody": { "type": "boolean", "description": "The author's declaration that this function's permission check lives in its own body. Carries no runtime effect — it records a gate codegen cannot see, so an audit is not left to guess whether a sessionless function is open. Refused unless `allow.permissionsInBody` is set in `pikku.config.json`." }, "remote": { "type": "boolean" }, "scenarioStep": { "type": "boolean", "description": "A step RPC: invoked by name only from a scenario run and refused everywhere else, so it is never network-callable." }, "scenario": { "type": "boolean", "description": "The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`, so it is held back from the app bootstrap and from every deployed unit." }, "mcp": { "type": "boolean" }, "readonly": { "type": "boolean" }, "deploy": { "type": "string", "enum": ["serverless", "server", "auto"] }, "sessionless": { "type": "boolean" }, "workflowQueued": { "type": "boolean", "description": "When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error." }, "workflowRetries": { "type": "number", "description": "Retry count when this function is used as a workflow step." }, "workflowTimeout": { "type": "string", "description": "Timeout when this function is used as a workflow step (e.g. '30s', '5m')." }, "scenarioStepSurfaces": { "type": "array", "items": { "$ref": "#/definitions/ScenarioSurface" }, "description": "Scenario steps only: which surfaces this step declares a binding for.\n\nThe reporter derives coverage from this — a `then` with no binding for the surface the run targeted was never actually witnessed there, which is a gap worth counting rather than excusing." }, "scenarioStepRequiresActor": { "type": "boolean", "description": "Scenario steps only: this step runs as a persona, so every call site must pass one and the runner injects it as `wire.actor`.\n\nDeclared by `actor: true`, or implied by a `browser` binding — a window is opened as somebody. Absent on a step with nobody to be: an assertion over what an earlier step returned, or one posting credentials precisely because it must not reuse an actor's session." }, "scenarioStepKind": { "$ref": "#/definitions/ScenarioStepKind", "description": "Scenario steps only: who acts. Absent means `persona` — the ordinary step, and the only kind that existed before the other two.\n\nA `platform` or `addon` step is the app or a third-party system acting, and it must never reach a virtual user's catalogue. That is not tidiness: a virtual user that can invoke \"Stripe's webhook arrives\" can forge its own payment success, and every finding downstream of that is worthless." }, "scenarioStepAddon": { "type": "string", "description": "Addon steps only: the addon whose system acts — `wireAddon`'s `name`." }, "scenarioStepTemplate": { "type": "string", "description": "Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input." }, "audit": { "type": "object", "properties": { "durability": { "$ref": "#/definitions/AuditDurability" } }, "required": ["durability"], "additionalProperties": false, "description": "The function's `audit` config, resolved — `audit: true` reads as `{ durability: 'best-effort' }`. Absent means the function records nothing: `auditLog.write()` from an unmarked function is dropped with a warning, so this is the only place a reader can see which functions have a trail at all without running them.\n\nInformational. The runner resolves audit from the live function config, not from here, so meta and runtime cannot disagree about whether audit is on." }, "version": { "type": "number" }, "approvalRequired": { "type": "boolean" }, "approvalDescription": { "type": "string" }, "implementationHash": { "type": "string" }, "contractHash": { "type": "string" }, "inputHash": { "type": "string" }, "outputHash": { "type": "string" } }, "required": ["inputSchemaName", "outputSchemaName", "pikkuFuncId"] }, "FunctionServicesMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "FunctionWiresMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "wires": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "wires"], "additionalProperties": false }, "MiddlewareMetadata": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "route": { "type": "string" } }, "required": ["type", "route"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tag" }, "tag": { "type": "string" } }, "required": ["type", "tag"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false }] }, "PermissionMetadata": { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false, "description": "A reference to a permission function, resolved by name. Function-scoped only: there are no wire- or tag-level permission references." }, "ScenarioSurface": { "type": "string", "enum": ["browser", "cli", "default"], "description": "How an actor drives the system for one step.\n\nA step declares one implementation per surface it supports, and the runner picks between them — so the same ladder can run through a real browser, over the websocket, or entirely server-side.\n\n`default` is the floor: it is what every other surface falls back to, so it can never itself fall back." }, "ScenarioStepKind": { "type": "string", "enum": ["persona", "platform", "addon"], "description": "Who acts in a step.\n\n`persona` is a person driving the system through one of its surfaces — the ordinary `pikkuScenarioStep`. `platform` is the app acting on itself (\"the platform has expired the trial\"), and `addon` is a third-party system acting on it (\"Stripe's webhook arrives\"), contributed by the addon that wraps that service.\n\nThe three are separate declarations rather than a field on one, so the inspector verifies a step's kind by which function was called rather than by trusting a string literal — and so an addon package exports only addon steps, which is checkable." }, "AuditDurability": { "type": "string", "enum": ["best-effort", "transactional"] }, "HTTPWiringsMeta": { "type": "object", "properties": { "post": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "get": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "delete": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "patch": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "head": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "put": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } } }, "required": ["post", "get", "delete", "patch", "head", "put", "options"], "additionalProperties": false }, "HTTPWiringMeta": { "type": "object", "additionalProperties": false, "properties": { "route": { "type": "string" }, "method": { "$ref": "#/definitions/HTTPMethod" }, "auth": { "type": "boolean", "description": "The route's own `auth`, or the group's if the route did not set one." }, "requiresSession": { "type": "boolean", "description": "Whether reaching this route requires a session, resolved at codegen time across every layer that can demand one: the function's `sessionless`, its own `auth`, this route's `auth`, and the auth flag of the addon the function belongs to. Answering \"which routes are open?\" used to mean joining four separate places and knowing which of them wins; getting that join wrong reads an open route as a closed one." }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "headersSchemaName": { "type": "string" }, "sse": { "type": "boolean", "const": true }, "groupBasePath": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["method", "pikkuFuncId", "route"] }, "HTTPMethod": { "type": "string", "enum": ["post", "get", "delete", "patch", "head", "put", "options"] }, "HTTPFunctionMetaInputTypes": { "type": "object", "properties": { "params": { "type": "string" }, "query": { "type": "string" }, "body": { "type": "string" } }, "additionalProperties": false }, "ChannelsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMeta" } }, "ChannelMeta": { "type": "object", "properties": { "name": { "type": "string" }, "route": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "input": { "type": ["string", "null"] }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "connect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "disconnect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "message": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "messageWirings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMessageMeta" } } }, "binary": { "type": ["boolean", "null"] }, "gateway": { "type": "boolean", "description": "Set when the channel was wired by a gateway rather than declared directly." }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "channelMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["name", "route", "input", "connect", "disconnect", "message", "messageWirings"], "additionalProperties": false }, "ChannelMessageMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "CLIProgramMeta": { "type": "object", "properties": { "program": { "type": "string" }, "commands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "defaultRenderName": { "type": "string" }, "auth": { "type": "boolean", "description": "Whether the channel serving this program over a websocket requires a session. Only meaningful for the generated channel backend — a locally executed CLI has no connection to authenticate." } }, "required": ["program", "commands", "options"], "additionalProperties": false, "description": "CLI metadata collection (per program)" }, "CLICommandMeta": { "type": "object", "properties": { "parameters": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "positionals": { "type": "array", "items": { "$ref": "#/definitions/CLIPositional" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "renderName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "subcommands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "isDefault": { "type": "boolean" } }, "required": ["pikkuFuncId", "positionals", "options"], "additionalProperties": false, "description": "CLI command metadata for runtime" }, "CLIPositional": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "variadic": { "type": "boolean" } }, "required": ["name", "required"], "additionalProperties": false, "description": "Positional argument definition" }, "CLIOption": { "type": "object", "properties": { "description": { "type": "string" }, "short": { "type": "string" }, "type": { "$ref": "#/definitions/CLIOptionType" }, "default": {}, "choices": { "type": "array", "items": {} }, "required": { "type": "boolean" } }, "required": ["description"], "additionalProperties": false, "description": "CLI option definition" }, "CLIOptionType": { "type": "string", "enum": ["string", "number", "boolean", "string[]"], "description": "The shape an option's value is parsed into. `'string[]'` splits a single value on commas; `'boolean'` is a flag that consumes the next token only when it is an explicit literal (`true`/`false`/`1`/`0`/`yes`/`no`); every other type consumes one token verbatim, so a value may start with `-`. Left unset — which is the usual case — it is read from the command function's input schema, then from `default`, and otherwise falls back to `'string'`. Declare it only where neither can say: an option belonging to no function input, such as one the config factory reads straight off the CLI data." }, "McpMeta": { "type": "object", "properties": { "toolsMeta": { "$ref": "#/definitions/MCPToolMeta" }, "resourcesMeta": { "$ref": "#/definitions/MCPResourceMeta" }, "promptsMeta": { "$ref": "#/definitions/MCPPromptMeta" } }, "required": ["toolsMeta", "resourcesMeta", "promptsMeta"], "additionalProperties": false }, "MCPToolMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "streaming": { "type": "boolean" } }, "required": ["inputSchema", "name", "outputSchema", "pikkuFuncId"] } }, "MCPResourceMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "uri": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "streaming": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["description", "inputSchema", "outputSchema", "pikkuFuncId", "title", "uri"] } }, "MCPPromptMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "arguments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "description", "required"], "additionalProperties": false } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["arguments", "description", "inputSchema", "name", "outputSchema", "pikkuFuncId"] } } } }
+{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "author": { "type": "string" }, "repository": { "type": "string" }, "license": { "type": "string" }, "readme": { "type": "string" }, "icon": { "type": "string" }, "publishedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "functions": { "$ref": "#/definitions/FunctionsMeta" }, "agents": { "type": "object", "additionalProperties": {} }, "secrets": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "additionalProperties": {}, "description": "OAuth2 + wire credentials the addon declares (from its own `credentials/pikku-credentials-meta.gen.json`). Entries with an `oauth2` field are OAuth integrations to connect; the rest are wire credentials." }, "variables": { "type": "object", "additionalProperties": {} }, "httpRoutes": { "$ref": "#/definitions/HTTPWiringsMeta" }, "channels": { "$ref": "#/definitions/ChannelsMeta" }, "cli": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIProgramMeta" } }, "mcp": { "anyOf": [{ "$ref": "#/definitions/McpMeta" }, { "type": "null" }] }, "schemas": { "type": "object", "additionalProperties": {} } }, "required": ["id", "name", "displayName", "version", "description", "author", "publishedAt", "updatedAt", "tags", "categories", "functions", "agents", "secrets", "credentials", "variables", "httpRoutes", "channels", "cli", "mcp", "schemas"], "additionalProperties": false, "definitions": { "FunctionsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FunctionMeta" } }, "FunctionMeta": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "functionType": { "type": "string", "enum": ["user", "inline", "helper", "remote"], "description": "`remote`: a contract with no local body, answered by a connected client." }, "funcWrapper": { "type": "string" }, "services": { "$ref": "#/definitions/FunctionServicesMeta" }, "wires": { "$ref": "#/definitions/FunctionWiresMeta" }, "inputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "outputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "isDirectFunction": { "type": "boolean" }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "bodySourceFile": { "type": "string", "description": "File containing the handler body when it differs from sourceFile (imported handlers)" }, "bodyStart": { "type": "number", "description": "1-indexed first line of the handler body (verbose meta; coverage mapping)" }, "bodyEnd": { "type": "number", "description": "1-indexed last line of the handler body (verbose meta; coverage mapping)" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string", "description": "A human name for this wiring, shown wherever it is listed rather than called." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime." }, "summary": { "type": "string", "description": "A one-line description for listings, where the full `description` is too long." }, "description": { "type": "string", "description": "What this does, for whoever is reading the wiring rather than writing it." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Names of error classes this may throw, so each one's registered status is used instead of a 500." }, "inputSchemaName": { "type": ["string", "null"] }, "outputSchemaName": { "type": ["string", "null"] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this function. All are required (AND)." }, "expose": { "type": "boolean" }, "auth": { "type": "boolean", "description": "A sessionless function's own `auth: true`. `sessionless` carries the baseline — a `pikkuFunc` always requires a session — and this carries the tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to know whether a function is gated without running it." }, "permissionsInBody": { "type": "boolean", "description": "The author's declaration that this function's permission check lives in its own body. Carries no runtime effect — it records a gate codegen cannot see, so an audit is not left to guess whether a sessionless function is open. Refused unless `allow.permissionsInBody` is set in `pikku.config.json`." }, "remote": { "type": "boolean" }, "scenarioStep": { "type": "boolean", "description": "A step RPC: invoked by name only from a scenario run and refused everywhere else, so it is never network-callable." }, "scenario": { "type": "boolean", "description": "The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`, so it is held back from the app bootstrap and from every deployed unit." }, "mcp": { "type": "boolean" }, "readonly": { "type": "boolean" }, "deploy": { "type": "string", "enum": ["serverless", "server", "auto"] }, "sessionless": { "type": "boolean" }, "workflowQueued": { "type": "boolean", "description": "When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error." }, "workflowRetries": { "type": "number", "description": "Retry count when this function is used as a workflow step." }, "workflowTimeout": { "type": "string", "description": "Timeout when this function is used as a workflow step (e.g. '30s', '5m')." }, "scenarioStepSurfaces": { "type": "array", "items": { "$ref": "#/definitions/ScenarioSurface" }, "description": "Scenario steps only: which surfaces this step declares a binding for.\n\nThe reporter derives coverage from this — a `then` with no binding for the surface the run targeted was never actually witnessed there, which is a gap worth counting rather than excusing." }, "scenarioStepRequiresActor": { "type": "boolean", "description": "Scenario steps only: this step runs as a persona, so every call site must pass one and the runner injects it as `wire.actor`.\n\nDeclared by `actor: true`, or implied by a `browser` binding — a window is opened as somebody. Absent on a step with nobody to be: an assertion over what an earlier step returned, or one posting credentials precisely because it must not reuse an actor's session." }, "scenarioStepKind": { "$ref": "#/definitions/ScenarioStepKind", "description": "Scenario steps only: who acts. Absent means `persona` — the ordinary step, and the only kind that existed before the other two.\n\nA `platform` or `addon` step is the app or a third-party system acting, and it must never reach a virtual user's catalogue. That is not tidiness: a virtual user that can invoke \"Stripe's webhook arrives\" can forge its own payment success, and every finding downstream of that is worthless." }, "scenarioStepAddon": { "type": "string", "description": "Addon steps only: the addon whose system acts — `wireAddon`'s `name`." }, "scenarioStepTemplate": { "type": "string", "description": "Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input." }, "audit": { "type": "object", "properties": { "durability": { "$ref": "#/definitions/AuditDurability" } }, "required": ["durability"], "additionalProperties": false, "description": "The function's `audit` config, resolved — `audit: true` reads as `{ durability: 'best-effort' }`. Absent means the function records nothing: `auditLog.write()` from an unmarked function is dropped with a warning, so this is the only place a reader can see which functions have a trail at all without running them.\n\nInformational. The runner resolves audit from the live function config, not from here, so meta and runtime cannot disagree about whether audit is on." }, "version": { "type": "number" }, "approvalRequired": { "type": "boolean" }, "approvalDescription": { "type": "string" }, "implementationHash": { "type": "string" }, "contractHash": { "type": "string" }, "inputHash": { "type": "string" }, "outputHash": { "type": "string" } }, "required": ["inputSchemaName", "outputSchemaName", "pikkuFuncId"] }, "FunctionServicesMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "FunctionWiresMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "wires": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "wires"], "additionalProperties": false }, "MiddlewareMetadata": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "route": { "type": "string" } }, "required": ["type", "route"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tag" }, "tag": { "type": "string" } }, "required": ["type", "tag"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false }] }, "PermissionMetadata": { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false, "description": "A reference to a permission function, resolved by name. Function-scoped only: there are no wire- or tag-level permission references." }, "ScenarioSurface": { "type": "string", "enum": ["browser", "cli", "default"], "description": "How an actor drives the system for one step.\n\nA step declares one implementation per surface it supports, and the runner picks between them — so the same ladder can run through a real browser, over the websocket, or entirely server-side.\n\n`default` is the floor: it is what every other surface falls back to, so it can never itself fall back." }, "ScenarioStepKind": { "type": "string", "enum": ["persona", "platform", "addon"], "description": "Who acts in a step.\n\n`persona` is a person driving the system through one of its surfaces — the ordinary `pikkuScenarioStep`. `platform` is the app acting on itself (\"the platform has expired the trial\"), and `addon` is a third-party system acting on it (\"Stripe's webhook arrives\"), contributed by the addon that wraps that service.\n\nThe three are separate declarations rather than a field on one, so the inspector verifies a step's kind by which function was called rather than by trusting a string literal — and so an addon package exports only addon steps, which is checkable." }, "AuditDurability": { "type": "string", "enum": ["best-effort", "transactional"] }, "HTTPWiringsMeta": { "type": "object", "properties": { "post": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "get": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "delete": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "patch": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "head": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "put": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } } }, "required": ["post", "get", "delete", "patch", "head", "put", "options"], "additionalProperties": false }, "HTTPWiringMeta": { "type": "object", "additionalProperties": false, "properties": { "route": { "type": "string" }, "method": { "$ref": "#/definitions/HTTPMethod" }, "auth": { "type": "boolean", "description": "The route's own `auth`, or the group's if the route did not set one." }, "requiresSession": { "type": "boolean", "description": "Whether reaching this route requires a session, resolved at codegen time across every layer that can demand one: the function's `sessionless`, its own `auth`, this route's `auth`, and the auth flag of the addon the function belongs to. Answering \"which routes are open?\" used to mean joining four separate places and knowing which of them wins; getting that join wrong reads an open route as a closed one." }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "headersSchemaName": { "type": "string" }, "sse": { "type": "boolean", "const": true }, "groupBasePath": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string", "description": "A human name for this wiring, shown wherever it is listed rather than called." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime." }, "summary": { "type": "string", "description": "A one-line description for listings, where the full `description` is too long." }, "description": { "type": "string", "description": "What this does, for whoever is reading the wiring rather than writing it." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Names of error classes this may throw, so each one's registered status is used instead of a 500." }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["method", "pikkuFuncId", "route"] }, "HTTPMethod": { "type": "string", "enum": ["post", "get", "delete", "patch", "head", "put", "options"] }, "HTTPFunctionMetaInputTypes": { "type": "object", "properties": { "params": { "type": "string" }, "query": { "type": "string" }, "body": { "type": "string" } }, "additionalProperties": false }, "ChannelsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMeta" } }, "ChannelMeta": { "type": "object", "properties": { "name": { "type": "string" }, "route": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "input": { "type": ["string", "null"] }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "connect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "disconnect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "message": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "messageWirings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMessageMeta" } } }, "binary": { "type": ["boolean", "null"] }, "gateway": { "type": "boolean", "description": "Set when the channel was wired by a gateway rather than declared directly." }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "channelMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["name", "route", "input", "connect", "disconnect", "message", "messageWirings"], "additionalProperties": false }, "ChannelMessageMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "CLIProgramMeta": { "type": "object", "properties": { "program": { "type": "string" }, "commands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "defaultRenderName": { "type": "string" }, "auth": { "type": "boolean", "description": "Whether the channel serving this program over a websocket requires a session. Only meaningful for the generated channel backend — a locally executed CLI has no connection to authenticate." } }, "required": ["program", "commands", "options"], "additionalProperties": false, "description": "CLI metadata collection (per program)" }, "CLICommandMeta": { "type": "object", "properties": { "parameters": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "positionals": { "type": "array", "items": { "$ref": "#/definitions/CLIPositional" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "renderName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "subcommands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "isDefault": { "type": "boolean" } }, "required": ["pikkuFuncId", "positionals", "options"], "additionalProperties": false, "description": "CLI command metadata for runtime" }, "CLIPositional": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "variadic": { "type": "boolean" } }, "required": ["name", "required"], "additionalProperties": false, "description": "Positional argument definition" }, "CLIOption": { "type": "object", "properties": { "description": { "type": "string" }, "short": { "type": "string" }, "type": { "$ref": "#/definitions/CLIOptionType" }, "default": {}, "choices": { "type": "array", "items": {} }, "required": { "type": "boolean" } }, "required": ["description"], "additionalProperties": false, "description": "CLI option definition" }, "CLIOptionType": { "type": "string", "enum": ["string", "number", "boolean", "string[]"], "description": "The shape an option's value is parsed into. `'string[]'` splits a single value on commas; `'boolean'` is a flag that consumes the next token only when it is an explicit literal (`true`/`false`/`1`/`0`/`yes`/`no`); every other type consumes one token verbatim, so a value may start with `-`. Left unset — which is the usual case — it is read from the command function's input schema, then from `default`, and otherwise falls back to `'string'`. Declare it only where neither can say: an option belonging to no function input, such as one the config factory reads straight off the CLI data." }, "McpMeta": { "type": "object", "properties": { "toolsMeta": { "$ref": "#/definitions/MCPToolMeta" }, "resourcesMeta": { "$ref": "#/definitions/MCPResourceMeta" }, "promptsMeta": { "$ref": "#/definitions/MCPPromptMeta" } }, "required": ["toolsMeta", "resourcesMeta", "promptsMeta"], "additionalProperties": false }, "MCPToolMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string", "description": "How the model calls this tool. It is the tool's identity, so renaming it breaks any client that already knows it." }, "title": { "type": "string", "description": "The name a human sees, where the calling `name` is not readable." }, "description": { "type": "string", "description": "What the tool does and when to reach for it. This is what the model decides on, so it earns more care than the rest of this object." }, "summary": { "type": "string", "description": "A one-line description for listings, where the full `description` is too long." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Names of error classes this may throw, so the client is told which failures are its own fault." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime." }, "streaming": { "type": "boolean", "description": "Whether the function returns its result in chunks rather than at once." } }, "required": ["inputSchema", "name", "outputSchema", "pikkuFuncId"] } }, "MCPResourceMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "uri": { "type": "string", "description": "How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema." }, "title": { "type": "string", "description": "The name a human sees in a client's resource list." }, "description": { "type": "string", "description": "What the resource holds, written for the model deciding whether to read it." }, "summary": { "type": "string", "description": "A one-line description for listings, where the full `description` is too long." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Names of error classes this may throw, so the client is told which failures are its own fault." }, "mimeType": { "type": "string", "description": "The media type of what the function returns, so the client knows whether it is text, JSON or an image." }, "size": { "type": "number", "description": "Size in bytes, where it is known ahead of the read. A client uses it to decide whether to fetch at all." }, "streaming": { "type": "boolean", "description": "Whether the function returns the content in chunks rather than at once." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime." } }, "required": ["description", "inputSchema", "outputSchema", "pikkuFuncId", "title", "uri"] } }, "MCPPromptMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "arguments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "description", "required"], "additionalProperties": false } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string", "description": "How the client asks for this prompt." }, "description": { "type": "string", "description": "What the prompt is for, written for the human picking it out of a list." }, "summary": { "type": "string", "description": "A one-line description for listings, where the full `description` is too long." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Names of error classes this may throw, so the client is told which failures are its own fault." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime." } }, "required": ["arguments", "description", "inputSchema", "name", "outputSchema", "pikkuFuncId"] } } } }