@pikku/inspector 0.12.22 → 0.12.24

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## 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
+
+- 807a8d0: Add `refHTTP` / `refChannel` / `refCLI` so a consumer can wire an addon's HTTP routes, channel actions, and CLI commands directly from the addon's published `.pikku` contract metadata — no addon source is imported and nothing is hand-wired. These mirror the existing `ref('namespace:fn')` helper: each reference resolves the addon's already-loaded contract (via `wireAddon`) and proxies every function through `ref()` (RPC) at runtime.
+  - **Inspector:** `wireHTTPRoutes`/`wireChannel`/`wireCLI` now expand `refHTTP('ns:contract')` / `refChannel('ns:contract')` / `refCLI('ns:contract')` call expressions against `state.exportedContracts.addon{Http,Channel,Cli}` (already namespaced and `packageName`-tagged by `loadAddonFunctionsMeta`). An optional second argument overrides the mount basePath, e.g. `refHTTP('ext:helloRoutes', { basePath: '/ext' })`; otherwise the addon contract's own basePath is preserved.
+  - **CLI codegen:** the generated `pikku-function-types.gen.ts` now emits `refHTTP`/`refChannel`/`refCLI` (exported through `#pikku`) backed by const maps built from each wired addon's contract metadata, with every function pre-bound to `ref('ns:fn')`. Type-checking and runtime wiring resolve from the same generated artifact, so a reference can never be an inert marker.
+  - **Addon authoring bans:** when inspecting an addon package (`isAddon`), the inspector now raises a critical error if the addon calls a transport wiring helper (`wireHTTP`/`wireHTTPRoutes`/`wireChannel`/`wireCLI`/`wireScheduler`/`wireQueueWorker`/`wireMCPPrompt`/`wireMCPResource`/`wireTrigger`/`wireTriggerSource`/`wireGateway`/`wireAddon`) — these are the consuming app's responsibility (`PKU920`) — or if a `define*` contract carries `middleware`/`permissions`, which the consuming app applies, not the addon (`PKU921`). Service declarations (`wireSecret`/`wireVariable`/`wireCredential`) and function-level middleware/permissions remain allowed.
+  - **Deploy-bundle fix:** the HTTP/channel/CLI codegen commands now always emit their wiring and meta gen files once they report the category as active (truthy return), including the contracts-only or synthetic-route case where there are no local `wireHTTP`/`addChannel`/`wireCLI` source files. The generated bootstrap imports those files unconditionally, so skipping them left per-unit deploy bundles (e.g. Cloudflare units for scheduled tasks and workflow steps) unable to resolve `pikku-http-wirings.gen.js` and failing to build.
+
 ## 0.12.22
 
 ### Patch Changes

package/dist/add/add-addon-bans.d.ts

