@pikku/inspector 0.12.58 → 0.12.59

package/CHANGELOG.md

@@ -1,3 +1,58 @@
+## 0.12.59
+
+### Patch Changes
+
+- 02c4fe5: fix(core,inspector): let a host grant an addon secrets it could not declare
+
+  Scoping an addon's `SecretService` to its `declaredSecrets` left generic addons
+  with nothing readable: `declaredSecrets` is derived from the addon package's own
+  source, but the secrets an addon like `@pikku/addon-graph` reads are named by the
+  consuming app's workflow nodes at runtime. Every authenticated `graph:httpRequest`
+  threw.
+
+  `wireAddon` now takes `secretGrants: string[]` and `credentialGrants: string[]`,
+  completing the grant family alongside `secretOverrides` (grant + rename) and
+  `globalSecrets` (grant everything, with a reason). Grants name the secret as the
+  addon reads it, since the scope check runs before the override map renames it —
+  which is also why an override's key grants and its value does not.
+
+  A grant naming a secret the project does not declare is an `INVALID_VALUE`
+  critical at codegen, resolved through the override map before lookup.
+
+- 438b776: Move the scenario and feature surface off `@pikku/core/workflow` and onto
+  `@pikku/core/scenario`. Scenarios extend workflows, so the production workflow
+  wiring no longer names a scenario module in its import graph. Feature and
+  scenario types are declared in their own `scenario.types.ts` rather than in
+  `workflow.types.ts`. Import `requireActor`, `requireScenarioEnv`, `pollUntil`,
+  `createCookieJar`, `addFeature`, `ScenarioHttpResponse` and the rest from
+  `@pikku/core/scenario`; `HttpPersonasConfig` now comes from
+  `@pikku/core/persona` rather than `@pikku/core/services`.
+- ad63f47: feat(cli): warn before codegen when a linked dependency splits a package's type identity
+
+  `pikku all` now runs the split-type-identity check as a preflight, beside the
+  existing `@pikku/core` one, and warns with `PKU719` naming each package, both
+  versions and both paths.
+
+  It has to run _before_ the work rather than after it fails. The failure it
+  explains is a V8 heap OOM, which aborts the process — `process.on('exit')`,
+  `uncaughtException` and `finally` never run, so nothing printed after the fact is
+  ever seen. By the time there is a symptom, the only thing that can help is
+  already on screen above it. Without this the user sees a codegen step that dies
+  of memory pressure with no indication that two copies of one package are the
+  reason, and the obvious next move is to raise `--max-old-space-size`, which
+  hides it further.
+
+  Warns rather than throws: a skewed linked dependency is a strong signal, not a
+  certainty, and refusing to build on a heuristic would break working setups.
+  `PIKKU_SKIP_TYPE_IDENTITY_CHECK=1` silences it, matching
+  `PIKKU_ALLOW_DUPLICATE_CORE`. It also swallows its own errors — it runs on every
+  codegen, so it must never be the reason a build stops.
+
+- Updated dependencies [02c4fe5]
+- Updated dependencies [438b776]
+- Updated dependencies [438b776]
+  - @pikku/core@0.12.83
+
 ## 0.12.58
 
 ### Patch Changes

package/dist/add/add-wire-addon.js

