@pikku/core 0.12.107 → 0.12.111

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.107",
+  "version": "0.12.111",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikkujs/pikku.git",
+    "directory": "packages/core"
+  },
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -13,7 +18,7 @@
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
-    "prepublishOnly": "yarn build",
+    "prepublishOnly": "bun run build",
     "api-report": "tsx scripts/generate-api-report.mts"
   },
   "sideEffects": [
@@ -51,6 +56,7 @@
     "./mcp": "./dist/wirings/mcp/index.js",
     "./agent": "./dist/wirings/agent/index.js",
     "./agent-scorer": "./dist/wirings/agent-scorer/index.js",
+    "./analytics": "./dist/analytics/index.js",
     "./gateway": "./dist/wirings/gateway/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/command-parser": "./dist/wirings/cli/command-parser.js",
@@ -65,6 +71,7 @@
     "./oauth2": "./dist/wirings/oauth2/index.js",
     "./errors": "./dist/errors/index.js",
     "./services": "./dist/services/index.js",
+    "./flag": "./dist/wirings/flag/index.js",
     "./services/local-meta": "./dist/services/meta-service.js",
     "./services/v8-coverage": "./dist/services/v8-coverage-service.js",
     "./services/istanbul-coverage": "./dist/services/istanbul-coverage-service.js",
@@ -92,10 +99,9 @@
     "@ag-ui/core": "0.0.57",
     "@types/node": "^24.13.3",
     "esbuild": "~0.28.2",
-    "tsx": "^4.23.12",
-    "typescript": "^6.0.3"
+    "tsx": "^4.23.12"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/run-tests.sh

@@ -1,8 +1,5 @@
 #!/bin/bash
 
-script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$script_dir"
-
 # Enable nullglob to handle cases where no files match the pattern
 shopt -s nullglob
 
@@ -43,18 +40,29 @@ if [ ${#files[@]} -eq 0 ]; then
   exit 0
 fi
 
-# Construct the node command
-node_cmd=(node --import tsx --test)
+# Construct the bun command
+#
+# --parallel gives every test file its own worker process, which is what node's
+# `--test` did. Several suites keep module-level caches (a TypeScript program, a
+# temp fixture directory) that a shared process would leak between files.
+#
+# --timeout because bun caps a test at 5s by default where node had no cap, and
+# the suites that build real TypeScript programs run well past that.
+bun_cmd=(bun test --parallel --timeout 120000)
 
 # Append options based on flags
 if [ "$watch_mode" = true ]; then
-  node_cmd+=(--watch)
+  # --watch reruns in one process; parallel workers have nothing to watch.
+  bun_cmd=(bun test --watch --timeout 120000)
 fi
 
 if [ "$coverage_mode" = true ]; then
-  node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
+  # --coverage-dir=. keeps lcov.info at the package root: CI merges every
+  # package's report by prefixing its SF paths with the file's own directory,
+  # so a nested coverage/ directory would re-root them one level too deep.
+  bun_cmd+=(--coverage --coverage-reporter=lcov --coverage-reporter=text --coverage-dir=.)
   export PIKKU_TEST_COVERAGE=1
 fi
 
-# Execute the node command with the expanded list of files
-"${node_cmd[@]}" "${files[@]}"
+# Execute the bun command with the expanded list of files
+"${bun_cmd[@]}" "${files[@]}"

package/src/public-surface.json

@@ -350,6 +350,7 @@
     "BadRequestError",
     "ConflictError",
     "ExpectationFailedError",
+    "FeatureUnavailableError",
     "ForbiddenError",
     "GatewayTimeoutError",
     "GoneError",
@@ -449,6 +450,19 @@
     "verifyActorSecret",
     "withoutSecrets"
   ],
+  "./flag": [
+    "CachedFlagSource",
+    "assertFeatureAvailable",
+    "bucketOf",
+    "compiledFallbackSnapshot",
+    "defineFeatureFlags",
+    "flattenFeatureFlagDefinitions",
+    "resolveFlag",
+    "resolveFlagForClient",
+    "resolveFlagsForClient",
+    "subjectIdOf",
+    "validateAndBuildFeatureFlagDefinitionsMeta"
+  ],
   "./services/local-meta": [
     "LocalMetaService"
   ],
@@ -549,5 +563,17 @@
     "pikkuDevReloader",
     "reconcileAddonRegistry",
     "reloadGeneratedMeta"
+  ],
+  "./analytics": [
+    "LoggerAnalyticsService",
+    "anonymousAnalyticsIdentity",
+    "composeAnalyticsIdentity",
+    "cookieAnalyticsIdentity",
+    "createInvocationAnalytics",
+    "defineAnalyticsEvents",
+    "fanOutAnalytics",
+    "flattenAnalyticsEvent",
+    "mintCookie",
+    "randomDigits"
   ]
 }

