@pikku/core 0.12.84 → 0.12.88

package/src/types/core.types.ts

@@ -4,11 +4,7 @@ import type { SecretService } from '../services/secret-service.js'
 import type { SchemaService } from '../services/schema-service.js'
 import type { JWTService } from '../services/jwt-service.js'
 import type { PikkuHTTP } from '../wirings/http/http.types.js'
-import type {
-  PikkuChannel,
-  CorePikkuChannelMiddleware,
-  CorePikkuChannelMiddlewareFactory,
-} from '../wirings/channel/channel.types.js'
+import type { PikkuChannel } from '../wirings/channel/channel.types.js'
 import type { EventHubService } from '../wirings/channel/eventhub-service.js'
 import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import type { PikkuMCP } from '../wirings/mcp/mcp.types.js'
@@ -25,8 +21,6 @@ import type { PikkuScenarioWire } from '../wirings/workflow/scenario.types.js'
 import type {
   PikkuBrowserWire,
   PikkuScenarioStepWire,
-  ScenarioStepKind,
-  ScenarioSurface,
 } from '../wirings/workflow/scenario-step.types.js'
 import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js'
 import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
@@ -44,8 +38,9 @@ import type { AgentRunnerService } from '../services/agent-runner-service.js'
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js'
 import type { AgentRunStateService } from '../services/agent-run-state-service.js'
 import type { AgentRunService } from '../wirings/agent/agent.types.js'
+import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
+import type { PermissionMetadata } from '../function/function-meta.types.js'
 import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js'
-import type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js'
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { EmailService } from '../services/email-service.js'
@@ -76,175 +71,6 @@ export type PikkuWiringTypes =
   | 'agent'
   | 'gateway'
 
