@pikku/inspector 0.12.45 → 0.12.47

package/CHANGELOG.md

@@ -1,3 +1,48 @@
+## 0.12.47
+
+### Patch Changes
+
+- 91077ff: The auth factory's services are read from the auth definition, not from the handler generated out of it.
+
+  `pikkuBetterAuth((services) => ...)`'s destructured services are what `authorize` and the session callbacks actually use, and they reach the generated services map by being stamped onto the auth handler's function meta. On the first run in a clean checkout that handler's file has not been written yet — so there is nothing to stamp, nothing to aggregate, and the map comes out marking those services unused. Run it a second time, with the file now on disk, and it says the opposite.
+
+  The consequence is not cosmetic: `RequiredSingletonServices` is built from that map, so a clean build types the services as optional and tree-shakes them out of the deployed auth worker — the exact failure the stamping exists to prevent, reintroduced by the one case where it cannot run. A CI checkout is always the first run.
+
+  The definition is inspected from hand-written source on every pass, so its services are now folded into the required set directly. A clean build and an incremental one give the same answer.
+
+## 0.12.46
+
+### Patch Changes
+
+- a8f9a7d: Distinguish an unresolvable schema type from an unsupported schema library.
+
+  Both failures shared one message, so a plain `z.object({...})` whose type TypeScript
+  could not resolve — a file outside tsconfig `include`, or a generated file such as
+  `.pikku/db/zod.gen.ts` that had not been written yet — was reported as
+  "Ensure your schema is imported from a supported validation library". The schema is
+  dropped either way (`inputSchemaName: null`, no generated schema file), so the message
+  is the only signal that a function has silently lost its input contract, and that
+  advice is unactionable when the schema already is zod.
+
+- eaabcbf: fix(inspector): don't reject plain destructuring in DSL workflows
+
+  `extractDestructuredDeclaration` reported "Destructuring a step result is not
+  supported in DSL workflows" for EVERY destructuring statement whose initializer
+  wasn't `await Promise.all([...])` — including ordinary local bindings that
+  involve no step at all, such as `const { runId } = input`.
+
+  Destructuring the workflow's own input is the single most idiomatic line in a
+  DSL workflow, so this rejected working workflows wholesale under a message
+  about step results that named nothing the author had written.
+
+  The diagnostic now fires only when the destructured initializer really is a
+  step (`await workflow.do(...)`, a parallel group, or a parallel fanout).
+  Anything else passes through as a non-step, exactly as the identifier path
+  already does for `const x = someLocal`.
+
+- Updated dependencies [f11675f]
+  - @pikku/core@0.12.68
+
 ## 0.12.45
 
 ### Patch Changes

package/dist/utils/detect-schema-vendor.d.ts

