@pikku/core 0.12.63 → 0.12.66

package/src/wirings/rpc/rpc-types.ts

@@ -1,9 +1,9 @@
 export type PikkuRPC<
-  Invoke extends Function = any,
-  Remote extends Function = any,
-  startWorkflow extends Function = any,
-  AgentRun extends Function = any,
-  AgentStream extends Function = any,
+  Invoke extends (...args: any[]) => any = (...args: any[]) => any,
+  Remote extends (...args: any[]) => any = (...args: any[]) => any,
+  startWorkflow extends (...args: any[]) => any = (...args: any[]) => any,
+  AgentRun extends (...args: any[]) => any = (...args: any[]) => any,
+  AgentStream extends (...args: any[]) => any = (...args: any[]) => any,
 > = {
   depth: number
   global: boolean
@@ -52,5 +52,16 @@ export interface ResolvedFunction {
     auth?: boolean
     tags?: string[]
     rpcEndpoint?: string
+    secretOverrides?: Record<string, string>
+    variableOverrides?: Record<string, string>
+    credentialOverrides?: Record<string, string>
+    /** Set by `wireRemoteAddon`: dispatch this namespace's RPCs over HTTP */
+    remote?: boolean
+    serverUrl?: string | ((services: any) => string | Promise<string>)
+    remoteAuth?:
+      | { credentialId: string }
+      | { secretId: string }
+      | { resolve: (services: any, wire: any) => string | Promise<string> }
+    remoteName?: (fn: string) => string
   }
 }

package/src/wirings/rpc/wire-addon.test.ts

@@ -17,9 +17,9 @@ describe('wireAddon', () => {
       auth: true,
       mcp: true,
       tags: ['payments', 'billing'],
-      secretOverrides: { apiKey: 'secretName' },
-      variableOverrides: { region: 'eu-west-1' },
-      credentialOverrides: { oauth: 'credentialName' },
+      secretOverrides: { apiKey: 'STRIPE_API_KEY' },
+      variableOverrides: { region: 'AWS_REGION' },
+      credentialOverrides: { oauth: 'stripeOAuth' },
     })
 
     assert.deepEqual(pikkuState(null, 'addons', 'packages').get('stripe'), {
@@ -27,6 +27,9 @@ describe('wireAddon', () => {
       rpcEndpoint: 'https://rpc.example.com',
       auth: true,
       tags: ['payments', 'billing'],
+      secretOverrides: { apiKey: 'STRIPE_API_KEY' },
+      variableOverrides: { region: 'AWS_REGION' },
+      credentialOverrides: { oauth: 'stripeOAuth' },
     })
   })
 

package/src/wirings/rpc/wire-addon.ts

@@ -18,5 +18,14 @@ export const wireAddon = (config: WireAddonConfig): void => {
     rpcEndpoint: config.rpcEndpoint,
     auth: config.auth,
     tags: config.tags,
+    ...(config.secretOverrides
+      ? { secretOverrides: config.secretOverrides }
+      : {}),
+    ...(config.variableOverrides
+      ? { variableOverrides: config.variableOverrides }
+      : {}),
+    ...(config.credentialOverrides
+      ? { credentialOverrides: config.credentialOverrides }
+      : {}),
   })
 }

package/src/wirings/rpc/wire-remote-addon.ts

@@ -0,0 +1,57 @@
+import { pikkuState } from '../../pikku-state.js'
+import type { CoreServices, PikkuWire } from '../../types/core.types.js'
+
+/**
+ * How the consumer supplies the token the hosted addon's auth expects.
+ *
+ * This is a CLIENT authenticating to a hosted library — NOT pikku's trusted
+ * machine-to-machine mesh (which uses `PIKKU_REMOTE_SECRET`). The consumer binds
+ * the addon's declared auth requirement to a local source:
+ *  - `credentialId` — per-user credential, resolved via `wire.getCredential(id)`
+ *  - `secretId`     — platform key, resolved via the secrets service
+ *  - `resolve`      — custom escape hatch
+ * Omit entirely when the addon declares its remote surface is public.
+ *
+ * The value is sent `Authorization: Bearer <token>` by default; a non-default
+ * header is declared once by the addon (its meta), never chosen here.
+ */
+export type RemoteAddonAuth =
+  | { credentialId: string }
+  | { secretId: string }
+  | { resolve: (services: CoreServices, wire: PikkuWire) => string | Promise<string> }
+
+export type WireRemoteAddonConfig = {
+  /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
+  name: string
+  /**
+   * The addon package. Installed as a **devDependency** (types only — its
+   * handlers run on the host); `pikku verify` enforces this.
+   */
+  package: string
+  /** Base URL of the host serving the addon's remote surface. */
+  serverUrl: string | ((services: CoreServices) => string | Promise<string>)
+  /** Bind the addon's declared auth to a local source. Omit if the surface is public. */
+  auth?: RemoteAddonAuth
+  /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
+  remoteName?: (fn: string) => string
+  tags?: string[]
+}
+
+/**
+ * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
+ *
+ * Unlike `wireAddon` (which bundles the addon's functions in-process, a
+ * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
+ * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
+ * only). See {@link RemoteAddonAuth} for how auth is bound.
+ */
+export const wireRemoteAddon = (config: WireRemoteAddonConfig): void => {
+  pikkuState(null, 'addons', 'packages').set(config.name, {
+    package: config.package,
+    tags: config.tags,
+    remote: true,
+    serverUrl: config.serverUrl,
+    ...(config.auth ? { remoteAuth: config.auth } : {}),
+    ...(config.remoteName ? { remoteName: config.remoteName } : {}),
+  })
+}

