@pikku/inspector 0.12.55 → 0.12.56

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+## 0.12.56
+
+### Patch Changes
+
+- 7e60867: Delete exports nothing references
+
+  A sweep of the `@pikku/core` surface for exports with no consumer anywhere in the repo — no package, template, verifier or e2e project imports them: `ExtractFunctionOutput`, `CLICommandDefinition`, `RequestHeaders`, `HTTPFunctionsMeta`, `HTTPWiringMiddleware`, `JsonRpcError`, `TriggerSourceInfo`, `getMCPResources`, `getMCPPrompts`, `onGraphNodeComplete` and `InputRef`.
+
+  Every one was a compatibility promise with nothing on the other end of it. Removing them narrows what 0.13 has to keep stable.
+
+  `isRef` looked like the twelfth, and isn't. It is the type guard that reads what `createRef` writes — the `__isRef` brand marking a graph node input as "substitute another node's output here". Nothing imported it because neither it nor `RefValue` was reachable from any entry point, so the one consumer that needed it, the inspector's graph serializer, had reimplemented the same four conditions privately as `isRefValue` along with its own structural copy of `RefValue`. Deleting `isRef` would have made that duplicate permanent, with the brand's shape asserted in two places free to drift apart.
+
+  So `isRef` and `RefValue` are exported from `@pikku/core/workflow` instead, and the inspector imports them rather than keeping its own copy.
+
+- a879ab3: **Codegen reports a schema it named but never generated (PKU463).** A named
+  contract type that is declared but not exported is imported by the virtual
+  source file the schema generator compiles, resolves to nothing, and yields no
+  schema — while the function meta still carries the name. `pikku all` exited 0
+  and the first call to that function failed in a deployment with
+  `MissingSchemaError`. The reference is now checked once addon schemas are
+  merged, since an addon supplies its own and checking earlier would report every
+  one of them as unresolved.
+- Updated dependencies [41c1a95]
+- Updated dependencies [ce96383]
+- Updated dependencies [7e60867]
+- Updated dependencies [f8f1244]
+- Updated dependencies [dcf20cb]
+- Updated dependencies [6512384]
+- Updated dependencies [e3b4c14]
+- Updated dependencies [efd0ed1]
+- Updated dependencies [cba98fb]
+- Updated dependencies [ce96383]
+- Updated dependencies [f8f1244]
+- Updated dependencies [f8f1244]
+- Updated dependencies [6e93a35]
+- Updated dependencies [6dada45]
+  - @pikku/core@0.12.80
+
 ## 0.12.55
 
 ### Patch Changes

package/dist/error-codes.d.ts

@@ -37,6 +37,7 @@ export declare enum ErrorCode {
     DB_FORM_ON_NON_STRING = "PKU484",
     DB_DEFAULT_SCHEMA_NAME_COLLISION = "PKU485",
     SCHEMA_GENERATION_ERROR = "PKU456",
+    SCHEMA_REFERENCE_UNRESOLVED = "PKU463",
     INLINE_SCHEMA = "PKU489",
     FUNCTION_METADATA_NOT_FOUND = "PKU559",
     DUPLICATE_AUTH_DEFINITION = "PKU581",

package/dist/error-codes.js

@@ -42,6 +42,7 @@ export var ErrorCode;
     ErrorCode["DB_DEFAULT_SCHEMA_NAME_COLLISION"] = "PKU485";
     // Configuration errors
     ErrorCode["SCHEMA_GENERATION_ERROR"] = "PKU456";
+    ErrorCode["SCHEMA_REFERENCE_UNRESOLVED"] = "PKU463";
     ErrorCode["INLINE_SCHEMA"] = "PKU489";
     // Function errors
     ErrorCode["FUNCTION_METADATA_NOT_FOUND"] = "PKU559";

package/dist/inspector.js

@@ -6,12 +6,12 @@ import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeSecretBrokers, validateNoSecretAliasServices, validateSecretUsage, computeDiagnostics, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeSecretBrokers, validateNoSecretAliasServices, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
-import { pikkuState } from '@pikku/core/internal';
+import { pikkuState } from '@pikku/core/ecosystem';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
 import { finalizeWorkflowHelperTypes, finalizeWorkflowWires, } from './utils/workflow/graph/finalize-workflow-wires.js';
@@ -336,6 +336,11 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         }
         // Re-load addon schemas (generateAllSchemas replaces state.schemas)
         await loadAddonSchemas(logger, state);
+        // After the addon merge, not before: an addon supplies its own schemas here,
+        // and checking earlier would report every one of them as unresolved.
+        if (options.schemaConfig) {
+            validateSchemaReferences(logger, state);
+        }
         state.manifest.initial = options.manifest ?? null;
         const contracts = extractContractsFromMeta(state.functions.meta);
         const baseManifest = state.manifest.initial ?? createEmptyManifest();

package/dist/utils/post-process.d.ts

