@pikku/core 0.12.80 → 0.12.82

package/scripts/generate-api-report.mts

@@ -16,6 +16,10 @@
  * disagree — so a member-level change is a reviewable diff rather than a
  * surprise in someone else's CI.
  *
+ * A member per line, and no member bodies. Both are load-bearing rather than
+ * cosmetic: the report exists to be diffed, and a class emitted as one long
+ * line of its own source is neither reviewable nor mergeable.
+ *
  * Run: yarn api-report
  */
 import { readFileSync, writeFileSync } from 'node:fs'
@@ -50,7 +54,132 @@ const program = ts.createProgram(
 )
 const checker = program.getTypeChecker()
 
-/** One line per symbol: how it is declared, flattened and stripped of noise. */
+/** Comments are noise in a report the diff is read for. */
+const stripComments = (text: string): string =>
+  text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '')
+
+/**
+ * Punctuation that makes a line and its successor one thing.
+ *
+ * Read from both ends rather than one, because the closers are ambiguous from
+ * behind: `string[]`, `Promise<T>` and `= {}` all end in a closing bracket and
+ * none of them is a continuation. What the *next* line starts with is not.
+ */
+const CONTINUES = /(=>|[,;{([<|&=])$/
+const CLOSES = /^(=>|extends\b|[}\])>,;|&])/
+
+/**
+ * A member's own text on one line — long, but never long enough to matter.
+ *
+ * Inside an object type the author's newline *was* the separator, so collapsing
+ * without restoring it produces `{ a: string b: number }`, which is not the
+ * type it describes and does not parse in the ```ts fence it is printed into.
+ */
+const oneLine = (text: string): string => {
+  const lines = stripComments(text)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+  let depth = 0
+  const joined = lines
+    .map((line, index) => {
+      const inObjectType = depth > 0
+      for (const character of line) {
+        if (character === '{') depth++
+        else if (character === '}') depth--
+      }
+      const next = lines[index + 1]
+      return inObjectType &&
+        next !== undefined &&
+        !CONTINUES.test(line) &&
+        !CLOSES.test(next)
+        ? `${line};`
+        : line
+    })
+    .join(' ')
+  return joined.replace(/\(\s+/g, '(').replace(/\s+\)/g, ')')
+}
+
+/**
+ * A class member as a consumer sees it: the signature, and nothing after it.
+ *
+ * The body is where every character of this report used to come from — a class
+ * arrived as its own source, so the report promised implementation details and
+ * a one-word change to a method rewrote the whole declaration. Truncating at
+ * the body leaves exactly the part a compatibility promise covers.
+ */
+const memberSignature = (member: ts.ClassElement | ts.TypeElement): string => {
+  const source = member.getSourceFile().text
+  const start = member.getStart()
+
+  const body = (member as { body?: ts.Node }).body
+  if (body) {
+    const head = oneLine(source.slice(start, body.getStart())).replace(
+      /\s*$/,
+      ''
+    )
+    // An inferred return type is still a return type a consumer depends on, and
+    // truncating at the body is what threw the author's away.
+    if (ts.isMethodDeclaration(member) || ts.isGetAccessorDeclaration(member)) {
+      const signature = member.type
+        ? undefined
+        : checker.getSignatureFromDeclaration(member)
+      if (signature) {
+        const returns = checker.getReturnTypeOfSignature(signature)
+        return `${head}: ${checker.typeToString(returns, undefined, ts.TypeFormatFlags.NoTruncation)}`
+      }
+    }
+    return head
+  }
+
+  // A property's initializer is a body by another name. Its annotation stands in
+  // for it, and the checker supplies one when the author left it inferred.
+  if (ts.isPropertyDeclaration(member) && member.initializer) {
+    if (member.type) return oneLine(source.slice(start, member.type.end))
+    const type = checker.getTypeAtLocation(member)
+    return `${oneLine(source.slice(start, member.name.end))}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`
+  }
+
+  return oneLine(member.getText())
+}
+
+/** Members a consumer can reach, so a private field is not a promise. */
+const isPublic = (member: ts.ClassElement | ts.TypeElement): boolean =>
+  !(ts.getModifiers(member as ts.HasModifiers) ?? []).some(
+    (modifier) => modifier.kind === ts.SyntaxKind.PrivateKeyword
+  ) && !(member.name && ts.isPrivateIdentifier(member.name))
+
+/**
+ * A declaration with members, one member per line.
+ *
+ * The line break is the point. Two branches that touch different methods of the
+ * same class are a textual conflict when the class is one line and an ordinary
+ * merge when it is not, which is a tax the whole repo was paying: every rebase
+ * over this file stopped to re-resolve a forty-thousand-character line by hand.
+ */
+const membered = (
+  declaration:
+    | ts.ClassDeclaration
+    | ts.InterfaceDeclaration
+    | ts.EnumDeclaration,
+  members: ts.NodeArray<ts.ClassElement | ts.TypeElement | ts.EnumMember>
+): string => {
+  if (members.length === 0) return oneLine(declaration.getText())
+  const source = declaration.getSourceFile().text
+  // `members.pos` is the offset just past the `{`, so the header comes with its
+  // own brace and needs no reassembling.
+  const header = oneLine(source.slice(declaration.getStart(), members.pos))
+  const lines = ts.isEnumDeclaration(declaration)
+    ? (members as readonly ts.EnumMember[]).map(
+        (member) => `${oneLine(member.getText())},`
+      )
+    : (members as readonly (ts.ClassElement | ts.TypeElement)[])
+        .filter(isPublic)
+        .map(memberSignature)
+  return [header, ...lines.map((line) => `  ${line}`), '}'].join('\n')
+}
+
+/** How a symbol is declared, in as many lines as its members need. */
 const signature = (exported: ts.Symbol): string => {
   // A re-export is an alias; the declaration that matters is the target's, so
   // an interface re-exported through a barrel still reports its members.
@@ -62,20 +191,21 @@ const signature = (exported: ts.Symbol): string => {
   if (!declaration) return exported.getName()
 
   if (
-    ts.isInterfaceDeclaration(declaration) ||
     ts.isClassDeclaration(declaration) ||
-    ts.isTypeAliasDeclaration(declaration) ||
+    ts.isInterfaceDeclaration(declaration) ||
     ts.isEnumDeclaration(declaration)
   ) {
-    // The declaration itself, so member changes show up in the diff.
-    return declaration
-      .getText()
-      .replace(/\/\*\*[\s\S]*?\*\//g, '')
-      .replace(/\/\/[^\n]*/g, '')
+    return membered(declaration, declaration.members)
+  }
+
+  if (ts.isTypeAliasDeclaration(declaration)) {
+    // No members to walk, so the author's own line breaks are the ones that
+    // keep a long union reviewable.
+    return stripComments(declaration.getText())
       .split('\n')
-      .map((l) => l.trim())
-      .filter(Boolean)
-      .join(' ')
+      .map((l) => l.trimEnd())
+      .filter((l) => l.trim())
+      .join('\n')
   }
 
   const type = checker.getTypeOfSymbolAtLocation(symbol, declaration)
@@ -92,17 +222,12 @@ const ECOSYSTEM_SUBPATHS = new Set(['./ecosystem', './internal'])
 
 type Exported = { name: string; members: number; signature: string }
 
-/** Members a consumer can reach, so a private field is not a promise. */
+/** The members the report lists, which is what the tally is counting. */
 const memberCount = (declaration: ts.Declaration): number => {
   if (ts.isInterfaceDeclaration(declaration)) return declaration.members.length
   if (ts.isEnumDeclaration(declaration)) return declaration.members.length
   if (!ts.isClassDeclaration(declaration)) return 0
-  return declaration.members.filter(
-    (member) =>
-      !(ts.getModifiers(member) ?? []).some(
-        (modifier) => modifier.kind === ts.SyntaxKind.PrivateKeyword
-      ) && !(member.name && ts.isPrivateIdentifier(member.name))
-  ).length
+  return declaration.members.filter(isPublic).length
 }
 
 const modules = new Map<string, Exported[]>()

package/src/api-report.test.ts

@@ -1,7 +1,7 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 import { execFileSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { join, dirname } from 'node:path'
 
@@ -39,7 +39,7 @@ describe('the API report matches the code', () => {
       const firstDiff = regeneratedLines.findIndex(
         (line, i) => line !== committedLines[i]
       )
-      require('node:fs').writeFileSync(reportPath, committed)
+      writeFileSync(reportPath, committed)
 
       assert.fail(
         'the public API changed but api-report.md was not regenerated.\n' +

package/src/errors/index.ts

@@ -1,2 +1,2 @@
 export * from './errors.js'
-export { PikkuError, addError, addErrors } from './error-handler.js'
+export { PikkuError, addError } from './error-handler.js'

package/src/function/function-runner.test.ts

@@ -14,6 +14,7 @@ import type { CorePermissionGroup } from './functions.types.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
 import { MissingScopeError, ReadonlySessionError } from '../errors/errors.js'
 import { createInvocationAudit } from '../services/audit-service.js'
+import { SecretAccessDeniedError } from '../services/secretless.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -1563,3 +1564,54 @@ describe('runPikkuFunc - scopes', () => {
     })
   })
 })
+
+describe('runPikkuFunc - secrets', () => {
+  const singletonServicesWithSecrets = {
+    ...mockSingletonServices,
+    secrets: { getSecret: async () => 'super-secret' },
+  } as any
+
+  const addSecretReadingFunction = (
+    funcName: string,
+    seen: { error?: unknown }
+  ) => {
+    addTestFunction(funcName, {
+      func: async (services: any) => {
+        try {
+          return services.secrets
+        } catch (error) {
+          seen.error = error
+          return 'denied'
+        }
+      },
+    })
+  }
+
+  const run = (funcName: string) =>
+    runPikkuFunc('rpc', Math.random().toString(), funcName, {
+      singletonServices: singletonServicesWithSecrets,
+      getAllServices: () => singletonServicesWithSecrets,
+      data: () => ({}),
+      auth: false,
+      wire: {},
+    })
+
+  test('a function never receives the secrets service', async () => {
+    const seen: { error?: unknown } = {}
+    addSecretReadingFunction('readsSecrets', seen)
+
+    assert.equal(await run('readsSecrets'), 'denied')
+    assert.ok(seen.error instanceof SecretAccessDeniedError)
+  })
+
+  test('no metadata flag can restore the secrets service', async () => {
+    const seen: { error?: unknown } = {}
+    addSecretReadingFunction('claimsAnExemption', seen)
+    Object.assign(pikkuState(null, 'function', 'meta')['claimsAnExemption']!, {
+      secretBroker: true,
+    })
+
+    assert.equal(await run('claimsAnExemption'), 'denied')
+    assert.ok(seen.error instanceof SecretAccessDeniedError)
+  })
+})

package/src/function/function-runner.ts

@@ -177,8 +177,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName
 
-  const keepsSecrets = funcMeta.secretBroker === true
-
   const resolvedSingletonServices = packageName
     ? await getOrCreatePackageSingletonServices(
         packageName,
@@ -363,12 +361,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
     await runPermissions({
       funcPermissions: funcConfig.permissions,
-      services: keepsSecrets
-        ? resolvedSingletonServices
-        : (withoutSecrets(
-            resolvedSingletonServices,
-            'a permission'
-          ) as CoreSingletonServices),
+      services: withoutSecrets(
+        resolvedSingletonServices,
+        'a permission'
+      ) as CoreSingletonServices,
       // knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
       wire: invocationWire as PermissionWire,
       data: actualData,
@@ -420,7 +416,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         enumerable: true,
       })
       return await funcConfig.func(
-        keepsSecrets ? services : withoutSecrets(services, 'a pikku function'),
+        withoutSecrets(services, 'a pikku function'),
         actualData,
         invocationWire
       )

package/src/function/index.ts

@@ -18,6 +18,4 @@ export type {
   ListInput,
   ListOutput,
   Filter,
-  LeafFilter,
-  LeafValue,
 } from './list.types.js'

package/src/index.ts

@@ -17,12 +17,10 @@ export type {
   CreateConfig,
   ServerLifecycle,
   FunctionMeta,
-  FunctionRuntimeMeta,
   FunctionServicesMeta,
   FunctionWiresMeta,
   FunctionsMeta,
   FunctionsRuntimeMeta,
-  JSONPrimitive,
   JSONValue,
   MakeRequired,
   MiddlewareMetadata,
@@ -43,7 +41,6 @@ export type {
   SecuritySeverity,
   SecurityUpdateLevel,
   SerializedError,
-  WireServices,
 } from './types/core.types.js'
 export {
   pikkuAIMiddleware,
@@ -57,7 +54,6 @@ export type {
   CorePikkuAuthConfig,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
-  CorePikkuFunctionHook,
   CorePikkuPermission,
   CorePikkuPermissionConfig,
   CorePikkuPermissionFactory,
@@ -75,8 +71,6 @@ export type {
   ListInput,
   ListOutput,
   Filter,
-  LeafFilter,
-  LeafValue,
 } from './function/list.types.js'
 export { pikkuCLIRender } from './wirings/cli/cli-runner.js'
 export { PikkuRequest } from './pikku-request.js'
@@ -92,9 +86,6 @@ export {
 } from './version.js'
 export {
   AbandonedError,
-  beginChanges,
-  getAbortScope,
-  runInAbortScope,
   type AbortScope,
 } from './function/abort-scope.js'
 export { fetch } from './wirings/http/http-runner.js'
@@ -152,7 +143,6 @@ export type { QueueService } from './wirings/queue/queue.types.js'
 export type { JWTService } from './services/jwt-service.js'
 export type {
   EmailService,
-  EmailTemplateReference,
   SendEmailInput,
   SendEmailResult,
   SendHTMLEmailInput,
@@ -188,8 +178,6 @@ export type { SessionService } from './services/user-session-service.js'
 export {
   NoopAuditService,
   createInvocationAudit,
-  resolveAuditConfig,
-  resolveAuditUserIdentityFromWire,
 } from './services/audit-service.js'
 export type {
   AuditConfig,
@@ -198,31 +186,14 @@ export type {
   AuditEventBatch,
   AuditFacets,
   AuditLog,
-  AuditLogWriteInput,
-  AuditOutcome,
   AuditQuery,
   AuditQueryResult,
   AuditService,
-  AuditSource,
   AuditUserIdentity,
   ResolvedAuditConfig,
 } from './services/audit-service.js'
 export type {
   AIAgentRunnerService,
-  AIEmbedManyParams,
-  AIEmbedManyResult,
-  AIEmbedParams,
-  AIEmbedResult,
-  AIGenerateImageParams,
-  AIGenerateImagePrompt,
-  AIGenerateImageResult,
-  AIGenerateSpeechParams,
-  AIGenerateSpeechResult,
-  AIProviderOptions,
-  AIRerankParams,
-  AIRerankResult,
-  AITranscriptionParams,
-  AITranscriptionResult,
 } from './services/ai-agent-runner-service.js'
 export type { AIEmbeddingService } from './services/ai-embedding-service.js'
 export type { AIRunStateService } from './services/ai-run-state-service.js'
@@ -230,8 +201,6 @@ export type { AIStorageService } from './services/ai-storage-service.js'
 export type {
   EmailsMeta,
   EmailTemplateMeta,
-  EmailTemplateLocaleMeta,
-  EmailTemplateAssets,
   MetaService,
 } from './services/meta-service.js'
 export type { HTTPMethod } from './wirings/http/http.types.js'
@@ -266,7 +235,6 @@ export type {
   Secret,
   Classification,
   AnonymizeStrategy,
-  ColumnClassification,
   ClassificationManifest,
   ColumnForm,
   WrappedValue,
@@ -276,9 +244,6 @@ export type {
 
 export {
   hashToken,
-  unsafeAsWrapped,
-  unsafeAsSealed,
-  unsafeAsHashed,
 } from './column-form.js'
 
 export type { SecretValue, Safe } from './secret-value.js'

package/src/pikku-state.ts

@@ -10,6 +10,7 @@ import type {
   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 { 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,6 +119,9 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   agent: {
     agents: new Map(),
     agentsMeta: {} as AIAgentMeta,
+    scorers: new Map(),
+    scorersMeta: {} as ScorerMeta,
+    modelAliases: {},
   },
   gateway: {
     gateways: new Map(),
@@ -151,6 +155,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
     authFactory: null,
     credentialsMeta: null,
     requiredParentServices: null,
+    declaredSecrets: null,
   },
 })