package/src/wirings/scope/index.ts

@@ -0,0 +1,14 @@
+export { wireScope } from './wire-scope.js'
+export {
+  flattenScopeDefinitions,
+  validateAndBuildScopeDefinitionsMeta,
+} from './validate-scope-definitions.js'
+export type {
+  CoreScopes,
+  CoreScopeNode,
+  FlatScope,
+  ScopeDefinitionMeta,
+  ScopeDefinitionsMeta,
+  ScopeDefinitions,
+  ScopeNodeMeta,
+} from './scope.types.js'

package/src/wirings/scope/scope.test.ts

@@ -0,0 +1,135 @@
+import { describe, test } from 'node:test'
+import * as assert from 'node:assert'
+import {
+  flattenScopeDefinitions,
+  validateAndBuildScopeDefinitionsMeta,
+} from './validate-scope-definitions.js'
+import type { ScopeDefinitions } from './scope.types.js'
+
+describe('flattenScopeDefinitions', () => {
+  test('a flat scope yields itself', () => {
+    const definitions: ScopeDefinitions = [
+      { name: 'admin', description: 'Administration' },
+    ]
+
+    assert.deepEqual(flattenScopeDefinitions(definitions), [
+      { id: 'admin', description: 'Administration' },
+    ])
+  })
+
+  test('nested scopes yield every intermediate level', () => {
+    const definitions: ScopeDefinitions = [
+      {
+        name: 'admin',
+        scopes: {
+          invoices: {
+            description: 'Invoice management',
+            scopes: { create: { description: 'Create invoices' } },
+          },
+        },
+      },
+    ]
+
+    assert.deepEqual(flattenScopeDefinitions(definitions), [
+      { id: 'admin', description: undefined },
+      { id: 'admin:invoices', description: 'Invoice management' },
+      { id: 'admin:invoices:create', description: 'Create invoices' },
+    ])
+  })
+
+  test('siblings are flattened depth-first', () => {
+    const definitions: ScopeDefinitions = [
+      {
+        name: 'billing',
+        scopes: { read: {}, write: {} },
+      },
+    ]
+
+    assert.deepEqual(
+      flattenScopeDefinitions(definitions).map((s) => s.id),
+      ['billing', 'billing:read', 'billing:write']
+    )
+  })
+
+  test('several definitions are flattened together', () => {
+    const definitions: ScopeDefinitions = [
+      { name: 'admin', scopes: { users: {} } },
+      { name: 'billing' },
+    ]
+
+    assert.deepEqual(
+      flattenScopeDefinitions(definitions).map((s) => s.id),
+      ['admin', 'admin:users', 'billing']
+    )
+  })
+})
+
+describe('validateAndBuildScopeDefinitionsMeta', () => {
+  test('keys definitions by name', () => {
+    const meta = validateAndBuildScopeDefinitionsMeta([
+      { name: 'admin', description: 'Administration' },
+    ])
+
+    assert.equal(meta.admin!.name, 'admin')
+    assert.equal(meta.admin!.description, 'Administration')
+  })
+
+  test('an identical duplicate is tolerated', () => {
+    const meta = validateAndBuildScopeDefinitionsMeta([
+      { name: 'admin', scopes: { users: {} } },
+      { name: 'admin', scopes: { users: {} } },
+    ])
+
+    assert.equal(Object.keys(meta).length, 1)
+  })
+
+  test('a conflicting duplicate throws and names both files', () => {
+    assert.throws(
+      () =>
+        validateAndBuildScopeDefinitionsMeta([
+          { name: 'admin', scopes: { users: {} }, sourceFile: 'a.ts' },
+          { name: 'admin', scopes: { invoices: {} }, sourceFile: 'b.ts' },
+        ]),
+      (err: Error) => {
+        assert.match(err.message, /admin/)
+        assert.match(err.message, /a\.ts/)
+        assert.match(err.message, /b\.ts/)
+        return true
+      }
+    )
+  })
+
+  test('rejects a name containing the separator', () => {
+    assert.throws(
+      () => validateAndBuildScopeDefinitionsMeta([{ name: 'admin:users' }]),
+      /separator/i
+    )
+  })
+
+  test('rejects a nested key containing the separator', () => {
+    assert.throws(
+      () =>
+        validateAndBuildScopeDefinitionsMeta([
+          { name: 'admin', scopes: { 'a:b': {} } },
+        ]),
+      /separator/i
+    )
+  })
+
+  test('rejects a wildcard as a declared name', () => {
+    assert.throws(
+      () => validateAndBuildScopeDefinitionsMeta([{ name: '*' }]),
+      /wildcard/i
+    )
+  })
+
+  test('rejects a wildcard nested inside a scope', () => {
+    assert.throws(
+      () =>
+        validateAndBuildScopeDefinitionsMeta([
+          { name: 'admin', scopes: { '*': {} } },
+        ]),
+      /wildcard/i
+    )
+  })
+})

