@pikku/core 0.12.106 → 0.12.111

package/src/middleware-runner.ts

@@ -1,232 +0,0 @@
-import type { PikkuWiringTypes } from './types/core.types.js'
-import type {
-  CorePikkuMiddleware,
-  CorePikkuMiddlewareGroup,
-  MiddlewareMetadata,
-  MiddlewarePriority,
-} from './middleware/middleware.types.js'
-import { pikkuState } from './pikku-state.js'
-import { freezeDedupe, getTagGroups } from './utils.js'
-
-const PRIORITY_ORDER: Record<MiddlewarePriority, number> = {
-  highest: 0,
-  high: 1,
-  medium: 2,
-  low: 3,
-  lowest: 4,
-}
-
-const getMiddlewarePriority = (fn: CorePikkuMiddleware<any, any>): number => {
-  const priority = (
-    fn as CorePikkuMiddleware<any, any> & { __priority?: MiddlewarePriority }
-  ).__priority
-  return PRIORITY_ORDER[priority ?? 'medium']
-}
-
-const sortByPriority = (
-  middlewares: CorePikkuMiddleware<any, any>[]
-): CorePikkuMiddleware<any, any>[] => {
-  return middlewares.sort(
-    (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
-  )
-}
-
-export const runMiddleware = async <
-  Middleware extends CorePikkuMiddleware<any, any>,
->(
-  services: Parameters<Middleware>[0],
-  wire: Parameters<Middleware>[1],
-  middlewares: readonly Middleware[],
-  main?: () => Promise<unknown>
-): Promise<unknown> => {
-  const sorted = isSortedByPriority(middlewares)
-    ? middlewares
-    : ([...middlewares].sort(
-        (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
-      ) as readonly Middleware[])
-  let result: any
-  const dispatch = async (index: number): Promise<any> => {
-    if (sorted && index < sorted.length) {
-      return await sorted[index]!(
-        services as Parameters<Middleware>[0],
-        wire,
-        () => dispatch(index + 1)
-      )
-    } else if (main) {
-      result = await main()
-    }
-  }
-  await dispatch(0)
-  return result
-}
-
-const isSortedByPriority = (
-  middlewares: readonly CorePikkuMiddleware<any, any>[]
-): boolean => {
-  for (let i = 1; i < middlewares.length; i++) {
-    if (
-      getMiddlewarePriority(middlewares[i]) <
-      getMiddlewarePriority(middlewares[i - 1])
-    ) {
-      return false
-    }
-  }
-  return true
-}
-
-/**
- * Registers tag-scoped middleware for any wiring carrying the tag. Wrap in a
- * factory (`export const x = () => addTagMiddleware(...)`) for tree-shaking.
- */
-export const addTagMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
-  tag: string,
-  middleware: CorePikkuMiddlewareGroup,
-  packageName: string | null = null
-): CorePikkuMiddlewareGroup => {
-  const tagGroups = pikkuState(packageName, 'middleware', 'tagGroup')
-  const existing = tagGroups[tag] as CorePikkuMiddleware[] | undefined
-  tagGroups[tag] = existing
-    ? [...existing, ...(middleware as CorePikkuMiddleware[])]
-    : middleware
-  return middleware
-}
-
-/**
- * Registers wire-agnostic global middleware, which runs at the top of every
- * wiring's chain — before wire-, tag- and function-level entries.
- */
-export const addGlobalMiddleware = <
-  PikkuMiddleware extends CorePikkuMiddleware,
->(
-  middleware: CorePikkuMiddlewareGroup,
-  packageName: string | null = null
-): CorePikkuMiddlewareGroup => {
-  const state = pikkuState(
-    packageName,
-    'middleware',
-    'global'
-  ) as unknown as CorePikkuMiddlewareGroup
-  ;(state as CorePikkuMiddleware[]).push(
-    ...(middleware as CorePikkuMiddleware[])
-  )
-  return middleware
-}
-
-const getMiddlewareByName = (name: string): CorePikkuMiddleware | undefined => {
-  const middlewareStore = pikkuState(null, 'misc', 'middleware')
-  const middleware = middlewareStore[name]
-  return middleware?.[0]
-}
-
-const middlewareCache: Record<
-  PikkuWiringTypes,
-  Record<string, readonly CorePikkuMiddleware[]>
-> = {
-  http: {},
-  rpc: {},
-  channel: {},
-  queue: {},
-  scheduler: {},
-  trigger: {},
-  mcp: {},
-  agent: {},
-  cli: {},
-  workflow: {},
-  gateway: {},
-}
-
-export const clearMiddlewareCache = () => {
-  for (const key of Object.keys(middlewareCache) as PikkuWiringTypes[]) {
-    middlewareCache[key] = {}
-  }
-}
-
-export const combineMiddleware = (
-  wireType: PikkuWiringTypes,
-  uid: string,
-  {
-    wireInheritedMiddleware,
-    wireMiddleware,
-    funcInheritedMiddleware,
-    funcMiddleware,
-    packageName = null,
-  }: {
-    wireInheritedMiddleware?: MiddlewareMetadata[]
-    wireMiddleware?: CorePikkuMiddleware[]
-    funcInheritedMiddleware?: MiddlewareMetadata[]
-    funcMiddleware?: CorePikkuMiddleware[]
-    packageName?: string | null
-  } = {}
-): readonly CorePikkuMiddleware[] => {
-  if (middlewareCache[wireType][uid]) {
-    return middlewareCache[wireType][uid]
-  }
-
-  const resolved: CorePikkuMiddleware[] = []
-
-  const globals = pikkuState(
-    packageName,
-    'middleware',
-    'global'
-  ) as unknown as CorePikkuMiddleware[]
-  if (globals && globals.length > 0) {
-    resolved.push(...globals)
-  }
-
-  if (wireInheritedMiddleware) {
-    for (const meta of wireInheritedMiddleware) {
-      if (meta.type === 'http') {
-        const group = pikkuState(packageName, 'middleware', 'httpGroup')[
-          meta.route
-        ]
-        if (group) {
-          // At runtime, all factories should be resolved to middleware
-          resolved.push(...(group as CorePikkuMiddleware[]))
-        }
-      } else if (meta.type === 'tag') {
-        const groups = getTagGroups(
-          pikkuState(packageName, 'middleware', 'tagGroup'),
-          meta.tag
-        )
-        for (const group of groups) {
-          resolved.push(...(group as CorePikkuMiddleware[]))
-        }
-      } else if (meta.type === 'wire') {
-        const middleware = getMiddlewareByName(meta.name)
-        if (middleware) {
-          resolved.push(middleware)
-        }
-      }
-    }
-  }
-
-  if (wireMiddleware) {
-    resolved.push(...wireMiddleware)
-  }
-
-  // Only tags here; wire middleware is resolved via wireInheritedMiddleware.
-  if (funcInheritedMiddleware) {
-    for (const meta of funcInheritedMiddleware) {
-      if (meta.type === 'tag') {
-        const groups = getTagGroups(
-          pikkuState(packageName, 'middleware', 'tagGroup'),
-          meta.tag
-        )
-        for (const group of groups) {
-          resolved.push(...(group as CorePikkuMiddleware[]))
-        }
-      }
-    }
-  }
-
-  if (funcMiddleware) {
-    resolved.push(...funcMiddleware)
-  }
-
-  sortByPriority(resolved)
-  middlewareCache[wireType][uid] = freezeDedupe(
-    resolved
-  ) as readonly CorePikkuMiddleware[]
-
-  return middlewareCache[wireType][uid]
-}

package/src/no-any-casts.test.ts

@@ -1,57 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { readFileSync, readdirSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join, dirname, relative } from 'node:path'
-
-const srcRoot = dirname(fileURLToPath(import.meta.url))
-const thisFile = fileURLToPath(import.meta.url)
-
-/**
- * `as any` in a cast position. The word boundary and the following delimiter
- * keep prose such as "as any URL a browser can load" out of the match.
- */
-const AS_ANY = /\bas any\b(?!\s+[A-Za-z])/
-
-const collectSourceFiles = (directory: string): string[] =>
-  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
-    const entryPath = join(directory, entry.name)
-    if (entry.isDirectory()) {
-      return entry.name === 'dist' ? [] : collectSourceFiles(entryPath)
-    }
-    return entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')
-      ? [entryPath]
-      : []
-  })
-
-describe('core asserts to named types, never to any', () => {
-  test('no non-test module casts through `as any`', () => {
-    const offenders = collectSourceFiles(srcRoot)
-      .filter((file) => file !== thisFile)
-      .flatMap((file) =>
-        readFileSync(file, 'utf-8')
-          .split('\n')
-          .flatMap((line, index) =>
-            AS_ANY.test(line)
-              ? [`${relative(srcRoot, file)}:${index + 1}  ${line.trim()}`]
-              : []
-          )
-      )
-
-    assert.deepEqual(
-      offenders,
-      [],
-      '`as any` discards the target type, so a wrong value passes as readily as ' +
-        'a right one. Assert to the type actually wanted — and if the narrowing ' +
-        'cannot be expressed, say why in a knowledge note and point at it:\n' +
-        offenders.join('\n')
-    )
-  })
-
-  test('the matcher finds a cast and ignores the prose that reads like one', () => {
-    // Guards the test above: a regex that matched nothing would pass forever.
-    assert.equal(AS_ANY.test('const x = y as any'), true)
-    assert.equal(AS_ANY.test('foo(bar as any)'), true)
-    assert.equal(AS_ANY.test('a picture, as any URL a browser can load'), false)
-  })
-})