@@ -0,0 +1,7 @@
+import type { AddWiring } from '../types.js';
+/**
+ * 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 declare const checkAddonBans: AddWiring;

package/dist/add/add-addon-bans.js

@@ -0,0 +1,65 @@
+import * as ts from 'typescript';
+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) => {
+    let found = false;
+    const visit = (current) => {
+        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 = (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.`);
+        }
+    }
+};

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-channel.js

@@ -10,6 +10,8 @@ import { resolveIdentifier } from '../utils/resolve-identifier.js';
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js';
 import { resolveAddonName } from '../utils/resolve-addon-package.js';
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js';
+import { getExportedVariableName } from '../utils/get-exported-variable-name.js';
+import { resolveRefContract } from '../utils/resolve-ref-contract.js';
 /**
  * Safely get the "initializer" expression of a property-like AST node:
  * - for `foo: expr`, returns `expr`
@@ -25,6 +27,17 @@ function getInitializerOf(elem) {
     }
     return undefined;
 }
+function getObjectPropertyName(name) {
+    if (!name)
+        return null;
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    if (ts.isComputedPropertyName(name))
+        return null;
+    return name.getText();
+}
 /**
  * Resolve a handler expression (Identifier, CallExpression, or { func })
  * into its underlying function name.
@@ -84,6 +97,14 @@ function getHandlerNameFromExpression(expr, checker, rootDir) {
     }
     return null;
 }
+function extractExportedChannelRoutes(logger, routes, state, checker) {
+    const wrapper = ts.factory.createObjectLiteralExpression([
+        ts.factory.createPropertyAssignment('onMessageWiring', ts.factory.createObjectLiteralExpression([
+            ts.factory.createPropertyAssignment('contract', routes),
+        ])),
+    ]);
+    return addMessagesRoutes(logger, wrapper, state, checker).contract ?? {};
+}
 /**
  * Build out the nested message-routes by looking up each handler
  * in state.functions.meta instead of re-inferring it here.
@@ -108,9 +129,21 @@ export function addMessagesRoutes(logger, obj, state, checker) {
                 chanInit = resolved;
             }
         }
+        const refContract = resolveRefContract(chanInit, 'refChannel', state.exportedContracts.addonChannel);
+        if (refContract) {
+            const refChannelKey = getObjectPropertyName(chanElem.name);
+            if (!refChannelKey)
+                continue;
+            result[refChannelKey] = {
+                ...refContract.contract,
+            };
+            continue;
+        }
         if (!ts.isObjectLiteralExpression(chanInit))
             continue;
-        const channelKey = chanElem.name.getText();
+        const channelKey = getObjectPropertyName(chanElem.name);
+        if (!channelKey)
+            continue;
         result[channelKey] = {};
         for (const routeElem of chanInit.properties) {
             const init = getInitializerOf(routeElem);
@@ -120,11 +153,9 @@ export function addMessagesRoutes(logger, obj, state, checker) {
             const routeName = routeElem.name;
             if (!routeName)
                 continue;
-            let routeKey = routeName.getText();
-            // For string literals like 'greet' or "greet", strip the quotes
-            if (ts.isStringLiteral(routeName)) {
-                routeKey = routeName.text;
-            }
+            const routeKey = getObjectPropertyName(routeName);
+            if (!routeKey)
+                continue;
             // For shorthand properties, we need to resolve the identifier to its declaration
             if (ts.isShorthandPropertyAssignment(routeElem)) {
                 // Get the symbol for the shorthand property
@@ -359,6 +390,16 @@ export function addMessagesRoutes(logger, obj, state, checker) {
 export const addChannel = (logger, node, checker, state, options) => {
     if (!ts.isCallExpression(node))
         return;
+    if (ts.isIdentifier(node.expression) &&
+        node.expression.text === 'defineChannelRoutes') {
+        const exportName = getExportedVariableName(node, options.sourceFile);
+        const [firstArg] = node.arguments;
+        if (exportName && firstArg && ts.isObjectLiteralExpression(firstArg)) {
+            state.exportedContracts.channel[exportName] =
+                extractExportedChannelRoutes(logger, firstArg, state, checker);
+        }
+        return;
+    }
     const { expression, arguments: args } = node;
     if (!ts.isIdentifier(expression) || expression.text !== 'wireChannel')
         return;

package/dist/add/add-cli.js

@@ -8,6 +8,8 @@ import { resolveIdentifier } from '../utils/resolve-identifier.js';
 import { resolveAddonName } from '../utils/resolve-addon-package.js';
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js';
 import { extractServicesFromFunction } from '../utils/extract-services.js';
+import { getExportedVariableName } from '../utils/get-exported-variable-name.js';
+import { resolveRefContract } from '../utils/resolve-ref-contract.js';
 // Track if we've warned about missing Config type to avoid duplicate warnings
 const configTypeWarningShown = new Set();
 /**
@@ -16,6 +18,15 @@ const configTypeWarningShown = new Set();
 export const addCLI = (logger, node, typeChecker, inspectorState, options) => {
     if (!ts.isCallExpression(node))
         return;
+    if (ts.isIdentifier(node.expression) &&
+        node.expression.text === 'defineCLICommands') {
+        const exportName = getExportedVariableName(node, options.sourceFile);
+        const [firstArg] = node.arguments;
+        if (exportName && firstArg && ts.isObjectLiteralExpression(firstArg)) {
+            inspectorState.exportedContracts.cli[exportName] = processCommands(logger, firstArg, node.getSourceFile(), typeChecker, exportName, inspectorState, options);
+        }
+        return;
+    }
     // Check if this is a wireCLI call
     if (!node || !node.expression) {
         return;
@@ -129,6 +140,12 @@ function processCommands(logger, node, sourceFile, typeChecker, programName, ins
                 const spreadCommands = processCommands(logger, spreadTarget, sourceFile, typeChecker, programName, inspectorState, options, programTags);
                 Object.assign(commands, spreadCommands);
             }
+            else {
+                const refCommands = resolveRefContract(prop.expression, 'refCLI', inspectorState.exportedContracts.addonCli);
+                if (refCommands) {
+                    Object.assign(commands, refCommands.contract);
+                }
+            }
             continue;
         }
         if (!ts.isPropertyAssignment(prop))

package/dist/add/add-http-route.d.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import type { AddWiring, InspectorState } from '../types.js';
+import type { AddWiring, ExportedHTTPRouteConfigMeta, InspectorState } from '../types.js';
 import type { InspectorLogger } from '../types.js';
 /**
  * Parameters for registering an HTTP route
@@ -14,11 +14,21 @@ export interface RegisterHTTPRouteParams {
     inheritedTags?: string[];
     inheritedAuth?: boolean;
 }
+export interface RegisterHTTPRouteMetaParams {
+    route: ExportedHTTPRouteConfigMeta;
+    state: InspectorState;
+    logger: InspectorLogger;
+    sourceFile: ts.SourceFile;
+    basePath?: string;
+    inheritedTags?: string[];
+    inheritedAuth?: boolean;
+}
 /**
  * Shared function to register an HTTP route in the inspector state.
  * Used by both wireHTTP and wireHTTPRoutes.
  */
 export declare function registerHTTPRoute({ obj, state, checker, logger, sourceFile, basePath, inheritedTags, inheritedAuth, }: RegisterHTTPRouteParams): void;
