@pikku/core 0.12.106 → 0.12.111

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

@@ -1,148 +0,0 @@
-import { pikkuState } from '../../../pikku-state.js'
-import { isProduction } from '../../../env.js'
-import type { CLIMeta } from '../cli.types.js'
-import { parseCLIArguments, generateCommandHelp } from '../command-parser.js'
-import { runCLICommand } from '../cli-runner.js'
-import type {
-  CoreSingletonServices,
-  CoreUserSession,
-  CreateWireServices,
-} from '../../../types/core.types.js'
-import type { PikkuChannel } from '../../channel/channel.types.js'
-
-/**
- * A frame sent from the server to a raw CLI client. `output` carries command
- * data to render; `complete` terminates the command and carries the exit code
- * so the client process can exit non-zero on failure.
- */
-export type RawCLIFrame =
-  | { action: 'cli-output'; commandId?: string; data: unknown }
-  | { action: 'cli-result'; commandId?: string; result: unknown }
-  | { action: 'cli-help'; help: string }
-  | { action: 'cli-error'; error: string }
-  | { action: 'cli-control'; event: 'complete'; exitCode: number }
-
-export interface RawCLIResult {
-  help?: string
-  result?: unknown
-  error?: string
-  /** 0 on success, 1 on any parse or execution failure. */
-  exitCode: number
-  /** The command the server resolved, so a client can pick a renderer. */
-  commandId?: string
-}
-
-/**
- * The client sends argv untouched and this side owns parsing, so the command
- * tree lives with the server and a client binary never needs to know it.
- */
-export async function handleRawCLI({
-  programName,
-  args,
-  singletonServices,
-  createWireServices,
-  onOutput,
-  session,
-  transport,
-}: {
-  programName: string
-  args: string[]
-  singletonServices: CoreSingletonServices
-  createWireServices?: CreateWireServices
-  /** Established during the upgrade; commands run as that user. */
-  session?: CoreUserSession
-  onOutput?: (data: unknown, commandId: string) => Promise<void> | void
-  /**
-   * The channel the command arrived on, so `channel.remote(...)` reaches the
-   * calling client rather than being refused as a one-way stream.
-   */
-  transport?: PikkuChannel<unknown, any, any>
-}): Promise<RawCLIResult> {
-  const allCLIMeta = pikkuState(null, 'cli', 'meta') as CLIMeta | undefined
-  if (!allCLIMeta) {
-    return { error: 'CLI metadata not found', exitCode: 1 }
-  }
-
-  const programMeta = allCLIMeta.programs[programName]
-  if (!programMeta) {
-    return { error: `Program "${programName}" not found`, exitCode: 1 }
-  }
-
-  if (
-    args.length === 0 ||
-    args.includes('--help') ||
-    args.includes('-h') ||
-    args[0] === 'help'
-  ) {
-    const helpArgs = args.filter(
-      (a) => a !== 'help' && a !== '--help' && a !== '-h'
-    )
-    const helpText = generateCommandHelp(programName, allCLIMeta, helpArgs)
-    return { help: helpText, exitCode: 0 }
-  }
-
-  const parsed = parseCLIArguments(args, programName, allCLIMeta)
-
-  if (parsed.errors.length > 0 || parsed.commandPath.length === 0) {
-    const helpText = generateCommandHelp(
-      programName,
-      allCLIMeta,
-      parsed.commandPath
-    )
-    // Help says what is available, not what they got wrong — so the parser's
-    // reason rides alongside it.
-    return {
-      help: helpText,
-      error: parsed.errors.length > 0 ? parsed.errors.join('\n') : undefined,
-      exitCode: 1,
-    }
-  }
-
-  let current:
-    { pikkuFuncId?: string; subcommands?: Record<string, any> } | undefined =
-    programMeta.commands[parsed.commandPath[0]]
-  for (let i = 1; i < parsed.commandPath.length; i++) {
-    current = current?.subcommands?.[parsed.commandPath[i]]
-  }
-  if (!current?.pikkuFuncId) {
-    const helpText = generateCommandHelp(
-      programName,
-      allCLIMeta,
-      parsed.commandPath
-    )
-    return { help: helpText, exitCode: 0 }
-  }
-
-  const data = { ...parsed.positionals, ...parsed.options }
-  const commandId = parsed.commandPath.join('.')
-
-  try {
-    const result = await runCLICommand({
-      program: programName,
-      commandPath: parsed.commandPath,
-      data,
-      singletonServices,
-      createWireServices,
-      session,
-      // Not known until parsing finishes here, so it is supplied per-frame.
-      onOutput: onOutput && ((data) => onOutput(data, commandId)),
-      transport,
-    })
-    return { result, exitCode: 0, commandId }
-  } catch (e: unknown) {
-    // A command can throw anything; `.message` off a string is undefined, and
-    // the run would then exit 1 saying nothing at all.
-    const message = e instanceof Error ? e.message : String(e)
-    // The raw message can carry internals (a stack, a DB error, a path). This
-    // runs over a channel that may be remote, so return a generic error in
-    // production and keep the detail server-side. Dev keeps the message inline.
-    singletonServices.logger.error?.(
-      `CLI channel command failed: ${message}`,
-      e
-    )
-    const clientError = isProduction()
-      ? 'Command failed'
-      : message || 'Command failed'
-    return { error: clientError, exitCode: 1, commandId }
-  }
-}

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

