@pikku/core 0.12.84 → 0.12.86

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

@@ -0,0 +1,179 @@
+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 generated `#pikku` alias is the app developer's public API. An app
+ * reaching past it into `@pikku/core` is the smell this file measures: the
+ * alias is typed against that app's own functions, so a name pulled from core
+ * directly is one the app is holding untyped and one the CLI cannot evolve.
+ *
+ * The trees below are apps rather than packages, so they have no `src`
+ * convention to walk — bootstrap and test files sit wherever the runtime wants
+ * them. Walking each tree root means skipping what an app accumulates:
+ * installed dependencies, build output, and its own generated `.pikku`.
+ */
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+const appTrees = ['templates', 'e2e', 'verifiers']
+const skipped = new Set(['node_modules', 'dist', '.next', 'build'])
+
+/**
+ * `outDir` is a project's own setting, so the generated tree is not always
+ * `.pikku` — the treeshake verifier writes one output tree per scenario under
+ * `.pikku-shake`. Matching the prefix keeps a leaf's generated `index.ts`, which
+ * carries no `.gen.` in its name, from reading as hand-written app code.
+ */
+const isGeneratedTree = (entry: string) => entry.startsWith('.pikku')
+
+const walkApp = (dir: string, out: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    if (skipped.has(entry) || isGeneratedTree(entry)) continue
+    const path = join(dir, entry)
+    if (statSync(path).isDirectory()) walkApp(path, out)
+    else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)
+  }
+  return out
+}
+
+/**
+ * `.gen.*` and `.d.ts` files are CLI output, not hand-written source: what they
+ * import is decided by the codegen templates, which are the thing that writes
+ * the alias in the first place.
+ */
+const isGenerated = (path: string) =>
+  path.includes('.gen.') || path.endsWith('.d.ts')
+
+const appSourceFiles = () =>
+  appTrees
+    .flatMap((tree) => walkApp(join(repoRoot, tree)))
+    .filter((file) => !isGenerated(file))
+
+/**
+ * Parsed rather than grepped: a step body held as a template literal is fixture
+ * text describing a user's file, not an import the app itself makes.
+ */
+const coreImports = (file: string) => {
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true
+  )
+  const found: { specifier: string; line: number; names: string[] }[] = []
+  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
+    if (specifier !== '@pikku/core' && !specifier.startsWith('@pikku/core/')) {
+      continue
+    }
+    const { line } = source.getLineAndCharacterOfPosition(
+      statement.getStart(source)
+    )
+    const clause = ts.isImportDeclaration(statement)
+      ? statement.importClause?.namedBindings
+      : statement.exportClause
+    const names =
+      clause && (ts.isNamedImports(clause) || ts.isNamedExports(clause))
+        ? clause.elements.map((element) => element.name.text)
+        : []
+    found.push({ specifier, line: line + 1, names })
+  }
+  return found
+}
+
+/**
+ * The scenario and persona surfaces are test-only names — actors, cookie jars,
+ * polling helpers, the typed personas an app declares. They are app code, but a
+ * distinct surface from wiring, so they reach the app through their own
+ * sub-entry rather than crowding the main hub.
+ */
+const scenarioSubpaths = new Set(['@pikku/core/scenario', '@pikku/core/persona'])
+
+/**
+ * A relative path into the generated scenario barrel reaches the same file the
+ * alias does, so it compiles — and then hard-codes how far the app file sits
+ * from `outDir`. Moving either end breaks it, and the CLI has no way to see
+ * that it is depended upon.
+ */
+const relativeIntoScenarioBarrel = (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
+    if (!moduleSpecifier.text.startsWith('.')) continue
+    if (!/\/pikku-scenario-types\.gen\.js$/.test(moduleSpecifier.text)) continue
+    const { line } = source.getLineAndCharacterOfPosition(
+      statement.getStart(source)
+    )
+    found.push({ specifier: moduleSpecifier.text, line: line + 1 })
+  }
+  return found
+}
+
+describe('the #pikku alias is the app surface', () => {
+  test('scenario code reaches the test surface through #pikku/scenario', () => {
+    const offenders: string[] = []
+
+    for (const file of appSourceFiles()) {
+      for (const { specifier, line, names } of coreImports(file)) {
+        if (!scenarioSubpaths.has(specifier)) continue
+        offenders.push(
+          `${relative(repoRoot, file)}:${line}  ${names.join(', ')}  from '${specifier}'`
+        )
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `Scenario and persona names come from the generated ` +
+        `'#pikku/scenario' entry, which is typed against this app's own ` +
+        `personas and steps.\n` +
+        `Reaching '@pikku/core/scenario' or '@pikku/core/persona' directly ` +
+        `gets the untyped shape, from a subpath scheduled for deletion.\n\n` +
+        offenders.join('\n')
+    )
+  })
+
+  test('the scenario barrel is reached through the alias, not a relative path', () => {
+    const offenders: string[] = []
+
+    for (const file of appSourceFiles()) {
+      for (const { specifier, line } of relativeIntoScenarioBarrel(file)) {
+        offenders.push(`${relative(repoRoot, file)}:${line}  '${specifier}'`)
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `The generated scenario barrel is reached through '#pikku/scenario', ` +
+        `which the app's own 'imports' map points at.\n` +
+        `A relative path hard-codes the distance from the file to 'outDir', ` +
+        `so moving either end breaks it silently.\n\n` +
+        offenders.join('\n')
+    )
+  })
+})

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/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