@pikku/inspector 0.12.23 → 0.12.25

package/CHANGELOG.md

@@ -1,3 +1,60 @@
+## 0.12.25
+
+### Patch Changes
+
+- b6ba601: fix(lint): don't flag pikkuAuth's session param as a non-destructured wire
+
+  `pikkuAuth`'s handler is `(services, session)` — the second parameter is the
+  resolved user session, not a wires bag. The inspector was extracting "wires"
+  from that parameter (`extractUsedWires(handler, 1)`), so a permission like
+  `pikkuAuth(async ({ logger }, session) => !!session)` tripped
+  `wiresNotDestructured` even though `session` cannot be destructured. pikkuAuth
+  exposes no user-facing wires parameter, so no wires meta is recorded for it.
+
+- ae7fc5d: Include gateway platform and auth fields in inspected gateway metadata.
+- decdad5: fix(lint): don't fail the build on framework-synthesized functions
+
+  The `servicesNotDestructured`/`wiresNotDestructured` defaults (`error`) were
+  tripping on functions the user can't edit: generated `.gen.ts` wrappers (the
+  opaque `authHandler`, the cli channel raw dispatcher) and synthetic route→addon
+  bridges (`http:<method>:<route>`, no source file). `computeDiagnostics` now skips
+  any function without a real, non-generated source file, so the lint only nudges
+  hand-written user code. Also destructures the CLI's own `all` command.
+
+- Updated dependencies [ae7fc5d]
+- Updated dependencies [fa7a09c]
+  - @pikku/core@0.12.37
+
+## 0.12.24
+
+### Patch Changes
+
+- 5fe3f47: fix(better-auth): skip the auto-generated stateless session middleware when the
+  project registers its own. Closes #754.
+
+  With `session.cookieCache` enabled the CLI generates a global
+  `betterAuthStatelessSession()` using the default `{ userId }` map. Because session
+  middleware short-circuits once a session is set (`if (session) next()`) and the
+  generated file is imported before user wirings, that default-map middleware ran
+  first and **pre-empted** a project's own `betterAuthStatelessSession({ mapSession })`
+  — silently dropping custom session fields (`role`, `locale`, …).
+
+  The inspector now detects a user-owned global registration (a
+  `betterAuthStatelessSession(...)` call inside `addGlobalMiddleware` or the global
+  form of `addHTTPMiddleware` — the array form or the `'*'` pattern, not a
+  route-scoped `addHTTPMiddleware('/path', …)`; ignoring `.gen.ts` files and bare
+  standalone calls) and
+  sets `state.auth.userStatelessSession`. When set, the CLI skips writing
+  `auth-middleware.gen.ts` (and removes a stale one) so the project's own middleware
+  — with its custom `mapSession` — is the only one registered. Projects without a
+  custom map are unaffected: the default middleware is still generated.
+
+- 3ba12ca: Stop consumed-addon parent services from polluting every per-unit deploy bundle, and stub the AI SDKs out of non-agent units.
+
+  `aggregateRequiredServices` added `addonRequiredParentServices` (the services a consumed addon needs from its parent — e.g. `aiAgentRunner`, `deploymentService`, `metaService`) to **every** unit's `requiredServices` unconditionally. For any project that consumes an addon, this marked those services required on all units, so the per-unit service tree-shaking (and the gen-file/module stubs that key off the `false` flags) never fired — every unit shipped the full set. These parent services are now added only to units that actually deploy an addon function (its `pikkuFuncId` appears in `usedFunctions`); a unit that only calls the addon over RPC, or never touches it, no longer carries them.
+
+  On the back of the now-honest flags, the bundler stubs the AI SDK packages (`@pikku/ai-vercel`, `@ai-sdk/*`, `ai`) out of any unit where `aiAgentRunner` is not required, via a new service→module stub map alongside the existing gen-file stub map. The shared services factory must guard runner construction behind a defined-check on the dynamic import so a stubbed unit simply skips building the runner.
+
 ## 0.12.23
 
 ### Patch Changes

package/dist/add/add-auth.js

@@ -71,6 +71,36 @@ const readPluginId = (el) => {
         return el.expression.text;
     return undefined;
 };
