@pikku/inspector 0.12.17 → 0.12.19

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+## 0.12.19
+
+### Patch Changes
+
+- fe70fe0: fix(db): make classified columns usable in Kysely queries and emit real zod
+
+  Two fixes so data-classified DB columns (`@private`/`@pii`/`@secret`, default
+  `private`) are usable end-to-end instead of poisoning ordinary app code:
+  1. **Brand marker is now optional** (`{ readonly __classification__?: ... }`)
+     in both `@pikku/core` and the `pikku db migrate` schema header. A required
+     marker made a plain value (e.g. `string`) unassignable to a branded column
+     (`Private<string>`), breaking every Kysely `where`/insert/`.set()` operand —
+     any project with classified columns failed to type-check. Optional keeps the
+     brand structurally present (so the inspector's PKU910 output check still
+     detects it) while letting plain values flow IN. The inspector's level read is
+     now union-aware (`'pii' | undefined`) so pii/secret no longer silently
+     downgrade to private.
+  2. **Zod codegen resolves classified `ColumnType<>`** to proper scalars instead
+     of `z.unknown()`. `pikku db migrate` emits `<Table>Z`/`InsertZ`/`PatchZ` from
+     the Select slot, unwrapping the brand and honoring insert-optionality from the
+     Insert slot's `| undefined`. Public `Generated<T>`/bare/nested shapes are
+     unchanged.
+
+- Updated dependencies [fe70fe0]
+  - @pikku/core@0.12.31
+
+## 0.12.18
+
+### Patch Changes
+
+- 20750fd: feat(workflow): decide step dispatch purely per-function
+
+  Workflow step execution (inline vs queue dispatch) is now decided entirely by
+  the step's function `inline` flag — the workflow-level / run-level `inline`
+  meta no longer participates in per-step dispatch.
+  - Steps default to **inline**, so a normally-started (queue-backed) workflow
+    runs its whole chain in one orchestrator pass instead of one queue
+    round-trip per step.
+  - A function marked `inline: false` is dispatched via the queue (its own
+    worker, retry isolation). When `inline: false` but no `queueService` is
+    configured, the step falls back to inline and emits a `logger.warn` instead
+    of silently swallowing the misconfiguration.
+  - Removed the now-unused workflow-level `inline` from `WorkflowsMeta` /
+    `WorkflowRuntimeMeta`, the inspector's workflow extraction, the DSL→graph
+    converter, and the deploy analyzer / service inference (which now key off
+    the per-function flag). Run-level `inline` is retained: it still controls
+    whether a whole run executes in-process without queue infrastructure.
+
+- Updated dependencies [cd101a5]
+- Updated dependencies [ac16265]
+- Updated dependencies [a05e864]
+- Updated dependencies [20750fd]
+  - @pikku/core@0.12.30
+
 ## 0.12.17
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -488,6 +488,12 @@ export const addFunctions = (logger, node, checker, state, options) => {
     const genericTypes = (typeArguments ?? [])
         .map((tn) => checker.getTypeFromTypeNode(tn))
         .map((t) => unwrapPromise(checker, t));
+    // pikkuChannelConnectionFunc<Out> declares a single generic that is the
+    // OUTPUT type — its input is always void (PikkuFunctionSessionless<void, Out>).
+    // Every other wrapper reads generic[0] as INPUT, so without this guard the
+    // connect handler's output generic is mis-recorded as inputSchemaName and the
+    // empty WS handshake fails input validation at connect (1008/403).
+    const isChannelConnectionFunc = /ChannelConnection/i.test(expression.text);
     const capitalizedName = funcIdToTypeName(name);
     // --- Input Extraction ---
     let inputNames = [];
@@ -513,7 +519,10 @@ export const addFunctions = (logger, node, checker, state, options) => {
             inputTypes = [filterType];
         }
     }
