@pikku/core 0.12.83 → 0.12.86

package/src/middleware/telemetry.ts

@@ -1,5 +1,7 @@
-import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
-
+import {
+  pikkuMiddleware,
+  pikkuMiddlewareFactory,
+} from './middleware-factories.js'
 /** Outermost telemetry: total duration, including every middleware. */
 export const telemetryOuter = pikkuMiddlewareFactory<{
   environmentId?: string

package/src/middleware-runner.test.ts

@@ -9,9 +9,8 @@ import { pikkuState, resetPikkuState } from './pikku-state.js'
 import type {
   CorePikkuMiddleware,
   MiddlewarePriority,
-} from './types/core.types.js'
-import { pikkuMiddleware } from './types/core.types.js'
-
+} from './middleware/middleware.types.js'
+import { pikkuMiddleware } from './middleware/middleware-factories.js'
 const withPriority = (
   name: string,
   priority: MiddlewarePriority,

package/src/middleware-runner.ts

@@ -1,10 +1,10 @@
+import type { PikkuWiringTypes } from './types/core.types.js'
 import type {
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
-  PikkuWiringTypes,
   MiddlewareMetadata,
   MiddlewarePriority,
-} from './types/core.types.js'
+} from './middleware/middleware.types.js'
 import { pikkuState } from './pikku-state.js'
 import { freezeDedupe, getTagGroups } from './utils.js'
 

package/src/no-root-barrel.test.ts