+/**
+ * True when `node` sits inside a GLOBAL middleware registration — i.e. an actual
+ * global registration, not a bare standalone call or a route-scoped one.
+ *
+ * `addGlobalMiddleware(...)` is always global. `addHTTPMiddleware` is global only
+ * in its array form (`addHTTPMiddleware([...])`) or with the `'*'` wildcard
+ * pattern; a specific route pattern (`addHTTPMiddleware('/api/admin/*', [...])`)
+ * scopes the middleware to that route and must NOT count as a global stateless
+ * registration (#754).
+ */
+const isInsideGlobalMiddlewareRegistration = (node) => {
+    let parent = node.parent;
+    while (parent) {
+        if (ts.isCallExpression(parent) && ts.isIdentifier(parent.expression)) {
+            const fn = parent.expression.text;
+            if (fn === 'addGlobalMiddleware')
+                return true;
+            if (fn === 'addHTTPMiddleware') {
+                const first = parent.arguments[0];
+                if (!first)
+                    return false;
+                // String first arg → route pattern (global only when '*'); otherwise
+                // the array form, which is global.
+                return ts.isStringLiteral(first) ? first.text === '*' : true;
+            }
+        }
+        parent = parent.parent;
+    }
+    return false;
+};
 /**
  * Detects `pikkuBetterAuth((services) => betterAuth({...}))` calls.
  *
@@ -94,6 +124,19 @@ export const addAuth = (logger, node, _checker, state) => {
     if (!ts.isCallExpression(node))
         return;
     const expression = node.expression;
+    // A user-registered stateless session middleware (custom mapSession) means the
+    // CLI must NOT auto-generate its own default-map one — the generated one runs
+    // first and pre-empts the user's via the `if (session) next()` short-circuit
+    // (pikkujs/pikku#754). Only a GLOBAL registration counts (inside
+    // addHTTPMiddleware/addGlobalMiddleware) — a bare betterAuthStatelessSession()
+    // call (e.g. a test harness) is not a registration. Ignore generated files so
+    // the emitted middleware can't self-trigger the skip.
+    if (ts.isIdentifier(expression) &&
+        expression.text === 'betterAuthStatelessSession' &&
+        !node.getSourceFile().fileName.endsWith('.gen.ts') &&
+        isInsideGlobalMiddlewareRegistration(node)) {
+        state.auth.userStatelessSession = true;
+    }
     if (!ts.isIdentifier(expression) || expression.text !== 'pikkuBetterAuth')
         return;
     const sourceFile = node.getSourceFile().fileName;

package/dist/add/add-gateway.js

@@ -23,6 +23,8 @@ export const addGateway = (logger, node, checker, state, _options) => {
     const nameValue = getPropertyValue(obj, 'name');
     const typeValue = getPropertyValue(obj, 'type');
     const routeValue = getPropertyValue(obj, 'route');
+    const platformValue = getPropertyValue(obj, 'platform');
+    const authValue = getPropertyValue(obj, 'auth');
     const { disabled, tags, summary, description, errors } = getCommonWireMetaData(obj, 'Gateway', nameValue, logger, checker);
     if (disabled)
         return;
@@ -51,7 +53,9 @@ export const addGateway = (logger, node, checker, state, _options) => {
         ...(packageName && { packageName }),
         name: nameValue,
         type: typeValue,
-        route: routeValue,
+        ...(routeValue && { route: routeValue }),
+        ...(platformValue && { platform: platformValue }),
+        ...(typeof authValue === 'boolean' && { auth: authValue }),
         gateway: true,
         summary,
         description,

package/dist/add/add-permission.js

@@ -141,7 +141,11 @@ export const addPermission = (logger, node, checker, state) => {
             return;
         }
         const services = extractServicesFromFunction(actualHandler);
-        const wires = extractUsedWires(actualHandler, 1);
+        // pikkuAuth's handler is (services, session) — its second parameter is the
+        // resolved user session, NOT a wires bag, so it must not be analyzed (or
+        // flagged) as a non-destructured wires parameter. pikkuAuth exposes no
+        // user-facing wires parameter.
+        const wires = { optimized: true, wires: [] };
         let { pikkuFuncId, exportedName } = extractFunctionName(node, checker, state.rootDir);
         if (pikkuFuncId.startsWith('__temp_')) {
             if (ts.isVariableDeclaration(node.parent) &&

package/dist/types.d.ts

@@ -431,6 +431,11 @@ export interface InspectorState {
          *  codebase, if any. The CLI generates the `/auth/*` HTTP wiring from it.
          *  More than one `pikkuBetterAuth` is a critical error. */
         definition: AuthDefinition | null;
