@pikku/core 0.12.84 → 0.12.88

package/src/app-leaf-surface.test.ts

@@ -0,0 +1,217 @@
+import { test, describe } from 'node:test'
+import * as assert from 'assert'
+import ts from 'typescript'
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * `#pikku` is the app tier's only door onto Pikku, and it is a namespace rather
+ * than a module: `#pikku/http`, `#pikku/workflow`, one subpath per wiring.
+ *
+ * The bare specifier used to resolve to `.pikku/pikku-types.gen.ts`, which
+ * re-exported all twelve wiring leaves with `export *` — undoing the split the
+ * leaves exist for, each of which still says so in its own header ("HTTP-specific
+ * type definitions for tree-shaking optimization"). Reaching that barrel put 33
+ * distinct `@pikku/core` subpaths into the module graph, and neither of the two
+ * consumers could drop them again: bundlers keep `export *` chains because the
+ * app declares no `sideEffects`, and Node and tsx do not tree-shake at all, so
+ * an app with no queues still executed `@pikku/core/queue` at boot.
+ *
+ * Deleting the barrel also turns the addon boundary from advice into a rule. An
+ * addon's leaves are never generated, so `#pikku/http` fails to resolve at the
+ * specifier rather than yielding "no exported member" from a hub that quietly
+ * dropped the re-export.
+ */
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+/**
+ * Membership is discovered, not listed: every directory holding a
+ * `pikku.config.json` is a Pikku project, so a project added later arrives
+ * guarded rather than invisible. Listing them by hand is how the ecosystem
+ * guard reported green on four packages it had never scanned.
+ */
+const skipped = new Set([
+  'node_modules',
+  'dist',
+  '.pikku',
+  '.next',
+  'build',
+  '.git',
+  'coverage',
+])
+
+const findProjects = (dir: string, out: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    if (skipped.has(entry)) continue
+    const path = join(dir, entry)
+    if (!statSync(path).isDirectory()) continue
+    if (existsSync(join(path, 'pikku.config.json'))) out.push(path)
+    findProjects(path, out)
+  }
+  return out
+}
+
+const walk = (dir: string, out: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    if (skipped.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
+}
+
+/**
+ * `.gen.*` and `.d.ts` are the generator's own output — what they import is
+ * decided by the codegen templates, and `.pikku` is skipped outright.
+ */
+const isGenerated = (path: string) =>
+  path.includes('.gen.') || path.endsWith('.d.ts')
+
+const projectSourceFiles = (project: string) => {
+  const files: string[] = []
+  for (const entry of readdirSync(project)) {
+    if (skipped.has(entry)) continue
+    const path = join(project, entry)
+    if (!statSync(path).isDirectory()) continue
+    if (existsSync(join(path, 'pikku.config.json'))) continue
+    walk(path, files)
+  }
+  return files.filter((file) => !isGenerated(file))
+}
+
+/**
+ * Parsed rather than grepped: the CLI's serializers hold the specifiers they
+ * emit inside template literals, and those are output text rather than imports
+ * the CLI itself makes.
+ */
+const barrelSpecifiers = (file: string) => {
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true
+  )
+  const found: { specifier: string; line: number }[] = []
+  for (const statement of source.statements) {
+    if (
+      !ts.isImportDeclaration(statement) &&
+      !ts.isExportDeclaration(statement)
+    ) {
+      continue
+    }
+    const moduleSpecifier = statement.moduleSpecifier
+    if (!moduleSpecifier || !ts.isStringLiteral(moduleSpecifier)) continue
+    const specifier = moduleSpecifier.text
+    const isBarrel =
+      specifier === '#pikku' ||
+      /^#pikku\/pikku-types\.gen(\.js)?$/.test(specifier)
+    if (!isBarrel) continue
+    const { line } = source.getLineAndCharacterOfPosition(
+      statement.getStart(source)
+    )
+    found.push({ specifier, line: line + 1 })
+  }
+  return found
+}
+
+/**
+ * Names a leaf carries, mapped to the leaf that carries them. An app reaching
+ * `@pikku/core` for one of these is the smell that says the generator is not
+ * emitting something it should — the definer is already generated into the
+ * project's own `.pikku`, so naming core instead couples the app to a package
+ * it otherwise never imports.
+ */
+const namesOwnedByALeaf = new Map<string, string>([
+  ['defineCredential', '#pikku/credentials'],
+  ['defineSecret', '#pikku/secrets'],
+  ['defineVariable', '#pikku/variables'],
+  ['defineScope', '#pikku/scopes'],
+  ['defineSystemRole', '#pikku/scopes'],
+  ['cors', '#pikku/http'],
+  ['InvalidOriginError', '#pikku/error'],
+])
+
+const coreNamesThatHaveALeaf = (file: string) => {
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true
+  )
+  const found: { name: string; leaf: string; line: number }[] = []
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue
+    const moduleSpecifier = statement.moduleSpecifier
+    if (!ts.isStringLiteral(moduleSpecifier)) continue
+    if (!/^@pikku\/core(\/|$)/.test(moduleSpecifier.text)) continue
+
+    const bindings = statement.importClause?.namedBindings
+    if (!bindings || !ts.isNamedImports(bindings)) continue
+    for (const element of bindings.elements) {
+      const name = (element.propertyName ?? element.name).text
+      const leaf = namesOwnedByALeaf.get(name)
+      if (!leaf) continue
+      const { line } = source.getLineAndCharacterOfPosition(
+        element.getStart(source)
+      )
+      found.push({ name, leaf, line: line + 1 })
+    }
+  }
+  return found
+}
+
+describe('app leaf surface', () => {
+  test('no Pikku project reaches past a leaf for a name the leaf carries', () => {
+    const projects = findProjects(repoRoot)
+    assert.ok(projects.length > 0, 'expected to discover Pikku projects')
+
+    // A project nested inside another (an addon under `e2e/packages`) is
+    // discovered on its own account and again as its parent's source, so the
+    // same offence is reached twice.
+    const offenders = new Set<string>()
+    for (const project of projects) {
+      for (const file of projectSourceFiles(project)) {
+        for (const { name, leaf, line } of coreNamesThatHaveALeaf(file)) {
+          offenders.add(
+            `${relative(repoRoot, file)}:${line}  ${name} — import it from '${leaf}'`
+          )
+        }
+      }
+    }
+
+    assert.deepStrictEqual(
+      [...offenders].sort(),
+      [],
+      `An app developer imports from '#pikku/<leaf>'. Reaching past it to ` +
+        `'@pikku/core' for a name the leaf already carries is the smell that ` +
+        `says the generator is not emitting something it should.\n\n` +
+        [...offenders].sort().join('\n')
+    )
+  })
+
+  test('no Pikku project reaches the app tier through a barrel', () => {
+    const projects = findProjects(repoRoot)
+    assert.ok(projects.length > 0, 'expected to discover Pikku projects')
+
+    const offenders: string[] = []
+    for (const project of projects) {
+      for (const file of projectSourceFiles(project)) {
+        for (const { specifier, line } of barrelSpecifiers(file)) {
+          offenders.push(`${relative(repoRoot, file)}:${line}  ${specifier}`)
+        }
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `The app tier reaches Pikku through one subpath per wiring — ` +
+        `'#pikku/http', '#pikku/workflow', '#pikku/function'.\n` +
+        `A barrel import pulls every wiring's core dependencies into the ` +
+        `module graph, and nothing downstream can drop them again.\n\n` +
+        offenders.join('\n')
+    )
+  })
+})

package/src/bootstrap-compat/root.ts

@@ -0,0 +1,20 @@
+/**
+ * Bootstrap compatibility, not a public entry point.
+ *
+ * The package root carried a 206-name barrel; it is gone, and every name now
+ * lives on the subpath that owns it. What is left here is the handful of types
+ * the CLI pinned in `packages/cli/build.sh` still writes into the files it
+ * generates for the CLI itself — an unresolved type there is a silent `any` in
+ * the CLI's own generated surface, not a build failure, which is why this
+ * exists rather than letting it break loudly.
+ *
+ * `bootstrap-compat.test.ts` fails if the pinned CLI's output drifts from this
+ * list. Delete this file and its `exports` entry once the pin moves to a CLI
+ * released from this branch.
+ */
+export type { PikkuWire, SecretlessServices } from '../types/core.types.js'
+export type { CorePikkuMiddleware } from '../middleware/middleware.types.js'
+export type { PickRequired } from '../utils.js'
+export type { CorePermissionGroup } from '../function/functions.types.js'
+export type { ListInput, ListOutput } from '../function/list.types.js'
+export type { SecretService } from '../services/secret-service.js'

package/src/{column-form.test.ts → classification/column-form.test.ts}

@@ -11,7 +11,7 @@ import type {
   SealedValue,
   WrappedValue,
 } from './data-classification.js'
-import { deriveKEK, envelopeEncrypt, envelopeRewrap } from './crypto-utils.js'
+import { deriveKEK, envelopeEncrypt, envelopeRewrap } from '../crypto-utils.js'
 
 const KEY_MATERIAL = 'x'.repeat(32)
 
@@ -87,7 +87,7 @@ describe('the envelope primitives produce the brand', () => {
   test('decrypting accepts a bare string, so reading a row back needs no cast', async () => {
     const kek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
     const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'value')
-    const { envelopeDecrypt } = await import('./crypto-utils.js')
+    const { envelopeDecrypt } = await import('../crypto-utils.js')
     const fromRow: string = ciphertext
     assert.equal(
       await envelopeDecrypt<string>(kek, fromRow, wrappedDEK),

package/src/{data-classification.ts → classification/data-classification.ts}

@@ -5,11 +5,7 @@ export type Secret<T> = T & { readonly __classification__?: 'secret' }
 
 export type Classification = 'public' | 'private' | 'pii' | 'secret'
 export type AnonymizeStrategy =
-  | 'fake:email'
-  | 'fake:name'
-  | 'hash'
-  | 'keep'
-  | null
+  'fake:email' | 'fake:name' | 'hash' | 'keep' | null
 
 // knowledge: decisions/internals/core-column-form-is-an-axis-of-its-own.md
 

package/src/classification/index.ts

@@ -0,0 +1,38 @@
+/**
+ * What a value is, and how it must be handled: the classification brands a
+ * column carries, the stored forms those brands map to, and the wrapper that
+ * keeps a secret out of a log.
+ *
+ * These arrived as three entry points — one for the types, one for the
+ * runtime helpers, one for `SecretValue` — which is the same subject behind
+ * three doors, split by whether a name happens to be a type or a value.
+ */
+export type {
+  Private,
+  Pii,
+  Secret,
+  Classification,
+  AnonymizeStrategy,
+  ColumnForm,
+  WrappedValue,
+  SealedValue,
+  HashedValue,
+  ColumnClassification,
+  ClassificationManifest,
+} from './data-classification.js'
+
+export {
+  hashToken,
+  unsafeAsWrapped,
+  unsafeAsSealed,
+  unsafeAsHashed,
+} from './column-form.js'
+
+export {
+  REDACTED,
+  SecretCoercionError,
+  SecretValue,
+  createSecretValue,
+  isSecretValue,
+} from './secret-value.js'
+export type { Safe } from './secret-value.js'

package/src/{secret-value.test.ts → classification/secret-value.test.ts}

@@ -8,8 +8,8 @@ import {
   type Safe,
   type SecretValue,
 } from './secret-value.js'
-import type { Logger } from './services/logger.js'
-import type { AuditLog } from './services/audit-service.js'
+import type { Logger } from '../services/logger.js'
+import type { AuditLog } from '../services/audit-service.js'
 
 const VALUE = 'sk-live-DEADBEEF'
 

package/src/{secret-value.ts → classification/secret-value.ts}

@@ -70,12 +70,7 @@ export const isSecretValue = (value: unknown): value is SecretValue<unknown> =>
 type IsAny<T> = 0 extends 1 & T ? true : false
 
 type Passthrough =
-  | Function
-  | Date
-  | RegExp
-  | Error
-  | ArrayBuffer
-  | ArrayBufferView
+  Function | Date | RegExp | Error | ArrayBuffer | ArrayBufferView
 
 /**
  * Rejects a `SecretValue` anywhere in `T`, however deeply nested, by collapsing

package/src/crypto-utils.ts

@@ -1,4 +1,4 @@
-import type { WrappedValue } from './data-classification.js'
+import type { WrappedValue } from './classification/data-classification.js'
 import { WeakKeyMaterialError } from './errors/errors.js'
 
 const encoder = new TextEncoder()

package/src/dev/hot-reload.ts

@@ -11,7 +11,7 @@ import type { Logger } from '../services/logger.js'
 import type { CorePikkuFunctionConfig } from '../function/functions.types.js'
 import { createModuleRunner } from './module-runner.js'
 
-export * from './reload-meta.js'
+export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
 
 interface PikkuDevReloaderOptions {
   srcDirectories: string[]

package/src/dev/reload-meta.test.ts

@@ -6,7 +6,7 @@ import { tmpdir } from 'node:os'
 
 import { pikkuState, resetPikkuState } from '../pikku-state.js'
 import { getSchema } from '../schema.js'
-import { wireAddon } from '../wirings/rpc/wire-addon.js'
+import { wireAddon } from '../wirings/addon/wire-addon.js'
 import { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
 
 const createMockLogger = () => {

package/src/errors/index.ts

@@ -1,2 +1,11 @@
 export * from './errors.js'
 export { PikkuError, addError } from './error-handler.js'
+
+/**
+ * Types the exports above mention but do not themselves export. Without
+ * them a consumer's declaration emit has no name for the type it infers,
+ * and fails with TS2883 rather than reaching for the original entry point.
+ */
+export type { ErrorDetails } from './error-handler.js'
+export { isExpectedError } from './error-handler.js'
+export type { SerializedError } from './serialized-error.js'

package/src/errors/serialized-error.ts

@@ -0,0 +1,9 @@
+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
+}

package/src/factory-functions.test.ts

@@ -3,10 +3,12 @@ import assert from 'node:assert'
 import {
   pikkuAuth,
   pikkuPermission,
-  pikkuMiddleware,
   pikkuPermissionFactory,
+} from './function/functions.types.js'
+import {
+  pikkuMiddleware,
   pikkuMiddlewareFactory,
-} from './index.js'
+} from './middleware/middleware-factories.js'
 
 test('pikkuPermission returns the same function', async () => {
   const originalFn = async () => true

package/src/function/function-meta.types.ts

@@ -0,0 +1,151 @@
+import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
+import type { AuditDurability } from '../services/audit-service.js'
+import type {
+  ScenarioStepKind,
+  ScenarioSurface,
+} from '../wirings/workflow/scenario-step.types.js'
+import type { CommonWireMeta } from '../types/core.types.js'
+
+export interface FunctionServicesMeta {
+  optimized: boolean
+  services: string[]
+}
+
+export interface FunctionWiresMeta {
+  optimized: boolean
+  wires: string[]
+}
+
+/**
+ * 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: this step runs as a persona, so every call site must
+   * pass one and the runner injects it as `wire.actor`.
+   *
+   * Declared by `actor: true`, or implied by a `browser` binding — a window is
+   * opened as somebody. Absent on a step with nobody to be: an assertion over
+   * what an earlier step returned, or one posting credentials precisely because
+   * it must not reuse an actor's session.
+   */
+  scenarioStepRequiresActor?: boolean
+  /**
+   * 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>

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

@@ -6,10 +6,12 @@ import {
   getFunctionNames,
   runPikkuFunc,
 } from './function-runner.js'
-import { addGlobalPermission, addTagMiddleware } from '../index.js'
+import { addGlobalPermission } from '../permissions.js'
+import { addTagMiddleware } from '../middleware-runner.js'
 import { addSchema } from '../schema.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
-import type { CoreServices, CorePikkuMiddleware } from '../types/core.types.js'
+import type { CoreServices } from '../types/core.types.js'
+import type { CorePikkuMiddleware } from '../middleware/middleware.types.js'
 import type { CorePermissionGroup } from './functions.types.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
 import { MissingScopeError, ReadonlySessionError } from '../errors/errors.js'