package/src/wirings/scope/scope.types.ts

@@ -0,0 +1,44 @@
+/**
+ * A node within a scope tree. Every node is itself a grantable scope — given
+ * `admin` containing `invoices` containing `create`, all three of `admin`,
+ * `admin:invoices` and `admin:invoices:create` are valid scope ids.
+ */
+export type CoreScopeNode = {
+  /** Short human-readable name, e.g. "Administration". */
+  displayName?: string
+  /** Longer-form description, surfaced in the console when granting. */
+  description?: string
+  /** Nested scopes, keyed by their segment. */
+  scopes?: Record<string, CoreScopeNode>
+}
+
+/**
+ * Scope trees to declare, keyed by their root segment. A root is just a node —
+ * it is named by its key, exactly like every node beneath it. A key must not
+ * contain `:` or be `*`.
+ */
+export type CoreScopes = Record<string, CoreScopeNode>
+
+export type ScopeNodeMeta = {
+  displayName?: string
+  description?: string
+  scopes?: Record<string, ScopeNodeMeta>
+}
+
+export type ScopeDefinitionMeta = {
+  name: string
+  displayName?: string
+  description?: string
+  scopes?: Record<string, ScopeNodeMeta>
+  sourceFile?: string
+}
+
+export type ScopeDefinitions = ScopeDefinitionMeta[]
+export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>
+
+/** A single scope, flattened out of the declared tree. */
+export type FlatScope = {
+  /** Colon-delimited id, e.g. `admin:invoices:create`. */
+  id: string
+  description?: string
+}

package/src/wirings/scope/validate-scope-definitions.ts

@@ -0,0 +1,110 @@
+import type {
+  FlatScope,
+  ScopeDefinitions,
+  ScopeDefinitionsMeta,
+  ScopeNodeMeta,
+} from './scope.types.js'
+
+const SEPARATOR = ':'
+const WILDCARD = '*'
+
+const assertSegment = (segment: string, scopeName: string): void => {
+  if (segment.includes(SEPARATOR)) {
+    throw new Error(
+      `Scope segment '${segment}' in '${scopeName}' contains the '${SEPARATOR}' separator. ` +
+        `Nest scopes with the 'scopes' property instead of embedding '${SEPARATOR}' in a name.`
+    )
+  }
+  if (segment === WILDCARD) {
+    throw new Error(
+      `Scope segment '${segment}' in '${scopeName}' is the wildcard. ` +
+        `'${WILDCARD}' is reserved for granting a scope and its descendants, and cannot be declared.`
+    )
+  }
+  if (segment.length === 0) {
+    throw new Error(`Scope '${scopeName}' contains an empty segment.`)
+  }
+}
+
+const assertNodesValid = (
+  nodes: Record<string, ScopeNodeMeta> | undefined,
+  scopeName: string
+): void => {
+  for (const [segment, node] of Object.entries(nodes ?? {})) {
+    assertSegment(segment, scopeName)
+    assertNodesValid(node.scopes, scopeName)
+  }
+}
+
+const flattenNodes = (
+  nodes: Record<string, ScopeNodeMeta> | undefined,
+  prefix: string,
+  out: FlatScope[]
+): void => {
+  for (const [segment, node] of Object.entries(nodes ?? {})) {
+    const id = `${prefix}${SEPARATOR}${segment}`
+    out.push({ id, description: node.description })
+    flattenNodes(node.scopes, id, out)
+  }
+}
+
+/**
+ * Flattens declared scope trees into the full list of grantable scope ids,
+ * depth-first. Every node is emitted, including intermediate ones.
+ *
+ * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
+ * the declared set into its store.
+ */
+export const flattenScopeDefinitions = (
+  definitions: ScopeDefinitions
+): FlatScope[] => {
+  const out: FlatScope[] = []
+  for (const def of definitions) {
+    out.push({ id: def.name, description: def.description })
+    flattenNodes(def.scopes, def.name, out)
+  }
+  return out
+}
+
+/**
+ * Validates declared scopes and keys them by name.
+ *
+ * Definitions sharing a name must be identical; a conflicting redeclaration is
+ * a hard error naming both source files.
+ */
+export function validateAndBuildScopeDefinitionsMeta(
+  definitions: ScopeDefinitions
+): ScopeDefinitionsMeta {
+  const meta: ScopeDefinitionsMeta = {}
+
+  for (const def of definitions) {
+    assertSegment(def.name, def.name)
+    assertNodesValid(def.scopes, def.name)
+
+    const existing = meta[def.name]
+    if (existing) {
+      const sameShape =
+        JSON.stringify(existing.scopes ?? {}) ===
+        JSON.stringify(def.scopes ?? {})
+      if (!sameShape) {
+        throw new Error(
+          `Scope '${def.name}' is declared with different nested scopes.\n` +
+            `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+            `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
+            `Scopes sharing a name must declare the same tree.`
+        )
+      }
+      continue
+    }
+
+    meta[def.name] = {
+      name: def.name,
+      displayName: def.displayName,
+      description: def.description,
+      scopes: def.scopes,
+      sourceFile: def.sourceFile,
+    }
+  }
+
+  return meta
+}