+export declare function registerHTTPRouteMeta({ route, state, logger, sourceFile, basePath, inheritedTags, inheritedAuth, }: RegisterHTTPRouteMetaParams): void;
 /**
  * Process wireHTTP calls
  */

package/dist/add/add-http-route.js

@@ -251,6 +251,43 @@ export function registerHTTPRoute({ obj, state, checker, logger, sourceFile, bas
         groupBasePath: basePath || undefined,
     };
 }
+export function registerHTTPRouteMeta({ route, state, logger, sourceFile, basePath = '', inheritedTags = [], inheritedAuth, }) {
+    const method = route.method.toLowerCase();
+    const fullRoute = basePath + route.route;
+    const tags = [...inheritedTags, ...(route.tags || [])];
+    const funcName = route.func.pikkuFuncId;
+    const fnMeta = resolveFunctionMeta(state, funcName);
+    if (!fnMeta) {
+        logger.critical(ErrorCode.FUNCTION_METADATA_NOT_FOUND, `No function metadata found for '${funcName}'.`);
+        return;
+    }
+    let params = [];
+    try {
+        const keys = pathToRegexp(fullRoute).keys;
+        params = keys.filter((k) => k.type === 'param').map((k) => k.name);
+    }
+    catch (error) {
+        logger.error(`Failed to parse route '${fullRoute}': ${error instanceof Error ? error.message : error}`);
+        return;
+    }
+    if (!route.func.packageName) {
+        computeInputTypes(state.http.metaInputTypes, method, fnMeta.inputs?.[0] || null, [], params);
+    }
+    state.serviceAggregation.usedFunctions.add(funcName);
+    state.http.files.add(sourceFile.fileName);
+    state.http.meta[method][fullRoute] = {
+        pikkuFuncId: funcName,
+        ...(route.func.packageName && { packageName: route.func.packageName }),
+        route: fullRoute,
+        sourceFile: sourceFile.fileName,
+        method: method,
+        params: params.length > 0 ? params : undefined,
+        inputTypes: undefined,
+        tags: tags.length > 0 ? tags : undefined,
+        sse: route.sse ? true : undefined,
+        groupBasePath: basePath || undefined,
+    };
+}
 /**
  * Process wireHTTP calls
  */

package/dist/add/add-http-routes.d.ts

@@ -1,5 +1,2 @@
 import type { AddWiring } from '../types.js';
-/**
- * Process wireHTTPRoutes calls
- */
 export declare const addHTTPRoutes: AddWiring;