@pikku/inspector 0.12.42 → 0.12.44

package/src/utils/post-process.ts

@@ -10,9 +10,12 @@ import type {
   MiddlewareMetadata,
   PermissionMetadata,
 } from '@pikku/core'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { extractTypeKeys } from './type-utils.js'
 import { ErrorCode } from '../error-codes.js'
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js'
+import { flattenScopeDefinitions } from '@pikku/core/scope'
 
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
@@ -46,7 +49,7 @@ export function stampAuthHandlerServices(
  * Skips type:'http' and type:'tag' (reference groups, not individuals).
  */
 export function extractWireNames(
-  list?: MiddlewareMetadata[] | PermissionMetadata[]
+  list?: Array<MiddlewareMetadata | PermissionMetadata>
 ): string[] {
   if (!list) return []
   return list
@@ -57,34 +60,25 @@ export function extractWireNames(
 }
 
 /**
- * Helper to expand middleware/permission groups into individual names
- * and add their services to the aggregation.
- * This handles tag-based and HTTP-pattern-based middleware/permission groups.
+ * Helper to expand middleware groups into individual names and add their
+ * services to the aggregation. Handles tag-based and HTTP-pattern-based
+ * middleware groups. Permissions are function-scoped only and carry no groups.
  */
 function expandAndAddGroupServices(
-  list: MiddlewareMetadata[] | PermissionMetadata[] | undefined,
+  list: MiddlewareMetadata[] | undefined,
   state: InspectorState | Omit<InspectorState, 'typesLookup'>,
-  addServices: (services: FunctionServicesMeta | undefined) => void,
-  isMiddleware: boolean
+  addServices: (services: FunctionServicesMeta | undefined) => void
 ): void {
   if (!list) return
 
   for (const item of list) {
     if (item.type === 'tag') {
-      // Expand tag-based group
-      const groupMeta = isMiddleware
-        ? state.middleware.tagMiddleware.get(item.tag)
-        : state.permissions.tagPermissions.get(item.tag)
-
+      const groupMeta = state.middleware.tagMiddleware.get(item.tag)
       if (groupMeta?.services) {
         addServices(groupMeta.services)
       }
     } else if (item.type === 'http' && 'route' in item) {
-      // Expand HTTP-pattern-based group
-      const groupMeta = isMiddleware
-        ? state.http.routeMiddleware.get(item.route)
-        : state.http.routePermissions.get(item.route)
-
+      const groupMeta = state.http.routeMiddleware.get(item.route)
       if (groupMeta?.services) {
         addServices(groupMeta.services)
       }
@@ -188,55 +182,33 @@ export function aggregateRequiredServices(
     'options',
   ] as const) {
     for (const routeMeta of Object.values(state.http.meta[method])) {
-      expandAndAddGroupServices(routeMeta.middleware, state, addServices, true)
-      expandAndAddGroupServices(
-        routeMeta.permissions,
-        state,
-        addServices,
-        false
-      )
+      expandAndAddGroupServices(routeMeta.middleware, state, addServices)
     }
   }
 
   // Also check other wiring types (channels, queues, schedulers, MCP)
   for (const channelMeta of Object.values(state.channels.meta)) {
-    expandAndAddGroupServices(channelMeta.middleware, state, addServices, true)
-    expandAndAddGroupServices(
-      channelMeta.permissions,
-      state,
-      addServices,
-      false
-    )
+    expandAndAddGroupServices(channelMeta.middleware, state, addServices)
   }
 
   for (const queueMeta of Object.values(state.queueWorkers.meta)) {
-    expandAndAddGroupServices(queueMeta.middleware, state, addServices, true)
-    // expandAndAddGroupServices(queueMeta.permissions, state, addServices, false)
+    expandAndAddGroupServices(queueMeta.middleware, state, addServices)
   }
 
   for (const scheduleMeta of Object.values(state.scheduledTasks.meta)) {
-    expandAndAddGroupServices(scheduleMeta.middleware, state, addServices, true)
-    // expandAndAddGroupServices(scheduleMeta.permissions, state, addServices, false)
+    expandAndAddGroupServices(scheduleMeta.middleware, state, addServices)
   }
 
   for (const toolMeta of Object.values(state.mcpEndpoints.toolsMeta)) {
-    expandAndAddGroupServices(toolMeta.middleware, state, addServices, true)
-    expandAndAddGroupServices(toolMeta.permissions, state, addServices, false)
+    expandAndAddGroupServices(toolMeta.middleware, state, addServices)
   }
 
   for (const promptMeta of Object.values(state.mcpEndpoints.promptsMeta)) {
-    expandAndAddGroupServices(promptMeta.middleware, state, addServices, true)
-    expandAndAddGroupServices(promptMeta.permissions, state, addServices, false)
+    expandAndAddGroupServices(promptMeta.middleware, state, addServices)
   }
 
   for (const resourceMeta of Object.values(state.mcpEndpoints.resourcesMeta)) {
-    expandAndAddGroupServices(resourceMeta.middleware, state, addServices, true)
-    expandAndAddGroupServices(
-      resourceMeta.permissions,
-      state,
-      addServices,
-      false
-    )
+    expandAndAddGroupServices(resourceMeta.middleware, state, addServices)
   }
 
   // 5. Services from session service factories
@@ -378,17 +350,24 @@ export function validateSecretOverrides(
   const { wireAddonDeclarations } = state.rpc
   if (!wireAddonDeclarations || wireAddonDeclarations.size === 0) return
 
-  const secretNames = new Set(state.secrets.definitions.map((d) => d.name))
+  // secretOverrides key on (and resolve to) SECRET IDs — the string the addon
+  // passes to getSecret — so validate against secretId, falling back to name for
+  // older meta without a secretId field.
+  const secretIds = new Set(
+    state.secrets.definitions.map((d: any) => d.secretId ?? d.name)
+  )
 
   for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
     if (!addonDecl.secretOverrides) continue
 
-    for (const secretKey of Object.keys(addonDecl.secretOverrides)) {
-      if (!secretNames.has(secretKey)) {
-        const availableSecrets = Array.from(secretNames)
+    for (const [logicalName, resolvedName] of Object.entries(
+      addonDecl.secretOverrides
+    )) {
+      if (!secretIds.has(resolvedName)) {
+        const availableSecrets = Array.from(secretIds)
         logger.critical(
           ErrorCode.INVALID_VALUE,
-          `Secret override '${secretKey}' in addon '${namespace}' (${addonDecl.package}) does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`
+          `Secret override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a secret that does not exist. Available secrets: ${availableSecrets.join(', ') || 'none'}`
         )
       }
     }
@@ -409,12 +388,14 @@ export function validateCredentialOverrides(
   for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
     if (!addonDecl.credentialOverrides) continue
 
-    for (const credentialKey of Object.keys(addonDecl.credentialOverrides)) {
-      if (!credentialNames.has(credentialKey)) {
+    for (const [logicalName, resolvedName] of Object.entries(
+      addonDecl.credentialOverrides
+    )) {
+      if (!credentialNames.has(resolvedName)) {
         const availableCredentials = Array.from(credentialNames)
         logger.critical(
           ErrorCode.INVALID_VALUE,
-          `Credential override '${credentialKey}' in addon '${namespace}' (${addonDecl.package}) does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`
+          `Credential override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`
         )
       }
     }
@@ -428,23 +409,120 @@ export function validateVariableOverrides(
   const { wireAddonDeclarations } = state.rpc
   if (!wireAddonDeclarations || wireAddonDeclarations.size === 0) return
 
-  const variableNames = new Set(state.variables.definitions.map((d) => d.name))
+  // variableOverrides key on (and resolve to) VARIABLE IDs, so validate against
+  // variableId, falling back to name for older meta without a variableId field.
+  const variableIds = new Set(
+    state.variables.definitions.map((d: any) => d.variableId ?? d.name)
+  )
 
   for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
     if (!addonDecl.variableOverrides) continue
 
-    for (const variableKey of Object.keys(addonDecl.variableOverrides)) {
-      if (!variableNames.has(variableKey)) {
-        const availableVariables = Array.from(variableNames)
+    for (const [logicalName, resolvedName] of Object.entries(
+      addonDecl.variableOverrides
+    )) {
+      if (!variableIds.has(resolvedName)) {
+        const availableVariables = Array.from(variableIds)
         logger.critical(
           ErrorCode.INVALID_VALUE,
-          `Variable override '${variableKey}' in addon '${namespace}' (${addonDecl.package}) does not exist. Available variables: ${availableVariables.join(', ') || 'none'}`
+          `Variable override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a variable that does not exist. Available variables: ${availableVariables.join(', ') || 'none'}`
         )
       }
     }
   }
 }
 
+/**
+ * A `wireRemoteAddon` package ships types only — its handlers run on the host —
+ * so it MUST be a devDependency, not a production dependency (a prod dep would
+ * drag in the runtime deps remote consumption exists to avoid). This is the
+ * mirror image of `wireAddon`, which requires a production dependency.
+ */
+export function validateRemoteAddonDependencies(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  const { wireAddonDeclarations } = state.rpc
+  if (!wireAddonDeclarations || wireAddonDeclarations.size === 0) return
+
+  const hasRemote = Array.from(wireAddonDeclarations.values()).some(
+    (d) => d.remote
+  )
+  if (!hasRemote) return
+
+  const pkgJsonPath = join(state.rootDir, 'package.json')
+  if (!existsSync(pkgJsonPath)) return // no manifest to check (e.g. some tests)
+
+  let pkgJson: {
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  try {
+    pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'))
+  } catch (e: any) {
+    logger.warn(
+      `Could not read ${pkgJsonPath} to verify remote addon dependencies: ${e?.message ?? e}`
+    )
+    return
+  }
+
+  const prodDeps = pkgJson.dependencies ?? {}
+  const devDeps = pkgJson.devDependencies ?? {}
+
+  for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+    if (!decl.remote) continue
+    if (decl.package in devDeps) continue // correct
+
+    if (decl.package in prodDeps) {
+      logger.critical(
+        ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY,
+        `Remote addon '${namespace}' ('${decl.package}') is a production dependency, but wireRemoteAddon consumes it for types only — its handlers run on the host. Move '${decl.package}' from "dependencies" to "devDependencies".`
+      )
+    } else {
+      logger.critical(
+        ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY,
+        `Remote addon '${namespace}' ('${decl.package}') is wired with wireRemoteAddon but is not in "devDependencies". Add '${decl.package}' to "devDependencies" (types only).`
+      )
+    }
+  }
+}
+
+/**
+ * The auth a `wireRemoteAddon` consumer binds must reference a slot the consumer
+ * actually declares: a `credentialId` must be a wired credential, a `secretId`
+ * a wired secret. A custom `resolve()` and a public (omitted) surface are not
+ * statically checkable and are left to runtime.
+ */
+export function validateRemoteAddonAuth(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  const { wireAddonDeclarations } = state.rpc
+  if (!wireAddonDeclarations || wireAddonDeclarations.size === 0) return
+
+  const credentialNames = new Set(
+    state.credentials?.definitions.map((d) => d.name) ?? []
+  )
+  const secretNames = new Set(state.secrets.definitions.map((d) => d.name))
+
+  for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+    if (!decl.remote) continue
+
+    if (decl.authCredentialId && !credentialNames.has(decl.authCredentialId)) {
+      logger.critical(
+        ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED,
+        `Remote addon '${namespace}' binds auth.credentialId '${decl.authCredentialId}', but no such credential is wired. Available credentials: ${Array.from(credentialNames).join(', ') || 'none'}`
+      )
+    }
+    if (decl.authSecretId && !secretNames.has(decl.authSecretId)) {
+      logger.critical(
+        ErrorCode.REMOTE_ADDON_AUTH_UNRESOLVED,
+        `Remote addon '${namespace}' binds auth.secretId '${decl.authSecretId}', but no such secret is wired. Available secrets: ${Array.from(secretNames).join(', ') || 'none'}`
+      )
+    }
+  }
+}
+
 export function computeResolvedIOTypes(state: InspectorState): void {
   const { functions } = state
   for (const [pikkuFuncId, meta] of Object.entries(functions.meta)) {
@@ -531,36 +609,8 @@ export function computeMiddlewareGroupsMeta(state: InspectorState): void {
 }
 
 export function computePermissionsGroupsMeta(state: InspectorState): void {
-  const httpGroups: Record<string, any> = {}
-  for (const [pattern, meta] of state.http.routePermissions.entries()) {
-    httpGroups[pattern] = {
-      exportName: meta.exportName,
-      sourceFile: meta.sourceFile,
-      position: meta.position,
-      services: meta.services,
-      count: meta.count,
-      instanceIds: meta.instanceIds,
-      isFactory: meta.isFactory,
-    }
-  }
-
-  const tagGroups: Record<string, any> = {}
-  for (const [tag, meta] of state.permissions.tagPermissions.entries()) {
-    tagGroups[tag] = {
-      exportName: meta.exportName,
-      sourceFile: meta.sourceFile,
-      position: meta.position,
-      services: meta.services,
-      count: meta.count,
-      instanceIds: meta.instanceIds,
-      isFactory: meta.isFactory,
-    }
-  }
-
   state.permissionsGroupsMeta = {
     definitions: state.permissions.definitions,
-    httpGroups,
-    tagGroups,
   }
 }
 
@@ -632,6 +682,44 @@ export function validateAgentModels(
   }
 }
 
+/**
+ * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
+ * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never
+ * registers and codegen fails deep in type-checking with an opaque error. Fail
+ * early with an actionable message pointing at `scaffold: { graph: true }`.
+ */
+export function validateWorkflowGraphAddons(
+  logger: InspectorLogger,
+  state: InspectorState
+): void {
+  const addonGraphWired = Array.from(
+    state.rpc.wireAddonDeclarations.values()
+  ).some((decl) => decl.package === '@pikku/addon-graph')
+  if (addonGraphWired) {
+    return
+  }
+
+  for (const [name, graph] of Object.entries(state.workflows.graphMeta)) {
+    for (const node of Object.values(graph.nodes)) {
+      if (!('rpcName' in node) || typeof node.rpcName !== 'string') {
+        continue
+      }
+      if (!node.rpcName.startsWith('graph:')) {
+        continue
+      }
+      if (state.functions.meta[node.rpcName]) {
+        continue
+      }
+      logger.critical(
+        ErrorCode.WORKFLOW_GRAPH_ADDON_NOT_WIRED,
+        `Workflow graph '${name}' references '${node.rpcName}' but @pikku/addon-graph is not wired. ` +
+          `Enable "scaffold": { "graph": true } in pikku.config.json (and install @pikku/addon-graph), ` +
+          `or wire it manually with wireAddon({ name: 'graph', package: '@pikku/addon-graph' }).`
+      )
+    }
+  }
+}
+
 /**
  * Validates that Zod schemas and wiring side-effects (wireHTTPRoutes,
  * addPermission, addHTTPMiddleware, etc.) do not coexist in the same file.
@@ -658,14 +746,6 @@ export function validateSchemaWiringSeparation(
     wiringFiles.add(file)
   }
 
-  // Permission wirings (addPermission calls)
-  for (const meta of state.permissions.tagPermissions.values()) {
-    wiringFiles.add(meta.sourceFile)
-  }
-  for (const meta of state.http.routePermissions.values()) {
-    wiringFiles.add(meta.sourceFile)
-  }
-
   // Middleware wirings (addHTTPMiddleware calls)
   for (const meta of state.http.routeMiddleware.values()) {
     wiringFiles.add(meta.sourceFile)
@@ -769,3 +849,44 @@ export function computeDiagnostics(state: InspectorState): void {
 
   state.diagnostics = diagnostics
 }
+
+/**
+ * Validates that every scope referenced by a function is declared via
+ * `wireScope`. Runs after all visitors, so declaration order does not matter.
+ *
+ * A `*` suffix is a wildcard requirement: `admin:*` requires the `admin` scope
+ * to be declared, and grants its whole subtree.
+ */
+export function validateScopeReferences(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  const declared = new Set(
+    flattenScopeDefinitions(state.scopes.definitions).map((s) => s.id)
+  )
+
+  for (const [funcName, meta] of Object.entries(state.functions.meta)) {
+    if (!meta.scopes?.length) continue
+
+    for (const scope of meta.scopes) {
+      // A trailing wildcard grants a subtree; the node it hangs off must exist.
+      const declaredForm = scope.endsWith(':*') ? scope.slice(0, -2) : scope
+
+      if (scope === '*') {
+        logger.critical(
+          ErrorCode.INVALID_VALUE,
+          `Function '${funcName}' requires the bare wildcard scope '*'. A function must require a specific scope — '*' is only meaningful as a grant.`
+        )
+        continue
+      }
+
+      if (!declared.has(declaredForm)) {
+        const available = Array.from(declared)
+        logger.critical(
+          ErrorCode.INVALID_VALUE,
+          `Function '${funcName}' requires scope '${scope}' which is not declared. Declare it with wireScope. Available scopes: ${available.join(', ') || 'none'}`
+        )
+      }
+    }
+  }
+}

package/src/utils/schema-generator.test.ts

@@ -0,0 +1,164 @@
+import { test, describe, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { getInitialInspectorState } from '../inspector.js'
+import { generateAllSchemas } from './schema-generator.js'
+
+const debugLines: string[] = []
+const logger = {
+  debug(message: string) {
+    debugLines.push(message)
+  },
+  info() {},
+  warn() {},
+  error() {},
+} as any
+
+const UNRELATED_FILE_COUNT = 300
+
+let projectDir: string
+
+before(() => {
+  projectDir = mkdtempSync(join(tmpdir(), 'pikku-schema-gen-'))
+  mkdirSync(join(projectDir, 'src'))
+  writeFileSync(
+    join(projectDir, 'tsconfig.json'),
+    JSON.stringify({
+      compilerOptions: {
+        target: 'ESNext',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        strict: true,
+        skipLibCheck: true,
+      },
+      include: ['src/**/*.ts'],
+    })
+  )
+  writeFileSync(
+    join(projectDir, 'src', 'types.ts'),
+    'export type Thing = { id: string; count: number }\n'
+  )
+  // Files the tsconfig picks up but no generated custom type references. They
+  // stand in for the bulk of a real project, which the schema program has no
+  // reason to load.
+  for (let i = 0; i < UNRELATED_FILE_COUNT; i += 1) {
+    writeFileSync(
+      join(projectDir, 'src', `unrelated-${i}.ts`),
+      `export type Unrelated${i} = { a: string; b: number; c: boolean }\n`
+    )
+  }
+})
+
+after(() => {
+  rmSync(projectDir, { recursive: true, force: true })
+})
+
+describe('generateAllSchemas', () => {
+  // NOTE: this must be the first test in the file. The module-level caches are
+  // per-process, so only the first call actually builds a program — a later call
+  // reuses it and would measure a few MB no matter what.
+  //
+  // The schema generator builds a second ts.Program over the whole tsconfig —
+  // on a real tree that is ~2.5k files and ~600MB, and it used to be pinned at
+  // module scope for the life of the process. Combined with the main inspector
+  // program it pushed peak heap past 2GB and OOM'd `pikku all` (#982).
+  //
+  // Only the program is released; cachedTSSchemas (the small result cache that
+  // powers the same-process fast path) is deliberately kept.
+  test('does not retain the schema ts.Program after returning', async (t) => {
+    if (typeof global.gc !== 'function') {
+      t.skip('requires --expose-gc')
+      return
+    }
+
+    const state = getInitialInspectorState(projectDir) as any
+    // A distinct type keeps this off the cachedTSSchemas fast path, so the
+    // program is genuinely rebuilt (and therefore genuinely retainable) here.
+    state.functions.typesMap.addCustomType(
+      'RetentionProbeInput',
+      '{ probe: string; n: number }',
+      []
+    )
+
+    global.gc!()
+    const before = process.memoryUsage().heapUsed
+
+    await generateAllSchemas(
+      logger,
+      { tsconfig: join(projectDir, 'tsconfig.json') },
+      state
+    )
+
+    global.gc!()
+    const retainedMB = (process.memoryUsage().heapUsed - before) / 1024 / 1024
+
+    // A retained program (with its SourceFiles and TypeChecker) measures tens of
+    // MB even for this one-file fixture; the schemas themselves are a few KB.
+    assert.ok(
+      retainedMB < 10,
+      `expected the schema program to be released, but ${retainedMB.toFixed(1)}MB is still retained after GC`
+    )
+  })
+
+  // The virtual file explicitly imports every type it needs, so it is a complete
+  // root on its own. Rooting the program at the whole tsconfig instead made it
+  // load the entire project (2572 files on a real tree vs 870), for no gain in
+  // what could be resolved (#982).
+  test('scopes the schema program to the virtual file import closure', async () => {
+    debugLines.length = 0
+
+    const state = getInitialInspectorState(projectDir) as any
+    state.functions.typesMap.addCustomType(
+      'ScopingProbeInput',
+      '{ scope: string }',
+      []
+    )
+
+    await generateAllSchemas(
+      logger,
+      { tsconfig: join(projectDir, 'tsconfig.json') },
+      state
+    )
+
+    const line = debugLines.find((l) => l.includes('Created schema program'))
+    assert.ok(
+      line,
+      `expected a "Created schema program" debug line, got: ${debugLines.join(' | ')}`
+    )
+
+    const fileCount = Number(line!.match(/(\d+) files/)?.[1])
+    assert.ok(
+      Number.isFinite(fileCount),
+      `could not parse a file count out of: ${line}`
+    )
+    // The virtual file plus types.ts plus the default lib. Rooting at the whole
+    // tsconfig would pull in all UNRELATED_FILE_COUNT files on top of that.
+    assert.ok(
+      fileCount < UNRELATED_FILE_COUNT,
+      `expected the schema program to skip the ${UNRELATED_FILE_COUNT} unreferenced files, but it loaded ${fileCount}`
+    )
+  })
+
+  test('produces a schema for a custom type', async () => {
+    const state = getInitialInspectorState(projectDir) as any
+    state.functions.typesMap.addCustomType(
+      'ThingInput',
+      '{ id: string; count: number }',
+      []
+    )
+
+    const schemas = await generateAllSchemas(
+      logger,
+      { tsconfig: join(projectDir, 'tsconfig.json') },
+      state
+    )
+
+    assert.ok(
+      Object.keys(schemas).length > 0,
+      'expected at least one generated schema'
+    )
+  })
+})

package/src/utils/schema-generator.ts

@@ -87,7 +87,9 @@ const inspectorVersion: string = (() => {
   try {
     const pkgUrl = new URL('../../package.json', import.meta.url)
     const pkg = JSON.parse(readFileSync(pkgUrl, 'utf-8'))
-    return typeof pkg.version === 'string' ? pkg.version : `v${SCHEMA_CACHE_VERSION}`
+    return typeof pkg.version === 'string'
+      ? pkg.version
+      : `v${SCHEMA_CACHE_VERSION}`
   } catch {
     return `v${SCHEMA_CACHE_VERSION}`
   }
@@ -98,7 +100,10 @@ const inspectorVersion: string = (() => {
 // inspector version (schema-format changes ship with a version bump).
 function tsSchemaCacheKey(
   customTypesContent: string,
-  config: { schemasFromTypes?: string[]; schema?: { additionalProperties?: boolean } }
+  config: {
+    schemasFromTypes?: string[]
+    schema?: { additionalProperties?: boolean }
+  }
 ): string {
   return createHash('sha1')
     .update(`v${SCHEMA_CACHE_VERSION}\0`)
@@ -145,6 +150,7 @@ function writeDiskTSSchemas(
 }
 
 function createProgramWithVirtualFile(
+  logger: InspectorLogger,
   tsconfig: string,
   virtualFilePath: string,
   virtualFileContent: string
@@ -165,7 +171,11 @@ function createProgramWithVirtualFile(
   }
 
   const resolvedVirtualPath = resolve(virtualFilePath)
-  const fileNames = [...cachedParsedConfig.fileNames, resolvedVirtualPath]
+  // The virtual file imports every type it references, so it is a complete root
+  // on its own and TypeScript pulls in exactly the transitive closure it needs.
+  // Rooting at cachedParsedConfig.fileNames instead loaded the whole project
+  // (2572 files vs 870 on a real tree) without widening what could be resolved.
+  const fileNames = [resolvedVirtualPath]
 
   const defaultHost = ts.createCompilerHost(cachedParsedConfig.options)
   const customHost: ts.CompilerHost = {
@@ -200,6 +210,7 @@ function createProgramWithVirtualFile(
     },
   }
 
+  const startProgram = performance.now()
   const program = ts.createProgram(
     fileNames,
     cachedParsedConfig.options,
@@ -207,6 +218,9 @@ function createProgramWithVirtualFile(
     cachedSchemaProgram // reuse previous program for incremental compilation
   )
   cachedSchemaProgram = program
+  logger.debug(
+    `Created schema program in ${(performance.now() - startProgram).toFixed(0)}ms (${program.getSourceFiles().length} files)`
+  )
   return program
 }
 
@@ -274,6 +288,7 @@ function generateTSSchemas(
     '__pikku_virtual_types__.ts'
   )
   const program = createProgramWithVirtualFile(
+    logger,
     tsconfig,
     virtualFilePath,
     customTypesContent
@@ -614,6 +629,14 @@ export async function generateAllSchemas(
     zodSchemas
   )
 
+  // Release the program once the schemas are out of it. It spans the whole
+  // tsconfig (~2.5k files, ~600MB on a large tree) and was previously pinned at
+  // module scope for the life of the process, so it stacked on top of the main
+  // inspector program and pushed `pikku all` past a 2GB heap (#982). The result
+  // cache below is what the same-process fast path actually needs; the program
+  // only bought incremental reuse on a rebuild, at a cost that dwarfs it.
+  cachedSchemaProgram = undefined
+
   cachedCustomTypesContent = customTypesContent
   cachedTSSchemas = tsSchemas