@@ -0,0 +1,114 @@
+import { test, describe } from 'node:test'
+import * as assert from 'assert'
+import ts from 'typescript'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * The package root was one barrel of 206 names that no bundler could take
+ * apart, and the one specifier that revealed nothing about what a consumer
+ * actually used.
+ *
+ * It is gone. Every name lives on the subpath that owns it, and every import
+ * carries that subpath. What survives is a bootstrap shim, which the second
+ * test here holds to its exact contents.
+ */
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+const skipDirectory = new Set([
+  'node_modules',
+  'dist',
+  '.git',
+  'build',
+  'coverage',
+])
+
+const walk = (dir: string, out: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    if (skipDirectory.has(entry)) continue
+    const path = join(dir, entry)
+    if (statSync(path).isDirectory()) walk(path, out)
+    else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)
+  }
+  return out
+}
+
+/**
+ * Generated output belongs to whichever CLI wrote it — including the pinned
+ * published one that bootstraps `packages/cli` and still emits the old
+ * specifiers. What this branch's serializers emit is covered by the CLI's own
+ * tests, against the template rather than its output.
+ */
+const isGenerated = (path: string) =>
+  path.includes('.gen.') || path.endsWith('.d.ts') || path.includes('/.pikku/')
+
+describe('no root barrel', () => {
+  /**
+   * Parsed rather than grepped: several tests hold a user's file as a template
+   * literal, and `import { pikkuSessionlessFunc } from '@pikku/core'` inside
+   * one is fixture text for the inspector, not an import this repo makes.
+   */
+  test('nothing imports the package root', () => {
+    const offenders: string[] = []
+
+    for (const file of walk(repoRoot)) {
+      if (isGenerated(file)) continue
+      const source = ts.createSourceFile(
+        file,
+        readFileSync(file, 'utf8'),
+        ts.ScriptTarget.Latest,
+        true
+      )
+      for (const statement of source.statements) {
+        if (
+          !ts.isImportDeclaration(statement) &&
+          !ts.isExportDeclaration(statement)
+        ) {
+          continue
+        }
+        const specifier = statement.moduleSpecifier
+        if (!specifier || !ts.isStringLiteral(specifier)) continue
+        if (specifier.text !== '@pikku/core') continue
+        const { line } = source.getLineAndCharacterOfPosition(
+          statement.getStart(source)
+        )
+        offenders.push(`${relative(repoRoot, file)}:${line + 1}`)
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `The '@pikku/core' root is a bootstrap shim, not an entry point. Every ` +
+        `import carries the subpath that owns the name — '@pikku/core/types' ` +
+        `for the shared types, '@pikku/core/services' for the services.\n\n` +
+        offenders.join('\n')
+    )
+  })
+
+  /**
+   * The shim exists because `packages/cli` is generated by the published CLI
+   * pinned in its `build.sh`, which still writes these specifiers. Holding it
+   * to an exact list is what keeps it a shim: a name can only be added here by
+   * someone who has read why it should not be.
+   */
+  test('the bootstrap shim carries only what the pinned CLI emits', () => {
+    const surface = (file: string) =>
+      readFileSync(join(dirname(fileURLToPath(import.meta.url)), file), 'utf8')
+        .replace(/\/\*\*[\s\S]*?\*\//g, '')
+        .match(/\b[A-Za-z][A-Za-z0-9]*\b(?=[,\n\s]*(?:,|\}))/g)
+        ?.sort() ?? []
+
+    assert.deepStrictEqual(surface('bootstrap-compat/root.ts'), [
+      'CorePermissionGroup',
+      'CorePikkuMiddleware',
+      'ListInput',
+      'ListOutput',
+      'PickRequired',
+      'PikkuWire',
+      'SecretService',
+      'SecretlessServices',
+    ])
+  })
+})

package/src/permissions.ts

@@ -75,8 +75,7 @@ export const addGlobalPermission = (
   packageName: string | null = null
 ): CorePermissionGroup | CorePikkuPermission[] => {
   const state = pikkuState(packageName, 'permissions', 'global') as unknown as (
-    | CorePermissionGroup
-    | CorePikkuPermission
+    CorePermissionGroup | CorePikkuPermission
   )[]
   if (Array.isArray(permissions)) {
     state.push(...(permissions as CorePikkuPermission[]))
@@ -91,8 +90,7 @@ const bucket = (
   packageName: string | null
 ): (CorePermissionGroup | CorePikkuPermission)[] =>
   (pikkuState(packageName, 'permissions', 'global') as unknown as (
-    | CorePermissionGroup
-    | CorePikkuPermission
+    CorePermissionGroup | CorePikkuPermission
   )[]) ?? []
 
 /**

package/src/pikku-state.ts

@@ -1,4 +1,4 @@
-import type { PikkuPackageState } from './index.js'
+import type { PikkuPackageState } from './types/state.types.js'
 import type {
   CoreSingletonServices,
   CreateWireServices,
@@ -9,8 +9,8 @@ import type {
   MCPToolMeta,
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
-import type { AIAgentMeta } from './wirings/ai-agent/ai-agent.types.js'
-import type { ScorerMeta } from './wirings/ai-scorer/ai-scorer.types.js'
+import type { AgentsMeta } from './wirings/agent/agent.types.js'
+import type { ScorerMeta } from './wirings/agent-scorer/agent-scorer.types.js'
 import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
 import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
 import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
@@ -118,7 +118,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   },
   agent: {
     agents: new Map(),
-    agentsMeta: {} as AIAgentMeta,
+    agentsMeta: {} as AgentsMeta,
     scorers: new Map(),
     scorersMeta: {} as ScorerMeta,
     modelAliases: {},
@@ -202,3 +202,5 @@ export const addPackageServiceFactories = (
 ): void => {
   pikkuState(packageName, 'package', 'factories', factories)
 }
+
+export type { PikkuPackageState } from './types/state.types.js'

package/src/public-surface.json

@@ -1,93 +1,6 @@
 {
-  ".": [
-    "AIProviderAuthError",
-    "AIProviderNotConfiguredError",
-    "AbandonedError",
-    "BadGatewayError",
-    "BadRequestError",
-    "ConflictError",
-    "ExpectationFailedError",
-    "ForbiddenError",
-    "GatewayTimeoutError",
-    "GoneError",
-    "HTTPVersionNotSupportedError",
-    "InternalServerError",
-    "InvalidMiddlewareWireError",
-    "InvalidOriginError",
-    "InvalidSessionError",
-    "LengthRequiredError",
-    "LocalEnvironmentOnlyError",
-    "LockedError",
-    "MaxComputeTimeReachedError",
-    "MethodNotAllowedError",
-    "MissingCredentialError",
-    "MissingSchemaError",
-    "MissingScopeError",
-    "MissingServiceError",
-    "MissingSessionError",
-    "NoopAuditService",
-    "NotAcceptableError",
-    "NotFoundError",
-    "NotImplementedError",
-    "PayloadTooLargeError",
-    "PaymentRequiredError",
-    "PikkuError",
-    "PikkuMissingMetaError",
-    "PikkuRequest",
-    "PreconditionFailedError",
-    "ProxyAuthenticationRequiredError",
-    "REDACTED",
-    "RangeNotSatisfiableError",
-    "ReadonlySessionError",
-    "RequestTimeoutError",
-    "SchedulerService",
-    "SecretAccessDeniedError",
-    "SecretCoercionError",
-    "SecretHostNotAllowedError",
-    "ServiceUnavailableError",
-    "TooManyRequestsError",
-    "URITooLongError",
-    "UnauthorizedError",
-    "UnprocessableContentError",
-    "UnsupportedMediaTypeError",
-    "addGlobalPermission",
-    "addTagMiddleware",
-    "assertSecretAllowedForHost",
-    "checkAuthPermissions",
-    "clearPikkuRuntimeState",
-    "createGraph",
-    "createInvocationAudit",
-    "createSecretValue",
-    "fetch",
-    "formatVersionedId",
-    "getAllFunctionNames",
-    "getRelativeTimeOffsetFromNow",
-    "hasScopes",
-    "hashToken",
-    "isExpectedError",
-    "isSecretValue",
-    "isSerializable",
-    "isVersionedId",
-    "parseDurationString",
-    "parseVersionedId",
-    "pikkuAIMiddleware",
-    "pikkuApprovalDescription",
-    "pikkuAuth",
-    "pikkuCLIRender",
-    "pikkuChannelMiddleware",
-    "pikkuChannelMiddlewareFactory",
-    "pikkuMiddleware",
-    "pikkuMiddlewareFactory",
-    "pikkuPermission",
-    "pikkuPermissionFactory",
-    "pikkuServerLifecycle",
-    "runMiddleware",
-    "stopSingletonServices",
-    "verifyScopes",
-    "wireAddon",
-    "wireRemoteAddon",
-    "withoutSecrets"
-  ],
+  ".": [],
+  "./types": [],
   "./middleware": [
     "addGlobalMiddleware",
     "addGlobalPermission",
@@ -97,18 +10,27 @@
     "authBearer",
     "authCookie",
     "cors",
+    "pikkuAgentMiddleware",
+    "pikkuChannelMiddleware",
+    "pikkuChannelMiddlewareFactory",
+    "pikkuMiddleware",
+    "pikkuMiddlewareFactory",
     "pikkuRemoteAuthMiddleware",
     "runMiddleware",
     "telemetryInner",
     "telemetryOuter"
   ],
   "./function": [
+    "AbandonedError",
+    "PikkuRequest",
     "addFunction",
+    "checkAuthPermissions",
     "getAllFunctionNames",
     "pikkuApprovalDescription",
     "pikkuAuth",
     "pikkuPermission",
-    "pikkuPermissionFactory"
+    "pikkuPermissionFactory",
+    "runPikkuFunc"
   ],
   "./channel": [
     "ChannelDeploymentService",
@@ -139,6 +61,7 @@
     "addWorkflow",
     "assertWorkflowRunOwner",
     "buildRunTimeline",
+    "createGraph",
     "deriveInvocationId",
     "isRef",
     "pikkuWorkflowGraph",
@@ -150,7 +73,7 @@
   "./scenario": [
     "PikkuScenarioService",
     "SCENARIO_SURFACES",
-    "ScenarioBrowserActorRequired",
+    "ScenarioActorRequired",
     "ScenarioBrowserUnavailable",
     "ScenarioHookError",
     "ScenarioNoSurfaceBinding",
@@ -162,7 +85,6 @@
     "createScenarioRunner",
     "pollUntil",
     "renderStepTemplate",
-    "requireActor",
     "requireScenarioEnv",
     "resolveFeatureScenarios",
     "resolveScenarioSurfaces"
@@ -173,9 +95,7 @@
     "reconstructStateAt"
   ],
   "./workflow/types": [],
-  "./actor-flow": [
-    "runConversation"
-  ],
+  "./actor-flow": ["runConversation"],
   "./virtual-user": [
     "DISPOSITIONS",
     "IntentStack",
@@ -213,14 +133,13 @@
     "defineHTTPRoutes",
     "fetch",
     "fetchData",
+    "httpRouter",
     "logRoutes",
     "toWebRequest",
     "wireHTTP",
     "wireHTTPRoutes"
   ],
-  "./remote": [
-    "buildRemoteHeaders"
-  ],
+  "./remote": ["buildRemoteHeaders"],
   "./queue": [
     "QueueJobDiscardedError",
     "QueueJobFailedError",
@@ -235,19 +154,17 @@
     "runScheduledTask",
     "wireScheduler"
   ],
-  "./trigger": [
-    "PikkuTriggerService",
-    "wireTrigger",
-    "wireTriggerSource"
-  ],
+  "./trigger": ["PikkuTriggerService", "wireTrigger", "wireTriggerSource"],
   "./rpc": [
     "PikkuRPCService",
     "RPCNotFoundError",
-    "RemoteAddonAuthError",
     "RemoteAddonConfigError",
     "RemoteAddonRequestError",
+    "rpcService"
+  ],
+  "./addon": [
+    "RemoteAddonAuthError",
     "resolveRemoteAddonToken",
-    "rpcService",
     "wireAddon",
     "wireRemoteAddon"
   ],
@@ -257,10 +174,7 @@
     "safeFetch",
     "setDefaultHostResolver"
   ],
-  "./node-host-resolver": [
-    "installNodeHostResolver",
-    "nodeHostResolver"
-  ],
+  "./node-host-resolver": ["installNodeHostResolver", "nodeHostResolver"],
   "./mcp": [
     "MCPEndpointRegistry",
     "MCPError",
@@ -273,28 +187,28 @@
     "wireMCPPrompt",
     "wireMCPResource"
   ],
-  "./ai-agent": [
+  "./agent": [
     "AgentInterruptedError",
     "NoSpeechDetectedError",
     "SPOKEN_TRANSCRIPT",
     "SPOKEN_TURN",
     "ToolApprovalRequired",
     "ToolCredentialRequired",
-    "addAIAgent",
+    "addAgent",
     "agent",
     "agentApprove",
     "agentInterrupt",
     "agentResume",
     "agentStream",
     "canAccessThread",
-    "interruptAIAgent",
+    "interruptAgent",
     "isOwnedByPrincipal",
     "resolveModelAlias",
-    "resumeAIAgent",
-    "resumeAIAgentSync",
-    "runAIAgent",
+    "resumeAgent",
+    "resumeAgentSync",
+    "runAgent",
     "signalRunInterrupt",
-    "streamAIAgent",
+    "streamAgent",
     "threadOwnerConstraint",
     "unspeakableScripts",
     "voiceForText",
@@ -302,16 +216,16 @@
     "voiceOutput",
     "wrapChannelWithAGUI"
   ],
-  "./ai-scorer": [
-    "addAIScorer",
+  "./agent-scorer": [
+    "addAgentScorer",
     "enableScoreSnapshots",
-    "getAIScorers",
-    "getAIScorersMeta",
+    "getAgentScorers",
+    "getAgentScorersMeta",
     "getScoreSnapshot",
     "gradeRun",
-    "pikkuAIJudge",
-    "pikkuAIScorer",
-    "wireAIScorerQueueWorkers"
+    "pikkuAgentJudge",
+    "pikkuAgentScorer",
+    "wireAgentScorerQueueWorkers"
   ],
   "./gateway": [
     "createListenerMessageHandler",
@@ -328,10 +242,7 @@
     "runCLICommand",
     "wireCLI"
   ],
-  "./cli/command-parser": [
-    "generateCommandHelp",
-    "parseCLIArguments"
-  ],
+  "./cli/command-parser": ["generateCommandHelp", "parseCLIArguments"],
   "./cli/channel": [
     "executeCLIViaChannel",
     "executeRawCLIViaChannel",
@@ -345,7 +256,9 @@
   "./scope": [
     "defineScope",
     "flattenScopeDefinitions",
-    "validateAndBuildScopeDefinitionsMeta"
+    "hasScopes",
+    "validateAndBuildScopeDefinitionsMeta",
+    "verifyScopes"
   ],
   "./role": [
     "defineSystemRole",
@@ -368,14 +281,8 @@
     "validateAndBuildPersonasMeta",
     "verifyPersonaRoles"
   ],
-  "./secret": [
-    "defineSecret",
-    "validateAndBuildSecretDefinitionsMeta"
-  ],
-  "./variable": [
-    "defineVariable",
-    "validateAndBuildVariableDefinitionsMeta"
-  ],
+  "./secret": ["defineSecret", "validateAndBuildSecretDefinitionsMeta"],
+  "./variable": ["defineVariable", "validateAndBuildVariableDefinitionsMeta"],
   "./oauth2": [],
   "./errors": [
     "AIProviderAuthError",
@@ -423,12 +330,14 @@
     "UnprocessableContentError",
     "UnsupportedMediaTypeError",
     "WeakKeyMaterialError",
-    "addError"
+    "addError",
+    "isExpectedError"
   ],
   "./services": [
     "ConsoleLogger",
     "DEFAULT_WEBHOOK_RETRIES",
-    "InMemoryAIRunStateService",
+    "FileScenarioRunStore",
+    "InMemoryAgentRunStateService",
     "InMemoryQueueService",
     "InMemorySessionStore",
     "InMemoryTriggerService",
@@ -445,8 +354,10 @@
     "PikkuCredentialWireService",
     "PikkuSessionService",
     "QueueWebhookService",
+    "SchedulerService",
     "ScopedCredentialService",
     "ScopedSecretService",
+    "SecretAccessDeniedError",
     "SecretHostNotAllowedError",
     "StubTracker",
     "TypedCredentialService",
@@ -460,22 +371,16 @@
     "getStubTracker",
     "isTestRun",
     "pikkuWebhookWorkerFunc",
+    "scenarioArtifactContentType",
+    "scenarioRunSummary",
     "spy",
-    "stub"
-  ],
-  "./services/local-meta": [
-    "LocalMetaService"
-  ],
-  "./services/v8-coverage": [
-    "V8CoverageService"
-  ],
-  "./services/istanbul-coverage": [
-    "IstanbulCoverageService"
-  ],
-  "./services/local-content": [
-    "LocalContent",
-    "signedContentPath"
+    "stub",
+    "withoutSecrets"
   ],
+  "./services/local-meta": ["LocalMetaService"],
+  "./services/v8-coverage": ["V8CoverageService"],
+  "./services/istanbul-coverage": ["IstanbulCoverageService"],
+  "./services/local-content": ["LocalContent", "signedContentPath"],
   "./services/local-content-request-handler": [
     "createLocalContentRequestHandler",
     "verifySignedContentRequest"
@@ -505,23 +410,44 @@
     "verifyWithKeyMaterial",
     "wrapDEK"
   ],
-  "./hmac": [
-    "hmacSha256Hex",
-    "timingSafeStringEqual"
-  ],
-  "./ecosystem": [
-    "addFunction",
-    "addGlobalMiddleware",
-    "addMiddleware",
+  "./hmac": ["hmacSha256Hex", "timingSafeStringEqual"],
+  "./state": [
+    "addPackageServiceFactories",
     "getAllPackageStates",
     "getCreateWireServices",
     "getSingletonServices",
-    "httpRouter",
+    "initializePikkuState",
     "pikkuState",
     "resetPikkuState",
-    "runPikkuFunc",
     "setSingletonServices"
   ],
+  "./classification": [
+    "REDACTED",
+    "SecretCoercionError",
+    "SecretValue",
+    "createSecretValue",
+    "hashToken",
+    "isSecretValue",
+    "unsafeAsHashed",
+    "unsafeAsSealed",
+    "unsafeAsWrapped"
+  ],
+  "./utils": [
+    "closeWireServices",
+    "createWeakUID",
+    "formatVersionedId",
+    "freezeDedupe",
+    "getDurationInMilliseconds",
+    "getRelativeTimeOffset",
+    "getRelativeTimeOffsetFromNow",
+    "getTagGroups",
+    "isSerializable",
+    "isVersionedId",
+    "parseDurationString",
+    "parseVersionedId",
+    "pikkuServerLifecycle",
+    "stopSingletonServices"
+  ],
   "./schema": [
     "addSchema",
     "applyDefaultsFromSchema",
@@ -530,12 +456,6 @@
     "getSchema",
     "validateSchema"
   ],
-  "./testing": [
-    "defineServiceTests"
-  ],
-  "./dev": [
-    "pikkuDevReloader",
-    "reconcileAddonRegistry",
-    "reloadGeneratedMeta"
-  ]
+  "./testing": ["clearPikkuRuntimeState", "defineServiceTests"],
+  "./dev": ["pikkuDevReloader", "reconcileAddonRegistry", "reloadGeneratedMeta"]
 }

package/src/public-surface.json.README

@@ -5,17 +5,35 @@ disagree, so widening the API is a visible diff rather than a side effect of an
 
 Types are not pinned: they are erased before the test can enumerate them.
 
+A wildcard subpath is expanded to the files it matches, so it is pinned as one
+entry per area rather than as a pattern — otherwise a new sub-barrel joins the
+published API without a diff.
+
 Regenerate after an intentional change, from `packages/core`:
 
 ```bash
 cat > src/__gen-surface.mts <<'EOF'
-import { readFileSync, writeFileSync } from 'node:fs'
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 const pkg = JSON.parse(readFileSync('package.json', 'utf-8'))
+const expand = ([sub, dist]: [string, string]): [string, string][] => {
+  if (!sub.includes('*')) return [[sub, dist]]
+  const [prefix] = dist.split('*') as [string]
+  return readdirSync(resolve(prefix.replace('./dist/', './src/')), {
+    recursive: true,
+    encoding: 'utf-8',
+  })
+    .filter((f) => f.endsWith('.ts') && !f.endsWith('.d.ts'))
+    .map((f) => f.slice(0, -'.ts'.length))
+    .sort()
+    .map((area) => [sub.replace('*', area), dist.replace('*', area)])
+}
 const surface: Record<string, string[]> = {}
-for (const [sub, dist] of Object.entries(pkg.exports as Record<string, string>)) {
+for (const [sub, dist] of Object.entries(
+  pkg.exports as Record<string, string>
+).flatMap(expand)) {
   const src = pathToFileURL(resolve(dist.replace('./dist/', './src/'))).href
   surface[sub] = Object.keys(await import(src)).sort()
 }