@@ -1,480 +0,0 @@
-import { describe, test } from 'node:test'
-import * as assert from 'node:assert/strict'
-
-import { executeRawCLIViaChannel } from './cli-raw-client-runner.js'
-import {
-  CHANNEL_RPC_PENDING,
-  CHANNEL_RPC_REQUEST,
-  CHANNEL_RPC_RESPONSE,
-} from '../../channel/channel-rpc.js'
-
-/**
- * The client half of the transport, stubbed at the surface
- * `executeRawCLIViaChannel` actually uses: a route to send on, a subscription
- * for incoming frames, and the socket's own open/close/error events.
- */
-const fakeWS = ({ readyState = 1 }: { readyState?: number } = {}) => {
-  const sent: Array<{ method: string; data: unknown }> = []
-  const rawSent: unknown[] = []
-  const subscribers = new Set<(message: any) => void>()
-  const listeners = new Map<string, Array<(event: any) => void>>()
-  let closed = false
-
-  const pikkuWS = {
-    getRoute: () => ({
-      send: (method: string, data: unknown) => {
-        sent.push({ method, data })
-      },
-    }),
-    subscribe: (handler: (message: any) => void) => subscribers.add(handler),
-    unsubscribe: (handler: (message: any) => void) =>
-      subscribers.delete(handler),
-    ws: {
-      readyState,
-      // Reverse-RPC answers go straight out on the socket rather than on a
-      // command route — the server takes them off before routing.
-      send: (data: string) => {
-        rawSent.push(JSON.parse(data))
-      },
-      close: () => {
-        closed = true
-      },
-      addEventListener: (event: string, listener: (event: any) => void) => {
-        const existing = listeners.get(event) ?? []
-        existing.push(listener)
-        listeners.set(event, existing)
-      },
-    },
-  }
-
-  return {
-    pikkuWS,
-    sent,
-    rawSent,
-    isClosed: () => closed,
-    /** Delivers a frame the way the runtime's message dispatch would. */
-    receive: (message: unknown) => {
-      // Copied first: a handler unsubscribes itself when the command completes.
-      const current = Array.from(subscribers)
-      for (const subscriber of current) {
-        subscriber(message)
-      }
-    },
-    emit: (event: string, payload?: unknown) => {
-      for (const listener of listeners.get(event) ?? []) {
-        listener(payload)
-      }
-    },
-  }
-}
-
-/** Captures what the runner would have written to the terminal. */
-const captureConsole = () => {
-  const out: string[] = []
-  const err: string[] = []
-  const log = console.log
-  const error = console.error
-  console.log = (...args: unknown[]) => out.push(args.join(' '))
-  console.error = (...args: unknown[]) => err.push(args.join(' '))
-  return {
-    out,
-    err,
-    restore: () => {
-      console.log = log
-      console.error = error
-    },
-  }
-}
-
-describe('executeRawCLIViaChannel', () => {
-  test('forwards argv untouched — the client never parses it', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['deploy', '--stage', 'prod', '--force'],
-    })
-    ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-    await run
-    console.restore()
-
-    assert.deepEqual(ws.sent, [
-      {
-        method: '__raw',
-        data: { args: ['deploy', '--stage', 'prod', '--force'] },
-      },
-    ])
-  })
-
-  test('waits for the socket to open before sending', async () => {
-    const ws = fakeWS({ readyState: 0 })
-    const console = captureConsole()
-
-    // The capture replaces the process-global console, so a throwing assertion
-    // between here and the restore would leave it replaced for every test
-    // after this one — including their own idea of what the original was.
-    try {
-      const run = executeRawCLIViaChannel({
-        pikkuWS: ws.pikkuWS,
-        args: ['ping'],
-      })
-      assert.deepEqual(
-        ws.sent,
-        [],
-        'nothing may be written before the open event'
-      )
-
-      ws.emit('open')
-      assert.equal(ws.sent.length, 1)
-
-      ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-      await run
-    } finally {
-      console.restore()
-    }
-  })
-
-  test('renders output with the renderer for the command the server reports', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-    const rendered: unknown[] = []
-
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['deploy'],
-      renderers: {
-        deploy: (_services, data) => rendered.push(data),
-      },
-    })
-    ws.receive({
-      action: 'cli-output',
-      commandId: 'deploy',
-      data: { phase: 'building' },
-    })
-    ws.receive({
-      action: 'cli-result',
-      commandId: 'deploy',
-      result: { url: 'https://example.com' },
-    })
-    ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-    await run
-    console.restore()
-
-    assert.deepEqual(rendered, [
-      { phase: 'building' },
-      { url: 'https://example.com' },
-    ])
-    assert.deepEqual(console.out, [], 'a matched renderer owns the output')
-  })
-
-  test('falls back to JSON for a command the client does not know', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    // The normal case once the server owns the command tree: a client built
-    // before this command existed must still print something usable.
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['stage', 'describe'],
-      renderers: { deploy: () => assert.fail('wrong renderer') },
-    })
-    ws.receive({
-      action: 'cli-output',
-      commandId: 'stage.describe',
-      data: { name: 'prod' },
-    })
-    ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-    await run
-    console.restore()
-
-    assert.deepEqual(console.out, ['{"name":"prod"}'])
-  })
-
-  test('help goes to stdout and errors to stderr', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    const run = executeRawCLIViaChannel({ pikkuWS: ws.pikkuWS, args: ['nope'] })
-    ws.receive({ action: 'cli-help', help: 'Usage: release <command>' })
-    ws.receive({ action: 'cli-error', error: 'Unknown command "nope"' })
-    ws.receive({ action: 'cli-control', event: 'complete', exitCode: 1 })
-    const exitCode = await run
-    console.restore()
-
-    assert.equal(exitCode, 1)
-    assert.deepEqual(console.out, ['Usage: release <command>'])
-    assert.deepEqual(console.err, ['Unknown command "nope"'])
-  })
-
-  test('answers a capability the server calls back for', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-    const rendered: unknown[] = []
-
-    try {
-      const run = executeRawCLIViaChannel({
-        pikkuWS: ws.pikkuWS,
-        args: ['deploy'],
-        defaultRenderer: (_services, data) => rendered.push(data),
-        capabilities: {
-          localCheckout: {
-            execute: () => ({ sha: 'deadbeef', branch: 'main' }),
-            needsApproval: false,
-          },
-        },
-      })
-      ws.receive({
-        action: CHANNEL_RPC_REQUEST,
-        id: '1',
-        funcName: 'localCheckout',
-        data: {},
-      })
-
-      // Answering is async, so let the responder settle before asserting.
-      await new Promise((resolve) => setImmediate(resolve))
-
-      assert.deepEqual(ws.rawSent[0], {
-        action: CHANNEL_RPC_RESPONSE,
-        id: '1',
-        ok: true,
-        result: { sha: 'deadbeef', branch: 'main' },
-      })
-      assert.equal(
-        ws.sent.length,
-        1,
-        'the answer does not go out on a command route'
-      )
-      assert.deepEqual(rendered, [], 'an RPC request is not command output')
-
-      ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-      await run
-    } finally {
-      console.restore()
-    }
-  })
-
-  test('an unclassified capability is put to the user before it runs', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-    const asked: unknown[] = []
-    let ran = false
-
-    try {
-      const run = executeRawCLIViaChannel({
-        pikkuWS: ws.pikkuWS,
-        args: ['publish'],
-        // A bare function: nobody classified it. The map says this *can* run;
-        // approval is what says this particular call *should*.
-        capabilities: {
-          localPush: () => {
-            ran = true
-            return 'pushed'
-          },
-        },
-        approve: (request) => {
-          asked.push(request)
-          return true
-        },
-      })
-      ws.receive({
-        action: CHANNEL_RPC_REQUEST,
-        id: '1',
-        funcName: 'localPush',
-        data: { tag: 'v2' },
-      })
-      await new Promise((resolve) => setImmediate(resolve))
-
-      assert.equal(asked.length, 1, 'the user was asked exactly once')
-      assert.equal(ran, true)
-
-      // The hold goes out first. The server's timer knows nothing about how
-      // long a person takes, and an answer arriving past it would be dropped.
-      assert.equal((ws.rawSent[0] as any).action, CHANNEL_RPC_PENDING)
-      assert.equal((ws.rawSent[1] as any).result, 'pushed')
-
-      ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-      await run
-    } finally {
-      console.restore()
-    }
-  })
-
-  test('with nobody to ask, an unclassified capability is refused', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-    let ran = false
-
-    try {
-      // No `approve` and no terminal — a non-interactive run. Refusing is the
-      // point: CI is where an unattended push would otherwise happen.
-      const run = executeRawCLIViaChannel({
-        pikkuWS: ws.pikkuWS,
-        args: ['publish', '--auto-approve'],
-        capabilities: {
-          localPush: () => {
-            ran = true
-            return 'pushed'
-          },
-          gitHead: { execute: () => ({ sha: 'abc' }), needsApproval: false },
-        },
-      })
-      ws.receive({
-        action: CHANNEL_RPC_REQUEST,
-        id: '1',
-        funcName: 'localPush',
-        data: {},
-      })
-      ws.receive({
-        action: CHANNEL_RPC_REQUEST,
-        id: '2',
-        funcName: 'gitHead',
-        data: {},
-      })
-      await new Promise((resolve) => setImmediate(resolve))
-
-      assert.equal(ran, false, 'the unclassified capability did not run')
-      assert.equal((ws.rawSent[0] as any).error.name, 'RPCNotApprovedError')
-      // ...while the classified-safe one is exactly what --auto-approve is for.
-      assert.deepEqual((ws.rawSent[1] as any).result, { sha: 'abc' })
-
-      // The flag is the client's business and never reaches the server.
-      assert.deepEqual(ws.sent[0]?.data, { args: ['publish'] })
-
-      ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-      await run
-    } finally {
-      console.restore()
-    }
-  })
-
-  test('refuses a capability outside the declared map', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    try {
-      const run = executeRawCLIViaChannel({
-        pikkuWS: ws.pikkuWS,
-        args: ['deploy'],
-        capabilities: { localCheckout: () => ({}) },
-      })
-      ws.receive({
-        action: CHANNEL_RPC_REQUEST,
-        id: '1',
-        funcName: 'readSSHKey',
-        data: {},
-      })
-      // `toString` is not in the map, but a map is an object and inherits one.
-      // Refusing it is the same refusal as for a name nobody has heard of.
-      ws.receive({
-        action: CHANNEL_RPC_REQUEST,
-        id: '2',
-        funcName: 'toString',
-        data: {},
-      })
-      await new Promise((resolve) => setImmediate(resolve))
-
-      for (const sent of ws.rawSent) {
-        const response = sent as { ok: boolean; error: { name: string } }
-        assert.equal(response.ok, false)
-        assert.equal(response.error.name, 'RPCNotFoundError')
-      }
-      assert.equal(ws.rawSent.length, 2)
-
-      ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-      await run
-    } finally {
-      console.restore()
-    }
-  })
-
-  test('ignores frames that are not part of the CLI protocol', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['deploy'],
-    })
-    // The runtime's own routing echo, and anything else sharing the socket:
-    // rendering these would print noise between a command's real output.
-    ws.receive({ action: 'unrelated' })
-    ws.receive('a bare string')
-    ws.receive(null)
-    ws.receive({ command: '__raw' })
-    ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-    await run
-    console.restore()
-
-    assert.deepEqual(console.out, [])
-    assert.deepEqual(console.err, [])
-  })
-
-  test('a socket that closes before completing is a failed run', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['deploy'],
-    })
-    // A rejected upgrade or a connection dropped mid-command: the command did
-    // not finish, and reporting 0 would let a caller treat a connection
-    // failure as a successful run.
-    ws.emit('close')
-    const exitCode = await run
-    console.restore()
-
-    assert.equal(exitCode, 1)
-  })
-
-  test('a transport error is reported like a failed command', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['deploy'],
-    })
-    ws.emit('error', { message: 'ECONNRESET' })
-    const exitCode = await run
-    console.restore()
-
-    assert.equal(exitCode, 1)
-    assert.deepEqual(console.err, ['ECONNRESET'])
-  })
-
-  test('a close after completing does not overwrite the exit code', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['deploy'],
-    })
-    ws.receive({ action: 'cli-control', event: 'complete', exitCode: 0 })
-    // The runner closes the socket itself on completion, so this always
-    // follows a successful run.
-    ws.emit('close')
-    const exitCode = await run
-    console.restore()
-
-    assert.equal(exitCode, 0)
-    assert.equal(ws.isClosed(), true)
-  })
-
-  test('a complete with no exit code is a success', async () => {
-    const ws = fakeWS()
-    const console = captureConsole()
-
-    const run = executeRawCLIViaChannel({
-      pikkuWS: ws.pikkuWS,
-      args: ['deploy'],
-    })
-    ws.receive({ action: 'cli-control', event: 'complete' })
-    const exitCode = await run
-    console.restore()
-
-    assert.equal(exitCode, 0)
-  })
-})