@pikku/core 0.12.106 → 0.12.111

package/src/wirings/cli/channel/cli-approval.test.ts

@@ -1,177 +0,0 @@
-import { describe, test } from 'node:test'
-import * as assert from 'node:assert/strict'
-import { EventEmitter } from 'node:events'
-
-import {
-  APPROVAL_FLAGS,
-  approverForMode,
-  createTerminalApprover,
-  takeApprovalFlags,
-} from './cli-approval.js'
-
-/** stdin/stderr stand-ins: an emitter to feed keystrokes, a buffer to read. */
-const fakeIO = () => {
-  const input = new EventEmitter() as any
-  input.off = input.removeListener.bind(input)
-  input.pause = () => {}
-  const written: string[] = []
-  const output = { write: (s: string) => void written.push(s) } as any
-  return { input, output, written }
-}
-
-describe('takeApprovalFlags', () => {
-  test('no flag is the prompting mode', () => {
-    assert.deepEqual(takeApprovalFlags(['deploy', '--stage', 'prod'], {}), {
-      mode: 'prompt',
-      args: ['deploy', '--stage', 'prod'],
-    })
-  })
-
-  test('the flags are stripped before argv reaches the server', () => {
-    // The server owns the command tree and has never heard of these. More to
-    // the point, the decision of what may run on this machine is this
-    // machine's — a flag the server can see is one the server could act on.
-    const { mode, args } = takeApprovalFlags(
-      ['deploy', APPROVAL_FLAGS.auto, '--stage', 'prod'],
-      {}
-    )
-    assert.equal(mode, 'auto')
-    assert.deepEqual(args, ['deploy', '--stage', 'prod'])
-  })
-
-  test('dangerous wins over auto however it was asked for', () => {
-    assert.equal(
-      takeApprovalFlags([APPROVAL_FLAGS.auto, APPROVAL_FLAGS.dangerous], {})
-        .mode,
-      'dangerous'
-    )
-    assert.equal(
-      takeApprovalFlags([], { PIKKU_DANGEROUSLY_AUTO_APPROVE: '1' }).mode,
-      'dangerous'
-    )
-    assert.equal(
-      takeApprovalFlags([], { PIKKU_AUTO_APPROVE: '1' }).mode,
-      'auto'
-    )
-  })
-})
-
-describe('approverForMode', () => {
-  test('auto has nobody to ask, so approval-needing calls are refused', () => {
-    // Not a silent yes: undefined is what the responder reads as "there is
-    // nobody to ask", and it refuses rather than running.
-    assert.equal(approverForMode('auto', { isTTY: true }), undefined)
-  })
-
-  test('a non-interactive run refuses rather than assuming yes', () => {
-    // CI is exactly where an unattended push would otherwise happen.
-    assert.equal(approverForMode('prompt', { isTTY: false }), undefined)
-  })
-
-  test('dangerous approves everything and says so once', async () => {
-    const warnings: string[] = []
-    const approve = approverForMode('dangerous', {
-      isTTY: false,
-      warn: (m) => warnings.push(m),
-    })
-
-    assert.ok(approve)
-    assert.equal(await approve({ funcName: 'localPush', data: {} }), true)
-    assert.equal(warnings.length, 1)
-    assert.match(warnings[0]!, /without asking/)
-  })
-})
-
-describe('createTerminalApprover', () => {
-  const answer = async (
-    approve: ReturnType<typeof createTerminalApprover>,
-    io: ReturnType<typeof fakeIO>,
-    key: string,
-    funcName = 'localPush'
-  ) => {
-    const asked = approve({ funcName, data: {} })
-    setImmediate(() => io.input.emit('data', `${key}\n`))
-    return asked
-  }
-
-  test('y allows, n refuses', async () => {
-    const io = fakeIO()
-    const approve = createTerminalApprover(io)
-
-    assert.equal(await answer(approve, io, 'y'), true)
-    assert.equal(await answer(approve, io, 'n'), false)
-  })
-
-  test('the prompt goes to stderr and names what is being asked', async () => {
-    const io = fakeIO()
-    const approve = createTerminalApprover(io)
-
-    const asked = approve({
-      funcName: 'localPush',
-      data: {},
-      description: 'push tag v2.1.0 to origin',
-    })
-    setImmediate(() => io.input.emit('data', 'y\n'))
-    await asked
-
-    // stderr so a command whose stdout is being piped still shows the prompt
-    // rather than corrupting the stream it is asking about.
-    const prompt = io.written.join('')
-    assert.match(prompt, /push tag v2\.1\.0 to origin/)
-    assert.match(prompt, /localPush/)
-  })
-
-  test('always is remembered for that capability only', async () => {
-    const io = fakeIO()
-    const approve = createTerminalApprover(io)
-
-    assert.equal(await answer(approve, io, 'a', 'gitHead'), true)
-    io.written.length = 0
-
-    // No keystroke is sent: a second `gitHead` must not ask again.
-    assert.equal(await approve({ funcName: 'gitHead', data: {} }), true)
-    assert.deepEqual(io.written, [], 'the remembered answer asks nothing')
-
-    // ...but a different capability still does. Widening "always" to the whole
-    // session would quietly turn an interactive run into --dangerously-auto-approve.
-    assert.equal(await answer(approve, io, 'n', 'localPush'), false)
-    assert.match(io.written.join(''), /localPush/)
-  })
-
-  test('one keystroke cannot answer two questions', async () => {
-    const io = fakeIO()
-    const approve = createTerminalApprover(io)
-
-    // Requests are dispatched without awaiting, so both of these are in flight
-    // together. Unserialized they interleave on stderr and this single 'y'
-    // resolves both — approving a capability the user never read.
-    const first = approve({ funcName: 'gitHead', data: {} })
-    const second = approve({ funcName: 'localPush', data: {} })
-    setImmediate(() => io.input.emit('data', 'y\n'))
-
-    assert.equal(await first, true)
-    assert.match(io.written.join(''), /gitHead/)
-    assert.doesNotMatch(
-      io.written.join(''),
-      /localPush/,
-      'the second question waits its turn'
-    )
-
-    setImmediate(() => io.input.emit('data', 'n\n'))
-    assert.equal(await second, false)
-  })
-
-  test('a prompt left open when the run ends stops waiting', async () => {
-    const io = fakeIO()
-    const ended = new AbortController()
-    const approve = createTerminalApprover({ ...io, signal: ended.signal })
-
-    const asked = approve({ funcName: 'localPush', data: {} })
-    // Nothing is typed. The listener would otherwise hold the event loop open
-    // and the process would never exit after the command finished.
-    ended.abort()
-
-    assert.equal(await asked, false, 'an abandoned prompt is a refusal')
-    assert.equal(io.input.listenerCount('data'), 0, 'the listener is released')
-  })
-})

