@pikku/inspector 0.12.11 → 0.12.13

package/dist/utils/resolve-addon-package.js

@@ -1,12 +1,42 @@
 import * as ts from 'typescript';
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, parse } from 'path';
+const packageNameCache = new Map();
+const findPackageNameForFile = (filePath) => {
+    if (packageNameCache.has(filePath)) {
+        return packageNameCache.get(filePath);
+    }
+    const root = parse(filePath).root;
+    let dir = dirname(filePath);
+    while (dir && dir !== root) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                const name = typeof pkg.name === 'string' ? pkg.name : null;
+                packageNameCache.set(filePath, name);
+                return name;
+            }
+            catch {
+                packageNameCache.set(filePath, null);
+                return null;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    packageNameCache.set(filePath, null);
+    return null;
+};
 /**
  * Resolve the addon package name from an imported identifier.
  * Checks if the identifier's import module specifier matches any
- * configured addon package.
- *
- * This is a general utility — any wire handler that processes a `func`
- * property can use it to detect when the function comes from an
- * addon package.
+ * configured addon package — and if the import is relative (because
+ * the identifier resolves to a source file inside the addon package
+ * itself), walks up to the nearest package.json to obtain the real
+ * package name.
  */
 export const resolveAddonName = (identifier, checker, wireAddonDeclarations) => {
     if (!wireAddonDeclarations || wireAddonDeclarations.size === 0) {
@@ -16,18 +46,36 @@ export const resolveAddonName = (identifier, checker, wireAddonDeclarations) =>
     if (!sym)
         return null;
     const decl = sym.declarations?.[0];
-    if (!decl || !ts.isImportSpecifier(decl))
-        return null;
-    // ImportSpecifier -> NamedImports -> ImportClause -> ImportDeclaration
-    const importDecl = decl.parent?.parent?.parent;
-    if (!importDecl || !ts.isImportDeclaration(importDecl))
+    if (!decl)
         return null;
-    if (!ts.isStringLiteral(importDecl.moduleSpecifier))
-        return null;
-    const moduleSpecifier = importDecl.moduleSpecifier.text;
-    for (const addonDecl of wireAddonDeclarations.values()) {
-        if (addonDecl.package === moduleSpecifier) {
-            return addonDecl.package;
+    let candidatePackage = null;
+    if (ts.isImportSpecifier(decl)) {
+        // ImportSpecifier -> NamedImports -> ImportClause -> ImportDeclaration
+        const importDecl = decl.parent?.parent?.parent;
+        if (importDecl &&
+            ts.isImportDeclaration(importDecl) &&
+            ts.isStringLiteral(importDecl.moduleSpecifier)) {
+            candidatePackage = importDecl.moduleSpecifier.text;
+        }
+    }
+    // Bare package import path
+    if (candidatePackage && !candidatePackage.startsWith('.')) {
+        for (const addonDecl of wireAddonDeclarations.values()) {
+            if (addonDecl.package === candidatePackage)
+                return addonDecl.package;
+        }
+    }
+    // Fall back to package.json lookup based on the declaration's source file.
+    // This catches the case where the identifier resolves into an addon
+    // package's own internal source (relative import inside that package).
+    const declFile = decl.getSourceFile()?.fileName;
+    if (declFile) {
+        const pkgName = findPackageNameForFile(declFile);
+        if (pkgName) {
+            for (const addonDecl of wireAddonDeclarations.values()) {
+                if (addonDecl.package === pkgName)
+                    return addonDecl.package;
+            }
         }
     }
     return null;

package/dist/utils/resolve-deploy-target.d.ts

@@ -0,0 +1,28 @@
+import type { FunctionMeta } from '@pikku/core';
+/**
+ * Thrown when a function's explicit `deploy: 'serverless'` conflicts
+ * with one of its services being declared `serverlessIncompatible`.
+ * The user has to either remove the explicit flag (let it auto-resolve
+ * to 'server'), or set `deploy: 'server'` explicitly.
+ */
+export declare class IncompatibleDeployTargetError extends Error {
+    readonly functionName: string;
+    readonly incompatibleServices: string[];
+    constructor(functionName: string, incompatibleServices: string[]);
+}
+/**
+ * Determine the effective deploy target for a function.
+ *
+ * Resolution order:
+ *   1. If any of the function's services is in `serverlessIncompatible`:
+ *      - throw if the function explicitly declares `deploy: 'serverless'`
+ *      - otherwise target is 'server'
+ *   2. Explicit `funcMeta.deploy: 'serverless' | 'server'`
+ *   3. Default 'serverless'
+ *
+ * Used both by the per-unit deploy analyzer (when bucketing functions
+ * into deployment units) and by `filterInspectorState` (when
+ * `pikku all --deploy <target>` is used to emit a target-scoped set
+ * of gen files).
+ */
+export declare function resolveDeployTarget(funcMeta: Pick<FunctionMeta, 'deploy' | 'services'>, serverlessIncompatible: Set<string>, functionName?: string): 'serverless' | 'server';

package/dist/utils/resolve-deploy-target.js

@@ -0,0 +1,56 @@
+/**
+ * Thrown when a function's explicit `deploy: 'serverless'` conflicts
+ * with one of its services being declared `serverlessIncompatible`.
+ * The user has to either remove the explicit flag (let it auto-resolve
+ * to 'server'), or set `deploy: 'server'` explicitly.
+ */
+export class IncompatibleDeployTargetError extends Error {
+    functionName;
+    incompatibleServices;
+    constructor(functionName, incompatibleServices) {
+        super(`Function '${functionName}' is declared deploy: 'serverless' but uses ` +
+            `serverless-incompatible service(s) [${incompatibleServices.join(', ')}]. ` +
+            `Either remove deploy: 'serverless' (will auto-resolve to 'server'), ` +
+            `or set deploy: 'server' explicitly.`);
+        this.functionName = functionName;
+        this.incompatibleServices = incompatibleServices;
+        this.name = 'IncompatibleDeployTargetError';
+    }
+}
+/**
+ * Determine the effective deploy target for a function.
+ *
+ * Resolution order:
+ *   1. If any of the function's services is in `serverlessIncompatible`:
+ *      - throw if the function explicitly declares `deploy: 'serverless'`
+ *      - otherwise target is 'server'
+ *   2. Explicit `funcMeta.deploy: 'serverless' | 'server'`
+ *   3. Default 'serverless'
+ *
+ * Used both by the per-unit deploy analyzer (when bucketing functions
+ * into deployment units) and by `filterInspectorState` (when
+ * `pikku all --deploy <target>` is used to emit a target-scoped set
+ * of gen files).
+ */
+export function resolveDeployTarget(funcMeta, serverlessIncompatible, functionName = '<unknown>') {
+    // Service compatibility wins over the explicit flag — a serverless
+    // bundle of a function that needs (e.g.) node:fs would crash at runtime.
+    const incompatibleHits = [];
+    if (funcMeta.services?.services) {
+        for (const svc of funcMeta.services.services) {
+            if (serverlessIncompatible.has(svc))
+                incompatibleHits.push(svc);
+        }
+    }
+    if (incompatibleHits.length > 0) {
+        if (funcMeta.deploy === 'serverless') {
+            throw new IncompatibleDeployTargetError(functionName, incompatibleHits);
+        }
+        return 'server';
+    }
+    if (funcMeta.deploy === 'server')
+        return 'server';
+    if (funcMeta.deploy === 'serverless')
+        return 'serverless';
+    return 'serverless';
+}

package/dist/utils/resolve-versions.js

@@ -96,6 +96,7 @@ export function resolveLatestVersions(state, logger) {
     }
 }
 function updateWiringReferences(state, oldId, newId) {
+    // HTTP routes
     if (state.http) {
         for (const methods of Object.values(state.http.meta)) {
             for (const meta of Object.values(methods)) {
@@ -105,4 +106,82 @@ function updateWiringReferences(state, oldId, newId) {
             }
         }
     }
+    // Channels: connect/disconnect/message slots + action-routed message wirings
+    if (state.channels) {
+        for (const channel of Object.values(state.channels.meta)) {
+            for (const slot of [
+                channel.connect,
+                channel.disconnect,
+                channel.message,
+            ]) {
+                if (slot && slot.pikkuFuncId === oldId) {
+                    slot.pikkuFuncId = newId;
+                }
+            }
+            for (const routes of Object.values(channel.messageWirings)) {
+                for (const message of Object.values(routes)) {
+                    if (message.pikkuFuncId === oldId) {
+                        message.pikkuFuncId = newId;
+                    }
+                }
+            }
+        }
+    }
+    // CLI programs: commands and nested subcommands. This also covers
+    // CLI-over-channel generation, which reads command funcIds from this meta.
+    if (state.cli) {
+        const updateCommands = (commands) => {
+            for (const command of Object.values(commands)) {
+                if (command.pikkuFuncId === oldId) {
+                    command.pikkuFuncId = newId;
+                }
+                if (command.subcommands) {
+                    updateCommands(command.subcommands);
+                }
+            }
+        };
+        for (const program of Object.values(state.cli.meta.programs)) {
+            updateCommands(program.commands);
+        }
+    }
+    // Scheduled tasks
+    if (state.scheduledTasks) {
+        for (const task of Object.values(state.scheduledTasks.meta)) {
+            if (task.pikkuFuncId === oldId) {
+                task.pikkuFuncId = newId;
+            }
+        }
+    }
+    // Queue workers
+    if (state.queueWorkers) {
+        for (const worker of Object.values(state.queueWorkers.meta)) {
+            if (worker.pikkuFuncId === oldId) {
+                worker.pikkuFuncId = newId;
+            }
+        }
+    }
+    // Trigger sources (TriggerSourceMeta carries the handler's pikkuFuncId).
+    // Gateways/workflows/agents reference functions by bare rpc name and are
+    // resolved at runtime via state.rpc.internalMeta, so they need no rewrite here.
+    if (state.triggers) {
+        for (const source of Object.values(state.triggers.sourceMeta)) {
+            if (source.pikkuFuncId === oldId) {
+                source.pikkuFuncId = newId;
+            }
+        }
+    }
+    // MCP resources, tools, and prompts
+    if (state.mcpEndpoints) {
+        for (const collection of [
+            state.mcpEndpoints.resourcesMeta,
+            state.mcpEndpoints.toolsMeta,
+            state.mcpEndpoints.promptsMeta,
+        ]) {
+            for (const endpoint of Object.values(collection)) {
+                if (endpoint.pikkuFuncId === oldId) {
+                    endpoint.pikkuFuncId = newId;
+                }
+            }
+        }
+    }
 }

package/dist/utils/schema-generator.js

@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 import { dirname, join, resolve } from 'path';
 import { createGenerator, RootlessError } from 'ts-json-schema-generator';
-import { register, tsImport } from 'tsx/esm/api';
+import { register } from 'tsx/esm/api';
 import * as z from 'zod';
 import { zodToTs, createAuxiliaryTypeStore } from 'zod-to-ts';
 import { ErrorCode } from '../error-codes.js';
@@ -212,7 +212,16 @@ async function batchImportWithRegister(logger, sourceFiles) {
         return null;
     }
     finally {
-        unregister?.();
+        await unregister?.();
+    }
+}
+async function importWithRegister(sourceFile) {
+    const unregister = register();
+    try {
+        return await import(sourceFile);
+    }
+    finally {
+        await unregister();
     }
 }
 function processZodSchema(schemaName, zodSchema, schemas, typesMap, auxiliaryTypeStore, printer, fakeSourceFile, logger) {
@@ -243,6 +252,7 @@ function processZodSchema(schemaName, zodSchema, schemas, typesMap, auxiliaryTyp
 }
 async function generateZodSchemas(logger, schemaLookup, typesMap) {
     const schemas = {};
+    const errors = [];
     const auxiliaryTypeStore = createAuxiliaryTypeStore();
     const printer = ts.createPrinter();
     const fakeSourceFile = ts.createSourceFile('zod-types.ts', '', ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
@@ -258,10 +268,10 @@ async function generateZodSchemas(logger, schemaLookup, typesMap) {
     const uniqueSourceFiles = [
         ...new Set([...schemaLookup.values()].map((ref) => ref.sourceFile)),
     ];
-    logger.info(`[TIMING] Zod schemas: ${schemaLookup.size} schemas from ${uniqueSourceFiles.length} files`);
+    logger.debug(`[TIMING] Zod schemas: ${schemaLookup.size} schemas from ${uniqueSourceFiles.length} files`);
     const importStart = performance.now();
     const importedModules = await batchImportWithRegister(logger, uniqueSourceFiles);
-    logger.info(`[TIMING] Batch import: ${(performance.now() - importStart).toFixed(0)}ms`);
+    logger.debug(`[TIMING] Batch import: ${(performance.now() - importStart).toFixed(0)}ms`);
     const processStart = performance.now();
     // Track schemas that need per-file tsImport fallback
     const fallbackSchemas = [];
@@ -270,39 +280,48 @@ async function generateZodSchemas(logger, schemaLookup, typesMap) {
         if (mod) {
             const zodSchema = mod[ref.variableName];
             if (!zodSchema) {
-                logger.warn(`Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(mod).join(', ')}`);
+                errors.push(`Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(mod).join(', ')}`);
                 continue;
             }
             try {
                 processZodSchema(schemaName, zodSchema, schemas, typesMap, auxiliaryTypeStore, printer, fakeSourceFile, logger);
             }
             catch (e) {
-                logger.warn(`Could not convert Zod schema '${schemaName}': ${e instanceof Error ? e.message : e}`);
+                errors.push(`Could not convert Zod schema '${schemaName}': ${e instanceof Error ? e.message : e}`);
             }
         }
         else {
             fallbackSchemas.push([schemaName, ref]);
         }
     }
-    // Fallback: use tsImport for any schemas that batch import couldn't handle
+    // Fallback: use a scoped tsx register/import cycle for any schemas that
+    // batch import couldn't handle. Avoid tsImport() here because its ESM path
+    // can leave loader plumbing alive after failed imports, which prevents the
+    // CLI process from exiting on schema errors.
     if (fallbackSchemas.length > 0) {
-        logger.debug(`Falling back to tsImport for ${fallbackSchemas.length} schema(s)`);
+        logger.debug(`Falling back to register() import for ${fallbackSchemas.length} schema(s)`);
         for (const [schemaName, ref] of fallbackSchemas) {
             try {
-                const module = await tsImport(ref.sourceFile, import.meta.url);
+                const module = await importWithRegister(ref.sourceFile);
                 const zodSchema = module[ref.variableName];
                 if (!zodSchema) {
-                    logger.warn(`Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(module).join(', ')}`);
+                    errors.push(`Could not find exported schema '${ref.variableName}' in ${ref.sourceFile} for ${schemaName}. Available exports: ${Object.keys(module).join(', ')}`);
                     continue;
                 }
                 processZodSchema(schemaName, zodSchema, schemas, typesMap, auxiliaryTypeStore, printer, fakeSourceFile, logger);
             }
             catch (e) {
-                logger.warn(`Could not convert Zod schema '${schemaName}': ${e instanceof Error ? e.message : e}`);
+                errors.push(`Could not convert Zod schema '${schemaName}': ${e instanceof Error ? e.message : e}`);
             }
         }
     }
-    logger.info(`[TIMING] Process schemas: ${(performance.now() - processStart).toFixed(0)}ms (${Object.keys(schemas).length} generated)`);
+    if (errors.length > 0) {
+        for (const message of errors) {
+            logger.error(message);
+        }
+        throw new Error(`Schema generation failed for ${errors.length} schema${errors.length === 1 ? '' : 's'}`);
+    }
+    logger.debug(`[TIMING] Process schemas: ${(performance.now() - processStart).toFixed(0)}ms (${Object.keys(schemas).length} generated)`);
     return schemas;
 }
 export async function generateAllSchemas(logger, config, state) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "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.19",
+    "@pikku/core": "^0.12.25",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",

package/src/add/add-cli.ts

@@ -479,10 +479,16 @@ function processCommand(
         }
         break
 
-      case 'subcommands':
-        if (ts.isObjectLiteralExpression(prop.initializer)) {
+      case 'subcommands': {
+        let subcommandsNode: ts.Node | undefined = prop.initializer
+        if (ts.isIdentifier(prop.initializer)) {
+          subcommandsNode = resolveIdentifier(prop.initializer, typeChecker, [
+            'defineCLICommands',
+          ])
+        }
+        if (subcommandsNode && ts.isObjectLiteralExpression(subcommandsNode)) {
           meta.subcommands = {}
-          for (const subProp of prop.initializer.properties) {
+          for (const subProp of subcommandsNode.properties) {
             if (!ts.isPropertyAssignment(subProp)) continue
 
             const subName = getPropertyName(subProp)
@@ -507,6 +513,7 @@ function processCommand(
           }
         }
         break
+      }
 
       case 'isDefault':
         if (

package/src/add/add-credential.ts

@@ -2,6 +2,7 @@ import * as ts from 'typescript'
 import {
   getPropertyValue,
   getArrayPropertyValue,
+  assertStringLiteralProperty,
 } from '../utils/get-property-value.js'
 import type { AddWiring } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
@@ -33,6 +34,8 @@ export const addCredential: AddWiring = (
   if (ts.isObjectLiteralExpression(firstArg)) {
     const obj = firstArg
 
+    assertStringLiteralProperty(obj, 'name', 'Credential', logger)
+
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const displayNameValue = getPropertyValue(obj, 'displayName') as
       | string

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

@@ -111,6 +111,64 @@ describe('addFunctions duplicate name handling', () => {
     }
   })
 
+  test('strips VN suffix so createUserV1 + version:1 groups with createUser as createUser@v1', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-vn-suffix-'))
+    const fileV1 = join(rootDir, 'create-user-v1.ts')
+    const fileLatest = join(rootDir, 'create-user.ts')
+
+    await writeFile(
+      fileV1,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUserV1 = pikkuFunc({',
+        '  version: 1,',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    await writeFile(
+      fileLatest,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  func: async () => ({ ok: true })',
+        '})',
+      ].join('\n')
+    )
+
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: () => {},
+      hasCriticalErrors: () => false,
+    }
+
+    try {
+      const state = await inspect(logger, [fileV1, fileLatest], { rootDir })
+      // V1 suffix stripped: createUserV1 + version:1 → createUser@v1
+      assert.ok(
+        state.functions.meta['createUser@v1'],
+        'createUser@v1 should exist'
+      )
+      assert.strictEqual(state.functions.meta['createUser@v1']!.version, 1)
+      // Unversioned createUser auto-promoted to createUser@v2
+      assert.ok(
+        state.functions.meta['createUser@v2'],
+        'createUser@v2 should exist'
+      )
+      assert.strictEqual(state.functions.meta['createUser@v2']!.version, 2)
+      // No stale createUserV1@v1 entry
+      assert.strictEqual(state.functions.meta['createUserV1@v1'], undefined)
+      // Latest alias points to v2
+      assert.strictEqual(state.rpc.internalMeta['createUser'], 'createUser@v2')
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
   test('logs a critical error when exposed function name is duplicated across files', async () => {
     const rootDir = await mkdtemp(
       join(tmpdir(), 'pikku-exposed-duplicate-function-')
@@ -167,3 +225,94 @@ describe('addFunctions duplicate name handling', () => {
     }
   })
 })
+
+describe('addFunctions implementationHash', () => {
+  test('records a stable implementation hash for an inline function', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-function-hash-inline-'))
+    const file = join(rootDir, 'inline.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { pikkuFunc } from '@pikku/core'",
+        'export const createUser = pikkuFunc({',
+        '  expose: true,',
+        '  func: async ({ logger }, input: { name: string }) => {',
+        "    logger.info('create user')",
+        '    return { ok: true, name: input.name }',
+        '  }',
+        '})',
+      ].join('\n')
+    )
+
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: () => {},
+      hasCriticalErrors: () => false,
+    }
+
+    try {
+      const first = await inspect(logger, [file], { rootDir })
+      const second = await inspect(logger, [file], { rootDir })
+      const firstHash = first.functions.meta['createUser']?.implementationHash
+      const secondHash = second.functions.meta['createUser']?.implementationHash
+
+      assert.match(firstHash ?? '', /^[0-9a-f]{16}$/)
+      assert.strictEqual(firstHash, secondHash)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('changes when a referenced handler implementation changes', async () => {
+    const rootDir = await mkdtemp(
+      join(tmpdir(), 'pikku-function-hash-referenced-')
+    )
+    const file = join(rootDir, 'referenced.ts')
+
+    const writeSource = async (bodyLine: string) => {
+      await writeFile(
+        file,
+        [
+          "import { pikkuFunc } from '@pikku/core'",
+          '',
+          'const handler = async () => {',
+          `  ${bodyLine}`,
+          '  return { ok: true }',
+          '}',
+          '',
+          'export const createUser = pikkuFunc({',
+          '  func: handler,',
+          '})',
+        ].join('\n')
+      )
+    }
+
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: () => {},
+      hasCriticalErrors: () => false,
+    }
+
+    try {
+      await writeSource("console.log('first')")
+      const first = await inspect(logger, [file], { rootDir })
+
+      await writeSource("console.log('second')")
+      const second = await inspect(logger, [file], { rootDir })
+
+      assert.notStrictEqual(
+        first.functions.meta['createUser']?.implementationHash,
+        second.functions.meta['createUser']?.implementationHash
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})