package/src/agent-naming.test.ts

@@ -1,68 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join, dirname } from 'node:path'
-
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
-const reportPath = join(packageRoot, 'api-report.md')
-
-/**
- * `AI` described the model provider, never the agent runtime, so #596 renamed
- * every agent symbol to `Agent`. The names below are the ones that survived,
- * because each really does wrap a provider call.
- *
- * Listing them here is what makes the rule checkable: anything else exported as
- * `AI*` is a symbol that slipped back to the old naming, and this fails rather
- * than letting it reach a consumer.
- */
-const PROVIDER_SYMBOLS = new Set([
-  'AIEmbeddingService',
-  'AIEmbedManyParams',
-  'AIEmbedManyResult',
-  'AIEmbedParams',
-  'AIEmbedResult',
-  'AIGenerateImageParams',
-  'AIGenerateImagePrompt',
-  'AIGenerateImageResult',
-  'AIGenerateSpeechParams',
-  'AIGenerateSpeechResult',
-  'AIProviderAuthError',
-  'AIProviderNotConfiguredError',
-  'AIProviderOptions',
-  'AIRerankParams',
-  'AIRerankResult',
-  'AITranscriptionParams',
-  'AITranscriptionResult',
-])
-
-describe('the agent runtime is not exported under the AI name', () => {
-  test('every AI* symbol in the public surface is a provider wrapper', () => {
-    const report = readFileSync(reportPath, 'utf-8')
-    const found = new Set(report.match(/\bAI[A-Z][A-Za-z]*/g) ?? [])
-
-    const strays = [...found].filter((name) => !PROVIDER_SYMBOLS.has(name))
-
-    assert.deepEqual(
-      strays,
-      [],
-      'these are exported as `AI*` but are not provider wrappers — rename them ' +
-        'to `Agent*`, or add them to PROVIDER_SYMBOLS if they genuinely wrap a ' +
-        'model provider call'
-    )
-  })
-
-  test('the agent entry points are the renamed ones', () => {
-    const { exports } = JSON.parse(
-      readFileSync(join(packageRoot, 'package.json'), 'utf-8')
-    )
-
-    assert.ok(exports['./agent'], 'expected the ./agent entry point')
-    assert.ok(
-      exports['./agent-scorer'],
-      'expected the ./agent-scorer entry point'
-    )
-    assert.equal(exports['./ai-agent'], undefined)
-    assert.equal(exports['./ai-scorer'], undefined)
-  })
-})

package/src/api-report.test.ts