package/src/wirings/cli/channel/cli-approval.ts

@@ -1,135 +0,0 @@
-import type { ApprovalRequester } from '../../channel/channel-rpc.js'
-
-/**
- * - `prompt`   — ask about anything not classified `needsApproval: false`.
- * - `auto`     — run the classified-safe set, refuse the rest without asking.
- * - `dangerous`— run everything.
- */
-export type ApprovalMode = 'prompt' | 'auto' | 'dangerous'
-
-export const APPROVAL_FLAGS = {
-  auto: '--auto-approve',
-  dangerous: '--dangerously-auto-approve',
-} as const
-
-/**
- * Stripped from argv, not just read: the server owns the command tree and has
- * never heard of these, and a flag the server can see is one it could act on.
- */
-export const takeApprovalFlags = (
-  args: string[],
-  env: Record<string, string | undefined> = process.env
-): { mode: ApprovalMode; args: string[] } => {
-  const remaining = args.filter(
-    (arg) => arg !== APPROVAL_FLAGS.auto && arg !== APPROVAL_FLAGS.dangerous
-  )
-
-  const dangerous =
-    args.includes(APPROVAL_FLAGS.dangerous) ||
-    env.PIKKU_DANGEROUSLY_AUTO_APPROVE === '1'
-  const auto =
-    args.includes(APPROVAL_FLAGS.auto) || env.PIKKU_AUTO_APPROVE === '1'
-
-  return {
-    mode: dangerous ? 'dangerous' : auto ? 'auto' : 'prompt',
-    args: remaining,
-  }
-}
-
-/**
- * `a` is scoped to the one capability and to this run: widening it to every
- * capability would quietly turn an interactive run into
- * `--dangerously-auto-approve`, and persisting it would outlive anyone's memory
- * of agreeing.
- */
-export const createTerminalApprover = ({
-  input = process.stdin,
-  output = process.stderr,
-  signal,
-}: {
-  input?: NodeJS.ReadStream
-  output?: NodeJS.WritableStream
-  /** Aborted when the run ends, so a prompt nobody can answer stops waiting. */
-  signal?: AbortSignal
-} = {}): ApprovalRequester => {
-  const allowed = new Set<string>()
-
-  const ask: ApprovalRequester = async ({ funcName, description }) => {
-    if (allowed.has(funcName) || signal?.aborted) {
-      return allowed.has(funcName)
-    }
-
-    // stderr, so a command whose stdout is piped still shows the prompt rather
-    // than corrupting the stream it is asking about.
-    output.write(
-      `\nThe server is asking to run "${funcName}" on this machine.\n` +
-        (description ? `  ${description}\n` : '') +
-        `Allow? [y]es / [n]o / [a]lways for "${funcName}": `
-    )
-
-    const answer = await new Promise<string>((resolve) => {
-      const done = (value: string) => {
-        input.off('data', onData)
-        signal?.removeEventListener('abort', onAbort)
-        // Reading resumed stdin, which holds the event loop open.
-        input.pause?.()
-        resolve(value)
-      }
-      const onData = (chunk: Buffer | string) =>
-        done(String(chunk).trim().toLowerCase())
-      // An aborted prompt is a refusal: its command is already over.
-      const onAbort = () => done('n')
-
-      input.on('data', onData)
-      signal?.addEventListener('abort', onAbort, { once: true })
-    })
-
-    if (answer === 'a' || answer === 'always') {
-      allowed.add(funcName)
-      return true
-    }
-    return answer === 'y' || answer === 'yes'
-  }
-
-  // Requests are dispatched without awaiting, so two can be in flight at once.
-  // Unserialized, both prompts print interleaved and the first keystroke
-  // answers both — approving something the user never read.
-  let queue: Promise<unknown> = Promise.resolve()
-  return (request) => {
-    const answered = queue.then(() => ask(request))
-    queue = answered.catch(() => {})
-    return answered
-  }
-}
-
-/**
- * Undefined reads as "nobody to ask", which refuses rather than runs. That is
- * what a non-interactive run gets: CI is exactly where an unattended push would
- * otherwise happen.
- */
-export const approverForMode = (
-  mode: ApprovalMode,
-  {
-    isTTY = process.stdin.isTTY,
-    warn = console.error,
-    signal,
-  }: {
-    isTTY?: boolean
-    warn?: (message: string) => void
-    signal?: AbortSignal
-  } = {}
-): ApprovalRequester | undefined => {
-  if (mode === 'dangerous') {
-    // Once, on stderr, so the log of a run that went wrong records it.
-    warn(
-      `${APPROVAL_FLAGS.dangerous}: every capability this client exposes will run without asking.`
-    )
-    return () => true
-  }
-
-  if (mode === 'auto' || !isTTY) {
-    return undefined
-  }
-
-  return createTerminalApprover({ signal })
-}

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

