@pikku/core 0.12.72 → 0.12.77

package/src/wirings/channel/pikku-abstract-channel-handler.test.ts

@@ -1,14 +1,20 @@
-import { test, beforeEach } from 'node:test'
+import { test, beforeEach, describe } from 'node:test'
 import * as assert from 'node:assert/strict'
 import { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
+import { setSingletonServices } from '../../pikku-state.js'
+import { CHANNEL_RPC_RESPONSE } from './channel-rpc.js'
+import type { ChannelRPCError } from './channel-rpc.js'
+import { handleChannelRPCResponse } from './channel-host-rpc.js'
 
 // A concrete implementation of the abstract class for testing
 class TestChannelHandler extends PikkuAbstractChannelHandler<
   { param: string },
   { msg: string }
 > {
+  public sent: unknown[] = []
+
   public async send(message: { msg: string }, isBinary = false): Promise<void> {
-    // Mock send implementation
+    this.sent.push(message)
   }
 
   public sendBinary(_data: ArrayBuffer | Uint8Array): void {}
@@ -16,6 +22,12 @@ class TestChannelHandler extends PikkuAbstractChannelHandler<
 
 let handler: TestChannelHandler
 
+/**
+ * Arguments are checked before the request goes out, so the write lands a tick
+ * after the call rather than in the same one.
+ */
+const sent = () => new Promise((resolve) => setImmediate(resolve))
+
 beforeEach(() => {
   handler = new TestChannelHandler('test-channel-id', 'channel-name', {
     param: 'testParam',
@@ -52,3 +64,72 @@ test('close should change channel state to closed', () => {
     'State should be "closed" after calling close()'
   )
 })
+
+/**
+ * Every channel gets `remote` — reverse RPC is a property of having an open
+ * connection, not of any one wiring having asked for it.
+ */
+describe('channel.remote', () => {
+  beforeEach(() => {
+    // The transport builds a result validator from the singletons. Nothing
+    // here declares an RPC contract, so validation finds no schema and passes.
+    setSingletonServices({ logger: console } as never)
+  })
+
+  test('writes a request to the peer and resolves when it answers', async () => {
+    const channel = handler.getChannel()
+    const call = channel.remote('localCheckout', { cwd: '/repo' })
+    await sent()
+
+    const request = handler.sent[0] as {
+      action: string
+      id: string
+      funcName: string
+      data: unknown
+    }
+    assert.equal(request.funcName, 'localCheckout')
+    assert.deepEqual(request.data, { cwd: '/repo' })
+
+    handleChannelRPCResponse(channel.channelId, {
+      action: CHANNEL_RPC_RESPONSE,
+      id: request.id,
+      ok: true,
+      result: { sha: 'deadbeef' },
+    })
+
+    assert.deepEqual(await call, { sha: 'deadbeef' })
+    handler.close()
+  })
+
+  test('a closing channel fails what the peer still owed an answer to', async () => {
+    const channel = handler.getChannel()
+    const call = channel.remote('localCheckout')
+
+    handler.close()
+
+    await assert.rejects(call, (e: ChannelRPCError) => {
+      assert.equal(e.reason, 'closed')
+      return true
+    })
+  })
+
+  test('a second connection does not inherit the first transport', async () => {
+    const first = handler.getChannel()
+    const call = first.remote('localCheckout')
+    handler.close()
+    await assert.rejects(call)
+
+    const reconnected = new TestChannelHandler(
+      'test-channel-id',
+      'channel-name',
+      { param: 'testParam' }
+    )
+    const second = reconnected.getChannel().remote('localCheckout')
+    await sent()
+    // Ids restart, which is only safe because the closed transport was
+    // forgotten rather than reused.
+    assert.equal((reconnected.sent[0] as { id: string }).id, '1')
+    reconnected.close()
+    await assert.rejects(second)
+  })
+})

package/src/wirings/channel/pikku-abstract-channel-handler.ts

@@ -3,6 +3,7 @@ import type {
   PikkuChannel,
   PikkuChannelHandler,
 } from './channel.types.js'
+import { channelRemote, releaseChannelHostRPC } from './channel-host-rpc.js'
 
 export abstract class PikkuAbstractChannelHandler<
   OpeningData = unknown,
@@ -37,6 +38,8 @@ export abstract class PikkuAbstractChannelHandler<
         clearState: () => {
           channelState = undefined
         },
+        remote: (funcName: string, data?: unknown) =>
+          channelRemote(this.getChannel(), funcName, data),
       }
     }
     return this.channel
@@ -48,5 +51,9 @@ export abstract class PikkuAbstractChannelHandler<
 
   public close(): Promise<void> | void {
     this.getChannel().state = 'closed'
+    // Fails anything the departing peer still owed an answer to. Not awaited:
+    // `close` is on every runtime's synchronous path, and nothing here can fail
+    // in a way a closing channel could act on.
+    void releaseChannelHostRPC(this.channelId)
   }
 }

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

@@ -144,10 +144,10 @@ export const runChannelConnect = async ({
         channel,
         data: openingData,
         channelMiddlewareMeta: meta.channelMiddleware,
+        userSession,
       })
     }
 
-    // Store the pikkuUserId mapping after auth middleware has run
     const pikkuUserId = userSession.getPikkuUserId()
     if (pikkuUserId) {
       await channelStore.setPikkuUserId(channelId, pikkuUserId)
@@ -180,10 +180,6 @@ export const runChannelDisconnect = async ({
   const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
 
-  // Try to get channel from store. In serverless environments (especially with
-  // serverless-offline or worker threads), disconnect can be called multiple times
-  // or after the channel has already been cleaned up. If channel doesn't exist,
-  // there's nothing to disconnect, so we can return early.
   let channelData
   try {
     channelData = await channelStore.getChannel(channelId)
@@ -240,6 +236,7 @@ export const runChannelDisconnect = async ({
         services,
         channel,
         channelMiddlewareMeta: meta.channelMiddleware,
+        userSession,
       })
     } catch (e: any) {
       singletonServices.logger.error(

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

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

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

@@ -2,19 +2,11 @@ import { pikkuState } from '../../../pikku-state.js'
 import type { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
 import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
 
-/**
- * Default JSON renderer for CLI output. Emits single-line NDJSON so
- * the output stays machine-parseable when the CLI is run with
- * `--output json`; pretty-printing here would break NDJSON consumers.
- */
+// knowledge: decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md
 const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
   console.log(JSON.stringify(data))
 }
 
-/**
- * Execute a CLI program via WebSocket channel
- * This is the main entry point for CLI-over-Channel clients
- */
 export async function executeCLIViaChannel({
   programName,
   pikkuWS,
@@ -23,12 +15,11 @@ export async function executeCLIViaChannel({
   defaultRenderer,
 }: {
   programName: string
-  pikkuWS: any // CorePikkuWebsocket instance
+  pikkuWS: any // a CorePikkuWebsocket
   args?: string[]
   renderers?: Record<string, CorePikkuCLIRender<any>>
   defaultRenderer?: CorePikkuCLIRender<any>
 }): Promise<void> {
-  // Get CLI metadata from state
   const cliMeta = pikkuState(null, 'cli', 'meta')
   if (!cliMeta || !('programs' in cliMeta)) {
     throw new Error(
@@ -43,10 +34,9 @@ export async function executeCLIViaChannel({
     process.exit(1)
   }
 
-  // Parse arguments for this specific program
   const parsed = parseCLIArguments(args, programName, allCLIMeta)
 
-  // Handle help (check after parsing to support subcommand help)
+  // 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,
@@ -58,7 +48,7 @@ export async function executeCLIViaChannel({
   }
 
   if (parsed.errors.length > 0) {
-    // Check if any error is about an unknown command
+    // knowledge: decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md
     const hasUnknownCommand = parsed.errors.some(
       (error) =>
         error.startsWith('Unknown command:') ||
@@ -66,7 +56,6 @@ export async function executeCLIViaChannel({
     )
 
     if (hasUnknownCommand) {
-      // Show help instead of error for unknown commands
       const helpText = generateCommandHelp(
         programName,
         allCLIMeta,
@@ -75,45 +64,37 @@ export async function executeCLIViaChannel({
       console.log(helpText)
       process.exit(1)
     } else {
-      // Show errors for other types of errors
       console.error('Errors:')
       parsed.errors.forEach((error) => console.error(`  ${error}`))
       process.exit(1)
     }
   }
 
-  // Merge positionals and options into single data object
   const data = { ...parsed.positionals, ...parsed.options }
 
-  // Get the renderer for this command
   const commandId = parsed.commandPath.join('.')
   const renderer =
     renderers[commandId] || defaultRenderer || defaultJSONRenderer
 
   return new Promise((resolve, reject) => {
-    // Subscribe to responses for this command
     const commandRoute = pikkuWS.getRoute('command')
 
     const responseHandler = (response: any) => {
-      // Check if this is a control message
       if (
         response?.action === 'cli-control' &&
         response?.event === 'complete'
       ) {
-        // Server signals command is complete, close the connection client-side
         commandRoute.unsubscribe(commandId, responseHandler)
         pikkuWS.ws.close()
         resolve(undefined)
         return
       }
 
-      // Call renderer for any output
       renderer(null as any, response, undefined)
     }
 
     commandRoute.subscribe(commandId, responseHandler)
 
-    // Handle connection close
     pikkuWS.ws.addEventListener('close', () => {
       commandRoute.unsubscribe(commandId, responseHandler)
       resolve(undefined)
@@ -124,12 +105,9 @@ export async function executeCLIViaChannel({
       reject(error)
     })
 
-    // Send the command once connected
     if (pikkuWS.ws.readyState === 1) {
-      // Already open
       commandRoute.send(commandId, data)
     } else {
-      // Wait for open
       pikkuWS.ws.addEventListener('open', () => {
         commandRoute.send(commandId, data)
       })