+        /** True when a user (non-generated) file already registers
+         *  `betterAuthStatelessSession(...)`. The CLI then skips auto-generating its
+         *  own default-map stateless middleware, which would otherwise pre-empt the
+         *  user's custom mapSession (pikkujs/pikku#754). */
+        userStatelessSession?: boolean;
     };
     secrets: {
         definitions: SecretDefinitions;

package/dist/utils/post-process.js

@@ -245,9 +245,22 @@ export function aggregateRequiredServices(state) {
     if (Object.keys(state.channels.meta).length > 0) {
         requiredServices.add('eventHub');
     }
-    // 7. Services that addons need from the parent project
-    for (const service of state.addonRequiredParentServices ?? []) {
-        requiredServices.add(service);
+    // 7. Services that consumed addons need from the parent project.
+    // These are required ONLY by units that actually deploy an addon function;
+    // a unit that merely calls the addon over RPC (or never touches it) must not
+    // carry them, or every per-unit bundle would over-include the addon's
+    // parent-service dependencies (e.g. aiAgentRunner, deploymentService) and
+    // defeat per-unit tree-shaking.
+    const addonFuncIds = new Set();
+    for (const fns of Object.values(state.addonFunctions ?? {})) {
+        for (const id of Object.keys(fns))
+            addonFuncIds.add(id);
+    }
+    const unitDeploysAddonFn = [...usedFunctions].some((fn) => addonFuncIds.has(fn));
+    if (unitDeploysAddonFn) {
+        for (const service of state.addonRequiredParentServices ?? []) {
+            requiredServices.add(service);
+        }
     }
 }
 export function validateSecretOverrides(logger, state) {
@@ -512,6 +525,14 @@ export function validateSchemaWiringSeparation(logger, state) {
 export function computeDiagnostics(state) {
     const diagnostics = [];
     for (const [id, meta] of Object.entries(state.functions.meta)) {
+        // Skip framework-synthesized functions: generated wrappers (auth.gen.ts's
+        // opaque authHandler, the cli channel's raw dispatcher) and synthetic route
+        // bridges that reference addon functions (id `http:<method>:<route>`, no
+        // source file). The user can't edit any of these, so a destructure lint
+        // meant to nudge them about their own code must not fail the build over them.
+        if (!meta.sourceFile || meta.sourceFile.endsWith('.gen.ts')) {
+            continue;
+        }
         if (meta.services && !meta.services.optimized) {
             diagnostics.push({
                 code: ErrorCode.SERVICES_NOT_DESTRUCTURED,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.23",
+  "version": "0.12.25",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.35",
+    "@pikku/core": "^0.12.37",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",

package/src/add/add-auth.test.ts

@@ -522,4 +522,98 @@ describe('addAuth inspector', () => {
       await rm(rootDir, { recursive: true, force: true })
     }
   })
+
+  test('user-registered betterAuthStatelessSession sets userStatelessSession', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-stateless-'))
+    const file = join(rootDir, 'middleware.ts')
+    await writeFile(
+      file,
+      [
+        "import { addHTTPMiddleware } from '#pikku'",
+        "import { betterAuthStatelessSession } from '@pikku/better-auth'",
+        "addHTTPMiddleware('*', [",
+        '  betterAuthStatelessSession({',
+        '    mapSession: (r: any) => ({ userId: r.user.id, role: r.user.role }),',
+        '  }),',
+        '])',
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.equal(state.auth.userStatelessSession, true)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('a standalone betterAuthStatelessSession() call (not a registration) does NOT set the flag', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-standalone-'))
+    const file = join(rootDir, 'start.ts')
+    await writeFile(
+      file,
+      [
+        "import { betterAuthStatelessSession } from '@pikku/better-auth'",
+        '// harness use, not a global registration',
+        'const mw = betterAuthStatelessSession()',
+        'void mw',
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.ok(
+        !state.auth.userStatelessSession,
+        'a bare call must not count as a registration'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('a route-scoped addHTTPMiddleware registration does NOT set the flag', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-scoped-'))
+    const file = join(rootDir, 'middleware.ts')
+    await writeFile(
+      file,
+      [
+        "import { addHTTPMiddleware } from '#pikku'",
+        "import { betterAuthStatelessSession } from '@pikku/better-auth'",
+        "addHTTPMiddleware('/api/admin/*', [betterAuthStatelessSession()])",
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.ok(
+        !state.auth.userStatelessSession,
+        'a route-scoped registration must not suppress the global generated middleware'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('betterAuthStatelessSession in a .gen.ts file does NOT set the flag', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-auth-genonly-'))
+    const file = join(rootDir, 'auth-middleware.gen.ts')
+    await writeFile(
+      file,
+      [
+        "import { addHTTPMiddleware } from '#pikku'",
+        "import { betterAuthStatelessSession } from '@pikku/better-auth'",
+        "addHTTPMiddleware('*', [betterAuthStatelessSession()])",
+      ].join('\n')
+    )
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      assert.ok(
+        !state.auth.userStatelessSession,
+        'generated file must not self-trigger the skip'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
 })

package/src/add/add-auth.ts

@@ -99,6 +99,35 @@ const readPluginId = (el: ts.Expression): string | undefined => {
   return undefined
 }
 
+/**
+ * True when `node` sits inside a GLOBAL middleware registration — i.e. an actual
+ * global registration, not a bare standalone call or a route-scoped one.
+ *
+ * `addGlobalMiddleware(...)` is always global. `addHTTPMiddleware` is global only
+ * in its array form (`addHTTPMiddleware([...])`) or with the `'*'` wildcard
+ * pattern; a specific route pattern (`addHTTPMiddleware('/api/admin/*', [...])`)
+ * scopes the middleware to that route and must NOT count as a global stateless
+ * registration (#754).
+ */
+const isInsideGlobalMiddlewareRegistration = (node: ts.Node): boolean => {
+  let parent: ts.Node | undefined = node.parent
+  while (parent) {
+    if (ts.isCallExpression(parent) && ts.isIdentifier(parent.expression)) {
+      const fn = parent.expression.text
+      if (fn === 'addGlobalMiddleware') return true
+      if (fn === 'addHTTPMiddleware') {
+        const first = parent.arguments[0]
+        if (!first) return false
+        // String first arg → route pattern (global only when '*'); otherwise
+        // the array form, which is global.
+        return ts.isStringLiteral(first) ? first.text === '*' : true
+      }
+    }
+    parent = parent.parent
+  }
+  return false
+}
+
 /**
  * Detects `pikkuBetterAuth((services) => betterAuth({...}))` calls.
  *
@@ -122,6 +151,23 @@ export const addAuth: AddWiring = (logger, node, _checker, state) => {
   if (!ts.isCallExpression(node)) return
 
   const expression = node.expression
+
+  // A user-registered stateless session middleware (custom mapSession) means the
+  // CLI must NOT auto-generate its own default-map one — the generated one runs
+  // first and pre-empts the user's via the `if (session) next()` short-circuit
+  // (pikkujs/pikku#754). Only a GLOBAL registration counts (inside
+  // addHTTPMiddleware/addGlobalMiddleware) — a bare betterAuthStatelessSession()
+  // call (e.g. a test harness) is not a registration. Ignore generated files so
+  // the emitted middleware can't self-trigger the skip.
+  if (
+    ts.isIdentifier(expression) &&
+    expression.text === 'betterAuthStatelessSession' &&
+    !node.getSourceFile().fileName.endsWith('.gen.ts') &&
+    isInsideGlobalMiddlewareRegistration(node)
+  ) {
+    state.auth.userStatelessSession = true
+  }
+
   if (!ts.isIdentifier(expression) || expression.text !== 'pikkuBetterAuth')
     return
 

package/src/add/add-gateway.ts

@@ -43,7 +43,9 @@ export const addGateway: AddWiring = (
 
   const nameValue = getPropertyValue(obj, 'name') as string | null
   const typeValue = getPropertyValue(obj, 'type') as GatewayTransportType | null
-  const routeValue = getPropertyValue(obj, 'route') as string | undefined
+  const routeValue = getPropertyValue(obj, 'route') as string | null
+  const platformValue = getPropertyValue(obj, 'platform') as string | null
+  const authValue = getPropertyValue(obj, 'auth')
   const { disabled, tags, summary, description, errors } =
     getCommonWireMetaData(obj, 'Gateway', nameValue, logger, checker)
 
@@ -94,7 +96,9 @@ export const addGateway: AddWiring = (
     ...(packageName && { packageName }),
     name: nameValue,
     type: typeValue,
-    route: routeValue,
+    ...(routeValue && { route: routeValue }),
+    ...(platformValue && { platform: platformValue }),
+    ...(typeof authValue === 'boolean' && { auth: authValue }),
     gateway: true,
     summary,
     description,

package/src/add/add-permission-auth.test.ts

@@ -0,0 +1,59 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
+    critical: (code: ErrorCode, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }) satisfies InspectorLogger
+
+describe('addPermission — pikkuAuth', () => {
+  test('does not record a wires meta for the session parameter', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-auth-wires-'))
+    const file = join(rootDir, 'auth.ts')
+
+    await writeFile(
+      file,
+      [
+        'const pikkuAuth = (x: any) => x',
+        'export const isAuthenticated = pikkuAuth(async ({ logger }, session) => {',
+        '  logger.info({ type: "auth-check" })',
+        '  return !!session',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      const def = state.permissions.definitions['isAuthenticated']
+      assert.ok(def, 'isAuthenticated permission should be recorded')
+      // The pikkuAuth handler is (services, session) — session is NOT a wires
+      // bag and must not be flagged as a non-destructured wires parameter.
+      assert.equal(def.wires, undefined)
+      const wireDiag = (state.diagnostics ?? []).find(
+        (d) =>
+          d.code === ErrorCode.WIRES_NOT_DESTRUCTURED &&
+          d.message.includes('isAuthenticated')
+      )
+      assert.equal(wireDiag, undefined)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-permission.ts

@@ -1,4 +1,5 @@
 import * as ts from 'typescript'
+import type { FunctionWiresMeta } from '@pikku/core'
 import type { AddWiring, InspectorState } from '../types.js'
 import {
   extractFunctionName,
@@ -195,7 +196,11 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
     }
 
     const services = extractServicesFromFunction(actualHandler)
-    const wires = extractUsedWires(actualHandler, 1)
+    // pikkuAuth's handler is (services, session) — its second parameter is the
+    // resolved user session, NOT a wires bag, so it must not be analyzed (or
+    // flagged) as a non-destructured wires parameter. pikkuAuth exposes no
+    // user-facing wires parameter.
+    const wires: FunctionWiresMeta = { optimized: true, wires: [] }
     let { pikkuFuncId, exportedName } = extractFunctionName(
       node,
       checker,

package/src/types.ts

@@ -497,6 +497,11 @@ export interface InspectorState {
      *  codebase, if any. The CLI generates the `/auth/*` HTTP wiring from it.
      *  More than one `pikkuBetterAuth` is a critical error. */
     definition: AuthDefinition | null
+    /** True when a user (non-generated) file already registers
+     *  `betterAuthStatelessSession(...)`. The CLI then skips auto-generating its
+     *  own default-map stateless middleware, which would otherwise pre-empt the
+     *  user's custom mapSession (pikkujs/pikku#754). */
+    userStatelessSession?: boolean
   }
   secrets: {
     definitions: SecretDefinitions

package/src/utils/compute-diagnostics.test.ts

@@ -0,0 +1,69 @@
+import { test, describe } from 'node:test'
+import { strict as assert } from 'node:assert'
+import { computeDiagnostics } from './post-process.js'
+import type { InspectorState } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+function stateWithFunctions(
+  meta: InspectorState['functions']['meta']
+): InspectorState {
+  return {
+    functions: { meta },
+    middleware: { definitions: {} },
+    permissions: { definitions: {} },
+  } as unknown as InspectorState
+}
+
+describe('computeDiagnostics', () => {
+  test('flags a user-authored function that does not destructure services', () => {
+    const state = stateWithFunctions({
+      myFunc: {
+        pikkuFuncId: 'myFunc',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sourceFile: '/project/src/my-func.ts',
+        services: { optimized: false, services: ['kysely'] },
+      },
+    })
+    computeDiagnostics(state)
+    assert.equal(state.diagnostics.length, 1)
+    assert.equal(
+      state.diagnostics[0].code,
+      ErrorCode.SERVICES_NOT_DESTRUCTURED
+    )
+  })
+
+  test('does NOT flag a generated .gen.ts function (user cannot edit it)', () => {
+    const state = stateWithFunctions({
+      cliRaw: {
+        pikkuFuncId: 'cliRaw',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sourceFile: '/project/src/wirings/cli-channel.gen.ts',
+        services: { optimized: false, services: ['kysely'] },
+      },
+      authHandler: {
+        pikkuFuncId: 'authHandler',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sourceFile: '/project/.pikku/auth.gen.ts',
+        wires: { optimized: false, wires: ['http'] },
+      },
+    })
+    computeDiagnostics(state)
+    assert.equal(state.diagnostics.length, 0)
+  })
+
+  test('does NOT flag a synthetic route bridge with no source file', () => {
+    const state = stateWithFunctions({
+      'http:get:/workflow-run/:runId/stream': {
+        pikkuFuncId: 'http:get:/workflow-run/:runId/stream',
+        inputSchemaName: null,
+        outputSchemaName: null,
+        services: { optimized: false, services: [] },
+      },
+    })
+    computeDiagnostics(state)
+    assert.equal(state.diagnostics.length, 0)
+  })
+})

package/src/utils/post-process.ts

@@ -317,9 +317,23 @@ export function aggregateRequiredServices(
     requiredServices.add('eventHub')
   }
 
-  // 7. Services that addons need from the parent project
-  for (const service of state.addonRequiredParentServices ?? []) {
-    requiredServices.add(service)
+  // 7. Services that consumed addons need from the parent project.
+  // These are required ONLY by units that actually deploy an addon function;
+  // a unit that merely calls the addon over RPC (or never touches it) must not
+  // carry them, or every per-unit bundle would over-include the addon's
+  // parent-service dependencies (e.g. aiAgentRunner, deploymentService) and
+  // defeat per-unit tree-shaking.
+  const addonFuncIds = new Set<string>()
+  for (const fns of Object.values(state.addonFunctions ?? {})) {
+    for (const id of Object.keys(fns)) addonFuncIds.add(id)
+  }
+  const unitDeploysAddonFn = [...usedFunctions].some((fn) =>
+    addonFuncIds.has(fn)
+  )
+  if (unitDeploysAddonFn) {
+    for (const service of state.addonRequiredParentServices ?? []) {
+      requiredServices.add(service)
+    }
   }
 }
 
@@ -647,6 +661,14 @@ export function computeDiagnostics(state: InspectorState): void {
   const diagnostics: InspectorDiagnostic[] = []
 
   for (const [id, meta] of Object.entries(state.functions.meta)) {
+    // Skip framework-synthesized functions: generated wrappers (auth.gen.ts's
+    // opaque authHandler, the cli channel's raw dispatcher) and synthetic route
+    // bridges that reference addon functions (id `http:<method>:<route>`, no
+    // source file). The user can't edit any of these, so a destructure lint
+    // meant to nudge them about their own code must not fail the build over them.
+    if (!meta.sourceFile || meta.sourceFile.endsWith('.gen.ts')) {
+      continue
+    }
     if (meta.services && !meta.services.optimized) {
       diagnostics.push({
         code: ErrorCode.SERVICES_NOT_DESTRUCTURED,