@@ -1,118 +0,0 @@
-import { pikkuState } from '../../../pikku-state.js'
-import type { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
-import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
-
-// knowledge: decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md
-const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
-  console.log(JSON.stringify(data))
-}
-
-export async function executeCLIViaChannel({
-  programName,
-  pikkuWS,
-  args = process.argv.slice(2),
-  renderers = {},
-  defaultRenderer,
-}: {
-  programName: string
-  pikkuWS: any // a CorePikkuWebsocket
-  args?: string[]
-  renderers?: Record<string, CorePikkuCLIRender<any>>
-  defaultRenderer?: CorePikkuCLIRender<any>
-}): Promise<void> {
-  const cliMeta = pikkuState(null, 'cli', 'meta')
-  if (!cliMeta || !('programs' in cliMeta)) {
-    throw new Error(
-      '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.'
-    )
-  }
-  const allCLIMeta = cliMeta as CLIMeta
-  const programMeta = allCLIMeta.programs[programName]
-
-  if (!programMeta) {
-    console.error(`Error: CLI program "${programName}" not found`)
-    process.exit(1)
-  }
-
-  const parsed = parseCLIArguments(args, programName, allCLIMeta)
-
-  // Parsed first so that `<command> --help` resolves to that command's help.
-  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
-    const helpText = generateCommandHelp(
-      programName,
-      allCLIMeta,
-      parsed.commandPath
-    )
-    console.log(helpText)
-    return
-  }
-
-  if (parsed.errors.length > 0) {
-    // knowledge: decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md
-    const hasUnknownCommand = parsed.errors.some(
-      (error) =>
-        error.startsWith('Unknown command:') ||
-        error.startsWith('Command not found:')
-    )
-
-    if (hasUnknownCommand) {
-      const helpText = generateCommandHelp(
-        programName,
-        allCLIMeta,
-        parsed.commandPath
-      )
-      console.log(helpText)
-      process.exit(1)
-    } else {
-      console.error('Errors:')
-      parsed.errors.forEach((error) => console.error(`  ${error}`))
-      process.exit(1)
-    }
-  }
-
-  const data = { ...parsed.positionals, ...parsed.options }
-
-  const commandId = parsed.commandPath.join('.')
-  const renderer =
-    renderers[commandId] || defaultRenderer || defaultJSONRenderer
-
-  return new Promise((resolve, reject) => {
-    const commandRoute = pikkuWS.getRoute('command')
-
-    const responseHandler = (response: any) => {
-      if (
-        response?.action === 'cli-control' &&
-        response?.event === 'complete'
-      ) {
-        commandRoute.unsubscribe(commandId, responseHandler)
-        pikkuWS.ws.close()
-        resolve(undefined)
-        return
-      }
-
-      // A CLI channel response is rendered off-process: there are no services
-      // to hand the renderer, and every CLI renderer ignores the argument.
-      renderer(null as never, response, undefined)
-    }
-
-    commandRoute.subscribe(commandId, responseHandler)
-
-    pikkuWS.ws.addEventListener('close', () => {
-      commandRoute.unsubscribe(commandId, responseHandler)
-      resolve(undefined)
-    })
-
-    pikkuWS.ws.addEventListener('error', (error: any) => {
-      commandRoute.unsubscribe(commandId, responseHandler)
-      reject(error)
-    })
-
-    if (pikkuWS.ws.readyState === 1) {
-      commandRoute.send(commandId, data)
-    } else {
-      pikkuWS.ws.addEventListener('open', () => {
-        commandRoute.send(commandId, data)
-      })
-    }
-  })
-}

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

