@pikku/inspector 0.12.22 → 0.12.23

package/dist/inspector.js

@@ -1,5 +1,6 @@
 import * as ts from 'typescript';
 import { performance } from 'perf_hooks';
+import { resolve } from 'path';
 import { visitSetup, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
@@ -185,10 +186,19 @@ export function getInitialInspectorState(rootDir) {
         openAPISpec: null,
         diagnostics: [],
         addonFunctions: {},
+        exportedContracts: {
+            http: {},
+            cli: {},
+            channel: {},
+            addonHttp: {},
+            addonCli: {},
+            addonChannel: {},
+        },
         program: null,
     };
 }
 export const inspect = async (logger, routeFiles, options = {}) => {
+    const normalizedRouteFiles = routeFiles.map((file) => resolve(file));
     const compilerOptions = {
         target: ts.ScriptTarget.ESNext,
         module: ts.ModuleKind.Node16,
@@ -200,14 +210,14 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         checkJs: false,
     };
     const startProgram = performance.now();
-    const program = ts.createProgram(routeFiles, compilerOptions, undefined, // host
+    const program = ts.createProgram(normalizedRouteFiles, compilerOptions, undefined, // host
     options.oldProgram);
-    logger.debug(`Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${routeFiles.length} files${options.oldProgram ? ', incremental' : ''})`);
+    logger.debug(`Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files${options.oldProgram ? ', incremental' : ''})`);
     const startChecker = performance.now();
     const checker = program.getTypeChecker();
     logger.debug(`Got type checker in ${(performance.now() - startChecker).toFixed(2)}ms`);
     // Use provided rootDir or infer from source files
-    const rootDir = options.rootDir || findCommonAncestor(routeFiles);
+    const rootDir = options.rootDir || findCommonAncestor(normalizedRouteFiles);
     const startSourceFiles = performance.now();
     // node_modules under rootDir (e.g. a locally-installed addon) is a
     // dependency, not project source — scanning it double-counts the addon's
@@ -221,7 +231,8 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     // First sweep: add all functions
     const startSetup = performance.now();
     for (const sourceFile of sourceFiles) {
-        ts.forEachChild(sourceFile, (child) => visitSetup(logger, checker, child, state, options));
+        const sourceOptions = { ...options, sourceFile };
+        ts.forEachChild(sourceFile, (child) => visitSetup(logger, checker, child, state, sourceOptions));
     }
     logger.debug(`Visit setup phase completed in ${(performance.now() - startSetup).toFixed(0)}ms`);
     // Load addon function metadata so wirings can reference addon functions
@@ -230,7 +241,8 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         // Second sweep: add all transports
         const startRoutes = performance.now();
         for (const sourceFile of sourceFiles) {
-            ts.forEachChild(sourceFile, (child) => visitRoutes(logger, checker, child, state, options));
+            const sourceOptions = { ...options, sourceFile };
+            ts.forEachChild(sourceFile, (child) => visitRoutes(logger, checker, child, state, sourceOptions));
         }
         logger.debug(`Visit routes phase completed in ${(performance.now() - startRoutes).toFixed(0)}ms`);
         resolveLatestVersions(state, logger);

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type * as ts from 'typescript';
-import type { ChannelsMeta } from '@pikku/core/channel';
+import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel';
 import type { GatewaysMeta } from '@pikku/core/gateway';
 import type { HTTPWiringsMeta } from '@pikku/core/http';
 import type { ScheduledTasksMeta } from '@pikku/core/scheduler';
@@ -9,6 +9,7 @@ import type { WorkflowsMeta } from '@pikku/core/workflow';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp';
 import type { AIAgentMeta } from '@pikku/core/ai-agent';
 import type { CLIMeta } from '@pikku/core/cli';
+import type { CLICommandMeta } from '@pikku/core/cli';
 import type { NodesMeta } from '@pikku/core/node';
 import type { SecretDefinitions } from '@pikku/core/secret';
 import type { CredentialDefinitions } from '@pikku/core/credential';
@@ -80,6 +81,45 @@ export interface InspectorChannelState {
     meta: ChannelsMeta;
     files: Set<string>;
 }
+export interface ExportedHTTPRouteFunctionMeta {
+    pikkuFuncId: string;
+    packageName?: string;
+}
+export interface ExportedHTTPRouteConfigMeta {
+    method: string;
+    route: string;
+    func: ExportedHTTPRouteFunctionMeta;
+    auth?: boolean;
+    tags?: string[];
+    sse?: boolean;
+    contentType?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+export interface ExportedHTTPRoutesGroupMeta {
+    basePath?: string;
+    tags?: string[];
+    auth?: boolean;
+    routes: ExportedHTTPRouteMapMeta;
+}
+export type ExportedHTTPRouteEntryMeta = ExportedHTTPRouteConfigMeta | ExportedHTTPRoutesGroupMeta | ExportedHTTPRouteMapMeta;
+export interface ExportedHTTPRouteMapMeta {
+    [key: string]: ExportedHTTPRouteEntryMeta;
+}
+export type ExportedHTTPContractsMeta = Record<string, ExportedHTTPRoutesGroupMeta>;
+export interface ExportedChannelRouteMeta extends ChannelMessageMeta {
+    auth?: boolean;
+}
+export type ExportedChannelContractsMeta = Record<string, Record<string, ExportedChannelRouteMeta>>;
+export type ExportedCLIContractsMeta = Record<string, Record<string, CLICommandMeta>>;
+export interface InspectorExportedContractsState {
+    http: ExportedHTTPContractsMeta;
+    cli: ExportedCLIContractsMeta;
+    channel: ExportedChannelContractsMeta;
+    addonHttp: Record<string, ExportedHTTPContractsMeta>;
+    addonCli: Record<string, ExportedCLIContractsMeta>;
+    addonChannel: Record<string, ExportedChannelContractsMeta>;
+}
 export interface InspectorMiddlewareDefinition {
     services: FunctionServicesMeta;
     wires?: FunctionWiresMeta;
@@ -167,6 +207,7 @@ export type InspectorOptions = Partial<{
     setupOnly: boolean;
     rootDir: string;
     isAddon: boolean;
+    sourceFile: ts.SourceFile;
     types: Partial<{
         configFileType: string;
         userSessionType: string;
@@ -444,5 +485,6 @@ export interface InspectorState {
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
     addonFunctions: Record<string, FunctionsMeta>;
+    exportedContracts: InspectorExportedContractsState;
     program: ts.Program | null;
 }

package/dist/utils/get-exported-variable-name.d.ts

@@ -0,0 +1,2 @@
+import * as ts from 'typescript';
+export declare const getExportedVariableName: (node: ts.Node, sourceFile: ts.SourceFile | undefined) => string | null;

package/dist/utils/get-exported-variable-name.js

@@ -0,0 +1,34 @@
+import * as ts from 'typescript';
+const isExportedVariableStatement = (statement) => ts.isVariableStatement(statement) &&
+    (statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ??
+        false);
+export const getExportedVariableName = (node, sourceFile) => {
+    if (!sourceFile) {
+        return null;
+    }
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+        for (const statement of sourceFile.statements) {
+            if (!isExportedVariableStatement(statement))
+                continue;
+            for (const declaration of statement.declarationList.declarations) {
+                if (declaration === node) {
+                    return node.name.text;
+                }
+            }
+        }
+    }
+    if (!ts.isCallExpression(node)) {
+        return null;
+    }
+    for (const statement of sourceFile.statements) {
+        if (!isExportedVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) &&
+                declaration.initializer === node) {
+                return declaration.name.text;
+            }
+        }
+    }
+    return null;
+};

package/dist/utils/load-addon-functions-meta.js

@@ -1,6 +1,74 @@
 import { readFile, readdir } from 'fs/promises';
 import { createRequire } from 'module';
 import { join, dirname } from 'path';
+const isHTTPRouteConfig = (value) => typeof value === 'object' &&
+    value !== null &&
+    'method' in value &&
+    'func' in value &&
+    'route' in value;
+const isHTTPRouteGroup = (value) => typeof value === 'object' &&
+    value !== null &&
+    'routes' in value &&
+    !('method' in value);
+const applyPackageToHTTPRouteMap = (routes, packageName, namespace) => {
+    for (const value of Object.values(routes)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        if (isHTTPRouteConfig(value)) {
+            if (!value.func.packageName) {
+                value.func.packageName = packageName;
+            }
+            if (namespace && !value.func.pikkuFuncId.includes(':')) {
+                value.func.pikkuFuncId = `${namespace}:${value.func.pikkuFuncId}`;
+            }
+            continue;
+        }
+        if (isHTTPRouteGroup(value)) {
+            applyPackageToHTTPRouteMap(value.routes, packageName, namespace);
+            continue;
+        }
+        applyPackageToHTTPRouteMap(value, packageName, namespace);
+    }
+};
+const applyPackageToHTTPContracts = (contracts, packageName, namespace) => {
+    for (const contract of Object.values(contracts)) {
+        applyPackageToHTTPRouteMap(contract.routes, packageName, namespace);
+    }
+};
+const applyPackageToCLICommands = (commands, packageName, namespace) => {
+    for (const command of Object.values(commands)) {
+        if (command && typeof command === 'object') {
+            if (!command.packageName && command.pikkuFuncId) {
+                command.packageName = packageName;
+            }
+            if (namespace &&
+                typeof command.pikkuFuncId === 'string' &&
+                !command.pikkuFuncId.includes(':')) {
+                command.pikkuFuncId = `${namespace}:${command.pikkuFuncId}`;
+            }
+            if (command.subcommands) {
+                applyPackageToCLICommands(command.subcommands, packageName, namespace);
+            }
+        }
+    }
+};
+const applyPackageToCLIContracts = (contracts, packageName, namespace) => {
+    for (const commands of Object.values(contracts)) {
+        applyPackageToCLICommands(commands, packageName, namespace);
+    }
+};
+const applyPackageToChannelContracts = (contracts, packageName, namespace) => {
+    for (const routes of Object.values(contracts)) {
+        for (const route of Object.values(routes)) {
+            if (!route.packageName) {
+                route.packageName = packageName;
+            }
+            if (!route.pikkuFuncId.includes(':')) {
+                route.pikkuFuncId = `${namespace}:${route.pikkuFuncId}`;
+            }
+        }
+    }
+};
 /**
  * After the setup sweep discovers wireAddon() declarations, load each addon
  * package's function metadata so that wiring handlers (channels, HTTP routes,
@@ -81,6 +149,36 @@ export async function loadAddonFunctionsMeta(logger, state) {
             catch {
                 // No services gen — addon may not have requiredParentServices
             }
+            try {
+                const httpContractsPath = require.resolve(`${decl.package}/.pikku/http/pikku-http-contracts-meta.gen.json`);
+                const httpContractsRaw = await readFile(httpContractsPath, 'utf-8');
+                const httpContracts = JSON.parse(httpContractsRaw);
+                applyPackageToHTTPContracts(httpContracts, decl.package, namespace);
+                state.exportedContracts.addonHttp[namespace] = httpContracts;
+            }
+            catch {
+                // No addon HTTP contracts metadata
+            }
+            try {
+                const cliContractsPath = require.resolve(`${decl.package}/.pikku/cli/pikku-cli-contracts-meta.gen.json`);
+                const cliContractsRaw = await readFile(cliContractsPath, 'utf-8');
+                const cliContracts = JSON.parse(cliContractsRaw);
+                applyPackageToCLIContracts(cliContracts, decl.package, namespace);
+                state.exportedContracts.addonCli[namespace] = cliContracts;
+            }
+            catch {
+                // No addon CLI contracts metadata
+            }
+            try {
+                const channelContractsPath = require.resolve(`${decl.package}/.pikku/channel/pikku-channel-contracts-meta.gen.json`);
+                const channelContractsRaw = await readFile(channelContractsPath, 'utf-8');
+                const channelContracts = JSON.parse(channelContractsRaw);
+                applyPackageToChannelContracts(channelContracts, decl.package, namespace);
+                state.exportedContracts.addonChannel[namespace] = channelContracts;
+            }
+            catch {
+                // No addon channel contracts metadata
+            }
         }
         catch (error) {
             logger.warn(`Failed to load addon function metadata for '${namespace}' (${decl.package}): ${error.message}`);

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

@@ -61,8 +61,10 @@ export const resolveAddonName = (identifier, checker, wireAddonDeclarations) =>
     // Bare package import path
     if (candidatePackage && !candidatePackage.startsWith('.')) {
         for (const addonDecl of wireAddonDeclarations.values()) {
-            if (addonDecl.package === candidatePackage)
+            if (addonDecl.package === candidatePackage ||
+                candidatePackage.startsWith(`${addonDecl.package}/`)) {
                 return addonDecl.package;
+            }
         }
     }
     // Fall back to package.json lookup based on the declaration's source file.

package/dist/utils/resolve-ref-contract.d.ts

@@ -0,0 +1,21 @@
+import * as ts from 'typescript';
+export interface RefContractResolution<T> {
+    contract: T;
+    /**
+     * Optional basePath override supplied by the consumer via the second
+     * argument, e.g. refHTTP('ns:routes', { basePath: '/ext' }). When undefined
+     * the addon contract's own basePath is preserved.
+     */
+    basePath?: string;
+}
+/**
+ * Resolve a refHTTP / refChannel / refCLI call expression against the addon
+ * contracts already loaded (and namespaced) by loadAddonFunctionsMeta.
+ *
+ * The first string argument has the form 'namespace:contractName', mirroring
+ * how ref('namespace:fn') references an addon function. Detection is purely
+ * syntactic — no import resolution is required because the namespace and
+ * contract name are carried in the string literal. An optional second object
+ * argument may override mount details such as basePath.
+ */
+export declare const resolveRefContract: <T>(node: ts.Node, helperName: "refHTTP" | "refChannel" | "refCLI", addonContracts: Record<string, Record<string, T>>) => RefContractResolution<T> | null;

package/dist/utils/resolve-ref-contract.js

@@ -0,0 +1,46 @@
+import * as ts from 'typescript';
+const getStringProperty = (obj, name) => {
+    for (const prop of obj.properties) {
+        if (ts.isPropertyAssignment(prop) &&
+            (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) &&
+            prop.name.text === name &&
+            ts.isStringLiteral(prop.initializer)) {
+            return prop.initializer.text;
+        }
+    }
+    return undefined;
+};
+/**
+ * Resolve a refHTTP / refChannel / refCLI call expression against the addon
+ * contracts already loaded (and namespaced) by loadAddonFunctionsMeta.
+ *
+ * The first string argument has the form 'namespace:contractName', mirroring
+ * how ref('namespace:fn') references an addon function. Detection is purely
+ * syntactic — no import resolution is required because the namespace and
+ * contract name are carried in the string literal. An optional second object
+ * argument may override mount details such as basePath.
+ */
+export const resolveRefContract = (node, helperName, addonContracts) => {
+    if (!ts.isCallExpression(node))
+        return null;
+    if (!ts.isIdentifier(node.expression) ||
+        node.expression.text !== helperName) {
+        return null;
+    }
+    const [arg, optionsArg] = node.arguments;
+    if (!arg || !ts.isStringLiteral(arg))
+        return null;
+    const separator = arg.text.indexOf(':');
+    if (separator === -1)
+        return null;
+    const namespace = arg.text.slice(0, separator);
+    const contractName = arg.text.slice(separator + 1);
+    const contract = addonContracts[namespace]?.[contractName];
+    if (contract === undefined)
+        return null;
+    let basePath;
+    if (optionsArg && ts.isObjectLiteralExpression(optionsArg)) {
+        basePath = getStringProperty(optionsArg, 'basePath');
+    }
+    return { contract, basePath };
+};

package/dist/utils/serialize-inspector-state.d.ts

@@ -267,6 +267,7 @@ export interface SerializableInspectorState {
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
     addonFunctions: InspectorState['addonFunctions'];
+    exportedContracts: InspectorState['exportedContracts'];
 }
 /**
  * Serializes InspectorState to a JSON-compatible format

package/dist/utils/serialize-inspector-state.js

@@ -150,6 +150,7 @@ export function serializeInspectorState(state) {
         openAPISpec: state.openAPISpec,
         diagnostics: state.diagnostics,
         addonFunctions: state.addonFunctions,
+        exportedContracts: state.exportedContracts,
     };
 }
 /**
@@ -314,6 +315,14 @@ export function deserializeInspectorState(data) {
         openAPISpec: data.openAPISpec || null,
         diagnostics: data.diagnostics || [],
         addonFunctions: data.addonFunctions || {},
+        exportedContracts: data.exportedContracts || {
+            http: {},
+            cli: {},
+            channel: {},
+            addonHttp: {},
+            addonCli: {},
+            addonChannel: {},
+        },
         program: null,
     };
 }

package/dist/visit.js

@@ -3,6 +3,7 @@ import { addFileWithFactory } from './add/add-file-with-factory.js';
 import { addFileExtendsCoreType } from './add/add-file-extends-core-type.js';
 import { addHTTPRoute } from './add/add-http-route.js';
 import { addHTTPRoutes } from './add/add-http-routes.js';
+import { checkAddonBans } from './add/add-addon-bans.js';
 import { addSchedule } from './add/add-schedule.js';
 import { addTrigger } from './add/add-trigger.js';
 import { addQueueWorker } from './add/add-queue-worker.js';
@@ -41,23 +42,27 @@ export const visitSetup = (logger, checker, node, state, options) => {
     ts.forEachChild(node, (child) => visitSetup(logger, checker, child, state, options));
 };
 export const visitRoutes = (logger, checker, node, state, options) => {
-    addFunctions(logger, node, checker, state, options);
-    addAuth(logger, node, checker, state, options);
-    addSecret(logger, node, checker, state, options);
-    addCredential(logger, node, checker, state, options);
-    addVariable(logger, node, checker, state, options);
-    addHTTPRoute(logger, node, checker, state, options);
-    addHTTPRoutes(logger, node, checker, state, options);
-    addSchedule(logger, node, checker, state, options);
-    addTrigger(logger, node, checker, state, options);
-    addQueueWorker(logger, node, checker, state, options);
-    addChannel(logger, node, checker, state, options);
-    addGateway(logger, node, checker, state, options);
-    addCLI(logger, node, checker, state, options);
-    addCLIRenderers(logger, node, checker, state, options);
-    addMCPResource(logger, node, checker, state, options);
-    addMCPPrompt(logger, node, checker, state, options);
-    addWorkflowGraph(logger, node, checker, state, options);
-    addAIAgent(logger, node, checker, state, options);
-    ts.forEachChild(node, (child) => visitRoutes(logger, checker, child, state, options));
+    const nextOptions = ts.isSourceFile(node)
+        ? { ...options, sourceFile: node }
+        : options;
+    checkAddonBans(logger, node, checker, state, nextOptions);
+    addFunctions(logger, node, checker, state, nextOptions);
+    addAuth(logger, node, checker, state, nextOptions);
+    addSecret(logger, node, checker, state, nextOptions);
+    addCredential(logger, node, checker, state, nextOptions);
+    addVariable(logger, node, checker, state, nextOptions);
+    addHTTPRoute(logger, node, checker, state, nextOptions);
+    addHTTPRoutes(logger, node, checker, state, nextOptions);
+    addSchedule(logger, node, checker, state, nextOptions);
+    addTrigger(logger, node, checker, state, nextOptions);
+    addQueueWorker(logger, node, checker, state, nextOptions);
+    addChannel(logger, node, checker, state, nextOptions);
+    addGateway(logger, node, checker, state, nextOptions);
+    addCLI(logger, node, checker, state, nextOptions);
+    addCLIRenderers(logger, node, checker, state, nextOptions);
+    addMCPResource(logger, node, checker, state, nextOptions);
+    addMCPPrompt(logger, node, checker, state, nextOptions);
+    addWorkflowGraph(logger, node, checker, state, nextOptions);
+    addAIAgent(logger, node, checker, state, nextOptions);
+    ts.forEachChild(node, (child) => visitRoutes(logger, checker, child, state, nextOptions));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.22",
+  "version": "0.12.23",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",

package/src/add/add-addon-bans.ts

@@ -0,0 +1,84 @@
+import * as ts from 'typescript'
+import type { AddWiring } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+
+/**
+ * Wiring helpers an addon must not call. Addons declare contracts with the
+ * define* helpers and export functions; the consuming app does the wiring via
+ * refHTTP / refChannel / refCLI. Service declarations remain allowed.
+ */
+const BANNED_WIRINGS = new Set([
+  'wireAddon',
+  'wireChannel',
+  'wireCLI',
+  'wireGateway',
+  'wireHTTP',
+  'wireHTTPRoutes',
+  'wireMCPPrompt',
+  'wireMCPResource',
+  'wireQueueWorker',
+  'wireScheduler',
+  'wireTrigger',
+  'wireTriggerSource',
+])
+
+const CONTRACT_DEFINERS = new Set([
+  'defineHTTPRoutes',
+  'defineChannelRoutes',
+  'defineCLICommands',
+])
+
+const hasHandlerProperty = (node: ts.Node): boolean => {
+  let found = false
+  const visit = (current: ts.Node) => {
+    if (found) return
+    if (
+      ts.isPropertyAssignment(current) &&
+      (ts.isIdentifier(current.name) || ts.isStringLiteral(current.name)) &&
+      (current.name.text === 'middleware' ||
+        current.name.text === 'permissions')
+    ) {
+      found = true
+      return
+    }
+    ts.forEachChild(current, visit)
+  }
+  visit(node)
+  return found
+}
+
+/**
+ * Enforce addon authoring rules. Only runs when inspecting an addon package
+ * (options.isAddon). Addons cannot wire transports, and their contracts cannot
+ * carry middleware or permissions — those are the consuming app's concern.
+ */
+export const checkAddonBans: AddWiring = (
+  logger,
+  node,
+  _checker,
+  _state,
+  options
+) => {
+  if (!options.isAddon) return
+  if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return
+
+  const name = node.expression.text
+
+  if (BANNED_WIRINGS.has(name)) {
+    logger.critical(
+      ErrorCode.ADDON_WIRING_NOT_ALLOWED,
+      `Addons must not call '${name}'. Declare contracts with define* and export functions; the consuming app wires them via refHTTP / refChannel / refCLI.`
+    )
+    return
+  }
+
+  if (CONTRACT_DEFINERS.has(name)) {
+    const [arg] = node.arguments
+    if (arg && hasHandlerProperty(arg)) {
+      logger.critical(
+        ErrorCode.ADDON_CONTRACT_HANDLERS_NOT_ALLOWED,
+        `Addon contract '${name}' must not declare middleware or permissions — these are applied by the consuming app, not the addon.`
+      )
+    }
+  }
+}