@pikku/inspector 0.12.44 → 0.12.46

package/CHANGELOG.md

@@ -1,3 +1,129 @@
+## 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
+
+- ae4f59a: Gate admin capabilities on scopes, and scaffold user management
+
+  Admin capabilities were gated on `user.role === 'admin'` — a single text column
+  meaning "can do everything". Impersonating a user, rebinding a shared
+  credential and reading the user directory are distinct capabilities that one
+  user can hold independently, so they are now scopes on an `admin` tree:
+
+  | Gate                                   | Scope                    |
+  | -------------------------------------- | ------------------------ |
+  | impersonation                          | `admin:impersonate`      |
+  | `credentialOAuth`'s `canLinkSingleton` | `admin:credentials:link` |
+  | reading the user directory             | `admin:users:list`       |
+  | creating a user out of band            | `admin:users:create`     |
+  | ban / unban                            | `admin:users:ban`        |
+  | delete a user                          | `admin:users:remove`     |
+  | revoke a user's sessions               | `admin:users:sessions`   |
+  | set a user's password                  | `admin:users:password`   |
+
+  Holding the bare `admin` scope satisfies all of them via pikku's existing
+  parent-grant rule, so it is a one-for-one replacement for the old role.
+
+  better-auth's `admin()` plugin is still what implements ban, delete,
+  session-revocation and set-password, so it stays. Its `user.role` column is no
+  longer something pikku grants: it is _projected_ from the scope store when a
+  session is built, and only from the scopes whose capability better-auth's own
+  endpoints gate on the caller's role. Someone granted `admin:users:list` can read
+  the directory — which goes straight to the auth adapter — without gaining the
+  power to ban, and revoking a scope demotes the role on the next sign-in. Scopes
+  remain the single source of truth.
+
+  New `scaffold.userAdmin` in `pikku.config.json` generates the whole set —
+  `pikkuAdminListUsers`, `pikkuAdminCreateUser`, `pikkuAdminSetUserBanned`,
+  `pikkuAdminRemoveUser`, `pikkuAdminRevokeUserSessions` and
+  `pikkuAdminSetUserPassword` — into your project. Listing or banning a user is
+  ordinary application behaviour and must not require installing the console.
+  Codegen fails with an actionable error if better-auth is wired without
+  `admin()`. The console's Users page calls these same functions, showing each
+  action only where the caller holds its scope.
+
+  Every scaffold now emits a directory named for its domain — `scaffold/admin/`,
+  `scaffold/rpc/`, `scaffold/agent/`, `scaffold/auth/`, `scaffold/console/`,
+  `scaffold/graph/`, `scaffold/realtime/`, `scaffold/scenarios/`,
+  `scaffold/webhook/`, `scaffold/workflow/` — holding its wiring file beside a
+  `*.schemas.gen.ts` sibling, and every generated payload is a zod schema instead
+  of a TypeScript generic. The schemas have to stand alone: the inspector reads a
+  zod schema by importing the module that declares it, which it cannot do for a
+  wiring file whose relative pikku-types import per-unit deploy codegen rewrites.
+
+  Resolving a schema by reference rather than by name also fixes the agent HTTP
+  surface. `agentCaller` and `agentStreamCaller` take the same payload but had to
+  repeat the type literal verbatim in each generic position, because the extractor
+  synthesised the schema name from the _function_ name and so recorded an
+  `inputSchemaName` with no schema behind it whenever the two shared a named
+  alias — every agent call through that alias failed with `MissingSchemaError`.
+  One `AgentCall` schema now backs both.
+
+  Where a payload's shape belongs to `@pikku/core` (`WorkflowRunStatus`,
+  `FunctionCoverageReport`, `StubCall[]`) the generated function carries no
+  `output` schema and the inspector infers it from the handler's return type;
+  re-declaring a core type in zod would be a second definition free to drift.
+
+  Upgrading rewrites the layout in place: codegen prunes the pre-directory copy of
+  each scaffold file before it inspects the source tree, since the old flat file
+  still wires the same routes and leaving it behind would wire everything twice.
+
+  `@pikku/core` gains `hasScopes(required, held)`, the non-throwing counterpart to
+  `verifyScopes`, and declares `auth` on `CoreSingletonServices` — the auth
+  instance the generated `pikkuServices` wrapper already injected but never typed.
+  A scope root declared twice (an addon and its host both contributing the same
+  `admin` tree) now flattens to one entry per id instead of emitting it twice.
+
+  BREAKING: there is no role fallback for the scope-gated capabilities. An app
+  that relied on the old default must register a `ScopeService` and grant `admin`
+  (or a narrower `admin:*` scope). Every gate fails closed and warns when no
+  `ScopeService` is registered. `delegatedAuth`'s `defaultRole`/`mapRole` now
+  grant a pikku role through the `ScopeService` instead of writing better-auth's
+  `role` column, and the `credentialOAuth` platform user no longer sets `banned`.
+
+  BREAKING: the console reads its user directory over the scaffolded
+  `pikkuAdminListUsers` RPC (gated on `admin:users:list`, backed by better-auth's
+  `$context.adapter`) instead of `client.admin.listUsers`, and
+  `UsersTableUser`/`UsersTableLabels` no longer carry `role` — there is no role
+  column to render. `@pikku/addon-console` no longer ships a `console:listUsers`
+  function: user management is not the console's job, so a host that wants the
+  Users page must enable `scaffold.userAdmin`.
+
+- Updated dependencies [ae4f59a]
+  - @pikku/core@0.12.67
+
 ## 0.12.44
 
 ### 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/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.44",
+  "version": "0.12.46",
   "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.65"
+    "@pikku/core": "^0.12.68"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.65",
+    "@pikku/core": "^0.12.68",
     "@types/node": "^24.11.0"
   },
   "engines": {

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

@@ -190,11 +190,11 @@ describe('addAuth inspector', () => {
       [
         "import { pikkuBetterAuth } from '@pikku/better-auth'",
         "import { betterAuth } from 'better-auth'",
-        "import { bearer, admin, twoFactor } from 'better-auth/plugins'",
+        "import { bearer, apiKey, twoFactor } from 'better-auth/plugins'",
         'export const auth = pikkuBetterAuth(() =>',
         '  betterAuth({',
         "    socialProviders: { github: { clientId: 'x', clientSecret: 'y' } },",
-        '    plugins: [bearer(), admin(), twoFactor({ issuer: "pikku" })],',
+        '    plugins: [bearer(), apiKey(), twoFactor({ issuer: "pikku" })],',
         '  })',
         ')',
       ].join('\n')
@@ -204,10 +204,10 @@ describe('addAuth inspector', () => {
     try {
       const state = await inspect(makeLogger(criticals), [file], { rootDir })
       assert.equal(criticals.length, 0)
-      assert.deepEqual(state.auth.plugins, ['bearer', 'admin', 'twoFactor'])
+      assert.deepEqual(state.auth.plugins, ['bearer', 'apiKey', 'twoFactor'])
       assert.deepEqual(state.auth.definition?.plugins, [
         'bearer',
-        'admin',
+        'apiKey',
         'twoFactor',
       ])
     } finally {

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/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,