@@ -1,192 +0,0 @@
-import { test, describe, beforeEach, afterEach } from 'node:test'
-import * as assert from 'node:assert/strict'
-
-import { handleRawCLI } from './cli-raw-channel-runner.js'
-import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
-import { addFunction } from '../../../function/function-runner.js'
-import {
-  ChannelDeploymentService,
-  createChannelRPCResponder,
-  isChannelRPCRequest,
-} from '../../channel/channel-rpc.js'
-
-/**
- * Registers a one-command CLI program whose function body is supplied by the
- * test, standing in for what the inspector would generate.
- */
-const wireTestCLI = (func: (services: any, data: any, wire: any) => any) => {
-  pikkuState(null, 'cli', 'meta', {
-    programs: {
-      fabric: {
-        program: 'fabric',
-        commands: {
-          deploy: {
-            command: 'deploy',
-            pikkuFuncId: 'deployFunc',
-            positionals: [],
-            options: {},
-          },
-        },
-        options: {},
-      },
-    },
-    renderers: {},
-  })
-
-  pikkuState(null, 'cli', 'programs', {
-    fabric: { defaultRenderer: undefined, middleware: [], renderers: {} },
-  })
-
-  pikkuState(null, 'function', 'meta', {
-    deployFunc: {
-      pikkuFuncId: 'deployFunc',
-      inputSchemaName: null,
-      outputSchemaName: null,
-      sessionless: true,
-    },
-  })
-
-  addFunction('deployFunc', { func, auth: false })
-}
-
-describe('handleRawCLI', () => {
-  let singletonServices: any
-
-  beforeEach(() => {
-    resetPikkuState()
-    singletonServices = {
-      logger: {
-        info: () => {},
-        warn: () => {},
-        error: () => {},
-        debug: () => {},
-      },
-    }
-  })
-
-  afterEach(() => resetPikkuState())
-
-  test('streams progressive output to the sink instead of the server stdout', async () => {
-    const streamed: unknown[] = []
-
-    wireTestCLI(async (_services, _data, { cli }: any) => {
-      await cli.channel.send({ phase: 'building' })
-      await cli.channel.send({ phase: 'deploying' })
-      return { url: 'https://example.com' }
-    })
-
-    const result = await handleRawCLI({
-      programName: 'fabric',
-      args: ['deploy'],
-      singletonServices,
-      onOutput: (data) => void streamed.push(data),
-    })
-
-    assert.deepEqual(streamed, [{ phase: 'building' }, { phase: 'deploying' }])
-    assert.deepEqual(result.result, { url: 'https://example.com' })
-    assert.equal(result.exitCode, 0)
-    assert.equal(result.commandId, 'deploy')
-  })
-
-  test('reports a non-zero exit code when the command throws', async () => {
-    wireTestCLI(() => {
-      throw new Error('deploy plan is red')
-    })
-
-    const result = await handleRawCLI({
-      programName: 'fabric',
-      args: ['deploy'],
-      singletonServices,
-    })
-
-    assert.equal(result.exitCode, 1)
-    assert.match(result.error!, /deploy plan is red/)
-  })
-
-  test('masks the raw error message to the client in production', async () => {
-    const prior = process.env.NODE_ENV
-    process.env.NODE_ENV = 'production'
-    try {
-      wireTestCLI(() => {
-        throw new Error('connection to internal-db:5432 failed: bad password')
-      })
-
-      const result = await handleRawCLI({
-        programName: 'fabric',
-        args: ['deploy'],
-        singletonServices,
-      })
-
-      assert.equal(result.exitCode, 1)
-      assert.equal(result.error, 'Command failed')
-      assert.doesNotMatch(result.error!, /internal-db|password/)
-    } finally {
-      if (prior === undefined) delete process.env.NODE_ENV
-      else process.env.NODE_ENV = prior
-    }
-  })
-
-  test('exits 0 on help and 1 on an unknown command', async () => {
-    wireTestCLI(() => ({}))
-
-    const help = await handleRawCLI({
-      programName: 'fabric',
-      args: ['--help'],
-      singletonServices,
-    })
-    assert.equal(help.exitCode, 0)
-    assert.ok(help.help)
-
-    const unknown = await handleRawCLI({
-      programName: 'fabric',
-      args: ['not-a-command'],
-      singletonServices,
-    })
-    assert.equal(unknown.exitCode, 1)
-  })
-
-  test('a server-side command can call back into the client mid-run', async () => {
-    const streamed: unknown[] = []
-
-    // The "client": answers capability requests off the same socket. Reading a
-    // git sha takes no arguments and changes nothing, so it is classified safe
-    // and runs without anyone being asked.
-    const respond = createChannelRPCResponder({
-      capabilities: {
-        gitHead: {
-          execute: async () => ({ sha: 'deadbeef' }),
-          needsApproval: false,
-        },
-      },
-      send: (data) => deployment.handleResponse(data),
-    })
-
-    const deployment = new ChannelDeploymentService((data) => {
-      if (isChannelRPCRequest(data)) {
-        void respond(data)
-      }
-    })
-
-    singletonServices.deploymentService = deployment
-
-    wireTestCLI(async (_services, _data, { cli, rpc }: any) => {
-      const { sha } = (await rpc.remote('gitHead', {})) as { sha: string }
-      await cli.channel.send({ phase: `resolved ${sha}` })
-      return { deployed: sha }
-    })
-
-    const result = await handleRawCLI({
-      programName: 'fabric',
-      args: ['deploy'],
-      singletonServices,
-      onOutput: (data) => void streamed.push(data),
-    })
-
-    assert.equal(result.exitCode, 0, result.error)
-    // `onOutput` carries progressive output only. The result is returned to
-    // the caller, which owns how it is delivered — emitting it here too would
-    // send it to the client twice.
-    assert.deepEqual(streamed, [{ phase: 'resolved deadbeef' }])
-    assert.deepEqual(result.result, { deployed: 'deadbeef' })
-  })
-})