-export interface FunctionServicesMeta {
-  optimized: boolean
-  services: string[]
-}
-
-export interface FunctionWiresMeta {
-  optimized: boolean
-  wires: string[]
-}
-
-export type MiddlewareMetadata =
-  | {
-      type: 'http'
-      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
-    }
-  | {
-      type: 'tag'
-      tag: string
-    }
-  | {
-      type: 'wire'
-      name: string
-      inline?: boolean
-    }
-
-/**
- * A reference to a permission function, resolved by name. Function-scoped
- * only: there are no wire- or tag-level permission references.
- */
-export type PermissionMetadata = {
-  type: 'wire'
-  name: string
-  inline?: boolean
-}
-
-export type FunctionRuntimeMeta = {
-  pikkuFuncId: string
-  inputSchemaName: string | null
-  outputSchemaName: string | null
-  /** Scopes the session must hold to run this function. All are required (AND). */
-  scopes?: string[]
-  expose?: boolean
-  /**
-   * 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.
-   */
-  auth?: boolean
-  /**
-   * 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`.
-   */
-  permissionsInBody?: boolean
-  remote?: boolean
-  /**
-   * A step RPC: invoked by name only from a scenario run and refused
-   * everywhere else, so it is never network-callable.
-   */
-  scenarioStep?: boolean
-  /**
-   * 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.
-   */
-  scenario?: boolean
-  mcp?: boolean
-  readonly?: boolean
-  deploy?: 'serverless' | 'server' | 'auto'
-  sessionless?: boolean
-  /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. */
-  workflowQueued?: boolean
-  /** Retry count when this function is used as a workflow step. */
-  workflowRetries?: number
-  /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
-  workflowTimeout?: string
-  /**
-   * Scenario steps only: which surfaces this step declares a binding for.
-   *
-   * The 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.
-   */
-  scenarioStepSurfaces?: ScenarioSurface[]
-  /**
-   * Scenario steps only: who acts. Absent means `persona` — the ordinary step,
-   * and the only kind that existed before the other two.
-   *
-   * A `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.
-   */
-  scenarioStepKind?: ScenarioStepKind
-  /** Addon steps only: the addon whose system acts — `wireAddon`'s `name`. */
-  scenarioStepAddon?: string
-  /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
-  scenarioStepTemplate?: string
-  /**
-   * 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.
-   *
-   * Informational. The runner resolves audit from the live function config, not
-   * from here, so meta and runtime cannot disagree about whether audit is on.
-   */
-  audit?: {
-    durability: AuditDurability
-  }
-  version?: number
-  approvalRequired?: boolean
-  approvalDescription?: string
-  implementationHash?: string
-  contractHash?: string
-  inputHash?: string
-  outputHash?: string
-}
-
-export type FunctionMeta = FunctionRuntimeMeta &
-  Partial<
-    {
-      name: string
-      /** `remote`: a contract with no local body, answered by a connected client. */
-      functionType: 'user' | 'inline' | 'helper' | 'remote'
-      funcWrapper: string
-      services: FunctionServicesMeta
-      wires: FunctionWiresMeta
-      inputs: string[] | null
-      outputs: string[] | null
-      middleware: MiddlewareMetadata[]
-      permissions: PermissionMetadata[]
-      isDirectFunction: boolean
-      sourceFile: string
-      exportedName: string
-      /** File containing the handler body when it differs from sourceFile (imported handlers) */
-      bodySourceFile?: string
-      /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
-      bodyStart: number
-      /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
-      bodyEnd: number
-    } & CommonWireMeta
-  >
-
-export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
-export type FunctionsMeta = Record<string, FunctionMeta>
-
-export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
-  Required<Pick<T, K>>
-
-export type JSONPrimitive = string | number | boolean | null | undefined
-
-export type JSONValue =
-  | JSONPrimitive
-  | JSONValue[]
-  | {
-      [key: string]: JSONValue
-    }
-
-export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>
-
-export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>
-
-export type RequireAtLeastOne<T> = {
-  [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
-}[keyof T]
-
 /**
  * Runtime pool tuning for the Postgres adapter. The connection string stays
  * the flat `postgresUrl` config field — the contract the CLI's db commands read.
@@ -371,6 +197,22 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   auth?: () => Promise<AuthInstance>
 }
 
+/**
+ * Reads a single credential. The first signature resolves the value type from
+ * the project's generated `CredentialsMap`; the second keeps a name the map
+ * does not know callable with an explicit type.
+ *
+ * `TCredentials` is unconstrained because the generated map is an interface,
+ * which has no implicit index signature and so cannot satisfy
+ * `Record<string, unknown>`.
+ */
+export type GetCredential<TCredentials = Record<string, unknown>> = {
+  <K extends keyof TCredentials & string>(
+    name: K
+  ): TCredentials[K] | null | Promise<TCredentials[K] | null>
+  <T = unknown>(name: string): T | null | Promise<T | null>
+}
+
 export type PikkuWire<
   In = unknown,
   Out = unknown,
@@ -386,6 +228,7 @@ export type PikkuWire<
   // `ScenarioContext`.
   TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>,
   TypedActors extends ScenarioPersonas = ScenarioPersonas,
+  TypedCredentials = Record<string, unknown>,
 > = {
   /** Always present — lazily initialised on first access for every function invocation */
   rpc: TypedRPC
@@ -415,8 +258,18 @@ export type PikkuWire<
   workflow: TypedWorkflow
   scenario: TypedScenario
   actors: TypedActors
+  /**
+   * The persona this step runs as, injected by the runner.
+   *
+   * Required on a `browser` binding, which cannot be provisioned without one,
+   * and on any binding whose step declares `actor: true`. A step that declares
+   * neither has no `actor` on its wire at all rather than an optional one —
+   * a pure assertion has nobody to be, and `attemptsSignIn` deliberately posts
+   * credentials instead of reusing an actor's session.
+   */
+  actor: ScenarioPersonaOf<TypedActors>
   /** Present on every scenario step invocation */
-  scenarioStep: PikkuScenarioStepWire<ScenarioPersonaOf<TypedActors>>
+  scenarioStep: PikkuScenarioStepWire
   /** Present only when the runner provisioned a browser for this step */
   browser: PikkuBrowserWire
   workflowStep: WorkflowStepWire
@@ -435,11 +288,10 @@ export type PikkuWire<
   /** Set a credential value (available in middleware) */
   setCredential: (name: string, value: unknown) => void
   /** Get a single credential by name — lazy-loads from CredentialService on first call, sync thereafter */
-  getCredential: <T = unknown>(name: string) => T | null | Promise<T | null>
+  getCredential: GetCredential<TypedCredentials>
   /** Get all resolved credentials — lazy-loads from CredentialService on first call, sync thereafter */
   getCredentials: () =>
-    | Record<string, unknown>
-    | Promise<Record<string, unknown>>
+    Record<string, unknown> | Promise<Record<string, unknown>>
   audit: {
     durability: AuditDurability
   }
@@ -462,100 +314,6 @@ export type PikkuWire<
 /** Wire as constructed by runners, before the function runner lazily adds `rpc`. */
 export type PikkuRawWire = Omit<PikkuWire, 'rpc'>
 
-export type CorePikkuMiddleware<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = (
-  services: SingletonServices,
-  wires: PikkuWire,
-  next: () => Promise<void>
-) => Promise<void>
-
-/**
- * Execution order: `highest` runs first (outermost in the onion), `lowest`
- * runs last, closest to the function.
- */
-export type MiddlewarePriority =
-  | 'highest'
-  | 'high'
-  | 'medium'
-  | 'low'
-  | 'lowest'
-
-export type CorePikkuMiddlewareConfig<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = {
-  func: CorePikkuMiddleware<SingletonServices, UserSession>
-  name?: string
-  description?: string
-  /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
-  priority?: MiddlewarePriority
-}
-
-export type CorePikkuMiddlewareFactory<
-  In = any,
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>
-
-export type CorePikkuMiddlewareGroup<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = Array<
-  | CorePikkuMiddleware<SingletonServices, UserSession>
-  | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>
->
-
-export const pikkuMiddleware = <
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
->(
-  middleware:
-    | CorePikkuMiddleware<SingletonServices, UserSession>
-    | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
-): CorePikkuMiddleware<SingletonServices, UserSession> => {
-  if (typeof middleware === 'function') return middleware
-  const func = middleware.func as CorePikkuMiddleware<
-    SingletonServices,
-    UserSession
-  > & { __priority?: MiddlewarePriority }
-  if (middleware.priority) {
-    func.__priority = middleware.priority
-  }
-  return func
-}
-
-export const pikkuMiddlewareFactory = <In = any>(
-  factory: CorePikkuMiddlewareFactory<In>
-): CorePikkuMiddlewareFactory<In> => {
-  return factory
-}
-
-export const pikkuChannelMiddleware = <
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  Event = unknown,
->(
-  middleware: CorePikkuChannelMiddleware<SingletonServices, Event>
-): CorePikkuChannelMiddleware<SingletonServices, Event> => {
-  return middleware
-}
-
-export const pikkuChannelMiddlewareFactory = <In = any>(
-  factory: CorePikkuChannelMiddlewareFactory<In>
-): CorePikkuChannelMiddlewareFactory<In> => {
-  return factory
-}
-
-export type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js'
-
-export const pikkuAgentMiddleware = <
-  State extends Record<string, unknown> = Record<string, unknown>,
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
->(
-  hooks: PikkuAgentMiddlewareHooks<State, SingletonServices>
-): PikkuAgentMiddlewareHooks<State, SingletonServices> => hooks
-
 export type CoreServices<SingletonServices = CoreSingletonServices> =
   SingletonServices
 
@@ -666,16 +424,6 @@ export interface SecurityAuditReport {
   summary: SecurityAuditSummary
 }
 
-export interface SerializedError {
-  message: string
-  stack?: string
-  code?: string
-  // Set for a deliberate PikkuError; survives step-boundary rehydration so
-  // the workflow runner logs the message alone rather than a stack trace.
-  expected?: boolean
-  [key: string]: any
-}
-
 /**
  * A generated schema's declaration site, used by the credential/secret/variable
  * definition validators to point conflicting definitions at their source.

package/src/types/index.ts

@@ -0,0 +1,25 @@
+export type {
+  AuthInstance,
+  CommonWireMeta,
+  CoreConfig,
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateConfig,
+  CreateSingletonServices,
+  CreateWireServices,
+  GetCredential,
+  PikkuWire,
+  PikkuWiringTypes,
+  PostgresConfig,
+  SecretlessServices,
+  SecurityAuditIssue,
+  SecurityAuditReport,
+  SecurityAuditSummary,
+  SecurityAuditUpdate,
+  SecuritySeverity,
+  SecurityUpdateLevel,
+  ServerLifecycle,
+  WireServices,
+} from './core.types.js'
+export type * from './state.types.js'

package/src/types/state.types.ts

@@ -54,9 +54,6 @@ import type {
   TriggerSourceMeta,
 } from '../wirings/trigger/trigger.types.js'
 import type {
-  FunctionsMeta,
-  CorePikkuMiddleware,
-  CorePikkuMiddlewareGroup,
   CreateConfig,
   CreateSingletonServices,
   CreateWireServices,
@@ -65,6 +62,11 @@ import type {
   CoreServices,
   CoreUserSession,
 } from './core.types.js'
+import type { FunctionsMeta } from '../function/function-meta.types.js'
+import type {
+  CorePikkuMiddleware,
+  CorePikkuMiddlewareGroup,
+} from '../middleware/middleware.types.js'
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
 
 export interface PikkuPackageState {
@@ -210,8 +212,7 @@ export interface PikkuPackageState {
     /** The pikkuBetterAuth factory, self-registered when auth.ts is evaluated.
      *  pikkuServices reads it to build and inject the `auth` singleton. */
     authFactory:
-      | ((services: CoreSingletonServices) => unknown | Promise<unknown>)
-      | null
+      ((services: CoreSingletonServices) => unknown | Promise<unknown>) | null
     credentialsMeta: Record<
       string,
       { name: string; displayName: string; type: string; oauth2?: boolean }

package/src/types/typed-credentials.test.ts

@@ -0,0 +1,72 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import type { CoreUserSession, GetCredential, PikkuWire } from './core.types.js'
+import type { PikkuRPC } from '../wirings/rpc/rpc-types.js'
+import type { PikkuWorkflowWire } from '../wirings/workflow/workflow.types.js'
+import type { PikkuScenarioWire } from '../wirings/workflow/scenario.types.js'
+import type { ScenarioPersonas } from '../services/personas-service.js'
+
+interface CredentialsMap {
+  slack: { token: string }
+  stripe: { apiKey: string; accountId: string }
+}
+
+type TypedWire = PikkuWire<
+  unknown,
+  unknown,
+  false,
+  CoreUserSession,
+  PikkuRPC,
+  null,
+  never,
+  PikkuWorkflowWire,
+  unknown,
+  PikkuScenarioWire<any>,
+  ScenarioPersonas,
+  CredentialsMap
+>
+
+const VALUES: Record<string, unknown> = {
+  slack: { token: 'xoxb-1' },
+  stripe: { apiKey: 'sk-1', accountId: 'acct-1' },
+  'not-in-the-map': { anything: true },
+}
+
+// Mirrors `createWireServicesCredentialWireProps`, so this also pins that a
+// generic single-signature implementation still satisfies the overload pair.
+const getCredential: NonNullable<TypedWire['getCredential']> = <T = unknown>(
+  name: string
+) => (VALUES[name] ?? null) as T | null
+
+describe('wire.getCredential is typed by the generated CredentialsMap', () => {
+  test('resolves a mapped name without an explicit type argument', async () => {
+    const slack: { token: string } | null | Promise<{ token: string } | null> =
+      getCredential('slack')
+    assert.deepEqual(await slack, { token: 'xoxb-1' })
+
+    const stripe = await getCredential('stripe')
+    assert.equal(stripe?.accountId, 'acct-1')
+  })
+
+  test('rejects the wrong type for a mapped name', () => {
+    // @ts-expect-error 'slack' resolves to { token: string }, not a string
+    const wrong: string | null | Promise<string | null> = getCredential('slack')
+    assert.ok(wrong)
+  })
+
+  test('keeps an unmapped name callable with an explicit type argument', async () => {
+    const other = await getCredential<{ anything: boolean }>('not-in-the-map')
+    assert.equal(other?.anything, true)
+  })
+
+  test('falls back to unknown when no map is bound', async () => {
+    const untyped: GetCredential = <T = unknown>(name: string) =>
+      (VALUES[name] ?? null) as T | null
+    // @ts-expect-error no map is bound, so the value is unknown
+    const wrong: { token: string } | null = await untyped('slack')
+    assert.deepEqual(wrong, { token: 'xoxb-1' })
+    assert.deepEqual(await untyped<{ token: string }>('slack'), {
+      token: 'xoxb-1',
+    })
+  })
+})

package/src/utils.ts

@@ -129,3 +129,37 @@ export const pikkuServerLifecycle = <
 >(
   lifecycle: ServerLifecycle<SS>
 ): ServerLifecycle<SS> => lifecycle
+
+export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
+  Required<Pick<T, K>>
+
+export type JSONPrimitive = string | number | boolean | null | undefined
+
+export type JSONValue =
+  | JSONPrimitive
+  | JSONValue[]
+  | {
+      [key: string]: JSONValue
+    }
+
+export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>
+
+export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>
+
+export type RequireAtLeastOne<T> = {
+  [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
+}[keyof T]
+
+export {
+  getDurationInMilliseconds,
+  getRelativeTimeOffset,
+  getRelativeTimeOffsetFromNow,
+  parseDurationString,
+} from './time-utils.js'
+export type { RelativeTimeInput } from './time-utils.js'
+
+export {
+  formatVersionedId,
+  isVersionedId,
+  parseVersionedId,
+} from './version.js'

package/src/wirings/{rpc → addon}/addon-scopes.test.ts

@@ -4,7 +4,7 @@ import assert from 'node:assert/strict'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import { MissingScopeError } from '../../errors/errors.js'
-import { ContextAwareRPCService } from './rpc-runner.js'
+import { ContextAwareRPCService } from '../rpc/rpc-runner.js'
 import { wireAddon } from './wire-addon.js'
 
 const ADDON_PACKAGE = '@addon/console'

package/src/wirings/addon/index.ts

@@ -0,0 +1,12 @@
+export { wireAddon } from './wire-addon.js'
+export type { WireAddonConfig } from './wire-addon.js'
+export { wireRemoteAddon } from './wire-remote-addon.js'
+export type {
+  WireRemoteAddonConfig,
+  RemoteAddonAuth,
+} from './wire-remote-addon.js'
+export {
+  resolveRemoteAddonToken,
+  RemoteAddonAuthError,
+} from './remote-addon-auth.js'
+export type { RemoteAddonAuthBinding } from './remote-addon-auth.js'

package/src/wirings/{rpc → addon}/remote-addon-auth.ts

@@ -1,6 +1,9 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js'
 import { PikkuError, addError } from '../../errors/error-handler.js'
-import { isSecretValue, type SecretValue } from '../../secret-value.js'
+import {
+  isSecretValue,
+  type SecretValue,
+} from '../../classification/secret-value.js'
 
 export type RemoteAddonAuthBinding =
   | { credentialId: string }

package/src/wirings/{rpc → addon}/wire-addon.ts

@@ -1,7 +1,6 @@
 import { pikkuState } from '../../pikku-state.js'
 import { getTagGroups } from '../../utils.js'
-import type { CorePikkuMiddleware } from '../../types/core.types.js'
-
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
 export type WireAddonConfig = {
   name: string
   package: string
@@ -143,6 +142,42 @@ export const resolveAddonAuth = (
     (config) => config.auth === true
   )
 
+/**
+ * The package a namespaced function id belongs to, and the name that package
+ * publishes it under.
+ *
+ * A wiring that points at an addon function through `ref('ns:fn')` records
+ * `ns:fn` as its own function id — the same id every other wire type records —
+ * but the addon publishes its metadata under the bare `fn`, in its own package
+ * state. Without this the wire finds the function it registered and no metadata
+ * to run it by.
+ *
+ * The wiring itself stays the consuming app's, so `packageName` is the package
+ * the *wire* runs in, not the target's: it is null for a `ref()` the app wired,
+ * and only narrows the lookup when a wire really does run inside the addon.
+ */
+export const resolveAddonFunctionTarget = (
+  funcName: string,
+  packageName: string | null
+): { packageName: string; localName: string } | null => {
+  const separator = funcName.indexOf(':')
+  if (separator === -1) {
+    return null
+  }
+  const namespace = funcName.slice(0, separator)
+  const config = pikkuState(null, 'addons', 'packages').get(namespace)
+  if (!config) {
+    return null
+  }
+  if (packageName && config.package !== packageName) {
+    return null
+  }
+  return {
+    packageName: config.package,
+    localName: funcName.slice(separator + 1),
+  }
+}
+
 /**
  * Addon tags name middleware the *consuming app* registered, so they resolve
  * against the root tag groups rather than the addon package's own.