@pikku/core 0.12.72 → 0.12.74

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

@@ -0,0 +1,480 @@
+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)
+  })
+})

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

@@ -0,0 +1,155 @@
+import {
+  createChannelRPCResponder,
+  isChannelRPCRequest,
+} from '../../channel/channel-rpc.js'
+import type {
+  ApprovalRequester,
+  Capabilities,
+} from '../../channel/channel-rpc.js'
+import { approverForMode, takeApprovalFlags } from './cli-approval.js'
+import type { CorePikkuCLIRender } from '../cli.types.js'
+
+/** The normal case once the server owns the command tree. */
+const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
+  console.log(JSON.stringify(data))
+}
+
+/**
+ * The command ran on the server, so there are no services here — but a renderer
+ * written for local execution can still reach for `services.logger`.
+ */
+const clientServices = { logger: console } as any
+
+/**
+ * Runs a CLI command entirely on the server. Unlike `executeCLIViaChannel`,
+ * argv is forwarded untouched and never parsed here, so the client carries no
+ * command metadata and its version may drift from the server's.
+ *
+ * `capabilities` are the functions this client agrees to run on the server's
+ * behalf: the map says what *can* run, and approval whether a call *should*.
+ * `approve` overrides the mode otherwise read from argv and from whether there
+ * is a terminal to ask at.
+ */
+export async function executeRawCLIViaChannel({
+  pikkuWS,
+  args = process.argv.slice(2),
+  renderers = {},
+  defaultRenderer,
+  capabilities = {},
+  approve,
+}: {
+  pikkuWS: any // CorePikkuWebsocket instance
+  args?: string[]
+  renderers?: Record<string, CorePikkuCLIRender<any>>
+  defaultRenderer?: CorePikkuCLIRender<any>
+  capabilities?: Capabilities
+  approve?: ApprovalRequester
+}): Promise<number> {
+  // Stripped before argv goes to the server: a flag the server can see is one
+  // the server could act on.
+  const { mode, args: commandArgs } = takeApprovalFlags(args)
+  // Aborted when the run ends, so a prompt still on stdin stops holding the
+  // event loop open.
+  const runEnded = new AbortController()
+  const approver = approve ?? approverForMode(mode, { signal: runEnded.signal })
+
+  const render = (commandId: string | undefined, data: unknown) => {
+    const renderer =
+      (commandId ? renderers[commandId] : undefined) ||
+      defaultRenderer ||
+      defaultJSONRenderer
+    renderer(clientServices, data, undefined)
+  }
+
+  return new Promise<number>((resolve) => {
+    const commandRoute = pikkuWS.getRoute('command')
+
+    let settled = false
+
+    // Plain frames, not a command route: the server takes these off the socket
+    // before routing.
+    const respond = createChannelRPCResponder({
+      capabilities,
+      approve: approver,
+      send: (data) => {
+        // A capability can still be resolving when the run settles. `respond`
+        // is dispatched without a handler, so a throw here would surface as an
+        // unhandled rejection — and by then the answer is moot.
+        if (settled || pikkuWS.ws.readyState !== 1) {
+          return
+        }
+        pikkuWS.ws.send(JSON.stringify(data))
+      },
+    })
+
+    const finish = (code: number) => {
+      if (settled) {
+        return
+      }
+      settled = true
+      runEnded.abort()
+      pikkuWS.unsubscribe(handler)
+      try {
+        pikkuWS.ws.close()
+      } catch {
+        // Already closing — the exit code is what matters.
+      }
+      resolve(code)
+    }
+
+    // Every frame, not a command id: the server owns the command tree, and
+    // progressive `channel.send` frames carry no routing key at all.
+    const handler = (message: any) => {
+      // Classified synchronously so a request never also reaches the renderer.
+      // Answering is deliberately not awaited, so a slow capability cannot
+      // stall the output stream behind it.
+      if (isChannelRPCRequest(message)) {
+        void respond(message)
+        return
+      }
+
+      // Only declared shapes: the channel also carries the runtime's routing
+      // echo, and rendering that would print noise between real output.
+      switch (message?.action) {
+        case 'cli-output':
+          render(message.commandId, message.data)
+          break
+        case 'cli-result':
+          render(message.commandId, message.result)
+          break
+        case 'cli-help':
+          console.log(message.help)
+          break
+        case 'cli-error':
+          console.error(message.error)
+          break
+        case 'cli-control':
+          if (message.event === 'complete') {
+            finish(message.exitCode ?? 0)
+          }
+          break
+      }
+    }
+
+    pikkuWS.subscribe(handler)
+
+    // Only the server's `complete` frame reports success: a socket that closes
+    // before one means the command did not finish.
+    pikkuWS.ws.addEventListener('close', () => finish(1))
+    // A transport failure exits like a failed command rather than rejecting —
+    // to a CLI user both are simply a run that did not work.
+    pikkuWS.ws.addEventListener('error', (error: any) => {
+      if (!settled) {
+        console.error(error?.message ?? String(error))
+        finish(1)
+      }
+    })
+
+    const sendCommand = () => commandRoute.send('__raw', { args: commandArgs })
+    if (pikkuWS.ws.readyState === 1) {
+      sendCommand()
+    } else {
+      pikkuWS.ws.addEventListener('open', sendCommand)
+    }
+  })
+}

package/src/wirings/cli/channel/index.ts

@@ -1,2 +1,11 @@
 export { executeCLIViaChannel } from './cli-channel-runner.js'
 export { handleRawCLI } from './cli-raw-channel-runner.js'
+export type { RawCLIFrame, RawCLIResult } from './cli-raw-channel-runner.js'
+export { executeRawCLIViaChannel } from './cli-raw-client-runner.js'
+export {
+  APPROVAL_FLAGS,
+  approverForMode,
+  createTerminalApprover,
+  takeApprovalFlags,
+} from './cli-approval.js'
+export type { ApprovalMode } from './cli-approval.js'

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

@@ -96,7 +96,6 @@ describe('CLI Runner', () => {
         return { success: true }
       }
 
-      // Setup metadata
       pikkuState(null, 'cli', 'meta', {
         programs: {
           'test-cli': {