package/src/wirings/scope/wire-scope.ts

@@ -0,0 +1,34 @@
+import type { CoreScopes } from './scope.types.js'
+
+/**
+ * No-op function for declaring scopes.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `ScopeId` union,
+ * so a function referencing an undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * wireScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export const wireScope = (_config: CoreScopes): void => {}

package/src/wirings/secret/secret.types.ts

@@ -4,6 +4,13 @@ export type CoreSecret<T = unknown> = {
   description?: string
   secretId: string
   schema: T
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   /**
    * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
    * Stored in the generated secrets metadata so consumers can tell when a
@@ -27,6 +34,13 @@ export type SecretDefinitionMeta = {
   description?: string
   secretId: string
   schema?: Record<string, unknown> | string
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   oauth2?: OAuth2CredentialConfig
   rotationPeriod?: string
   sourceFile?: string

package/src/wirings/secret/validate-secret-definitions.ts

@@ -58,6 +58,7 @@ export function validateAndBuildSecretDefinitionsMeta(
           schema: def.schema,
           oauth2: def.oauth2,
           rotationPeriod: def.rotationPeriod,
+          docsUrl: def.docsUrl,
           sourceFile: def.sourceFile,
         }
       }
@@ -75,6 +76,7 @@ export function validateAndBuildSecretDefinitionsMeta(
         schema: def.schema,
         oauth2: def.oauth2,
         rotationPeriod: def.rotationPeriod,
+        docsUrl: def.docsUrl,
         sourceFile: def.sourceFile,
       }
     }

package/src/wirings/variable/validate-variable-definitions.ts

@@ -45,6 +45,7 @@ export function validateAndBuildVariableDefinitionsMeta(
           description: def.description,
           variableId: def.variableId,
           schema: def.schema,
+          docsUrl: def.docsUrl,
           sourceFile: def.sourceFile,
         }
       }
@@ -60,6 +61,7 @@ export function validateAndBuildVariableDefinitionsMeta(
         description: def.description,
         variableId: def.variableId,
         schema: def.schema,
+        docsUrl: def.docsUrl,
         sourceFile: def.sourceFile,
       }
     }

package/src/wirings/variable/variable.types.ts

@@ -4,6 +4,13 @@ export type CoreVariable<T = unknown> = {
   description?: string
   variableId: string
   schema: T
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
 }
 
 export type VariableDefinitionMeta = {
@@ -12,6 +19,13 @@ export type VariableDefinitionMeta = {
   description?: string
   variableId: string
   schema?: Record<string, unknown> | string
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   sourceFile?: string
 }
 

package/src/wirings/workflow/dsl/index.ts

@@ -9,6 +9,9 @@ export type {
   WorkflowWireDoInline,
   WorkflowWireSleep,
   WorkflowWireSuspend,
+  WorkflowWireApproval,
+  WorkflowApprovalOptions,
+  ApprovalOutcome,
   InputSource,
   OutputBinding,
   RpcStepMeta,
@@ -22,6 +25,7 @@ export type {
   SleepStepMeta,
   CancelStepMeta,
   SuspendStepMeta,
+  ApprovalStepMeta,
   SwitchCaseMeta,
   SwitchStepMeta,
   FilterStepMeta,