@@ -50,6 +50,21 @@ export declare function computeResolvedIOTypes(state: InspectorState): void;
 export declare function computeMiddlewareGroupsMeta(state: InspectorState): void;
 export declare function computePermissionsGroupsMeta(state: InspectorState): void;
 export declare function computeRequiredSchemas(state: InspectorState, options: InspectorOptions): void;
+/**
+ * Every schema a function's contract names has to exist once codegen is done.
+ *
+ * The way it stops existing is quiet. `generateCustomTypes` hands the schema
+ * generator a virtual source file that *imports* each named contract type, so a
+ * type that is declared but never exported resolves to nothing and yields no
+ * schema — while the function's meta still carries the name. Nothing downstream
+ * reads that name until the first call, which fails with a runtime
+ * `MissingSchemaError` in a deployment rather than in the build that caused it.
+ *
+ * Reported rather than critical: the reference is only *guaranteed* to break
+ * the functions that are actually invoked, so this blocks CI through
+ * `--fail-on-error` without failing a dev server over a function nobody calls.
+ */
+export declare function validateSchemaReferences(logger: InspectorLogger, state: InspectorState): void;
 export declare function validateAgentModels(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Scenarios are pure stories of remote RPCs (same rule as client-side CLI

package/dist/utils/post-process.js

@@ -554,6 +554,58 @@ export function computeRequiredSchemas(state, options) {
         ...Array.from(schemaLookup.keys()),
     ]);
 }