-    else if (!isListFunc && genericTypes.length >= 1 && genericTypes[0]) {
+    else if (!isChannelConnectionFunc &&
+        !isListFunc &&
+        genericTypes.length >= 1 &&
+        genericTypes[0]) {
         // Fall back to extracting from generic type arguments
         const result = getNamesAndTypes(checker, state.functions.typesMap, 'Input', name, genericTypes[0]);
         inputNames = result.names;

package/dist/add/add-keyed-wiring.js

@@ -2,6 +2,7 @@ import * as ts from 'typescript';
 import { getPropertyValue, assertStringLiteralProperty, } from '../utils/get-property-value.js';
 import { ErrorCode } from '../error-codes.js';
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
+import { parseDurationString } from '@pikku/core';
 export const createAddKeyedWiring = (config) => {
     return (logger, node, checker, state, _options) => {
         if (!ts.isCallExpression(node)) {
@@ -24,6 +25,7 @@ export const createAddKeyedWiring = (config) => {
             const nameValue = getPropertyValue(obj, 'name');
             const displayNameValue = getPropertyValue(obj, 'displayName');
             const descriptionValue = getPropertyValue(obj, 'description');
+            const rotationPeriodValue = getPropertyValue(obj, 'rotationPeriod');
             const idValue = getPropertyValue(obj, config.idField);
             let schemaVariableName = null;
             let schemaSourceFile = null;
@@ -74,6 +76,15 @@ export const createAddKeyedWiring = (config) => {
                 logger.critical(ErrorCode.MISSING_NAME, `${config.label} '${nameValue}' is missing the required 'schema' property or schema is not a variable reference.`);
                 return;
             }
+            if (rotationPeriodValue) {
+                try {
+                    parseDurationString(rotationPeriodValue);
+                }
+                catch {
+                    logger.critical(ErrorCode.INVALID_VALUE, `${config.label} '${nameValue}' has an invalid 'rotationPeriod': '${rotationPeriodValue}'. Use a duration like '1d', '30day', or '1w'.`);
+                    return;
+                }
+            }
             const sourceFile = node.getSourceFile().fileName;
             const wiringState = config.getState(state);
             wiringState.files.add(sourceFile);
@@ -90,6 +101,7 @@ export const createAddKeyedWiring = (config) => {
                 name: nameValue,
                 displayName: displayNameValue,
                 description: descriptionValue || undefined,
+                rotationPeriod: rotationPeriodValue || undefined,
                 [config.idField]: idValue,
                 schema: schemaLookupName,
                 sourceFile,

package/dist/add/add-workflow.js

@@ -182,7 +182,6 @@ export const addWorkflow = (logger, node, checker, state) => {
     let summary;
     let description;
     let errors;
-    let inline;
     let expose;
     if (ts.isObjectLiteralExpression(firstArg)) {
         const metadata = getCommonWireMetaData(firstArg, 'Workflow', workflowName, logger, checker);
@@ -192,10 +191,6 @@ export const addWorkflow = (logger, node, checker, state) => {
         summary = metadata.summary;
         description = metadata.description;
         errors = metadata.errors;
-        const inlineProp = getPropertyValue(firstArg, 'inline');
-        if (inlineProp === true) {
-            inline = true;
-        }
         expose = getPropertyValue(firstArg, 'expose');
     }
     // Validate that we got a valid function
@@ -279,7 +274,6 @@ export const addWorkflow = (logger, node, checker, state) => {
         description,
         errors,
         tags,
-        inline,
         expose,
     };
     // Workflow functions require platform services that aren't visible

package/dist/utils/check-pii-output.js

@@ -17,8 +17,12 @@ export function findPiiPaths(checker, type, path = '', depth = 0, seen = new Set
         return [];
     seen.add(type);
     // ── Is this type itself branded? ─────────────────────────────────────────
-    // Private<T> = T & { readonly __classification__: 'private' }  →  isIntersection()
-    // where one constituent has a `__classification__` property whose type is a string literal.
+    // Private<T> = T & { readonly __classification__?: 'private' }  →  isIntersection()
+    // where one constituent has a `__classification__` property whose type is a
+    // string literal. The marker is OPTIONAL (so plain values stay assignable to
+    // branded columns), which means its resolved type is `'private' | undefined` —
+    // a union, not a bare literal. Read the level union-aware via `literalString`,
+    // otherwise pii/secret silently downgrade to the `'private'` fallback.
     if (type.isIntersection()) {
         for (const t of type.types) {
             const classificationProp = t
@@ -28,7 +32,7 @@ export function findPiiPaths(checker, type, path = '', depth = 0, seen = new Set
                 const decl = classificationProp.valueDeclaration ??
                     classificationProp.declarations?.[0];
                 const classification = decl
-                    ? (checker.getTypeOfSymbolAtLocation(classificationProp, decl)?.value ?? 'private')
+                    ? (literalString(checker.getTypeOfSymbolAtLocation(classificationProp, decl)) ?? 'private')
                     : 'private';
                 return [{ path: path || '<return value>', classification }];
             }
@@ -71,3 +75,22 @@ export function findPiiPaths(checker, type, path = '', depth = 0, seen = new Set
     }
     return violations;
 }
+/**
+ * Recover a string-literal value from a type that may be the literal itself or a
+ * union containing it (e.g. `'private' | undefined`, produced by the optional
+ * `__classification__?` marker). Returns undefined when no string literal is
+ * present so the caller can apply its own fallback.
+ */
+function literalString(type) {
+    const value = type.value;
+    if (typeof value === 'string')
+        return value;
+    if (type.isUnion()) {
+        for (const member of type.types) {
+            const found = literalString(member);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}

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

@@ -760,10 +760,15 @@ export function filterInspectorState(state, filters, logger) {
         }
         filteredState.requiredSchemas = prunedSchemas;
     }
-    // If any surviving function is a non-inline workflow step, the unit needs
-    // workflowService + queueService even though the function doesn't use them.
-    // Check the ORIGINAL graph meta (before filtering pruned it).
+    // Step dispatch is decided purely per-function: a workflow step runs via the
+    // queue only when its function opts out of inline execution (inline: false).
+    // Such a unit needs workflowService + queueService injected even though the
+    // function itself doesn't reference them. Check the ORIGINAL graph meta
+    // (before filtering pruned it).
     const survivingFuncIds = new Set(Object.keys(filteredState.functions.meta));
+    const resolveFuncId = (rpcName) => filteredState.rpc.internalMeta[rpcName] ??
+        filteredState.rpc.exposedMeta[rpcName] ??
+        rpcName;
     // Use the snapshot taken before filtering
     for (const graph of Object.values(originalGraphMeta)) {
         if (!graph.nodes)
@@ -772,11 +777,12 @@ export function filterInspectorState(state, filters, logger) {
             if (!('rpcName' in node) || !node.rpcName)
                 continue;
             const rpcName = node.rpcName;
-            if (!survivingFuncIds.has(rpcName))
+            const funcId = resolveFuncId(rpcName);
+            if (!survivingFuncIds.has(funcId) && !survivingFuncIds.has(rpcName))
                 continue;
-            const isInline = node.options?.async !== true &&
-                graph.inline === true;
-            if (!isInline) {
+            const funcMeta = (filteredState.functions.meta[funcId] ??
+                filteredState.functions.meta[rpcName]);
+            if (funcMeta?.inline === false) {
                 filteredState.serviceAggregation.requiredServices.add('workflowService');
                 filteredState.serviceAggregation.requiredServices.add('queueService');
             }

package/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -301,7 +301,6 @@ export function convertDslToGraph(workflowName, meta) {
         source,
         description: meta.description,
         tags: meta.tags,
-        inline: meta.inline,
         context: meta.context,
         nodes: nodesRecord,
         entryNodeIds,

package/package.json

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

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

@@ -316,3 +316,55 @@ describe('addFunctions implementationHash', () => {
     }
   })
 })
+
+describe('pikkuChannelConnectionFunc generic mapping', () => {
+  // Regression: pikkuChannelConnectionFunc<Out> has a single generic that is the
+  // OUTPUT type (input is always void). The inspector must NOT record that generic
+  // as inputSchemaName — otherwise the empty WS handshake is validated against an
+  // input schema requiring the send-payload shape and the connect is rejected 403.
+  test('does not map the output generic to inputSchemaName', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-channel-connect-'))
+    const file = join(rootDir, 'channel.ts')
+
+    await writeFile(
+      file,
+      [
+        'type Sessionless<In, Out> = (',
+        '  services: any,',
+        '  data: In,',
+        '  interaction: any',
+        ') => Promise<Out>',
+        'export const pikkuChannelConnectionFunc = <Out = unknown>(',
+        '  func: Sessionless<void, Out>',
+        ') => ({ func })',
+        'export const onCardsConnect = pikkuChannelConnectionFunc<{',
+        "  type: 'hello'",
+        '  count: number',
+        '}>(async (_services, _data, _interaction) => {})',
+      ].join('\n')
+    )
+
+    const logger: InspectorLogger = {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      critical: () => {},
+      hasCriticalErrors: () => false,
+    }
+
+    try {
+      const state = await inspect(logger, [file], { rootDir })
+      const meta = state.functions.meta['onCardsConnect']
+      assert.ok(meta, 'onCardsConnect meta should exist')
+      assert.strictEqual(
+        meta!.inputSchemaName,
+        null,
+        'connect input must be void (no input schema), not the output generic'
+      )
+      assert.deepStrictEqual(meta!.inputs, [])
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-functions.ts

@@ -671,6 +671,13 @@ export const addFunctions: AddWiring = (
     .map((tn) => checker.getTypeFromTypeNode(tn))
     .map((t) => unwrapPromise(checker, t))
 
+  // pikkuChannelConnectionFunc<Out> declares a single generic that is the
+  // OUTPUT type — its input is always void (PikkuFunctionSessionless<void, Out>).
+  // Every other wrapper reads generic[0] as INPUT, so without this guard the
+  // connect handler's output generic is mis-recorded as inputSchemaName and the
+  // empty WS handshake fails input validation at connect (1008/403).
+  const isChannelConnectionFunc = /ChannelConnection/i.test(expression.text)
+
   const capitalizedName = funcIdToTypeName(name)
 
   // --- Input Extraction ---
@@ -708,7 +715,12 @@ export const addFunctions: AddWiring = (
     } else {
       inputTypes = [filterType]
     }
-  } else if (!isListFunc && genericTypes.length >= 1 && genericTypes[0]) {
+  } else if (
+    !isChannelConnectionFunc &&
+    !isListFunc &&
+    genericTypes.length >= 1 &&
+    genericTypes[0]
+  ) {
     // Fall back to extracting from generic type arguments
     const result = getNamesAndTypes(
       checker,

package/src/add/add-keyed-wiring.ts

@@ -6,6 +6,7 @@ import {
 import type { AddWiring, InspectorState } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
+import { parseDurationString } from '@pikku/core'
 
 export interface KeyedWiringConfig {
   functionName: string
@@ -52,6 +53,9 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
       const descriptionValue = getPropertyValue(obj, 'description') as
         | string
         | null
+      const rotationPeriodValue = getPropertyValue(obj, 'rotationPeriod') as
+        | string
+        | null
       const idValue = getPropertyValue(obj, config.idField) as string | null
 
       let schemaVariableName: string | null = null
@@ -123,6 +127,18 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
         return
       }
 
+      if (rotationPeriodValue) {
+        try {
+          parseDurationString(rotationPeriodValue)
+        } catch {
+          logger.critical(
+            ErrorCode.INVALID_VALUE,
+            `${config.label} '${nameValue}' has an invalid 'rotationPeriod': '${rotationPeriodValue}'. Use a duration like '1d', '30day', or '1w'.`
+          )
+          return
+        }
+      }
+
       const sourceFile = node.getSourceFile().fileName
 
       const wiringState = config.getState(state)
@@ -148,6 +164,7 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
         name: nameValue,
         displayName: displayNameValue,
         description: descriptionValue || undefined,
+        rotationPeriod: rotationPeriodValue || undefined,
         [config.idField]: idValue,
         schema: schemaLookupName,
         sourceFile,

package/src/add/add-workflow.ts

@@ -209,7 +209,6 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   let summary: string | undefined
   let description: string | undefined
   let errors: string[] | undefined
-  let inline: boolean | undefined
   let expose: boolean | undefined
 
   if (ts.isObjectLiteralExpression(firstArg)) {
@@ -226,11 +225,6 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     description = metadata.description
     errors = metadata.errors
 
-    const inlineProp = getPropertyValue(firstArg, 'inline')
-    if (inlineProp === true) {
-      inline = true
-    }
-
     expose = getPropertyValue(firstArg, 'expose') as boolean | undefined
   }
 
@@ -337,7 +331,6 @@ export const addWorkflow: AddWiring = (logger, node, checker, state) => {
     description,
     errors,
     tags,
-    inline,
     expose,
   }
 

package/src/add/pii-check.test.ts

@@ -27,10 +27,15 @@ function makeLogger() {
  * Mirrors what schema.d.ts emits so the TypeScript program sees the correct
  * structural brand type even without @pikku/core being importable from /tmp.
  */
+// Optional `__classification__?` mirrors what @pikku/core and `pikku db migrate`
+// actually emit (optional so plain values stay assignable to branded columns).
+// The `Secret`-in-sessioned-function cases below double as the level-fidelity
+// guard: they only pass if `findPiiPaths` reads the level union-aware
+// ('secret' | undefined), not via a naive `.value`.
 const BRAND_TYPES = `
-type Private<T> = T & { readonly __classification__: 'private' }
-type Pii<T> = T & { readonly __classification__: 'pii' }
-type Secret<T> = T & { readonly __classification__: 'secret' }
+type Private<T> = T & { readonly __classification__?: 'private' }
+type Pii<T> = T & { readonly __classification__?: 'pii' }
+type Secret<T> = T & { readonly __classification__?: 'secret' }
 `
 
 async function runInspect(sourceCode: string) {

package/src/utils/check-pii-output.ts

@@ -29,8 +29,12 @@ export function findPiiPaths(
   seen.add(type)
 
   // ── Is this type itself branded? ─────────────────────────────────────────
-  // Private<T> = T & { readonly __classification__: 'private' }  →  isIntersection()
-  // where one constituent has a `__classification__` property whose type is a string literal.
+  // Private<T> = T & { readonly __classification__?: 'private' }  →  isIntersection()
+  // where one constituent has a `__classification__` property whose type is a
+  // string literal. The marker is OPTIONAL (so plain values stay assignable to
+  // branded columns), which means its resolved type is `'private' | undefined` —
+  // a union, not a bare literal. Read the level union-aware via `literalString`,
+  // otherwise pii/secret silently downgrade to the `'private'` fallback.
   if (type.isIntersection()) {
     for (const t of type.types) {
       const classificationProp = t
@@ -41,9 +45,9 @@ export function findPiiPaths(
           classificationProp.valueDeclaration ??
           classificationProp.declarations?.[0]
         const classification = decl
-          ? ((
-              checker.getTypeOfSymbolAtLocation(classificationProp, decl) as any
-            )?.value ?? 'private')
+          ? (literalString(
+              checker.getTypeOfSymbolAtLocation(classificationProp, decl)
+            ) ?? 'private')
           : 'private'
         return [{ path: path || '<return value>', classification }]
       }
@@ -96,3 +100,21 @@ export function findPiiPaths(
 
   return violations
 }
+
+/**
+ * Recover a string-literal value from a type that may be the literal itself or a
+ * union containing it (e.g. `'private' | undefined`, produced by the optional
+ * `__classification__?` marker). Returns undefined when no string literal is
+ * present so the caller can apply its own fallback.
+ */
+function literalString(type: ts.Type): string | undefined {
+  const value = (type as { value?: unknown }).value
+  if (typeof value === 'string') return value
+  if (type.isUnion()) {
+    for (const member of type.types) {
+      const found = literalString(member)
+      if (found !== undefined) return found
+    }
+  }
+  return undefined
+}

package/src/utils/filter-inspector-state.ts

@@ -1061,21 +1061,28 @@ export function filterInspectorState(
     filteredState.requiredSchemas = prunedSchemas
   }
 
-  // If any surviving function is a non-inline workflow step, the unit needs
-  // workflowService + queueService even though the function doesn't use them.
-  // Check the ORIGINAL graph meta (before filtering pruned it).
+  // Step dispatch is decided purely per-function: a workflow step runs via the
+  // queue only when its function opts out of inline execution (inline: false).
+  // Such a unit needs workflowService + queueService injected even though the
+  // function itself doesn't reference them. Check the ORIGINAL graph meta
+  // (before filtering pruned it).
   const survivingFuncIds = new Set(Object.keys(filteredState.functions.meta))
+  const resolveFuncId = (rpcName: string): string =>
+    filteredState.rpc.internalMeta[rpcName] ??
+    filteredState.rpc.exposedMeta[rpcName] ??
+    rpcName
   // Use the snapshot taken before filtering
   for (const graph of Object.values(originalGraphMeta)) {
     if (!graph.nodes) continue
     for (const node of Object.values(graph.nodes)) {
       if (!('rpcName' in node) || !node.rpcName) continue
       const rpcName = node.rpcName as string
-      if (!survivingFuncIds.has(rpcName)) continue
-      const isInline =
-        (node as { options?: { async?: boolean } }).options?.async !== true &&
-        graph.inline === true
-      if (!isInline) {
+      const funcId = resolveFuncId(rpcName)
+      if (!survivingFuncIds.has(funcId) && !survivingFuncIds.has(rpcName))
+        continue
+      const funcMeta = (filteredState.functions.meta[funcId] ??
+        filteredState.functions.meta[rpcName]) as { inline?: boolean }
+      if (funcMeta?.inline === false) {
         filteredState.serviceAggregation.requiredServices.add('workflowService')
         filteredState.serviceAggregation.requiredServices.add('queueService')
       }

package/src/utils/workflow/graph/convert-dsl-to-graph.ts

@@ -400,7 +400,6 @@ export function convertDslToGraph(
     source,
     description: meta.description,
     tags: meta.tags,
-    inline: meta.inline,
     context: meta.context,
     nodes: nodesRecord,
     entryNodeIds,