@@ -1,4 +1,4 @@
-import type * as ts from 'typescript';
+import * as ts from 'typescript';
 import type { SchemaVendor, InspectorLogger } from '../types.js';
 /**
  * Detect the schema vendor by tracing the type back to its library origin.

package/dist/utils/detect-schema-vendor.js

@@ -1,4 +1,16 @@
+import * as ts from 'typescript';
 import { ErrorCode } from '../error-codes.js';
+/**
+ * Whether the checker could type the identifier at all.
+ *
+ * `any` here is not a schema written in an exotic library — it is TypeScript telling us
+ * it could not resolve the declaration, which happens when the schema comes from a file
+ * outside the program (not matched by tsconfig `include`) or from a generated file that
+ * has not been written yet (`.pikku/db/zod.gen.ts` before `pikku db generate` runs).
+ * The distinction matters because the two have opposite fixes, and conflating them told
+ * users to "import from a supported validation library" about a plain `z.object`.
+ */
+const isUnresolved = (type) => (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0;
 /**
  * Detect the schema vendor by tracing the type back to its library origin.
  * This handles locally-defined schemas like `export const MySchema = z.object({...})`
@@ -67,6 +79,20 @@ export const detectSchemaVendor = (identifier, checker) => {
 export const detectSchemaVendorOrError = (identifier, checker, logger, context, sourceFile) => {
     const vendor = detectSchemaVendor(identifier, checker);
     if (vendor === 'unknown') {
+        // Two different failures used to share one message. Reporting the wrong one is not a
+        // cosmetic problem: the schema is dropped either way (`inputSchemaName: null`, no
+        // generated schema file), so the message is the only thing standing between the user
+        // and a function that silently validates nothing — and "use a supported validation
+        // library" is unactionable when the schema already IS `z.object({...})`.
+        if (isUnresolved(checker.getTypeAtLocation(identifier))) {
+            logger.critical(ErrorCode.INLINE_SCHEMA, `${context} schema '${identifier.text}' could not be TYPED from '${sourceFile}' — ` +
+                `TypeScript resolved it to 'any', so its vendor cannot be traced. This is a ` +
+                `resolution problem, not a schema problem: the file it is imported from is either ` +
+                `outside your tsconfig 'include', or has not been generated yet (a schema built ` +
+                `from '.pikku/db/zod.gen.ts' needs 'pikku db generate' to have run first). ` +
+                `Fix the import so the type resolves, then re-run.`);
+            return undefined;
+        }
         logger.critical(ErrorCode.INLINE_SCHEMA, `${context} schema vendor could not be determined from '${sourceFile}'. ` +
             `Supported vendors: zod, valibot, arktype, @effect/schema. ` +
             `Ensure your schema is imported from a supported validation library.`);

package/dist/utils/post-process.js

@@ -120,6 +120,19 @@ export function aggregateRequiredServices(state) {
             addServices(funcMeta.services);
         }
     });
+    // 1b. Services the auth factory touches, read from the definition rather than
+    // from the generated handler.
+    //
+    // `stampAuthHandlerServices` copies them onto that handler's meta, but on the
+    // first run in a clean checkout the handler's file has not been written yet,
+    // so there is nothing to stamp and nothing to aggregate — and the services map
+    // comes out claiming `kysely` (or whatever else `authorize` reads) is unused.
+    // The second run, with the file on disk, says the opposite. The definition is
+    // inspected from hand-written source either way, so taking the answer from
+    // there makes a clean build agree with an incremental one.
+    if (state.auth?.definition) {
+        addServices(state.auth.definition.services);
+    }
     // 2. Services from used middleware (individual + groups)
     usedMiddleware.forEach((middlewareName) => {
         const middlewareMeta = state.middleware.definitions[middlewareName];

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -304,8 +304,15 @@ function extractVariableDeclaration(statement, context) {
  *
  * `const [a, b] = await Promise.all([...])` is the idiomatic way to run steps
  * in parallel and keep both results, so each element of the pattern is bound to
- * the matching child step's output. Every other destructuring shape reports a
+ * the matching child step's output. Every other destructuring OF A STEP reports a
  * diagnostic rather than silently dropping the step.
+ *
+ * A destructure whose initializer is NOT a step is just an ordinary local binding
+ * — `const { runId } = input`, `const { a } = someObject` — and has nothing to do
+ * with step results. Those pass through as non-steps, exactly as the identifier
+ * path already does for `const x = someLocal`. Reporting them was rejecting the
+ * single most idiomatic line in a DSL workflow (destructuring the workflow's own
+ * input), under a message about step results that named nothing the author wrote.
  */
 function extractDestructuredDeclaration(statement, decl, context) {
     const init = decl.initializer;
@@ -342,6 +349,17 @@ function extractDestructuredDeclaration(statement, decl, context) {
             }
         }
     }
