@pikku/core 0.12.99 → 0.12.101

package/src/wirings/cli/cli-runner.test.ts

@@ -1,6 +1,7 @@
 import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
 import { NotFoundError } from '../../errors/errors.js'
+import { PikkuError } from '../../errors/error-handler.js'
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
 import {
   CLIError,
@@ -724,5 +725,108 @@ describe('CLI Runner', () => {
         singletonServices
       )
     })
+    const wireFailingCommand = (error: unknown) => {
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              boom: {
+                command: 'boom',
+                pikkuFuncId: 'boomFunc',
+                positionals: [],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+      pikkuState(null, 'cli', 'programs', {
+        'test-cli': {
+          defaultRenderer: undefined,
+          middleware: [],
+          renderers: {},
+        },
+      })
+      pikkuState(null, 'function', 'meta', {
+        boomFunc: {
+          pikkuFuncId: 'boomFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+          sessionless: true,
+        },
+      })
+      addFunction('boomFunc', {
+        func: async () => {
+          throw error
+        },
+        auth: false,
+      })
+    }
+
+    const captureStderr = async (run: () => Promise<void>) => {
+      const errors: string[] = []
+      const originalError = console.error
+      console.error = (message?: any) => {
+        errors.push(String(message))
+      }
+      try {
+        await assert.rejects(run, CLIError)
+      } finally {
+        console.error = originalError
+      }
+      return errors
+    }
+
+    test('should print an expected failure as its message alone', async () => {
+      wireFailingCommand(new PikkuError('Refusing to run — the seed drifted.'))
+
+      const errors = await captureStderr(() =>
+        executeCLI({
+          programName: 'test-cli',
+          args: ['boom'],
+          createSingletonServices: async () => singletonServices,
+        })
+      )
+
+      assert.deepStrictEqual(errors, ['Refusing to run — the seed drifted.'])
+    })
+
+    test('should keep the stack of an unexpected failure', async () => {
+      wireFailingCommand(new TypeError('cannot read x of undefined'))
+
+      const errors = await captureStderr(() =>
+        executeCLI({
+          programName: 'test-cli',
+          args: ['boom'],
+          createSingletonServices: async () => singletonServices,
+        })
+      )
+
+      assert.strictEqual(errors.length, 1)
+      assert.ok(errors[0]!.startsWith('TypeError: cannot read x of undefined'))
+      assert.ok(errors[0]!.includes('at '))
+      assert.ok(!errors[0]!.includes('Error: Error:'))
+    })
+
+    test('should add the stack of an expected failure when --verbose is passed', async () => {
+      wireFailingCommand(new PikkuError('Refusing to run.'))
+
+      const errors = await captureStderr(() =>
+        executeCLI({
+          programName: 'test-cli',
+          args: ['boom', '--verbose'],
+          createSingletonServices: async () => singletonServices,
+        })
+      )
+
+      // `--verbose` is not an option this command declares, so the parser
+      // warns about it first — the trace is whatever it printed last.
+      const printed = errors.at(-1)!
+      assert.ok(printed.startsWith('Refusing to run.\n'))
+      assert.ok(printed.includes('at '))
+    })
   })
 })

package/src/wirings/cli/cli-runner.ts

@@ -1,5 +1,4 @@
 import { NotFoundError } from '../../errors/errors.js'
-import { isExpectedError } from '../../errors/error-handler.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
 import type { CoreUserSession } from '../../types/core.types.js'