@@ -1,138 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { execFileSync } from 'node:child_process'
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { fileURLToPath } from 'node:url'
-import { join, dirname } from 'node:path'
-
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
-const reportPath = join(packageRoot, 'api-report.md')
-
-/**
- * `public-surface.json` pins the *names* a consumer can reach. That catches an
- * export appearing or vanishing and nothing else — adding a method to
- * `MetaService`, or making a field on `ChannelMeta` required, sails past it,
- * as does every type-only export. Those are the changes that break a
- * consumer's build, and the report's summary counts how many more of them
- * there are than there are names.
- *
- * So `api-report.md` records what each symbol *is*, and this fails when the
- * committed report and the code disagree.
- *
- * knowledge: decisions/internals/the-api-report-pins-members-not-just-names.md
- */
-describe('the API report matches the code', () => {
-  test('regenerating produces no diff', () => {
-    const committed = readFileSync(reportPath, 'utf-8')
-
-    execFileSync(
-      'npx',
-      ['tsx', join(packageRoot, 'scripts', 'generate-api-report.mts')],
-      { cwd: packageRoot, stdio: 'pipe' }
-    )
-    const regenerated = readFileSync(reportPath, 'utf-8')
-
-    if (committed !== regenerated) {
-      // Restore, so a failing run does not leave the tree dirty.
-      const committedLines = committed.split('\n')
-      const regeneratedLines = regenerated.split('\n')
-      const firstDiff = regeneratedLines.findIndex(
-        (line, i) => line !== committedLines[i]
-      )
-      writeFileSync(reportPath, committed)
-
-      assert.fail(
-        'the public API changed but api-report.md was not regenerated.\n' +
-          `First difference at line ${firstDiff + 1}:\n` +
-          `  committed:   ${committedLines[firstDiff] ?? '(end of file)'}\n` +
-          `  regenerated: ${regeneratedLines[firstDiff] ?? '(end of file)'}\n` +
-          'Run `yarn api-report` and review the diff — a member added to an ' +
-          'exported interface or class is a change consumers compile against.'
-      )
-    }
-  })
-
-  test('the report actually contains member-level detail', () => {
-    // Guards the test above: a report of bare names would match itself forever
-    // while pinning nothing that public-surface.json does not already pin.
-    const report = readFileSync(reportPath, 'utf-8')
-
-    assert.ok(
-      /export interface MetaService \{[^}]*getHttpMeta/.test(report),
-      'expected MetaService to be reported with its members'
-    )
-    assert.ok(
-      !/^\w+: any$/m.test(report),
-      'symbols reported as `any` mean re-export aliases are not being followed'
-    )
-  })
-})
-
-/**
- * Every branch that touches the public surface rewrites the whole report, so
- * two of them meeting is a ~9000-line conflict with no meaningful resolution
- * in it. A merge driver takes the conflict away; the test above is what still
- * insists on a report that matches the code.
- *
- * knowledge: decisions/internals/the-api-report-pins-members-not-just-names.md
- */
-describe('merging the API report is not hand work', () => {
-  const repoRoot = join(packageRoot, '..', '..')
-
-  test('.gitattributes routes the report through the driver', () => {
-    const attributes = readFileSync(join(repoRoot, '.gitattributes'), 'utf-8')
-
-    assert.match(
-      attributes,
-      /^packages\/core\/api-report\.md\s+merge=api-report\b/m,
-      'the report must name the merge driver, or git conflicts on it as usual'
-    )
-  })
-
-  test('the setup script registers the driver as a plain take-one-side', () => {
-    // Against a throwaway repository rather than this one: a driver is written
-    // to `.git/config`, which every worktree of a checkout shares, so running
-    // this in place would reach into whatever else is checked out beside it.
-    const sandbox = mkdtempSync(join(tmpdir(), 'pikku-merge-driver-'))
-    try {
-      execFileSync('git', ['init', '--quiet', sandbox], { stdio: 'pipe' })
-      execFileSync(
-        'node',
-        [join(repoRoot, 'scripts', 'setup-merge-drivers.mjs')],
-        { cwd: sandbox, stdio: 'pipe' }
-      )
-      const driver = execFileSync(
-        'git',
-        ['config', '--local', 'merge.api-report.driver'],
-        { cwd: sandbox, stdio: 'pipe' }
-      )
-        .toString()
-        .trim()
-
-      // `true` writes nothing and succeeds, which is how a driver tells git to
-      // keep the side already in %A. Anything that regenerates the report is
-      // the trap this pins shut: git runs a driver while merging that one
-      // path, with the rest of the tree still unmerged, so the generator reads
-      // the old sources and resolves to a report missing exactly the API the
-      // incoming branch adds — conflict-free and wrong, which is worse than a
-      // conflict. The regeneration belongs to the guard above, which runs
-      // against a finished tree.
-      assert.equal(
-        driver,
-        'true',
-        'the driver must resolve to one side verbatim and run nothing'
-      )
-    } finally {
-      rmSync(sandbox, { recursive: true, force: true })
-    }
-  })
-
-  test('postinstall runs the setup, so a fresh clone is not left without it', () => {
-    const manifest = JSON.parse(
-      readFileSync(join(repoRoot, 'package.json'), 'utf-8')
-    )
-
-    assert.match(manifest.scripts.postinstall, /setup-merge-drivers\.mjs/)
-  })
-})

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

@@ -1,179 +0,0 @@
-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')
-    )
-  })
-})