+    // Only a destructure OF A STEP is an error. Anything else is a plain local
+    // binding the DSL simply doesn't model as a step.
+    const stepCall = init && ts.isAwaitExpression(init) && ts.isCallExpression(init.expression)
+        ? init.expression
+        : null;
+    const destructuresAStep = stepCall !== null &&
+        (isWorkflowDoCall(stepCall, context.checker) ||
+            isParallelGroup(stepCall) ||
+            isParallelFanout(stepCall));
+    if (!destructuresAStep)
+        return null;
     context.errors.push({
         message: `Destructuring a step result is not supported in DSL workflows. Assign it to a variable first (e.g. \`const result = await workflow.do(...)\`) and read its properties.`,
         node: statement,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.45",
+  "version": "0.12.47",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -44,10 +44,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.67"
+    "@pikku/core": "^0.12.68"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.67",
+    "@pikku/core": "^0.12.68",
     "@types/node": "^24.11.0"
   },
   "engines": {

package/src/utils/detect-schema-vendor.test.ts

@@ -0,0 +1,123 @@
+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 * as ts from 'typescript'
+
+import { detectSchemaVendorOrError } from './detect-schema-vendor.js'
+
+let projectDir: string
+let program: ts.Program
+let checker: ts.TypeChecker
+let sourceFile: ts.SourceFile
+
+const criticals: string[] = []
+const logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+  critical(_code: unknown, message: string) {
+    criticals.push(message)
+  },
+} as any
+
+const initializerIdentifier = (name: string): ts.Identifier => {
+  let found: ts.Identifier | undefined
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.name.text === name &&
+      node.initializer &&
+      ts.isIdentifier(node.initializer)
+    ) {
+      found = node.initializer
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  assert.ok(found, `no identifier initializer found for '${name}'`)
+  return found
+}
+
+before(() => {
+  projectDir = mkdtempSync(join(tmpdir(), 'pikku-schema-vendor-'))
+  mkdirSync(join(projectDir, 'src'))
+  writeFileSync(
+    join(projectDir, 'src', 'schemas.ts'),
+    [
+      // Imported from a file that does not exist — exactly what a schema built
+      // from an ungenerated '.pikku/db/zod.gen.ts' looks like to the checker.
+      `import { UngeneratedSchema } from './not-written-yet.js'`,
+      `export const unresolved = UngeneratedSchema`,
+      `const plainObject = { a: 1 }`,
+      `export const resolvedButNotASchema = plainObject`,
+      '',
+    ].join('\n')
+  )
+
+  program = ts.createProgram([join(projectDir, 'src', 'schemas.ts')], {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.NodeNext,
+    moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    strict: true,
+    skipLibCheck: true,
+    noEmit: true,
+  })
+  checker = program.getTypeChecker()
+  sourceFile = program.getSourceFile(join(projectDir, 'src', 'schemas.ts'))!
+})
+
+after(() => {
+  rmSync(projectDir, { recursive: true, force: true })
+})
+
+describe('detectSchemaVendorOrError', () => {
+  test('reports a type the checker could not resolve as a resolution failure', () => {
+    criticals.length = 0
+
+    const vendor = detectSchemaVendorOrError(
+      initializerIdentifier('unresolved'),
+      checker,
+      logger,
+      `Function 'createTodo' input`,
+      'src/schemas.ts'
+    )
+
+    assert.equal(vendor, undefined)
+    assert.equal(criticals.length, 1)
+    const [message] = criticals
+    assert.match(message, /could not be TYPED/)
+    assert.match(message, /UngeneratedSchema/)
+    assert.match(message, /pikku db generate/)
+    // The unactionable advice must NOT be given for a type that simply failed
+    // to resolve — the schema may well already be zod.
+    assert.doesNotMatch(
+      message,
+      /Ensure your schema is imported from a supported validation library/
+    )
+  })
+
+  test('still reports a resolvable non-vendor type as an unsupported library', () => {
+    criticals.length = 0
+
+    const vendor = detectSchemaVendorOrError(
+      initializerIdentifier('resolvedButNotASchema'),
+      checker,
+      logger,
+      `Function 'createTodo' input`,
+      'src/schemas.ts'
+    )
+
+    assert.equal(vendor, undefined)
+    assert.equal(criticals.length, 1)
+    const [message] = criticals
+    assert.match(
+      message,
+      /Ensure your schema is imported from a supported validation library/
+    )
+    assert.doesNotMatch(message, /could not be TYPED/)
+  })
+})

package/src/utils/detect-schema-vendor.ts

@@ -1,7 +1,20 @@
-import type * as ts from 'typescript'
+import * as ts from 'typescript'
 import type { SchemaVendor, InspectorLogger } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
 
+/**
+ * Whether the checker could type the identifier at all.
+ *
+ * `any` here is not a schema written in an exotic library — it is TypeScript telling us
+ * it could not resolve the declaration, which happens when the schema comes from a file
+ * outside the program (not matched by tsconfig `include`) or from a generated file that
+ * has not been written yet (`.pikku/db/zod.gen.ts` before `pikku db generate` runs).
+ * The distinction matters because the two have opposite fixes, and conflating them told
+ * users to "import from a supported validation library" about a plain `z.object`.
+ */
+const isUnresolved = (type: ts.Type): boolean =>
+  (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0
+
 /**
  * Detect the schema vendor by tracing the type back to its library origin.
  * This handles locally-defined schemas like `export const MySchema = z.object({...})`
@@ -78,6 +91,23 @@ export const detectSchemaVendorOrError = (
 ): Exclude<SchemaVendor, 'unknown'> | undefined => {
   const vendor = detectSchemaVendor(identifier, checker)
   if (vendor === 'unknown') {
+    // Two different failures used to share one message. Reporting the wrong one is not a
+    // cosmetic problem: the schema is dropped either way (`inputSchemaName: null`, no
+    // generated schema file), so the message is the only thing standing between the user
+    // and a function that silently validates nothing — and "use a supported validation
+    // library" is unactionable when the schema already IS `z.object({...})`.
+    if (isUnresolved(checker.getTypeAtLocation(identifier))) {
+      logger.critical(
+        ErrorCode.INLINE_SCHEMA,
+        `${context} schema '${identifier.text}' could not be TYPED from '${sourceFile}' — ` +
+          `TypeScript resolved it to 'any', so its vendor cannot be traced. This is a ` +
+          `resolution problem, not a schema problem: the file it is imported from is either ` +
+          `outside your tsconfig 'include', or has not been generated yet (a schema built ` +
+          `from '.pikku/db/zod.gen.ts' needs 'pikku db generate' to have run first). ` +
+          `Fix the import so the type resolves, then re-run.`
+      )
+      return undefined
+    }
     logger.critical(
       ErrorCode.INLINE_SCHEMA,
       `${context} schema vendor could not be determined from '${sourceFile}'. ` +

package/src/utils/post-process.test.ts

@@ -63,6 +63,7 @@ function makeState(
     functionsMeta?: Record<string, any>
     addonFunctions?: Record<string, Record<string, any>>
     addonRequiredParentServices?: string[]
+    authServices?: string[]
   } = {}
 ): Omit<InspectorState, 'typesLookup'> {
   return {
@@ -99,6 +100,13 @@ function makeState(
     rpc: { internalMeta: {}, exposedMeta: {} },
     addonFunctions: overrides.addonFunctions ?? {},
     addonRequiredParentServices: overrides.addonRequiredParentServices ?? [],
+    auth: overrides.authServices
+      ? {
+          definition: {
+            services: { optimized: true, services: overrides.authServices },
+          },
+        }
+      : {},
   } as unknown as Omit<InspectorState, 'typesLookup'>
 }
 
@@ -306,6 +314,26 @@ describe('aggregateRequiredServices — per-function addon services', () => {
   })
 })
 
+describe('aggregateRequiredServices — the auth factory’s own services', () => {
+  test('an auth definition contributes its services before its handler exists', () => {
+    // The state a clean checkout produces: the project declares
+    // `pikkuBetterAuth`, so the definition is inspected, but the handler the CLI
+    // generates from it has not been written yet — so nothing in functions.meta
+    // mentions the services `authorize` reads.
+    const state = makeState({ authServices: ['kysely', 'jwt'] })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(required.has('kysely'))
+    assert.ok(required.has('jwt'))
+  })
+
+  test('a project without auth is unaffected', () => {
+    const state = makeState()
+    aggregateRequiredServices(state)
+    assert.equal(state.serviceAggregation.requiredServices.size, 0)
+  })
+})
+
 describe('override validation resolves the override target (value), not the logical key', () => {
   test('validateSecretOverrides accepts an override whose value is a declared secret', () => {
     const { logger, criticals } = makeCriticalLogger()
@@ -422,7 +450,10 @@ describe('validateRemoteAddonDependencies (wireRemoteAddon must be a devDependen
         })
       )
       assert.equal(criticals.length, 1)
-      assert.equal(criticals[0]!.code, ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY)
+      assert.equal(
+        criticals[0]!.code,
+        ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY
+      )
       assert.match(criticals[0]!.message, /devDependencies/)
     } finally {
       rmSync(dir, { recursive: true, force: true })
@@ -441,7 +472,10 @@ describe('validateRemoteAddonDependencies (wireRemoteAddon must be a devDependen
         })
       )
       assert.equal(criticals.length, 1)
-      assert.equal(criticals[0]!.code, ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY)
+      assert.equal(
+        criticals[0]!.code,
+        ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY
+      )
     } finally {
       rmSync(dir, { recursive: true, force: true })
     }

package/src/utils/post-process.ts

@@ -154,6 +154,20 @@ export function aggregateRequiredServices(
     }
   })
 
+  // 1b. Services the auth factory touches, read from the definition rather than
+  // from the generated handler.
+  //
+  // `stampAuthHandlerServices` copies them onto that handler's meta, but on the
+  // first run in a clean checkout the handler's file has not been written yet,
+  // so there is nothing to stamp and nothing to aggregate — and the services map
+  // comes out claiming `kysely` (or whatever else `authorize` reads) is unused.
+  // The second run, with the file on disk, says the opposite. The definition is
+  // inspected from hand-written source either way, so taking the answer from
+  // there makes a clean build agree with an incremental one.
+  if (state.auth?.definition) {
+    addServices(state.auth.definition.services)
+  }
+
   // 2. Services from used middleware (individual + groups)
   usedMiddleware.forEach((middlewareName) => {
     const middlewareMeta = state.middleware.definitions[middlewareName]

package/src/utils/workflow/dsl/extract-dsl-workflow.ts

@@ -447,8 +447,15 @@ function extractVariableDeclaration(
  *
  * `const [a, b] = await Promise.all([...])` is the idiomatic way to run steps
  * in parallel and keep both results, so each element of the pattern is bound to
- * the matching child step's output. Every other destructuring shape reports a
+ * the matching child step's output. Every other destructuring OF A STEP reports a
  * diagnostic rather than silently dropping the step.
+ *
+ * A destructure whose initializer is NOT a step is just an ordinary local binding
+ * — `const { runId } = input`, `const { a } = someObject` — and has nothing to do
+ * with step results. Those pass through as non-steps, exactly as the identifier
+ * path already does for `const x = someLocal`. Reporting them was rejecting the
+ * single most idiomatic line in a DSL workflow (destructuring the workflow's own
+ * input), under a message about step results that named nothing the author wrote.
  */
 function extractDestructuredDeclaration(
   statement: ts.VariableStatement,
@@ -499,6 +506,19 @@ function extractDestructuredDeclaration(
     }
   }
 
+  // Only a destructure OF A STEP is an error. Anything else is a plain local
+  // binding the DSL simply doesn't model as a step.
+  const stepCall =
+    init && ts.isAwaitExpression(init) && ts.isCallExpression(init.expression)
+      ? init.expression
+      : null
+  const destructuresAStep =
+    stepCall !== null &&
+    (isWorkflowDoCall(stepCall, context.checker) ||
+      isParallelGroup(stepCall) ||
+      isParallelFanout(stepCall))
+  if (!destructuresAStep) return null
+
   context.errors.push({
     message: `Destructuring a step result is not supported in DSL workflows. Assign it to a variable first (e.g. \`const result = await workflow.do(...)\`) and read its properties.`,
     node: statement,