@pikku/core 0.12.106 → 0.12.111

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

@@ -1,91 +0,0 @@
-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

@@ -1,96 +0,0 @@
-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/cli/index.ts

@@ -1,19 +0,0 @@
-export {
-  wireCLI,
-  runCLICommand,
-  pikkuCLIRender,
-  executeCLI,
-  CLIError,
-} from './cli-runner.js'
-
-export { parseCLIArguments, generateCommandHelp } from './command-parser.js'
-
-export { defineCLICommands } from './define-cli-commands.js'
-export type {
-  CLIMeta,
-  CLICommandMeta,
-  CLIProgramMeta,
-  CoreCLI,
-  CoreCLICommandConfig,
-  CorePikkuCLIRender,
-} from './cli.types.js'

package/src/wirings/credential/credential.types.ts

@@ -1,37 +0,0 @@
-import type { OAuth2CredentialConfig } from '../secret/secret.types.js'
-
-export type CoreCredential<T = unknown> = {
-  /** How the credential is asked for in code. Generated into `CredentialsMap`, so it is what `credentials.get` autocompletes. */
-  name: string
-  /** The name shown to whoever has to supply the value, who is often not the person who wrote this. */
-  displayName: string
-  /** What the credential is for and where to obtain one. */
-  description?: string
-  /** `singleton` is one value for the whole deployment; `wire` is one per user, supplied by them and stored against their account. */
-  type: 'singleton' | 'wire'
-  /** The shape of the value, validated when it is supplied rather than when it is first used. */
-  schema: T
-  /** Where to go to create one, shown next to the field asking for it. */
-  docsUrl?: string
-  /** Makes this an OAuth connection rather than a value pasted in: the user is sent to the provider and the tokens are stored for them. */
-  oauth2?: OAuth2CredentialConfig & {
-    appCredentialSecretId: string
-  }
-}
-
-export type CredentialDefinitionMeta = {
-  name: string
-  displayName: string
-  description?: string
-  type: 'singleton' | 'wire'
-  schema?: Record<string, unknown> | string
-  docsUrl?: string
-  oauth2?: OAuth2CredentialConfig & {
-    appCredentialSecretId: string
-  }
-  sourceFile?: string
-}
-
-export type CredentialDefinitionsMeta = Record<string, CredentialDefinitionMeta>
-
-export type CredentialDefinitions = CredentialDefinitionMeta[]

package/src/wirings/credential/define-credential.ts

@@ -1,49 +0,0 @@
-import type { CoreCredential } from './credential.types.js'
-
-/**
- * Declares a credential. The body is a no-op that tree-shakes away — the CLI
- * reads the call by AST, so the declaration must be a top-level literal.
- * `type: 'wire'` is per-user, `type: 'singleton'` is platform-wide.
- *
- * @example
- * ```typescript
- * // Per-user API key
- * defineCredential({
- *   name: 'stripe',
- *   displayName: 'Stripe API Key',
- *   type: 'wire',
- *   schema: z.object({ apiKey: z.string() }),
- * })
- *
- * // Per-user OAuth
- * defineCredential({
- *   name: 'google-sheets',
- *   displayName: 'Google Sheets',
- *   type: 'wire',
- *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
- *   oauth2: {
- *     appCredentialSecretId: 'GOOGLE_OAUTH_APP',
- *     authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
- *     tokenUrl: 'https://oauth2.googleapis.com/token',
- *     scopes: ['https://www.googleapis.com/auth/spreadsheets'],
- *     tokenSecretId: 'GOOGLE_OAUTH_TOKENS',
- *   }
- * })
- *
- * // Platform-level OAuth (singleton)
- * defineCredential({
- *   name: 'slack',
- *   displayName: 'Slack',
- *   type: 'singleton',
- *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
- *   oauth2: {
- *     appCredentialSecretId: 'SLACK_OAUTH_APP',
- *     authorizationUrl: 'https://slack.com/oauth/v2/authorize',
- *     tokenUrl: 'https://slack.com/api/oauth.v2.access',
- *     scopes: ['chat:write', 'channels:read'],
- *     tokenSecretId: 'SLACK_OAUTH_TOKENS',
- *   }
- * })
- * ```
- */
-export const defineCredential = <T>(_config: CoreCredential<T>): void => {}

package/src/wirings/credential/index.ts

@@ -1,7 +0,0 @@
-export { defineCredential } from './define-credential.js'
-export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js'
-export type {
-  CoreCredential,
-  CredentialDefinitionsMeta,
-  CredentialDefinitions,
-} from './credential.types.js'

package/src/wirings/credential/validate-credential-definitions.ts

@@ -1,63 +0,0 @@
-import type {
-  CredentialDefinitions,
-  CredentialDefinitionsMeta,
-} from './credential.types.js'
-import type { SchemaRefLike } from '../../types/core.types.js'
-
-export type { SchemaRefLike }
-
-export function validateAndBuildCredentialDefinitionsMeta(
-  definitions: CredentialDefinitions,
-  schemaLookup: Map<string, SchemaRefLike>
-): CredentialDefinitionsMeta {
-  const meta: CredentialDefinitionsMeta = {}
-
-  for (const def of definitions) {
-    const existing = meta[def.name]
-
-    if (existing) {
-      if (def.schema && existing.schema) {
-        const defSchemaRef = schemaLookup.get(def.schema as string)
-        const existingSchemaRef = schemaLookup.get(existing.schema as string)
-
-        if (defSchemaRef && existingSchemaRef) {
-          if (
-            defSchemaRef.variableName !== existingSchemaRef.variableName ||
-            defSchemaRef.sourceFile !== existingSchemaRef.sourceFile
-          ) {
-            throw new Error(
-              `Credential '${def.name}' is defined with different schemas.\n` +
-                `  First definition: ${existing.sourceFile} (schema: ${existingSchemaRef.variableName})\n` +
-                `  Second definition: ${def.sourceFile} (schema: ${defSchemaRef.variableName})\n` +
-                `Credentials sharing a name must use the same schema.`
-            )
-          }
-        }
-      }
-
-      if (def.type !== existing.type) {
-        throw new Error(
-          `Credential '${def.name}' is defined with different types.\n` +
-            `  First definition: ${existing.sourceFile} (type: ${existing.type})\n` +
-            `  Second definition: ${def.sourceFile} (type: ${def.type})\n` +
-            `Credentials sharing a name must use the same type.`
-        )
-      }
-
-      continue
-    }
-
-    meta[def.name] = {
-      name: def.name,
-      displayName: def.displayName,
-      description: def.description,
-      type: def.type,
-      schema: def.schema,
-      oauth2: def.oauth2,
-      docsUrl: def.docsUrl,
-      sourceFile: def.sourceFile,
-    }
-  }
-
-  return meta
-}