@pikku/core 0.12.79 → 0.12.82

package/src/public-surface.json

@@ -0,0 +1,554 @@
+{
+  ".": [
+    "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"
+  ],
+  "./middleware": [
+    "addGlobalMiddleware",
+    "addGlobalPermission",
+    "addMiddleware",
+    "addTagMiddleware",
+    "authAPIKey",
+    "authBearer",
+    "authCookie",
+    "cors",
+    "pikkuRemoteAuthMiddleware",
+    "runMiddleware",
+    "telemetryInner",
+    "telemetryOuter"
+  ],
+  "./function": [
+    "addFunction",
+    "getAllFunctionNames",
+    "pikkuApprovalDescription",
+    "pikkuAuth",
+    "pikkuPermission",
+    "pikkuPermissionFactory"
+  ],
+  "./channel": [
+    "ChannelDeploymentService",
+    "ChannelRPCError",
+    "ChannelRPCRegistry",
+    "ChannelStore",
+    "EventHubStore",
+    "PikkuAbstractChannelHandler",
+    "addChannelMiddleware",
+    "combineChannelMiddleware",
+    "defineChannelRoutes",
+    "logChannels",
+    "unsupportedChannelRemote",
+    "wireChannel"
+  ],
+  "./workflow": [
+    "DEFAULT_STEP_RETRIES",
+    "PikkuWorkflowService",
+    "SCENARIO_SURFACES",
+    "WorkflowApprovalForbiddenError",
+    "WorkflowApprovalResolvedError",
+    "WorkflowCancelledException",
+    "WorkflowDispatchException",
+    "WorkflowNotFoundError",
+    "WorkflowRunForbiddenError",
+    "WorkflowRunNotFoundError",
+    "WorkflowStepFunctionMismatchError",
+    "WorkflowSuspendedException",
+    "addFeature",
+    "addWorkflow",
+    "assertWorkflowRunOwner",
+    "buildRunTimeline",
+    "composeStepProse",
+    "createCookieJar",
+    "deriveInvocationId",
+    "isRef",
+    "pikkuWorkflowGraph",
+    "pollUntil",
+    "reconstructFinalState",
+    "reconstructStateAt",
+    "renderStepTemplate",
+    "requireActor",
+    "requireScenarioEnv",
+    "resolveFeatureScenarios",
+    "resolveScenarioSurfaces",
+    "template",
+    "uuidv5"
+  ],
+  "./scenario": [
+    "PikkuScenarioService",
+    "ScenarioBrowserActorRequired",
+    "ScenarioBrowserUnavailable",
+    "ScenarioHookError",
+    "ScenarioNoSurfaceBinding",
+    "ScenarioNoWitness",
+    "ScenarioWitnessDisagreement",
+    "createScenarioRunner"
+  ],
+  "./workflow/timeline": [
+    "buildRunTimeline",
+    "reconstructFinalState",
+    "reconstructStateAt"
+  ],
+  "./workflow/types": [],
+  "./actor-flow": [
+    "runConversation"
+  ],
+  "./virtual-user": [
+    "DISPOSITIONS",
+    "IntentStack",
+    "PRODUCTION_DISPOSITION",
+    "catalogueClassification",
+    "catalogueLookup",
+    "deriveCatalogue",
+    "deriveIntents",
+    "dispositionProfile",
+    "intentsForPersona",
+    "isReadOnly",
+    "personaScopes",
+    "personaVirtualUserTarget",
+    "prepareVirtualUserRun",
+    "reachableCatalogue",
+    "runVirtualUser",
+    "unreachableCatalogue"
+  ],
+  "./channel/local": [
+    "LocalEventHubService",
+    "PikkuLocalChannelHandler",
+    "runLocalChannel"
+  ],
+  "./channel/serverless": [
+    "runChannelConnect",
+    "runChannelDisconnect",
+    "runChannelMessage"
+  ],
+  "./http": [
+    "DEFAULT_MAX_BODY_SIZE",
+    "PikkuFetchHTTPRequest",
+    "PikkuFetchHTTPResponse",
+    "addHTTPMiddleware",
+    "applyWebResponse",
+    "defineHTTPRoutes",
+    "fetch",
+    "fetchData",
+    "logRoutes",
+    "toWebRequest",
+    "wireHTTP",
+    "wireHTTPRoutes"
+  ],
+  "./remote": [
+    "buildRemoteHeaders"
+  ],
+  "./queue": [
+    "QueueJobDiscardedError",
+    "QueueJobFailedError",
+    "SignedQueueService",
+    "registerQueueWorkers",
+    "runQueueJob",
+    "wireQueueWorker"
+  ],
+  "./scheduler": [
+    "getScheduledTasks",
+    "logSchedulers",
+    "runScheduledTask",
+    "wireScheduler"
+  ],
+  "./trigger": [
+    "PikkuTriggerService",
+    "wireTrigger",
+    "wireTriggerSource"
+  ],
+  "./rpc": [
+    "PikkuRPCService",
+    "RPCNotFoundError",
+    "RemoteAddonAuthError",
+    "RemoteAddonConfigError",
+    "RemoteAddonRequestError",
+    "resolveRemoteAddonToken",
+    "rpcService",
+    "wireAddon",
+    "wireRemoteAddon"
+  ],
+  "./safe-fetch": [
+    "assertFetchableUrl",
+    "isPrivateHost",
+    "safeFetch",
+    "setDefaultHostResolver"
+  ],
+  "./node-host-resolver": [
+    "installNodeHostResolver",
+    "nodeHostResolver"
+  ],
+  "./mcp": [
+    "MCPEndpointRegistry",
+    "MCPError",
+    "getMCPPromptsMeta",
+    "getMCPResourcesMeta",
+    "getMCPToolsMeta",
+    "runMCPPrompt",
+    "runMCPResource",
+    "runMCPTool",
+    "wireMCPPrompt",
+    "wireMCPResource"
+  ],
+  "./ai-agent": [
+    "AgentInterruptedError",
+    "NoSpeechDetectedError",
+    "SPOKEN_TRANSCRIPT",
+    "SPOKEN_TURN",
+    "ToolApprovalRequired",
+    "ToolCredentialRequired",
+    "addAIAgent",
+    "agent",
+    "agentApprove",
+    "agentInterrupt",
+    "agentResume",
+    "agentStream",
+    "canAccessThread",
+    "interruptAIAgent",
+    "isOwnedByPrincipal",
+    "resolveModelAlias",
+    "resumeAIAgent",
+    "resumeAIAgentSync",
+    "runAIAgent",
+    "signalRunInterrupt",
+    "streamAIAgent",
+    "threadOwnerConstraint",
+    "unspeakableScripts",
+    "voiceForText",
+    "voiceInput",
+    "voiceOutput",
+    "wrapChannelWithAGUI"
+  ],
+  "./ai-scorer": [
+    "addAIScorer",
+    "enableScoreSnapshots",
+    "getAIScorers",
+    "getAIScorersMeta",
+    "getScoreSnapshot",
+    "gradeRun",
+    "pikkuAIJudge",
+    "pikkuAIScorer",
+    "wireAIScorerQueueWorkers"
+  ],
+  "./gateway": [
+    "createListenerMessageHandler",
+    "resolveGatewayAdapter",
+    "wireGateway"
+  ],
+  "./cli": [
+    "CLIError",
+    "defineCLICommands",
+    "executeCLI",
+    "generateCommandHelp",
+    "parseCLIArguments",
+    "pikkuCLIRender",
+    "runCLICommand",
+    "wireCLI"
+  ],
+  "./cli/command-parser": [
+    "generateCommandHelp",
+    "parseCLIArguments"
+  ],
+  "./cli/channel": [
+    "executeCLIViaChannel",
+    "executeRawCLIViaChannel",
+    "handleRawCLI"
+  ],
+  "./node": [],
+  "./credential": [
+    "defineCredential",
+    "validateAndBuildCredentialDefinitionsMeta"
+  ],
+  "./scope": [
+    "defineScope",
+    "flattenScopeDefinitions",
+    "validateAndBuildScopeDefinitionsMeta"
+  ],
+  "./role": [
+    "defineSystemRole",
+    "flattenSystemRoleDefinitions",
+    "validateAndBuildSystemRoleDefinitionsMeta"
+  ],
+  "./persona": [
+    "HttpPersona",
+    "createHttpPersonas",
+    "definePersonas",
+    "isRunnablePersona",
+    "personaEmail",
+    "personaEmails",
+    "personaEnvironmentErrors",
+    "personaEnvironmentRefusal",
+    "postScenarioJson",
+    "readScenarioHttpResponse",
+    "roleMismatchMessage",
+    "runnablePersonas",
+    "validateAndBuildPersonasMeta",
+    "verifyPersonaRoles"
+  ],
+  "./secret": [
+    "defineSecret",
+    "validateAndBuildSecretDefinitionsMeta"
+  ],
+  "./variable": [
+    "defineVariable",
+    "validateAndBuildVariableDefinitionsMeta"
+  ],
+  "./oauth2": [],
+  "./errors": [
+    "AIProviderAuthError",
+    "AIProviderNotConfiguredError",
+    "BadGatewayError",
+    "BadRequestError",
+    "ConflictError",
+    "ExpectationFailedError",
+    "ForbiddenError",
+    "GatewayTimeoutError",
+    "GoneError",
+    "HTTPVersionNotSupportedError",
+    "InternalServerError",
+    "InvalidMiddlewareWireError",
+    "InvalidOriginError",
+    "InvalidSessionError",
+    "LengthRequiredError",
+    "LocalEnvironmentOnlyError",
+    "LockedError",
+    "MaxComputeTimeReachedError",
+    "MethodNotAllowedError",
+    "MissingCredentialError",
+    "MissingSchemaError",
+    "MissingScopeError",
+    "MissingServiceError",
+    "MissingSessionError",
+    "NotAcceptableError",
+    "NotFoundError",
+    "NotImplementedError",
+    "PayloadTooLargeError",
+    "PaymentRequiredError",
+    "PikkuError",
+    "PikkuMissingMetaError",
+    "PreconditionFailedError",
+    "ProxyAuthenticationRequiredError",
+    "RangeNotSatisfiableError",
+    "ReadonlySessionError",
+    "RequestTimeoutError",
+    "ServiceUnavailableError",
+    "SystemRoleImmutableError",
+    "SystemRoleShadowedError",
+    "TooManyRequestsError",
+    "URITooLongError",
+    "UnauthorizedError",
+    "UnprocessableContentError",
+    "UnsupportedMediaTypeError",
+    "WeakKeyMaterialError",
+    "addError"
+  ],
+  "./services": [
+    "ConsoleLogger",
+    "DEFAULT_WEBHOOK_RETRIES",
+    "InMemoryAIRunStateService",
+    "InMemoryQueueService",
+    "InMemorySessionStore",
+    "InMemoryTriggerService",
+    "InMemoryWorkflowService",
+    "JsonConsoleLogger",
+    "LocalCredentialService",
+    "LocalEmailService",
+    "LocalGatewayService",
+    "LocalSecretService",
+    "LocalVariablesService",
+    "LogLevel",
+    "NoopAuditService",
+    "PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME",
+    "PikkuCredentialWireService",
+    "PikkuSessionService",
+    "QueueWebhookService",
+    "ScopedCredentialService",
+    "ScopedSecretService",
+    "SecretHostNotAllowedError",
+    "StubTracker",
+    "TypedCredentialService",
+    "TypedSecretService",
+    "TypedVariablesService",
+    "WebhookService",
+    "assertSecretAllowedForHost",
+    "createInvocationAudit",
+    "createMiddlewareSessionWireProps",
+    "createStubProxy",
+    "getStubTracker",
+    "isTestRun",
+    "pikkuWebhookWorkerFunc",
+    "spy",
+    "stub"
+  ],
+  "./services/local-meta": [
+    "LocalMetaService"
+  ],
+  "./services/v8-coverage": [
+    "V8CoverageService"
+  ],
+  "./services/istanbul-coverage": [
+    "IstanbulCoverageService"
+  ],
+  "./services/local-content": [
+    "LocalContent",
+    "signedContentPath"
+  ],
+  "./services/local-content-request-handler": [
+    "createLocalContentRequestHandler",
+    "verifySignedContentRequest"
+  ],
+  "./services/temporary-file-service": [
+    "TemporaryFileInstance",
+    "TemporaryFileService"
+  ],
+  "./crypto-utils": [
+    "MIN_KEY_MATERIAL_LENGTH",
+    "REMOTE_SESSION_INFO",
+    "assertStrongKeyMaterial",
+    "decodeBase64UrlText",
+    "decryptJSON",
+    "decryptWithKeyMaterial",
+    "deriveKEK",
+    "encodeBase64UrlText",
+    "encryptJSON",
+    "encryptWithKeyMaterial",
+    "envelopeDecrypt",
+    "envelopeEncrypt",
+    "envelopeRewrap",
+    "generateDEK",
+    "generateKEKSalt",
+    "signWithKeyMaterial",
+    "unwrapDEK",
+    "verifyWithKeyMaterial",
+    "wrapDEK"
+  ],
+  "./hmac": [
+    "hmacSha256Hex",
+    "timingSafeStringEqual"
+  ],
+  "./ecosystem": [
+    "addFunction",
+    "addGlobalMiddleware",
+    "addMiddleware",
+    "getAllPackageStates",
+    "getCreateWireServices",
+    "getSingletonServices",
+    "httpRouter",
+    "pikkuState",
+    "resetPikkuState",
+    "runPikkuFunc",
+    "setSingletonServices"
+  ],
+  "./internal": [
+    "addFunction",
+    "addGlobalMiddleware",
+    "addMiddleware",
+    "getAllPackageStates",
+    "getCreateWireServices",
+    "getSingletonServices",
+    "httpRouter",
+    "pikkuState",
+    "resetPikkuState",
+    "runPikkuFunc",
+    "setSingletonServices"
+  ],
+  "./schema": [
+    "addSchema",
+    "applyDefaultsFromSchema",
+    "coerceTopLevelDataFromSchema",
+    "compileAllSchemas",
+    "getSchema",
+    "validateSchema"
+  ],
+  "./testing": [
+    "defineServiceTests"
+  ],
+  "./dev": [
+    "pikkuDevReloader",
+    "reconcileAddonRegistry",
+    "reloadGeneratedMeta"
+  ]
+}