package/src/no-root-barrel.test.ts

@@ -1,122 +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 package root was one barrel of 206 names that no bundler could take
- * apart, and the one specifier that revealed nothing about what a consumer
- * actually used.
- *
- * It is gone. Every name lives on the subpath that owns it, and every import
- * carries that subpath. What survives is a bootstrap shim, which the second
- * test here holds to its exact contents.
- */
-const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
-
-const skipDirectory = new Set([
-  'node_modules',
-  'dist',
-  '.git',
-  'build',
-  'coverage',
-  // Agent scratch worktrees are whole Pikku projects scaffolded by whatever CLI
-  // version happened to write them, so they carry specifiers this repo does not
-  // own. They are gitignored and belong to no workspace, which is what puts them
-  // out of scope rather than merely making them noisy.
-  '.claude',
-])
-
-/** A verifier's scratch project, left behind by a run that did not clean up. */
-const isScratchProject = (entry: string) => entry.startsWith('.tmp-')
-
-const walk = (dir: string, out: string[] = []): string[] => {
-  for (const entry of readdirSync(dir)) {
-    if (skipDirectory.has(entry) || isScratchProject(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
-}
-
-/**
- * Generated output belongs to whichever CLI wrote it — including the pinned
- * published one that bootstraps `packages/cli` and still emits the old
- * specifiers. What this branch's serializers emit is covered by the CLI's own
- * tests, against the template rather than its output.
- */
-const isGenerated = (path: string) =>
-  path.includes('.gen.') || path.endsWith('.d.ts') || path.includes('/.pikku/')
-
-describe('no root barrel', () => {
-  /**
-   * Parsed rather than grepped: several tests hold a user's file as a template
-   * literal, and `import { pikkuSessionlessFunc } from '@pikku/core'` inside
-   * one is fixture text for the inspector, not an import this repo makes.
-   */
-  test('nothing imports the package root', () => {
-    const offenders: string[] = []
-
-    for (const file of walk(repoRoot)) {
-      if (isGenerated(file)) continue
-      const source = ts.createSourceFile(
-        file,
-        readFileSync(file, 'utf8'),
-        ts.ScriptTarget.Latest,
-        true
-      )
-      for (const statement of source.statements) {
-        if (
-          !ts.isImportDeclaration(statement) &&
-          !ts.isExportDeclaration(statement)
-        ) {
-          continue
-        }
-        const specifier = statement.moduleSpecifier
-        if (!specifier || !ts.isStringLiteral(specifier)) continue
-        if (specifier.text !== '@pikku/core') continue
-        const { line } = source.getLineAndCharacterOfPosition(
-          statement.getStart(source)
-        )
-        offenders.push(`${relative(repoRoot, file)}:${line + 1}`)
-      }
-    }
-
-    assert.deepStrictEqual(
-      offenders,
-      [],
-      `The '@pikku/core' root is a bootstrap shim, not an entry point. Every ` +
-        `import carries the subpath that owns the name — '@pikku/core/types' ` +
-        `for the shared types, '@pikku/core/services' for the services.\n\n` +
-        offenders.join('\n')
-    )
-  })
-
-  /**
-   * The shim exists because `packages/cli` is generated by the published CLI
-   * pinned in its `build.sh`, which still writes these specifiers. Holding it
-   * to an exact list is what keeps it a shim: a name can only be added here by
-   * someone who has read why it should not be.
-   */
-  test('the bootstrap shim carries only what the pinned CLI emits', () => {
-    const surface = (file: string) =>
-      readFileSync(join(dirname(fileURLToPath(import.meta.url)), file), 'utf8')
-        .replace(/\/\*\*[\s\S]*?\*\//g, '')
-        .match(/\b[A-Za-z][A-Za-z0-9]*\b(?=[,\n\s]*(?:,|\}))/g)
-        ?.sort() ?? []
-
-    assert.deepStrictEqual(surface('bootstrap-compat/root.ts'), [
-      'CorePermissionGroup',
-      'CorePikkuMiddleware',
-      'ListInput',
-      'ListOutput',
-      'PickRequired',
-      'PikkuWire',
-      'SecretService',
-      'SecretlessServices',
-    ])
-  })
-})

package/src/permissions.test.ts

@@ -1,256 +0,0 @@
-import { describe, test, beforeEach } from 'node:test'
-import * as assert from 'node:assert'
-import {
-  addGlobalPermission,
-  runPermissions,
-  clearPermissionsCache,
-  checkAuthPermissions,
-} from './permissions.js'
-import { resetPikkuState } from './pikku-state.js'
-import { pikkuAuth } from './function/functions.types.js'
-import type { CoreServices, CoreUserSession } from './types/core.types.js'
-import type { CorePermissionGroup } from './function/functions.types.js'
-
-beforeEach(() => {
-  resetPikkuState()
-  clearPermissionsCache()
-})
-
-const mockServices: CoreServices = {
-  logger: {
-    info: () => {},
-    warn: () => {},
-    error: () => {},
-    debug: () => {},
-  },
-} as any
-
-const mockSession: CoreUserSession = { userId: 'test-user' } as any
-
-const run = (opts: {
-  funcPermissions?: CorePermissionGroup | any[]
-  data?: any
-  wire?: any
-  packageName?: string | null
-}) =>
-  runPermissions({
-    funcPermissions: opts.funcPermissions,
-    services: mockServices,
-    wire: (opts.wire ?? { session: mockSession }) as any,
-    data: opts.data ?? {},
-    packageName: opts.packageName ?? null,
-  })
-
-describe('runPermissions — function permissions (OR gate)', () => {
-  test('passes when no permissions are defined', async () => {
-    await run({})
-  })
-
-  test('passes when at least one group is satisfied (OR)', async () => {
-    await run({
-      funcPermissions: {
-        owner: [async () => false],
-        admin: [async () => true],
-      },
-    })
-  })
-
-  test('throws when every group fails', async () => {
-    await assert.rejects(
-      run({
-        funcPermissions: {
-          owner: [async () => false],
-          admin: [async () => false],
-        },
-      }),
-      { message: 'Permission denied' }
-    )
-  })
-
-  test('ANDs the entries within a single branch array', async () => {
-    await assert.rejects(
-      run({ funcPermissions: { grp: [async () => true, async () => false] } }),
-      { message: 'Permission denied' }
-    )
-    await run({
-      funcPermissions: { grp: [async () => true, async () => true] },
-    })
-  })
-
-  test('accepts a bare permission array as a single AND branch', async () => {
-    await run({ funcPermissions: [async () => true] })
-    await assert.rejects(run({ funcPermissions: [async () => false] }), {
-      message: 'Permission denied',
-    })
-  })
-
-  test('passes request data and wire through to permission functions', async () => {
-    let received: any
-    const wire = { session: mockSession }
-    const data = { hello: 'world' }
-    await run({
-      funcPermissions: {
-        grp: [
-          async (services: any, d: any, w: any) => {
-            received = { services, d, w }
-            return true
-          },
-        ],
-      },
-      data,
-      wire,
-    })
-    assert.equal(received.services, mockServices)
-    assert.equal(received.d, data)
-    assert.equal(received.w, wire)
-  })
-})
-
-describe('runPermissions — global permissions (AND gate)', () => {
-  test('requires every registered global to pass', async () => {
-    addGlobalPermission([async () => true])
-    await run({})
-
-    resetPikkuState()
-    clearPermissionsCache()
-    addGlobalPermission([async () => false])
-    await assert.rejects(run({}), { message: 'Permission denied' })
-  })
-
-  test('ANDs multiple registered globals', async () => {
-    addGlobalPermission([async () => true])
-    addGlobalPermission([async () => false])
-    await assert.rejects(run({}), { message: 'Permission denied' })
-  })
-
-  test('a global group entry ORs internally but must still pass', async () => {
-    addGlobalPermission({
-      a: [async () => false],
-      b: [async () => true],
-    } as CorePermissionGroup)
-    await run({})
-  })
-})
-
-describe('runPermissions — gates are independent (no escalation)', () => {
-  test('a passing global does NOT satisfy a failing function permission', async () => {
-    // The classic escalation bug: a broad global must not grant an admin-only fn.
-    addGlobalPermission([async () => true])
-    await assert.rejects(
-      run({ funcPermissions: { admin: [async () => false] } }),
-      { message: 'Permission denied' }
-    )
-  })
-
-  test('a passing function permission does NOT bypass a failing global', async () => {
-    addGlobalPermission([async () => false])
-    await assert.rejects(
-      run({ funcPermissions: { anyone: [async () => true] } }),
-      { message: 'Permission denied' }
-    )
-  })
-
-  test('passes only when both gates pass', async () => {
-    addGlobalPermission([async () => true])
-    await run({ funcPermissions: { admin: [async () => true] } })
-  })
-})
-
-describe('runPermissions — package isolation', () => {
-  test('globals are scoped per package', async () => {
-    addGlobalPermission([async () => false], 'pkg-a')
-    // A different package sees no globals, so it passes.
-    await run({ packageName: 'pkg-b' })
-    // The registering package is gated.
-    await assert.rejects(run({ packageName: 'pkg-a' }), {
-      message: 'Permission denied',
-    })
-  })
-
-  test('a root global applies inside a package too', async () => {
-    // The generated `addGlobalPermission` wrapper takes no package argument, so
-    // an application's rules always land in the root bucket. If those stopped
-    // at the addon boundary, "every request needs a signed-in user" would
-    // silently exempt every function an addon contributed.
-    addGlobalPermission([async () => false])
-    await assert.rejects(run({ packageName: 'pkg-a' }), {
-      message: 'Permission denied',
-    })
-  })
-
-  test('root and package globals both have to pass', async () => {
-    addGlobalPermission([async () => true])
-    addGlobalPermission([async () => false], 'pkg-a')
-    await assert.rejects(run({ packageName: 'pkg-a' }), {
-      message: 'Permission denied',
-    })
-  })
-
-  test('passes when the root and package globals both pass', async () => {
-    addGlobalPermission([async () => true])
-    addGlobalPermission([async () => true], 'pkg-a')
-    await run({ packageName: 'pkg-a' })
-  })
-
-  test('a package global does not leak back out to the root', async () => {
-    addGlobalPermission([async () => false], 'pkg-a')
-    await run({})
-  })
-})
-
-describe('checkAuthPermissions', () => {
-  test('returns true when there are no auth predicates', async () => {
-    assert.equal(
-      await checkAuthPermissions(undefined, mockSession, mockServices),
-      true
-    )
-  })
-
-  test('honours a global pikkuAuth predicate at filter time', async () => {
-    addGlobalPermission([pikkuAuth(async () => false)])
-    assert.equal(
-      await checkAuthPermissions(undefined, mockSession, mockServices),
-      false
-    )
-
-    resetPikkuState()
-    clearPermissionsCache()
-    addGlobalPermission([pikkuAuth(async () => true)])
-    assert.equal(
-      await checkAuthPermissions(undefined, mockSession, mockServices),
-      true
-    )
-  })
-
-  test('evaluates a live pikkuAuth predicate from the config group', async () => {
-    assert.equal(
-      await checkAuthPermissions(
-        { admin: pikkuAuth(async () => false) as any },
-        mockSession,
-        mockServices
-      ),
-      false
-    )
-    assert.equal(
-      await checkAuthPermissions(
-        { admin: pikkuAuth(async () => true) as any },
-        mockSession,
-        mockServices
-      ),
-      true
-    )
-  })
-
-  test('ignores data-dependent permissions (no auth marker)', async () => {
-    // A bare pikkuPermission carries no __pikkuAuth brand, so it cannot be
-    // evaluated at filter time and must not gate the tool list.
-    assert.equal(
-      await checkAuthPermissions(
-        { ownsRow: (async () => false) as any },
-        mockSession,
-        mockServices
-      ),
-      true
-    )
-  })
-})