@@ -53,6 +53,8 @@ export function addWireAddon(node, state, logger) {
     let secretOverrides;
     let variableOverrides;
     let credentialOverrides;
+    let secretGrants;
+    let credentialGrants;
     let globalSecrets;
     let globalCredentials;
     for (const prop of firstArg.properties) {
@@ -96,6 +98,12 @@ export function addWireAddon(node, state, logger) {
             ts.isObjectLiteralExpression(prop.initializer)) {
             credentialOverrides = parseStringRecord(prop.initializer);
         }
+        else if (key === 'secretGrants') {
+            secretGrants = parseStringArray(prop.initializer);
+        }
+        else if (key === 'credentialGrants') {
+            credentialGrants = parseStringArray(prop.initializer);
+        }
         else if (key === 'globalSecrets') {
             // The grant is real at runtime whatever the reason evaluates to, so a
             // non-literal is recorded as its source text rather than dropped.
@@ -122,6 +130,8 @@ export function addWireAddon(node, state, logger) {
         secretOverrides,
         variableOverrides,
         credentialOverrides,
+        secretGrants,
+        credentialGrants,
         globalSecrets,
         globalCredentials,
     });

package/dist/error-codes.d.ts

@@ -69,6 +69,7 @@ export declare enum ErrorCode {
     FUNCTION_DYNAMIC_IMPORT = "PKU498",
     DUPLICATE_CORE_VERSION = "PKU717",
     CORE_VERSION_SKEW = "PKU718",
+    SPLIT_TYPE_IDENTITY = "PKU719",
     PII_IN_OUTPUT = "PKU910",
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
     ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",

package/dist/error-codes.js

@@ -90,6 +90,7 @@ export var ErrorCode;
     // Dependency integrity errors
     ErrorCode["DUPLICATE_CORE_VERSION"] = "PKU717";
     ErrorCode["CORE_VERSION_SKEW"] = "PKU718";
+    ErrorCode["SPLIT_TYPE_IDENTITY"] = "PKU719";
     // Data classification errors
     ErrorCode["PII_IN_OUTPUT"] = "PKU910";
     // Addon authoring errors

package/dist/types.d.ts

@@ -521,6 +521,10 @@ export interface InspectorState {
             secretOverrides?: Record<string, string>;
             variableOverrides?: Record<string, string>;
             credentialOverrides?: Record<string, string>;
+            /** Secrets the app lends this instance, named as the addon reads them. */
+            secretGrants?: string[];
+            /** Credentials the app lends this instance, named as the addon reads them. */
+            credentialGrants?: string[];
             /**
              * The app's stated reason for handing this instance the whole
              * `SecretService` instead of one scoped to its declared secrets.

package/dist/utils/post-process.js

@@ -317,14 +317,21 @@ export function validateSecretOverrides(logger, state) {
     // older meta without a secretId field.
     const secretIds = new Set(state.secrets.definitions.map((d) => d.secretId ?? d.name));
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
-        if (!addonDecl.secretOverrides)
-            continue;
-        for (const [logicalName, resolvedName] of Object.entries(addonDecl.secretOverrides)) {
+        for (const [logicalName, resolvedName] of Object.entries(addonDecl.secretOverrides ?? {})) {
             if (!secretIds.has(resolvedName)) {
                 const availableSecrets = Array.from(secretIds);
                 logger.critical(ErrorCode.INVALID_VALUE, `Secret override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`);
             }
         }
+        // A grant names the secret as the addon reads it, so it resolves through
+        // the override map before it can be looked up in the project.
+        for (const logicalName of addonDecl.secretGrants ?? []) {
+            const resolvedName = addonDecl.secretOverrides?.[logicalName] ?? logicalName;
+            if (!secretIds.has(resolvedName)) {
+                const availableSecrets = Array.from(secretIds);
+                logger.critical(ErrorCode.INVALID_VALUE, `Secret grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`);
+            }
+        }
     }
 }
 export function validateCredentialOverrides(logger, state) {
@@ -333,14 +340,19 @@ export function validateCredentialOverrides(logger, state) {
         return;
     const credentialNames = new Set(state.credentials?.definitions.map((d) => d.name) ?? []);
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
-        if (!addonDecl.credentialOverrides)
-            continue;
-        for (const [logicalName, resolvedName] of Object.entries(addonDecl.credentialOverrides)) {
+        for (const [logicalName, resolvedName] of Object.entries(addonDecl.credentialOverrides ?? {})) {
             if (!credentialNames.has(resolvedName)) {
                 const availableCredentials = Array.from(credentialNames);
                 logger.critical(ErrorCode.INVALID_VALUE, `Credential override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
             }
         }
+        for (const logicalName of addonDecl.credentialGrants ?? []) {
+            const resolvedName = addonDecl.credentialOverrides?.[logicalName] ?? logicalName;
+            if (!credentialNames.has(resolvedName)) {
+                const availableCredentials = Array.from(credentialNames);
+                logger.critical(ErrorCode.INVALID_VALUE, `Credential grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
+            }
+        }
     }
 }
 export function validateVariableOverrides(logger, state) {

package/dist/utils/serialize-inspector-state.d.ts

@@ -195,6 +195,8 @@ export interface SerializableInspectorState {
                 secretOverrides?: Record<string, string>;
                 variableOverrides?: Record<string, string>;
                 credentialOverrides?: Record<string, string>;
+                secretGrants?: string[];
+                credentialGrants?: string[];
                 globalSecrets?: string;
                 globalCredentials?: string;
             }

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -67,7 +67,8 @@ export interface NodeOptions {
  * Flow node types for control flow (no RPC call)
  */
 export type FlowType = 'sleep' | 'suspend' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
-import type { ContextVariable, ScenarioStepPhase, WorkflowContext, WorkflowPlannedStep } from '@pikku/core/workflow';
+import type { ContextVariable, WorkflowContext, WorkflowPlannedStep } from '@pikku/core/workflow';
+import type { ScenarioStepPhase } from '@pikku/core/scenario';
 export type { ContextVariable, WorkflowContext };
 /**
  * Base node properties shared by all node types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.58",
+  "version": "0.12.59",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.82"
+    "@pikku/core": "^0.12.83"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.82",
+    "@pikku/core": "^0.12.83",
     "@types/node": "^24.11.0"
   },
   "engines": {

package/src/add/add-functions.ts

@@ -9,7 +9,7 @@ import {
 import { extractFunctionNode } from '../utils/extract-function-node.js'
 import { extractUsedWires } from '../utils/extract-services.js'
 import type { AuditDurability, FunctionServicesMeta } from '@pikku/core'
-import type { ScenarioStepKind, ScenarioSurface } from '@pikku/core/workflow'
+import type { ScenarioStepKind, ScenarioSurface } from '@pikku/core/scenario'
 import { formatVersionedId, parseVersionedId } from '@pikku/core'
 
 /** Binding keys a `pikkuScenarioStep` may declare, in report order. */

package/src/add/add-scenario-step.test.ts

@@ -5,7 +5,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { inspect } from '../inspector.js'
 import type { InspectorLogger } from '../types.js'
-import type { ScenarioStepMeta, WorkflowStepMeta } from '@pikku/core/workflow'
+import type { WorkflowStepMeta } from '@pikku/core/workflow'
+import type { ScenarioStepMeta } from '@pikku/core/scenario'
 
 function makeLogger(
   criticals: Array<{ code: string; message: string }>

package/src/add/add-wire-addon.test.ts

@@ -61,11 +61,42 @@ describe('addWireAddon', () => {
       secretOverrides: undefined,
       variableOverrides: undefined,
       credentialOverrides: undefined,
+      secretGrants: undefined,
+      credentialGrants: undefined,
       globalSecrets: undefined,
       globalCredentials: undefined,
     })
   })
 
+  test('captures the secrets and credentials the host lends an addon', () => {
+    const declarations = inspect(`
+      wireAddon({
+        name: 'graph',
+        package: '@pikku/addon-graph',
+        secretGrants: ['STRIPE_KEY', 'GITHUB_TOKEN'],
+        credentialGrants: ['slack'],
+      })
+    `)
+
+    assert.deepEqual(declarations.get('graph').secretGrants, [
+      'STRIPE_KEY',
+      'GITHUB_TOKEN',
+    ])
+    assert.deepEqual(declarations.get('graph').credentialGrants, ['slack'])
+  })
+
+  test('drops a grant list that is not statically knowable', () => {
+    const declarations = inspect(`
+      wireAddon({
+        name: 'graph',
+        package: '@pikku/addon-graph',
+        secretGrants: someRuntimeList,
+      })
+    `)
+
+    assert.equal(declarations.get('graph').secretGrants, undefined)
+  })
+
   test('captures the reason an addon was exempted from credential scoping', () => {
     const declarations = inspect(`
       wireAddon({

package/src/add/add-wire-addon.ts

@@ -60,6 +60,8 @@ export function addWireAddon(
   let secretOverrides: Record<string, string> | undefined
   let variableOverrides: Record<string, string> | undefined
   let credentialOverrides: Record<string, string> | undefined
+  let secretGrants: string[] | undefined
+  let credentialGrants: string[] | undefined
   let globalSecrets: string | undefined
   let globalCredentials: string | undefined
 
@@ -104,6 +106,10 @@ export function addWireAddon(
       ts.isObjectLiteralExpression(prop.initializer)
     ) {
       credentialOverrides = parseStringRecord(prop.initializer)
+    } else if (key === 'secretGrants') {
+      secretGrants = parseStringArray(prop.initializer)
+    } else if (key === 'credentialGrants') {
+      credentialGrants = parseStringArray(prop.initializer)
     } else if (key === 'globalSecrets') {
       // The grant is real at runtime whatever the reason evaluates to, so a
       // non-literal is recorded as its source text rather than dropped.
@@ -130,6 +136,8 @@ export function addWireAddon(
     secretOverrides,
     variableOverrides,
     credentialOverrides,
+    secretGrants,
+    credentialGrants,
     globalSecrets,
     globalCredentials,
   })

package/src/error-codes.ts

@@ -105,6 +105,7 @@ export enum ErrorCode {
   // Dependency integrity errors
   DUPLICATE_CORE_VERSION = 'PKU717',
   CORE_VERSION_SKEW = 'PKU718',
+  SPLIT_TYPE_IDENTITY = 'PKU719',
 
   // Data classification errors
   PII_IN_OUTPUT = 'PKU910',

package/src/types.ts

@@ -588,6 +588,10 @@ export interface InspectorState {
         secretOverrides?: Record<string, string>
         variableOverrides?: Record<string, string>
         credentialOverrides?: Record<string, string>
+        /** Secrets the app lends this instance, named as the addon reads them. */
+        secretGrants?: string[]
+        /** Credentials the app lends this instance, named as the addon reads them. */
+        credentialGrants?: string[]
         /**
          * The app's stated reason for handing this instance the whole
          * `SecretService` instead of one scoped to its declared secrets.

package/src/utils/post-process.test.ts

@@ -59,6 +59,33 @@ const makeOverrideState = (
     },
   }) as unknown as Omit<InspectorState, 'typesLookup'>
 
+const makeGrantState = (
+  kind: 'secrets' | 'credentials',
+  declaredNames: string[],
+  decl: {
+    secretGrants?: string[]
+    credentialGrants?: string[]
+    secretOverrides?: Record<string, string>
+    credentialOverrides?: Record<string, string>
+  }
+): Omit<InspectorState, 'typesLookup'> =>
+  ({
+    rpc: {
+      wireAddonDeclarations: new Map([
+        ['slack-marketing', { package: '@addon/slack', ...decl }],
+      ]),
+    },
+    secrets: {
+      definitions:
+        kind === 'secrets' ? declaredNames.map((name) => ({ name })) : [],
+    },
+    credentials: {
+      definitions:
+        kind === 'credentials' ? declaredNames.map((name) => ({ name })) : [],
+    },
+    variables: { definitions: [] },
+  }) as unknown as Omit<InspectorState, 'typesLookup'>
+
 function makeState(
   overrides: {
     usedFunctions?: string[]
@@ -414,6 +441,46 @@ describe('override validation resolves the override target (value), not the logi
     validateVariableOverrides(logger, state)
     assert.deepEqual(criticals, [])
   })
+
+  test('validateSecretOverrides accepts a grant naming a declared secret', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    const state = makeGrantState('secrets', ['STRIPE_KEY'], {
+      secretGrants: ['STRIPE_KEY'],
+    })
+    validateSecretOverrides(logger, state)
+    assert.deepEqual(criticals, [])
+  })
+
+  test('validateSecretOverrides flags a grant naming no declared secret', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    const state = makeGrantState('secrets', ['STRIPE_KEY'], {
+      secretGrants: ['STIRPE_KEY'],
+    })
+    validateSecretOverrides(logger, state)
+    assert.equal(criticals.length, 1)
+    assert.match(criticals[0]!.message, /STIRPE_KEY/)
+    assert.match(criticals[0]!.message, /STRIPE_KEY/)
+  })
+
+  test('validateSecretOverrides resolves a grant through its override before looking it up', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    const state = makeGrantState('secrets', ['PROD_EMAIL_KEY'], {
+      secretGrants: ['MAILGUN_KEY'],
+      secretOverrides: { MAILGUN_KEY: 'PROD_EMAIL_KEY' },
+    })
+    validateSecretOverrides(logger, state)
+    assert.deepEqual(criticals, [])
+  })
+
+  test('validateCredentialOverrides flags a grant naming no declared credential', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    const state = makeGrantState('credentials', ['marketing_cred'], {
+      credentialGrants: ['ghost_cred'],
+    })
+    validateCredentialOverrides(logger, state)
+    assert.equal(criticals.length, 1)
+    assert.match(criticals[0]!.message, /ghost_cred/)
+  })
 })
 
 const makeRemoteState = (

package/src/utils/post-process.ts

@@ -383,10 +383,8 @@ export function validateSecretOverrides(
   )
 
   for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
-    if (!addonDecl.secretOverrides) continue
-
     for (const [logicalName, resolvedName] of Object.entries(
-      addonDecl.secretOverrides
+      addonDecl.secretOverrides ?? {}
     )) {
       if (!secretIds.has(resolvedName)) {
         const availableSecrets = Array.from(secretIds)
@@ -396,6 +394,20 @@ export function validateSecretOverrides(
         )
       }
     }
+
+    // A grant names the secret as the addon reads it, so it resolves through
+    // the override map before it can be looked up in the project.
+    for (const logicalName of addonDecl.secretGrants ?? []) {
+      const resolvedName =
+        addonDecl.secretOverrides?.[logicalName] ?? logicalName
+      if (!secretIds.has(resolvedName)) {
+        const availableSecrets = Array.from(secretIds)
+        logger.critical(
+          ErrorCode.INVALID_VALUE,
+          `Secret grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`
+        )
+      }
+    }
   }
 }
 
@@ -411,10 +423,8 @@ export function validateCredentialOverrides(
   )
 
   for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
-    if (!addonDecl.credentialOverrides) continue
-
     for (const [logicalName, resolvedName] of Object.entries(
-      addonDecl.credentialOverrides
+      addonDecl.credentialOverrides ?? {}
     )) {
       if (!credentialNames.has(resolvedName)) {
         const availableCredentials = Array.from(credentialNames)
@@ -424,6 +434,18 @@ export function validateCredentialOverrides(
         )
       }
     }
+
+    for (const logicalName of addonDecl.credentialGrants ?? []) {
+      const resolvedName =
+        addonDecl.credentialOverrides?.[logicalName] ?? logicalName
+      if (!credentialNames.has(resolvedName)) {
+        const availableCredentials = Array.from(credentialNames)
+        logger.critical(
+          ErrorCode.INVALID_VALUE,
+          `Credential grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`
+        )
+      }
+    }
   }
 }
 

package/src/utils/serialize-inspector-state.ts

@@ -170,6 +170,8 @@ export interface SerializableInspectorState {
           secretOverrides?: Record<string, string>
           variableOverrides?: Record<string, string>
           credentialOverrides?: Record<string, string>
+          secretGrants?: string[]
+          credentialGrants?: string[]
           globalSecrets?: string
           globalCredentials?: string
         },

package/src/utils/workflow/dsl/extract-dsl-workflow.ts

@@ -15,13 +15,13 @@ import type {
   SwitchCaseMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
-  ScenarioStepMeta,
   InputSource,
   OutputBinding,
   Condition,
   WorkflowContext,
   ContextVariable,
 } from '@pikku/core/workflow'
+import type { ScenarioStepMeta } from '@pikku/core/scenario'
 import {
   isWorkflowDoCall,
   isWorkflowExpectEventuallyCall,

package/src/utils/workflow/graph/workflow-graph.types.ts

@@ -113,10 +113,10 @@ export type FlowType =
 // Import and re-export context types from core
 import type {
   ContextVariable,
-  ScenarioStepPhase,
   WorkflowContext,
   WorkflowPlannedStep,
 } from '@pikku/core/workflow'
+import type { ScenarioStepPhase } from '@pikku/core/scenario'
 
 export type { ContextVariable, WorkflowContext }