@@ -30,6 +29,7 @@ import {
 } from '../../services/user-session-service.js'
 import { LocalVariablesService } from '../../services/local-variables.js'
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js'
+import { formatCLIError, wantsStackTrace } from './format-cli-error.js'
 
 /** The caller is expected to catch this and call `process.exit(exitCode)`. */
 export class CLIError extends Error {
@@ -532,16 +532,7 @@ export async function executeCLI({
       throw error
     }
 
-    // An expected PikkuError's message is written to be the whole output.
-    if (isExpectedError(error)) {
-      console.error(error.message)
-    } else {
-      console.error('Error:', error)
-    }
-
-    if (args.includes('--verbose') || args.includes('-v')) {
-      console.error('Stack trace:', error.stack)
-    }
+    console.error(formatCLIError(error, { verbose: wantsStackTrace(args) }))
 
     throw new CLIError(error.message || String(error), 1)
   }

package/src/wirings/cli/format-cli-error.test.ts

@@ -0,0 +1,91 @@
+import { test, describe } from 'node:test'
+import * as assert from 'assert'
+import { PikkuError } from '../../errors/error-handler.js'
+import { formatCLIError, wantsStackTrace } from './format-cli-error.js'
+
+describe('formatCLIError', () => {
+  test('prints an expected error as its message alone', () => {
+    const error = new PikkuError(
+      "Persona 'guest' missing guest. Refusing to run."
+    )
+    assert.strictEqual(
+      formatCLIError(error),
+      "Persona 'guest' missing guest. Refusing to run."
+    )
+  })
+
+  test('prints an error flagged as expected as its message alone', () => {
+    const error = Object.assign(new Error('token expired'), { expected: true })
+    assert.strictEqual(formatCLIError(error), 'token expired')
+  })
+
+  test('keeps the stack for an unexpected error', () => {
+    const error = new TypeError('cannot read properties of undefined')
+    const output = formatCLIError(error)
+    assert.ok(output.includes('TypeError: cannot read properties of undefined'))
+    assert.ok(output.includes('at '))
+  })
+
+  test('does not double the error name', () => {
+    const output = formatCLIError(new Error('boom'))
+    assert.ok(!output.includes('Error: Error:'))
+    assert.ok(output.startsWith('Error: boom'))
+  })
+
+  test('adds the stack to an expected error when verbose', () => {
+    const error = new PikkuError('nope')
+    const output = formatCLIError(error, { verbose: true })
+    assert.ok(output.startsWith('nope\n'))
+    assert.ok(output.includes('at '))
+  })
+
+  test('summarises a fetch failure without inspecting the response', () => {
+    const error = Object.assign(new Error('Bad Gateway'), {
+      status: 502,
+      statusText: 'Bad Gateway',
+      response: {
+        url: 'https://api.pikkufabric.com/rpc/getDeploymentStatus',
+        headers: { forbidden: 'do not print me' },
+        body: 'a stream',
+      },
+    })
+    assert.strictEqual(
+      formatCLIError(error),
+      '502 Bad Gateway from https://api.pikkufabric.com/rpc/getDeploymentStatus'
+    )
+  })
+
+  test('keeps a fetch failure message that says more than the status', () => {
+    const error = Object.assign(new Error('Deployment not found'), {
+      status: 404,
+      statusText: 'Not Found',
+      response: { url: 'https://api.pikkufabric.com/rpc/getDeploymentStatus' },
+    })
+    assert.strictEqual(
+      formatCLIError(error),
+      'Deployment not found\n' +
+        '  404 Not Found from https://api.pikkufabric.com/rpc/getDeploymentStatus'
+    )
+  })
+
+  test('falls back to a string for a thrown non-error', () => {
+    assert.strictEqual(formatCLIError('just a string'), 'just a string')
+  })
+})
+
+describe('wantsStackTrace', () => {
+  test('is off by default', () => {
+    assert.strictEqual(wantsStackTrace(['deploy'], {}), false)
+  })
+
+  test('honours --verbose and -v', () => {
+    assert.strictEqual(wantsStackTrace(['deploy', '--verbose'], {}), true)
+    assert.strictEqual(wantsStackTrace(['deploy', '-v'], {}), true)
+  })
+
+  test('honours PIKKU_DEBUG, but not when it is switched off', () => {
+    assert.strictEqual(wantsStackTrace(['deploy'], { PIKKU_DEBUG: '1' }), true)
+    assert.strictEqual(wantsStackTrace(['deploy'], { PIKKU_DEBUG: '0' }), false)
+    assert.strictEqual(wantsStackTrace(['deploy'], { PIKKU_DEBUG: '' }), false)
+  })
+})

package/src/wirings/cli/format-cli-error.ts

@@ -0,0 +1,96 @@
+import { isExpectedError } from '../../errors/error-handler.js'
+
+/**
+ * A `PikkuFetchError` — recognised by shape, not by `instanceof`, because
+ * `@pikku/client-fetch` depends on core and core cannot depend back on it.
+ */
+type FetchFailure = {
+  status: number
+  statusText: string
+  response: { url?: string }
+  message?: string
+}
+
+const isFetchFailure = (error: unknown): error is FetchFailure => {
+  const candidate = error as Partial<FetchFailure> | null
+  return (
+    typeof candidate?.status === 'number' &&
+    typeof candidate?.statusText === 'string' &&
+    typeof candidate?.response === 'object' &&
+    candidate.response !== null
+  )
+}
+
+/**
+ * The user asked to see the machinery. `--verbose`/`-v` is the flag the CLI
+ * already documents; `PIKKU_DEBUG` is for the times the flag cannot be typed —
+ * a command that does not declare the option, or a CLI run from a script.
+ */
+export const wantsStackTrace = (
+  args: string[],
+  env: Record<string, string | undefined> = process.env
+): boolean =>
+  args.includes('--verbose') ||
+  args.includes('-v') ||
+  (env.PIKKU_DEBUG !== undefined &&
+    env.PIKKU_DEBUG !== '' &&
+    env.PIKKU_DEBUG !== '0')
+
+/**
+ * What the CLI prints when a command throws.
+ *
+ * A stack trace is an answer to "which line of pikku broke", and almost every
+ * failure a user actually hits is not that question: a missing role, an expired
+ * token, a gateway that is down. Those errors are written to be read, so the
+ * message alone is the whole output — an expected error is one deliberately
+ * raised as `PikkuError` (or carrying `expected: true`), and everything else
+ * keeps its stack, because an unexpected `TypeError` with its frames removed is
+ * a bug nobody can diagnose.
+ *
+ * A stack already begins with `Name: message`, so it is returned as-is: the
+ * `console.error('Error:', error)` this replaced produced the doubled
+ * `Error: Error: …` prefix that made even real traces look broken.
+ */
+export const formatCLIError = (
+  error: unknown,
+  { verbose = false }: { verbose?: boolean } = {}
+): string => {
+  if (isFetchFailure(error)) {
+    return formatFetchFailure(error, verbose)
+  }
+
+  const stack = (error as { stack?: unknown } | null)?.stack
+  const message = (error as { message?: unknown } | null)?.message
+
+  if (!isExpectedError(error)) {
+    return typeof stack === 'string' && stack ? stack : String(error)
+  }
+
+  const text = typeof message === 'string' && message ? message : String(error)
+  return verbose && typeof stack === 'string' && stack
+    ? `${text}\n${stack}`
+    : text
+}
+
+/**
+ * A failed HTTP call, as the line the user needs: which status, from which URL.
+ *
+ * Never the `Response` itself. Node inspects an error's own properties when it
+ * prints one, so a thrown fetch error used to dump the headers, the body stream
+ * and the redirect flags — pages of output whose only real content was the
+ * status code.
+ */
+const formatFetchFailure = (error: FetchFailure, verbose: boolean): string => {
+  const url = error.response?.url
+  const where = url ? ` from ${url}` : ''
+  const summary = `${error.status} ${error.statusText}${where}`
+  const message = error.message
+  const text =
+    message && message !== error.statusText
+      ? `${message}\n  ${summary}`
+      : summary
+  const stack = (error as { stack?: unknown }).stack
+  return verbose && typeof stack === 'string' && stack
+    ? `${text}\n${stack}`
+    : text
+}

package/src/wirings/persona/index.ts

@@ -59,6 +59,7 @@ export {
   type PersonaSignIn,
   type OperatorSignInOptions,
   type OperatorSessionResult,
+  authMount,
 } from '../../services/persona-sign-in.js'
 export {
   ACTOR_ROOT_SECRET_MIN_LENGTH,

package/src/wirings/virtual-user/virtual-user-scaffold.ts

@@ -77,7 +77,6 @@ export const VIRTUAL_USER_VARIABLES = {
    * fallback for a run nobody handed a token to, which is what a schedule is.
    */
   operatorToken: 'FABRIC_OPERATOR_TOKEN',
-  createMissing: 'PIKKU_PERSONA_CREATE_MISSING',
 } as const
 
 /**
@@ -560,9 +559,6 @@ export const executeVirtualUserRun = async ({
       )
     }
 
-    const createMissing =
-      String(await variables.get(VIRTUAL_USER_VARIABLES.createMissing)) ===
-      'true'
     const model = await variables.get(VIRTUAL_USER_VARIABLES.model)
     if (!model) {
       throw new Error(
@@ -606,7 +602,6 @@ export const executeVirtualUserRun = async ({
         ? {
             operator: {
               token,
-              createMissing,
               signInPath: signInPathFor(configuredSignInPath, 'fabric'),
             },
           }