dsh-edge 0.1.0

package/scripts/cli.mjs

@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+
+import * as prompt from '@clack/prompts'
+import { realpathSync, writeSync } from 'node:fs'
+import { Writable } from 'node:stream'
+import { fileURLToPath } from 'node:url'
+import edgePackage from '../package.json' with { type: 'json' }
+import {
+  executeWrangler,
+  InstallCancelledError,
+  InstallerOutputError,
+  installEdge,
+} from './install.mjs'
+
+const INTERRUPT_EXIT_CODES = new Map([
+  ['SIGHUP', 129],
+  ['SIGINT', 130],
+  ['SIGTERM', 143],
+])
+const OUTPUT_DRAIN_TIMEOUT_MS = 1_000
+
+export class InstallInterruptedError extends InstallCancelledError {
+  constructor(signal) {
+    super()
+    this.exitCode = INTERRUPT_EXIT_CODES.get(signal)
+    this.signal = signal
+  }
+}
+
+export function parseCommand(args) {
+  if (args.length === 1 && (args[0] === 'install' || args[0] === 'upgrade')) return args[0]
+  if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]))) return 'help'
+  if (args.length === 1 && ['--version', '-v'].includes(args[0])) return 'version'
+  throw new Error('Usage: dsh-edge <install|upgrade>')
+}
+
+export function createInstallerUi(
+  clack = prompt,
+  signal,
+  writeDescriptor = writeSync,
+  output,
+  writeRecovery,
+  command = 'install',
+) {
+  const withOutput = options => output === undefined ? options : { ...options, output }
+  const log = (writer, message) => output === undefined
+    ? writer(message)
+    : writer(message, { output })
+  const note = (message, title) => output === undefined
+    ? clack.note(message, title)
+    : clack.note(message, title, { output })
+  return {
+    intro: message => log(clack.intro, message),
+    step: message => log(clack.log.step, message),
+    async selectRuntime() {
+      return await requireAnswer(await clack.select(withOutput({
+        message: 'Choose a runtime',
+        signal,
+        initialValue: 'direct',
+        options: [
+          {
+            value: 'direct',
+            label: 'Free — Direct Shell',
+            hint: 'recommended; runs on Workers Free',
+          },
+          {
+            value: 'isolated',
+            label: 'Isolated — Dynamic Worker',
+            hint: 'requires Workers Paid (starting at $5/month)',
+          },
+        ],
+      })))
+    },
+    async selectAccount(choices) {
+      return await requireAnswer(await clack.select(withOutput({
+        message: 'Choose a Cloudflare account',
+        options: choices,
+        signal,
+      })))
+    },
+    async workerName(initialValue, validate) {
+      return await requireAnswer(await clack.text(withOutput({
+        message: 'Worker name',
+        initialValue,
+        signal,
+        validate,
+      })))
+    },
+    async workerConflict(workerName) {
+      return await requireAnswer(await clack.select(withOutput({
+        message: `${workerName} already exists`,
+        signal,
+        options: [
+          { value: 'rename', label: 'Choose another name' },
+          { value: 'update', label: 'Update this Worker', hint: 'keeps its Durable Object data' },
+          { value: 'cancel', label: 'Cancel' },
+        ],
+      })))
+    },
+    async selectOwnerSecretMode() {
+      return await requireAnswer(await clack.select(withOutput({
+        message: 'Set the owner access key',
+        initialValue: 'generate',
+        signal,
+        options: [
+          { value: 'generate', label: 'Generate a secure key', hint: 'recommended' },
+          { value: 'custom', label: 'Enter my own key' },
+        ],
+      })))
+    },
+    async ownerSecret(validate) {
+      return await requireAnswer(await clack.password(withOutput({
+        message: 'Owner access key',
+        mask: '•',
+        signal,
+        validate,
+      })))
+    },
+    async deepSeekKey(validate) {
+      return await requireAnswer(await clack.password(withOutput({
+        message: 'DeepSeek API key',
+        mask: '•',
+        signal,
+        validate,
+      })))
+    },
+    async confirm(summary) {
+      note([
+        `Runtime: ${summary.modeLabel}`,
+        `Account: ${summary.accountLabel}`,
+        `Worker: ${summary.workerName}`,
+        `Cost: ${summary.paid ? 'Workers Paid is required' : 'Works on Workers Free'}`,
+        ...(command === 'upgrade' ? ['Existing Durable Object data is preserved.', 'The entered secrets replace the active values.'] : []),
+      ].join('\n'), command === 'upgrade' ? 'Upgrade summary' : 'Installation summary')
+      return await requireAnswer(await clack.confirm(withOutput({
+        message: command === 'upgrade' ? 'Upgrade this instance?' : 'Install this instance?',
+        initialValue: true,
+        signal,
+      })))
+    },
+    async acceptTemporaryTerms() {
+      note([
+        'Cloudflare Terms of Service: https://www.cloudflare.com/terms/',
+        'Cloudflare Privacy Policy: https://www.cloudflare.com/privacypolicy/',
+      ].join('\n'), 'Temporary account terms')
+      return await requireAnswer(await clack.confirm(withOutput({
+        message: 'Accept these terms and create a temporary Cloudflare account?',
+        initialValue: false,
+        signal,
+      })))
+    },
+    cleanupFailure(message) {
+      log(clack.log.warn, message)
+    },
+    recovery(result) {
+      note(recoveryLines(result).join('\n'), 'Worker uploaded — recovery details')
+    },
+    outputFailureRecovery(result, failedStream) {
+      const lines = [
+        '',
+        'Worker uploaded — recovery details',
+        ...recoveryLines(result),
+        '',
+      ]
+      if (writeRecovery !== undefined) {
+        return writeRecovery(failedStream, lines.join('\n'))
+      }
+      return writeAlternate(writeDescriptor, failedStream, lines)
+    },
+    success(result) {
+      const lines = [
+        `URL: ${result.publicUrl}`,
+        `Owner access key: ${result.ownerSecret}`,
+      ]
+      if (result.claimUrl !== undefined) {
+        lines.push(
+          `Claim URL: ${result.claimUrl}`,
+          '',
+          'Next steps:',
+          '1. Claim this temporary account within 60 minutes to keep the Worker and its data.',
+          '2. Open the URL above.',
+          '3. Enter the owner access key when prompted.',
+        )
+      } else {
+        lines.push(
+          '',
+          'Next steps:',
+          '1. Open the URL above.',
+          '2. Enter the owner access key when prompted.',
+        )
+      }
+      note(lines.join('\n'), command === 'upgrade' ? 'Worker upgraded' : 'Worker uploaded')
+      log(clack.outro, command === 'upgrade' ? 'Upgrade handoff complete.' : 'Installation handoff complete.')
+    },
+  }
+}
+
+function recoveryLines(result) {
+  const lines = [
+    `Worker: ${result.workerName}`,
+    `Active owner access key: ${result.ownerSecret}`,
+  ]
+  if (result.publicUrl !== undefined) lines.unshift(`URL: ${result.publicUrl}`)
+  if (result.claimUrl !== undefined) lines.push(`Claim URL: ${result.claimUrl}`)
+  lines.push('Save this key. Wrangler reported a successful upload, but the installer could not complete its handoff.')
+  return lines
+}
+
+function writeAlternate(writeDescriptor, failedStream, lines) {
+  const descriptor = failedStream === 'stdout' ? 2 : 1
+  try {
+    writeDescriptor(descriptor, lines.join('\n'))
+    return true
+  } catch {
+    // The alternate process stream is unavailable too; credential cleanup must continue.
+    return false
+  }
+}
+
+function requireAnswer(value) {
+  if (prompt.isCancel(value)) throw new InstallCancelledError()
+  return value
+}
+
+export async function runInstaller({
+  command = 'install',
+  install,
+  installEdgeImpl = installEdge,
+  installerUi,
+  outputDrainTimeoutMs = OUTPUT_DRAIN_TIMEOUT_MS,
+  uiFactory = (signal, output, writeRecovery) => createInstallerUi(
+    prompt,
+    signal,
+    writeSync,
+    output,
+    writeRecovery,
+    command,
+  ),
+  runtimeProcess = process,
+  stderr = process.stderr,
+  stdout = process.stdout,
+  wranglerRunner = executeWrangler,
+} = {}) {
+  const controller = new AbortController()
+  let interruption
+  let outputFailure
+  let notifyOutputFailure
+  const outputFailureDetected = new Promise(resolve => {
+    notifyOutputFailure = resolve
+  })
+  let recoveryStream
+  const failOutput = (stream, error) => {
+    if (outputFailure !== undefined) return
+    outputFailure = new InstallerOutputError(stream, error)
+    recoveryStream ??= stream
+    notifyOutputFailure()
+    controller.abort(outputFailure)
+  }
+  const stdoutBoundary = createInstallerOutput(stdout, error => failOutput('stdout', error))
+  const stderrBoundary = createInstallerOutput(stderr, error => failOutput('stderr', error))
+  const cancelBlockedOutput = () => {
+    const interruptError = interruption ?? controller.signal.reason
+    if (!(interruptError instanceof InstallInterruptedError)) return
+    const stdoutBlocked = stdoutBoundary.cancel()
+    const stderrBlocked = stderrBoundary.cancel()
+    recoveryStream ??= stderrBlocked && !stdoutBlocked ? 'stderr' : 'stdout'
+    interruptError.outputFailureStream = recoveryStream
+  }
+  controller.signal.addEventListener('abort', cancelBlockedOutput)
+  const installOperation = install ?? (options => installEdgeImpl({
+    ...options,
+    runWrangler: (args, runOptions) => wranglerRunner(args, {
+      ...runOptions,
+      stderrDestination: stderrBoundary.output,
+      stdoutDestination: stdoutBoundary.output,
+    }),
+  }))
+  const writeRecovery = (failedStream, value) => {
+    const alternateBoundary = failedStream === 'stdout' ? stderrBoundary : stdoutBoundary
+    return alternateBoundary.write(value)
+  }
+  const baseUi = installerUi
+    ?? uiFactory(controller.signal, stdoutBoundary.output, writeRecovery)
+  let lastRecovery
+  let alternateRecoveryAttempted = false
+  let alternateRecoveryPending
+  const deliverAlternateRecovery = (result, stream) => {
+    if (alternateRecoveryAttempted) return
+    alternateRecoveryAttempted = true
+    try {
+      alternateRecoveryPending = Promise.resolve(baseUi.outputFailureRecovery(result, stream))
+        .then(delivered => delivered !== false, () => false)
+    } catch {
+      alternateRecoveryPending = Promise.resolve()
+    }
+  }
+  const ui = {
+    ...baseUi,
+    recovery(result) {
+      lastRecovery = result
+      if (recoveryStream === undefined) baseUi.recovery(result)
+      else deliverAlternateRecovery(result, recoveryStream)
+    },
+    outputFailureRecovery(result, stream) {
+      lastRecovery = result
+      recoveryStream ??= stream
+      deliverAlternateRecovery(result, stream)
+    },
+    success(result) {
+      lastRecovery = result
+      if (recoveryStream === undefined) baseUi.success(result)
+      else deliverAlternateRecovery(result, recoveryStream)
+    },
+  }
+  const handlers = new Map([...INTERRUPT_EXIT_CODES].map(([signal]) => [
+    signal,
+    () => {
+      interruption ??= new InstallInterruptedError(signal)
+      if (controller.signal.aborted) cancelBlockedOutput()
+      else controller.abort(interruption)
+    },
+  ]))
+  for (const [signal, handler] of handlers) runtimeProcess.on(signal, handler)
+  let result
+  let installError
+  try {
+    try {
+      result = await installOperation({ command, ui, signal: controller.signal })
+    } catch (error) {
+      installError = error
+    }
+    if (outputFailure === undefined) {
+      await Promise.race([
+        Promise.all([stdoutBoundary.settled(), stderrBoundary.settled()]),
+        outputFailureDetected,
+      ])
+    }
+    if (recoveryStream !== undefined && lastRecovery !== undefined) {
+      deliverAlternateRecovery(lastRecovery, recoveryStream)
+    }
+    const outputsSettled = Promise.all([stdoutBoundary.settled(), stderrBoundary.settled()])
+    if (outputFailure !== undefined) {
+      let timeout
+      const drainTimedOut = new Promise(resolve => {
+        timeout = setTimeout(() => resolve(true), outputDrainTimeoutMs)
+      })
+      try {
+        const timedOut = await Promise.race([
+          outputsSettled.then(() => false),
+          drainTimedOut,
+        ])
+        if (timedOut) {
+          stdoutBoundary.cancel()
+          stderrBoundary.cancel()
+          await outputsSettled
+        }
+      } finally {
+        clearTimeout(timeout)
+      }
+    } else {
+      await outputsSettled
+    }
+    await alternateRecoveryPending
+    const abortError = interruption ?? controller.signal.reason
+    if (abortError instanceof InstallInterruptedError) throw abortError
+    if (outputFailure !== undefined && abortError === outputFailure) throw outputFailure
+    if (installError !== undefined) throw installError
+    if (abortError instanceof Error) throw abortError
+    if (controller.signal.aborted) throw new Error('Installation aborted without an Error reason.')
+    return result
+  } finally {
+    for (const [signal, handler] of handlers) runtimeProcess.removeListener(signal, handler)
+    controller.signal.removeEventListener('abort', cancelBlockedOutput)
+    stdoutBoundary.dispose()
+    stderrBoundary.dispose()
+  }
+}
+
+function createInstallerOutput(destination, onFailure) {
+  let activeWrite
+  let failed = false
+  let pendingWrites = 0
+  const settleWaiters = new Set()
+  const settle = () => {
+    if (pendingWrites !== 0 || output.writableLength !== 0) return
+    for (const resolve of settleWaiters) resolve()
+    settleWaiters.clear()
+  }
+  const fail = (error) => {
+    if (failed) return
+    failed = true
+    onFailure(error instanceof Error ? error : new Error(String(error)))
+    activeWrite?.()
+  }
+  const closed = () => fail(new Error('Output destination closed during installation.'))
+  const output = new Writable({
+    write(chunk, encoding, callback) {
+      if (failed) {
+        callback()
+        queueMicrotask(settle)
+        return
+      }
+      pendingWrites += 1
+      let completed = false
+      const written = (error) => {
+        if (completed) return
+        completed = true
+        activeWrite = undefined
+        if (error !== undefined && error !== null) fail(error)
+        pendingWrites = Math.max(0, pendingWrites - 1)
+        callback()
+        queueMicrotask(settle)
+      }
+      activeWrite = written
+      try {
+        destination.write(chunk, encoding, written)
+      } catch (error) {
+        written(error)
+      }
+    },
+  })
+  Object.defineProperties(output, {
+    columns: { get: () => destination.columns },
+    isTTY: { get: () => destination.isTTY },
+    rows: { get: () => destination.rows },
+  })
+  destination.on('error', fail)
+  destination.on('close', closed)
+  return {
+    output,
+    write(value) {
+      return new Promise(resolve => {
+        if (failed) {
+          resolve(false)
+          return
+        }
+        output.write(value, () => resolve(!failed))
+      })
+    },
+    cancel() {
+      const blocked = pendingWrites !== 0 || output.writableLength !== 0
+      if (!blocked) return false
+      failed = true
+      destination.destroy()
+      activeWrite?.()
+      return true
+    },
+    settled() {
+      if (pendingWrites === 0 && output.writableLength === 0) return Promise.resolve()
+      return new Promise(resolve => settleWaiters.add(resolve))
+    },
+    dispose() {
+      destination.removeListener('error', fail)
+      destination.removeListener('close', closed)
+    },
+  }
+}
+
+async function main() {
+  const command = parseCommand(process.argv.slice(2))
+  if (command === 'help') {
+    process.stdout.write('Usage: dsh-edge <install|upgrade>\n\nCommands:\n  install   Create or update an instance\n  upgrade   Upgrade an existing instance without deleting its data\n')
+    return
+  }
+  if (command === 'version') {
+    process.stdout.write(`${edgePackage.version}\n`)
+    return
+  }
+  await runInstaller({ command })
+}
+
+if (process.argv[1] !== undefined
+  && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch((error) => {
+    if (error instanceof InstallCancelledError) {
+      if (error instanceof InstallInterruptedError) {
+        writeAlternate(
+          writeSync,
+          error.outputFailureStream ?? 'stdout',
+          ['', `Installation interrupted by ${error.signal}.`, ''],
+        )
+        process.exitCode = error.exitCode
+      } else {
+        prompt.cancel(error.message)
+      }
+      return
+    }
+    if (error instanceof InstallerOutputError) {
+      writeAlternate(writeSync, error.stream, ['', `Installation failed: ${error.message}`, ''])
+      process.exitCode = 1
+      return
+    }
+    prompt.cancel(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  })
+}

package/scripts/install.d.mts

@@ -0,0 +1,149 @@
+export type RuntimeMode = 'direct' | 'isolated'
+export type InstallerCommand = 'install' | 'upgrade'
+
+export interface CloudflareAccount {
+  id: string
+  name: string
+}
+
+export interface CommandResult {
+  interrupted?: boolean
+  outputFailure?: InstallerOutputError
+  status: number | null
+  stdout: string
+  stderr: string
+}
+
+export interface InstallerUi {
+  intro(message: string): void
+  step(message: string): void
+  selectRuntime(): Promise<RuntimeMode>
+  selectAccount(choices: Array<{ value: string; label: string; hint?: string }>): Promise<string>
+  workerName(initialValue: string, validate: (value: string) => string | undefined): Promise<string>
+  workerConflict(workerName: string): Promise<'rename' | 'update' | 'cancel'>
+  selectOwnerSecretMode(): Promise<'generate' | 'custom'>
+  ownerSecret(validate: (value: string) => string | undefined): Promise<string>
+  deepSeekKey(validate: (value: string) => string | undefined): Promise<string>
+  confirm(summary: {
+    mode: RuntimeMode
+    modeLabel: string
+    accountLabel: string
+    workerName: string
+    paid: boolean
+  }): Promise<boolean>
+  acceptTemporaryTerms(): Promise<boolean>
+  cleanupFailure(message: string): void
+  recovery(result: InstallRecovery): void
+  outputFailureRecovery(
+    result: InstallRecovery,
+    failedStream: 'stderr' | 'stdout',
+  ): boolean | Promise<boolean> | void
+  success(result: InstallResult): void
+}
+
+export interface InstallRecovery {
+  claimUrl?: string
+  ownerSecret: string
+  publicUrl?: string
+  workerName: string
+}
+
+export interface InstallResult {
+  publicUrl: string
+  versionId?: string
+  account?: CloudflareAccount
+  claimUrl?: string
+  deploymentId: string
+  mode: RuntimeMode
+  ownerSecret: string
+  temporary: boolean
+  workerName: string
+}
+
+export const DEPLOYMENT_ID_DEFINE: string
+export const DEFAULT_WORKER_NAME: string
+export const LOGIN_PROFILE: string
+export const RUNTIME_MODES: Readonly<Record<RuntimeMode, Readonly<{
+  environment: string
+  expectedShell: string
+  label: string
+}>>>
+export class InstallCancelledError extends Error {}
+export class InstallerOutputError extends Error {
+  readonly stream: 'stderr' | 'stdout'
+}
+export function accountChoices(mode: RuntimeMode, accounts: CloudflareAccount[], command?: InstallerCommand): Array<{
+  value: string
+  label: string
+  hint?: string
+}>
+export function parseWhoami(source: string): { accounts: CloudflareAccount[]; email?: string }
+export function validateWorkerName(value: string): string | undefined
+export function validateOwnerSecret(value: string): string | undefined
+export function validateDeepSeekKey(value: string): string | undefined
+export function generateOwnerSecret(): string
+export function wranglerEnvironment(environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv
+export function unauthenticatedEnvironment(environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv
+export function wranglerDeployArgs(options: {
+  deploymentId: string
+  mode: RuntimeMode
+  workerName: string
+  secretsFile: string
+  configFile: string
+  profile?: string
+  temporary?: boolean
+}): string[]
+export function parseDeploymentOutput(source: string): { publicUrl: string; versionId?: string }
+export function parseClaimUrl(source: string): string | undefined
+export function parseWorkerExistence(result: CommandResult): boolean
+export function truncateUtf8Tail(value: string, maxBytes: number): string
+export function createOutputForwarder(
+  source: NodeJS.ReadableStream,
+  destination: NodeJS.WritableStream,
+  onFailure: (error: Error) => void,
+): {
+  write(chunk: string): void
+  settled(): Promise<void>
+  cancel(): void
+  dispose(): void
+}
+export function createTerminalSanitizer(): {
+  push(chunk: string): string
+}
+export function resolveWranglerClose(options: {
+  outputFailure?: InstallerOutputError
+  processError?: unknown
+  signal?: AbortSignal
+  status: number | null
+  stderr: string
+  stdout: string
+}): CommandResult
+export function installEdge(options: {
+  command?: InstallerCommand
+  ui: InstallerUi
+  runWrangler?: (args: string[], options?: {
+    environment?: NodeJS.ProcessEnv
+    interactive?: boolean
+    capture?: boolean
+    signal?: AbortSignal
+  }) => Promise<CommandResult>
+  deploymentId?: string
+  environment?: NodeJS.ProcessEnv
+  createTemporaryDirectory?: () => Promise<string>
+  removePath?: typeof import('node:fs/promises').rm
+  signal?: AbortSignal
+}): Promise<InstallResult>
+export function wranglerProcessInvocation(args: string[], options?: {
+  nodeExecutable?: string
+  wranglerCli?: string
+}): { command: string; args: string[] }
+export function executeWrangler(args: string[], options?: {
+  environment?: NodeJS.ProcessEnv
+  interactive?: boolean
+  capture?: boolean
+  forceKillAfterDelay?: number
+  invocation?: { command: string; args: string[] }
+  signal?: AbortSignal
+  stderrDestination?: NodeJS.WritableStream
+  stdoutDestination?: NodeJS.WritableStream
+}): Promise<CommandResult>