package/src/public-surface.json.README

@@ -0,0 +1,25 @@
+`public-surface.json` pins every runtime export reachable through a
+`package.json` `exports` subpath. `public-surface.test.ts` fails when the two
+disagree, so widening the API is a visible diff rather than a side effect of an
+`export *`.
+
+Types are not pinned: they are erased before the test can enumerate them.
+
+Regenerate after an intentional change, from `packages/core`:
+
+```bash
+cat > src/__gen-surface.mts <<'EOF'
+import { 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 surface: Record<string, string[]> = {}
+for (const [sub, dist] of Object.entries(pkg.exports as Record<string, string>)) {
+  const src = pathToFileURL(resolve(dist.replace('./dist/', './src/'))).href
+  surface[sub] = Object.keys(await import(src)).sort()
+}
+writeFileSync('src/public-surface.json', JSON.stringify(surface, null, 2) + '\n')
+EOF
+npx tsx src/__gen-surface.mts && rm src/__gen-surface.mts
+```

package/src/public-surface.test.ts

@@ -0,0 +1,105 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+const packageRoot = join(srcRoot, '..')
+
+const packageJson = JSON.parse(
+  readFileSync(join(packageRoot, 'package.json'), 'utf-8')
+)
+const expected: Record<string, string[]> = JSON.parse(
+  readFileSync(join(srcRoot, 'public-surface.json'), 'utf-8')
+)
+
+const subpaths = packageJson.exports as Record<string, string>
+
+/**
+ * Every runtime export reachable through an entry point, keyed by subpath.
+ *
+ * Types are absent: they are erased before this can see them, so a type-only
+ * addition is not pinned here.
+ */
+const actualSurface = async () => {
+  const surface: Record<string, string[]> = {}
+  for (const [subpath, dist] of Object.entries(subpaths)) {
+    const src = resolve(packageRoot, dist.replace('./dist/', './src/'))
+    const module = await import(pathToFileURL(src).href)
+    surface[subpath] = Object.keys(module).sort()
+  }
+  return surface
+}
+
+const REGENERATE =
+  'Regenerate with the snippet in public-surface.json.README, and make sure ' +
+  'every added name is one @pikku/core means to publish.'
+
+describe('the published surface is the surface we meant to publish', () => {
+  test('every export subpath resolves to a source file', () => {
+    const missing = Object.entries(subpaths).filter(([, dist]) => {
+      try {
+        readFileSync(
+          resolve(packageRoot, dist.replace('./dist/', './src/')).replace(
+            /\.js$/,
+            '.ts'
+          )
+        )
+        return false
+      } catch {
+        return true
+      }
+    })
+
+    assert.deepEqual(
+      missing.map(([subpath]) => subpath),
+      [],
+      'package.json exports point at files that do not exist in src'
+    )
+  })
+
+  test('no entry point gained or lost a runtime export', async () => {
+    const actual = await actualSurface()
+
+    assert.deepEqual(
+      Object.keys(actual).sort(),
+      Object.keys(expected).sort(),
+      `the set of export subpaths changed. ${REGENERATE}`
+    )
+
+    for (const subpath of Object.keys(expected)) {
+      const added = actual[subpath]!.filter(
+        (name) => !expected[subpath]!.includes(name)
+      )
+      const removed = expected[subpath]!.filter(
+        (name) => !actual[subpath]!.includes(name)
+      )
+
+      assert.deepEqual(
+        { added, removed },
+        { added: [], removed: [] },
+        `'${subpath}' changed its public exports.\n` +
+          (added.length ? `  added:   ${added.join(', ')}\n` : '') +
+          (removed.length ? `  removed: ${removed.join(', ')}\n` : '') +
+          `${REGENERATE}`
+      )
+    }
+  })
+
+  test('the wildcard re-exports have not widened past their barrels', async () => {
+    // `errors/index.ts` and `dev/hot-reload.ts` re-export with `export *`, so a
+    // new export in the wrapped module is published without anyone editing an
+    // entry point. This pins the two that are reachable publicly.
+    const actual = await actualSurface()
+
+    assert.equal(
+      actual['./errors']!.every(
+        (name) => name.endsWith('Error') || name.startsWith('addError')
+      ),
+      true,
+      `'@pikku/core/errors' exports something that is not an error or an error ` +
+        `registrar: ${actual['./errors']!.filter((n) => !n.endsWith('Error') && !n.startsWith('addError')).join(', ')}`
+    )
+  })
+})