+/**
+ * Every schema a function's contract names has to exist once codegen is done.
+ *
+ * The way it stops existing is quiet. `generateCustomTypes` hands the schema
+ * generator a virtual source file that *imports* each named contract type, so a
+ * type that is declared but never exported resolves to nothing and yields no
+ * schema — while the function's meta still carries the name. Nothing downstream
+ * reads that name until the first call, which fails with a runtime
+ * `MissingSchemaError` in a deployment rather than in the build that caused it.
+ *
+ * Reported rather than critical: the reference is only *guaranteed* to break
+ * the functions that are actually invoked, so this blocks CI through
+ * `--fail-on-error` without failing a dev server over a function nobody calls.
+ */
+export function validateSchemaReferences(logger, state) {
+    const { functions, schemas } = state;
+    const available = new Set(Object.keys(schemas ?? {}));
+    const unresolved = [];
+    const resolve = (typeName) => {
+        try {
+            return functions.typesMap.getUniqueName(typeName);
+        }
+        catch {
+            return typeName;
+        }
+    };
+    for (const [funcName, meta] of Object.entries(functions.meta)) {
+        for (const [role, declared] of [
+            ['input', meta.inputs?.[0]],
+            ['output', meta.outputs?.[0]],
+        ]) {
+            if (!declared || PRIMITIVE_TYPES.has(declared))
+                continue;
+            const resolved = resolve(declared);
+            if (PRIMITIVE_TYPES.has(resolved) || available.has(resolved))
+                continue;
+            unresolved.push(`${funcName}.${role} → '${resolved}'`);
+        }
+    }
+    if (unresolved.length === 0)
+        return;
+    logger.diagnostic({
+        severity: 'error',
+        code: ErrorCode.SCHEMA_REFERENCE_UNRESOLVED,
+        message: `${unresolved.length} function contract${unresolved.length === 1 ? '' : 's'} ` +
+            `name${unresolved.length === 1 ? 's' : ''} a schema that was never generated, so ` +
+            `calling ${unresolved.length === 1 ? 'it' : 'them'} fails at runtime with ` +
+            `MissingSchemaError: ${unresolved.join(', ')}. ` +
+            `The usual cause is a named type used as the function's input/output that ` +
+            `is declared but not exported — export it, or inline the type at the call site.`,
+    });
+}
 export function validateAgentModels(logger, state) {
     for (const [, meta] of Object.entries(state.agents.agentsMeta)) {
         const model = meta.model;

package/dist/utils/workflow/graph/serialize-workflow-graph.js

@@ -1,3 +1,4 @@
+import { isRef } from '@pikku/core/workflow';
 /**
  * Convert a RefValue (from runtime) to DataRef (serialized)
  */
@@ -7,22 +8,13 @@ function convertRef(ref) {
         path: ref.path,
     };
 }
-/**
- * Check if a value is a runtime RefValue
- */
-function isRefValue(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        '__isRef' in value &&
-        value.__isRef === true);
-}
 /**
  * Convert input mapping from runtime format to serialized format
  */
 function serializeInputMapping(input) {
     const result = {};
     for (const [key, value] of Object.entries(input)) {
-        if (isRefValue(value)) {
+        if (isRef(value)) {
             result[key] = convertRef(value);
         }
         else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.55",
+  "version": "0.12.56",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.79"
+    "@pikku/core": "^0.12.80"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.79",
+    "@pikku/core": "^0.12.80",
     "@types/node": "^24.11.0"
   },
   "engines": {

package/src/error-codes.ts

@@ -45,6 +45,7 @@ export enum ErrorCode {
 
   // Configuration errors
   SCHEMA_GENERATION_ERROR = 'PKU456',
+  SCHEMA_REFERENCE_UNRESOLVED = 'PKU463',
   INLINE_SCHEMA = 'PKU489',
 
   // Function errors

package/src/inspector.ts

@@ -32,6 +32,7 @@ import {
   validateNoSecretAliasServices,
   validateSecretUsage,
   computeDiagnostics,
+  validateSchemaReferences,
   validateSchemaWiringSeparation,
   validateScenarioServices,
   validateScenarioSteps,
@@ -41,7 +42,7 @@ import { validateExposedFunctionsGated } from './utils/validate-exposed-function
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js'
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
-import { pikkuState } from '@pikku/core/internal'
+import { pikkuState } from '@pikku/core/ecosystem'
 import { resolveLatestVersions } from './utils/resolve-versions.js'
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js'
 import {
@@ -444,6 +445,12 @@ export const inspect = async (
     // Re-load addon schemas (generateAllSchemas replaces state.schemas)
     await loadAddonSchemas(logger, state)
 
+    // After the addon merge, not before: an addon supplies its own schemas here,
+    // and checking earlier would report every one of them as unresolved.
+    if (options.schemaConfig) {
+      validateSchemaReferences(logger, state)
+    }
+
     state.manifest.initial = options.manifest ?? null
     const contracts = extractContractsFromMeta(state.functions.meta)
     const baseManifest = state.manifest.initial ?? createEmptyManifest()

package/src/utils/post-process.ts

@@ -689,6 +689,63 @@ export function computeRequiredSchemas(
   ])
 }
 
+/**
+ * Every schema a function's contract names has to exist once codegen is done.
+ *
+ * The way it stops existing is quiet. `generateCustomTypes` hands the schema
+ * generator a virtual source file that *imports* each named contract type, so a
+ * type that is declared but never exported resolves to nothing and yields no
+ * schema — while the function's meta still carries the name. Nothing downstream
+ * reads that name until the first call, which fails with a runtime
+ * `MissingSchemaError` in a deployment rather than in the build that caused it.
+ *
+ * Reported rather than critical: the reference is only *guaranteed* to break
+ * the functions that are actually invoked, so this blocks CI through
+ * `--fail-on-error` without failing a dev server over a function nobody calls.
+ */
+export function validateSchemaReferences(
+  logger: InspectorLogger,
+  state: InspectorState
+): void {
+  const { functions, schemas } = state
+  const available = new Set(Object.keys(schemas ?? {}))
+  const unresolved: string[] = []
+
+  const resolve = (typeName: string): string => {
+    try {
+      return functions.typesMap.getUniqueName(typeName)
+    } catch {
+      return typeName
+    }
+  }
+
+  for (const [funcName, meta] of Object.entries(functions.meta)) {
+    for (const [role, declared] of [
+      ['input', meta.inputs?.[0]],
+      ['output', meta.outputs?.[0]],
+    ] as const) {
+      if (!declared || PRIMITIVE_TYPES.has(declared)) continue
+      const resolved = resolve(declared)
+      if (PRIMITIVE_TYPES.has(resolved) || available.has(resolved)) continue
+      unresolved.push(`${funcName}.${role} → '${resolved}'`)
+    }
+  }
+
+  if (unresolved.length === 0) return
+
+  logger.diagnostic({
+    severity: 'error',
+    code: ErrorCode.SCHEMA_REFERENCE_UNRESOLVED,
+    message:
+      `${unresolved.length} function contract${unresolved.length === 1 ? '' : 's'} ` +
+      `name${unresolved.length === 1 ? 's' : ''} a schema that was never generated, so ` +
+      `calling ${unresolved.length === 1 ? 'it' : 'them'} fails at runtime with ` +
+      `MissingSchemaError: ${unresolved.join(', ')}. ` +
+      `The usual cause is a named type used as the function's input/output that ` +
+      `is declared but not exported — export it, or inline the type at the call site.`,
+  })
+}
+
 export function validateAgentModels(
   logger: InspectorLogger,
   state: InspectorState | Omit<InspectorState, 'typesLookup'>

package/src/utils/workflow/graph/serialize-workflow-graph.ts

@@ -1,3 +1,4 @@
+import { isRef } from '@pikku/core/workflow'
 import type {
   SerializedWorkflowGraph,
   SerializedGraphNode,
@@ -16,20 +17,6 @@ function convertRef(ref: { nodeId: string; path?: string }): DataRef {
   }
 }
 
-/**
- * Check if a value is a runtime RefValue
- */
-function isRefValue(
-  value: unknown
-): value is { __isRef: true; nodeId: string; path?: string } {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    '__isRef' in value &&
-    (value as any).__isRef === true
-  )
-}
-
 /**
  * Convert input mapping from runtime format to serialized format
  */
@@ -39,7 +26,7 @@ function serializeInputMapping(
   const result: Record<string, unknown | DataRef> = {}
 
   for (const [key, value] of Object.entries(input)) {
-    if (isRefValue(value)) {
+    if (isRef(value)) {
       result[key] = convertRef(value)
     } else {
       result[key] = value