switchroom 0.8.1 → 0.10.0

package/telegram-plugin/foreman/foreman-create-flow.ts

@@ -1,202 +0,0 @@
-/**
- * Pure create-agent flow state machine — extracted from foreman.ts for
- * testability. No grammY imports, no SQLite imports, no side effects.
- *
- * Each function takes current state + input and returns an Action
- * (what the foreman should do next). foreman.ts interprets actions
- * by calling the actual SQLite / grammY / orchestrator APIs.
- *
- * Steps:
- *   start                  → asked-name  (when no name given)
- *                          → asked-profile (when name provided inline)
- *   asked-name  + text     → asked-profile (if valid name)
- *   asked-profile + text   → asked-bot-token (if valid profile)
- *   asked-bot-token + text → asked-oauth-code (after createAgent())
- *   asked-oauth-code + text → done (after completeCreation())
- */
-
-import type { CreateFlowState, CreateFlowStep } from './state.js'
-
-// ─── Action types ────────────────────────────────────────────────────────
-
-export type CreateFlowAction =
-  | { kind: 'ask-name' }
-  | { kind: 'ask-profile'; profiles: string[] }
-  | { kind: 'ask-bot-token'; name: string; profile: string }
-  | { kind: 'call-create-agent'; name: string; profile: string; botToken: string }
-  | { kind: 'ask-oauth-code'; loginUrl: string; name: string }
-  | { kind: 'call-complete-creation'; name: string; code: string }
-  | { kind: 'done'; name: string; botUsername: string | null }
-  | { kind: 'error'; message: string; stayInStep: boolean }
-  | { kind: 'cancel'; reason: string }
-
-// ─── Name validation (mirrors assertSafeAgentName) ───────────────────────
-
-export function isValidAgentName(name: string): boolean {
-  return /^[a-z0-9][a-z0-9_-]{0,50}$/.test(name)
-}
-
-// ─── Flow entry point ────────────────────────────────────────────────────
-
-/**
- * Start or resume a /create-agent flow.
- *
- * @param inlineName  Optional name from the command args (/create-agent gymbro)
- * @param profiles    Available profile names (from listAvailableProfiles())
- * @returns Action to perform
- */
-export function startCreateFlow(
-  inlineName: string | null,
-  profiles: string[],
-): CreateFlowAction {
-  if (!inlineName) {
-    return { kind: 'ask-name' }
-  }
-
-  if (!isValidAgentName(inlineName)) {
-    return {
-      kind: 'error',
-      message: `"${inlineName}" is not a valid agent name. Names must be lowercase, alphanumeric, hyphens or underscores, max 51 chars.`,
-      stayInStep: false,
-    }
-  }
-
-  return { kind: 'ask-profile', profiles }
-}
-
-// ─── Step transition: handle inbound text for current step ───────────────
-
-export interface StepTransitionInput {
-  /** Current persisted state (or null if no state yet). */
-  state: CreateFlowState | null
-  /** The text the user sent. */
-  text: string
-  /** Available profiles (for profile validation). */
-  profiles: string[]
-}
-
-/**
- * Given the current state and user text, compute the next action.
- * The caller (foreman.ts) is responsible for persisting state changes
- * and executing the returned action.
- */
-export function handleFlowText(input: StepTransitionInput): CreateFlowAction {
-  const { state, text, profiles } = input
-  const trimmed = text.trim()
-
-  if (!state) {
-    // No active flow — ignore
-    return { kind: 'cancel', reason: 'no-active-flow' }
-  }
-
-  switch (state.step) {
-    case 'asked-name': {
-      if (!isValidAgentName(trimmed)) {
-        return {
-          kind: 'error',
-          message: `"${trimmed}" is not a valid agent name. Names must be lowercase, alphanumeric, hyphens or underscores, max 51 chars. Try again:`,
-          stayInStep: true,
-        }
-      }
-      return { kind: 'ask-profile', profiles }
-    }
-
-    case 'asked-profile': {
-      if (!profiles.includes(trimmed)) {
-        return {
-          kind: 'error',
-          message: `Unknown profile "${trimmed}". Choose one of: ${profiles.join(', ')}`,
-          stayInStep: true,
-        }
-      }
-      // Pre-#28 fix this fell back to `trimmed` (the profile name)
-      // when state.name was missing — silently treating the profile
-      // as the agent name. Now we cancel with missing-name instead,
-      // matching the asked-bot-token step's behaviour on corrupt
-      // state. The fallback wasn't exploitable (assertSafeAgentName
-      // catches it downstream), but it's semantically wrong.
-      if (!state.name) {
-        return { kind: 'cancel', reason: 'missing-name' }
-      }
-      return { kind: 'ask-bot-token', name: state.name, profile: trimmed }
-    }
-
-    case 'asked-bot-token': {
-      const name = state.name ?? ''
-      const profile = state.profile ?? ''
-      if (!name || !profile) {
-        return { kind: 'cancel', reason: 'missing-name-or-profile' }
-      }
-      // Basic bot token shape check (foreman.ts validates via Telegram API)
-      if (!trimmed.includes(':') || trimmed.length < 20) {
-        return {
-          kind: 'error',
-          message: "That doesn't look like a BotFather token. It should be in the form <code>1234567890:AAH...</code> — try again:",
-          stayInStep: true,
-        }
-      }
-      return { kind: 'call-create-agent', name, profile, botToken: trimmed }
-    }
-
-    case 'asked-oauth-code': {
-      const name = state.name ?? ''
-      if (!name) return { kind: 'cancel', reason: 'missing-name' }
-      // Codes are typically 8+ alphanumeric chars; pass through for server validation
-      if (trimmed.length < 4) {
-        return {
-          kind: 'error',
-          message: 'That code looks too short. Paste the full code from the browser:',
-          stayInStep: true,
-        }
-      }
-      return { kind: 'call-complete-creation', name, code: trimmed }
-    }
-
-    case 'done':
-      return { kind: 'cancel', reason: 'flow-already-done' }
-
-    default: {
-      const _exhaustive: never = state.step
-      return { kind: 'cancel', reason: `unknown-step:${_exhaustive}` }
-    }
-  }
-}
-
-// ─── State factory helpers (for foreman.ts to build new state objects) ───
-
-export function makeInitialState(chatId: string, name: string | null): CreateFlowState {
-  const now = Date.now()
-  return {
-    chatId,
-    step: name ? 'asked-profile' : 'asked-name',
-    name,
-    profile: null,
-    botToken: null,
-    authSessionName: null,
-    loginUrl: null,
-    startedAt: now,
-    updatedAt: now,
-  }
-}
-
-export function advanceState(
-  state: CreateFlowState,
-  updates: Partial<Omit<CreateFlowState, 'chatId' | 'startedAt'>>,
-): CreateFlowState {
-  return {
-    ...state,
-    ...updates,
-    updatedAt: Date.now(),
-  }
-}
-
-/** Compute the human-readable step label for recovery messages. */
-export function stepLabel(step: CreateFlowStep): string {
-  switch (step) {
-    case 'asked-name': return 'waiting for agent name'
-    case 'asked-profile': return 'waiting for profile selection'
-    case 'asked-bot-token': return 'waiting for BotFather token'
-    case 'asked-oauth-code': return 'waiting for OAuth code'
-    case 'done': return 'done'
-  }
-}

package/telegram-plugin/foreman/foreman-handlers.ts

@@ -1,493 +0,0 @@
-/**
- * Pure handler logic extracted from foreman.ts for testability.
- *
- * foreman.ts has process-level side effects (reads .env, connects Bot,
- * starts polling) that prevent direct import in tests. This module
- * exports the command handler implementations and their helpers so that
- * tests can exercise real code with mocked bot + ctx, rather than
- * re-implementing the logic locally.
- */
-
-import { execFileSync } from 'child_process'
-import { renameSync, existsSync } from 'fs'
-import { homedir } from 'os'
-import { join, resolve } from 'path'
-import {
-  escapeHtmlForTg,
-  preBlock,
-  stripAnsi,
-  formatSwitchroomOutput,
-} from '../shared/bot-runtime.js'
-
-// ─── Types ────────────────────────────────────────────────────────────────
-
-export type SwitchroomExecFn = (args: string[]) => string
-export type SwitchroomExecJsonFn = <T = unknown>(args: string[]) => T | null
-
-// ─── Agent name validation ────────────────────────────────────────────────
-
-/**
- * Throw if the agent name is not safe for use in journalctl unit names.
- * Mirrors AGENT_NAME_RE in src/agents/create-orchestrator.ts and the yaml
- * schema in src/config/schema.ts — all three MUST stay in sync. Max 51
- * chars (see operator-events.ts callback_data contract).
- */
-export function assertSafeAgentName(name: string): void {
-  if (!/^[a-z0-9][a-z0-9_-]{0,50}$/.test(name)) {
-    throw new Error(`invalid agent name: ${name}`)
-  }
-}
-
-// ─── Tail-N parsing ───────────────────────────────────────────────────────
-
-export function parseTailN(args: string[]): number {
-  let tailN = 50
-  const tailIdx = args.indexOf('--tail')
-  if (tailIdx !== -1 && args[tailIdx + 1]) {
-    const parsed = parseInt(args[tailIdx + 1], 10)
-    if (!isNaN(parsed) && parsed > 0) tailN = Math.min(parsed, 500)
-  }
-  return tailN
-}
-
-// ─── Text chunking ────────────────────────────────────────────────────────
-
-export function chunkText(text: string, maxLen = 4096): string[] {
-  if (text.length <= maxLen) return [text]
-  const chunks: string[] = []
-  let pos = 0
-  while (pos < text.length) {
-    chunks.push(text.slice(pos, pos + maxLen))
-    pos += maxLen
-  }
-  return chunks
-}
-
-// ─── /status handler impl ─────────────────────────────────────────────────
-
-export type AgentListEntry = {
-  name: string
-  status: string
-  uptime: string
-  template?: string | null
-  topic_name?: string | null
-}
-
-export function statusIcon(status: string): string {
-  if (status === 'active' || status === 'running') return '🟢'
-  if (status === 'inactive' || status === 'stopped' || status === 'dead') return '🔴'
-  if (status === 'failed') return '⚠️'
-  return '⚪'
-}
-
-export function buildFleetSummary(
-  switchroomExecJson: SwitchroomExecJsonFn,
-): string {
-  try {
-    const data = switchroomExecJson<{ agents: AgentListEntry[] }>(['agent', 'list'])
-    if (!data || data.agents.length === 0) return '<i>No agents defined</i>'
-    const lines = ['<b>Fleet status</b>']
-    for (const a of data.agents) {
-      lines.push(
-        `${statusIcon(a.status)} <b>${escapeHtmlForTg(a.name)}</b> · ${escapeHtmlForTg(a.status)} · ${escapeHtmlForTg(a.uptime)}`,
-      )
-      if (a.template || a.topic_name) {
-        const meta = [a.template, a.topic_name]
-          .filter(Boolean)
-          .map((s) => escapeHtmlForTg(s!))
-          .join(' → ')
-        lines.push(`  <i>${meta}</i>`)
-      }
-    }
-    return lines.join('\n')
-  } catch (err) {
-    return `<b>agent list failed:</b>\n${preBlock(formatSwitchroomOutput((err as Error).message))}`
-  }
-}
-
-// ─── /logs handler impl ───────────────────────────────────────────────────
-
-export const LOG_PAGE_BYTES = 3 * 1024 // 3 KB
-
-export interface LogsResult {
-  /** One or more reply strings. Send them in order. */
-  replies: Array<{ text: string; html: boolean }>
-}
-
-/**
- * Core /logs implementation — returns the reply payloads rather than
- * sending them directly, so the caller (foreman.ts) can use its own
- * switchroomReply and tests can inspect the output.
- *
- * @param match  The text after "/logs " from ctx.match
- * @param execFile  Injected execFileSync for testability
- */
-export function handleLogsCommand(
-  match: string,
-  execFile: typeof execFileSync = execFileSync,
-): LogsResult {
-  const args = match.trim().split(/\s+/).filter(Boolean)
-
-  if (args.length === 0) {
-    return { replies: [{ text: 'Usage: /logs &lt;agent&gt; [--tail N]', html: true }] }
-  }
-
-  const agentName = args[0]
-  try {
-    assertSafeAgentName(agentName)
-  } catch {
-    return { replies: [{ text: 'Invalid agent name.', html: true }] }
-  }
-
-  const tailN = parseTailN(args)
-
-  let output: string
-  try {
-    output = stripAnsi(
-      execFile(
-        'journalctl',
-        [
-          '--user',
-          '-u',
-          `switchroom-${agentName}`,
-          '-n',
-          String(tailN),
-          '--no-pager',
-          '--output=short-monotonic',
-        ],
-        {
-          encoding: 'utf-8',
-          timeout: 10000,
-          env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
-          stdio: ['ignore', 'pipe', 'pipe'],
-        },
-      ) as string,
-    )
-  } catch (err) {
-    const msg = err as { stdout?: string; stderr?: string; message?: string }
-    const detail = msg.stdout || msg.stderr || msg.message || 'unknown error'
-    return {
-      replies: [
-        {
-          text: `<b>logs failed for ${escapeHtmlForTg(agentName)}:</b>\n${preBlock(formatSwitchroomOutput(stripAnsi(detail)))}`,
-          html: true,
-        },
-      ],
-    }
-  }
-
-  const trimmed = output.trim()
-  if (!trimmed) {
-    return {
-      replies: [
-        {
-          text: `No logs found for <code>${escapeHtmlForTg(agentName)}</code>.`,
-          html: true,
-        },
-      ],
-    }
-  }
-
-  if (Buffer.byteLength(trimmed, 'utf8') > LOG_PAGE_BYTES) {
-    const chunks = chunkText(trimmed, 3800)
-    return {
-      replies: chunks.map((chunk, i) => {
-        const label = chunks.length > 1 ? ` (${i + 1}/${chunks.length})` : ''
-        return {
-          text: preBlock(chunk) + (label ? `\n<i>${label}</i>` : ''),
-          html: true,
-        }
-      }),
-    }
-  }
-
-  return { replies: [{ text: preBlock(trimmed), html: true }] }
-}
-
-// ─── /restart handler impl ────────────────────────────────────────────────
-
-export interface RestartResult {
-  ok: boolean
-  text: string
-  html: boolean
-}
-
-/**
- * Core /restart implementation.
- *
- * Shells out to `systemctl --user restart switchroom-<agent>` via execFileSync
- * (no shell, so agent name is safely passed as an arg — no injection risk).
- *
- * @param match      Text after "/restart " from ctx.match
- * @param execFile   Injected execFileSync for testability
- */
-export function handleRestartCommand(
-  match: string,
-  execFile: typeof execFileSync = execFileSync,
-): RestartResult {
-  const agentName = match.trim().split(/\s+/)[0] ?? ''
-
-  if (!agentName) {
-    return {
-      ok: false,
-      text: 'Usage: /restart &lt;agent&gt;',
-      html: true,
-    }
-  }
-
-  try {
-    assertSafeAgentName(agentName)
-  } catch {
-    return { ok: false, text: 'Invalid agent name.', html: true }
-  }
-
-  try {
-    execFile(
-      'systemctl',
-      ['--user', 'restart', `switchroom-${agentName}`],
-      {
-        encoding: 'utf-8',
-        timeout: 15000,
-        stdio: ['ignore', 'pipe', 'pipe'],
-      },
-    )
-    return {
-      ok: true,
-      text: `Restarted <code>switchroom-${escapeHtmlForTg(agentName)}</code>.`,
-      html: true,
-    }
-  } catch (err) {
-    const msg = err as { stderr?: string; stdout?: string; message?: string }
-    const detail = stripAnsi(msg.stderr || msg.stdout || msg.message || 'unknown error').trim()
-    return {
-      ok: false,
-      text: `<b>restart failed for ${escapeHtmlForTg(agentName)}:</b>\n${preBlock(formatSwitchroomOutput(detail))}`,
-      html: true,
-    }
-  }
-}
-
-// ─── /delete (destroy) handler impl ──────────────────────────────────────
-
-export interface DeleteResult {
-  replies: Array<{ text: string; html: boolean }>
-  /** When true, foreman.ts should also send an inline keyboard for confirmation. */
-  needsConfirm?: boolean
-  /** Agent name (for the confirmation prompt). */
-  agentForConfirm?: string
-}
-
-/**
- * Resolve the agents directory from environment or default location.
- * Exposed for testability.
- */
-export function resolveAgentsDirForDelete(): string {
-  const switchroomDir = process.env.SWITCHROOM_AGENTS_DIR
-    ?? join(homedir(), '.switchroom', 'agents')
-  return switchroomDir
-}
-
-/**
- * Core /delete first-step implementation — returns a confirmation prompt.
- *
- * The actual deletion is performed by executeDeleteAgent() once the user
- * confirms via callback_query or "YES" text.
- */
-export function handleDeleteCommand(match: string): DeleteResult {
-  const agentName = match.trim().split(/\s+/)[0] ?? ''
-
-  if (!agentName) {
-    return {
-      replies: [{ text: 'Usage: /delete &lt;agent&gt;', html: true }],
-    }
-  }
-
-  try {
-    assertSafeAgentName(agentName)
-  } catch {
-    return { replies: [{ text: 'Invalid agent name.', html: true }] }
-  }
-
-  return {
-    replies: [
-      {
-        text: `Are you sure you want to delete agent <b>${escapeHtmlForTg(agentName)}</b>?\n\nThis will stop and remove the systemd unit and archive the agent directory. Reply <b>YES</b> to confirm.`,
-        html: true,
-      },
-    ],
-    needsConfirm: true,
-    agentForConfirm: agentName,
-  }
-}
-
-/**
- * Execute agent deletion after confirmation.
- *
- * Archives the agent dir to `agents/_archived_<name>_<timestamp>/` before
- * running `switchroom agent destroy --yes <name>` so data is recoverable.
- *
- * @param agentName   Validated agent name
- * @param switchroomExec  Injected CLI exec for testability
- * @param execFile    Injected execFileSync for testability (systemctl)
- * @param agentsDir   Override agents dir (for tests)
- */
-export function executeDeleteAgent(
-  agentName: string,
-  switchroomExec: SwitchroomExecFn,
-  execFile: typeof execFileSync = execFileSync,
-  agentsDir: string = resolveAgentsDirForDelete(),
-): DeleteResult {
-  try {
-    assertSafeAgentName(agentName)
-  } catch {
-    return { replies: [{ text: 'Invalid agent name.', html: true }] }
-  }
-
-  const agentDir = resolve(agentsDir, agentName)
-  let archivePath: string | null = null
-
-  // Step 1: Archive the dir if it exists
-  if (existsSync(agentDir)) {
-    const timestamp = Date.now()
-    archivePath = resolve(agentsDir, `_archived_${agentName}_${timestamp}`)
-    try {
-      renameSync(agentDir, archivePath)
-    } catch (err) {
-      return {
-        replies: [
-          {
-            text: `<b>Archive failed for ${escapeHtmlForTg(agentName)}:</b>\n${preBlock(formatSwitchroomOutput((err as Error).message))}`,
-            html: true,
-          },
-        ],
-      }
-    }
-  }
-
-  // Step 2: Stop + remove systemd unit via CLI (--yes skips the interactive prompt)
-  let cliOutput = ''
-  let cliOk = true
-  try {
-    cliOutput = switchroomExec(['agent', 'destroy', '--yes', agentName])
-  } catch (err) {
-    cliOk = false
-    const msg = err as { stderr?: string; stdout?: string; message?: string }
-    cliOutput = stripAnsi(msg.stderr || msg.stdout || msg.message || 'unknown error').trim()
-  }
-
-  const lines: string[] = []
-
-  if (archivePath) {
-    lines.push(`Archived <code>${escapeHtmlForTg(agentName)}</code> to:`)
-    lines.push(`<code>${escapeHtmlForTg(archivePath)}</code>`)
-    lines.push('')
-  }
-
-  if (cliOk) {
-    lines.push(`Agent <b>${escapeHtmlForTg(agentName)}</b> deleted.`)
-    if (cliOutput.trim()) {
-      lines.push(preBlock(formatSwitchroomOutput(stripAnsi(cliOutput))))
-    }
-  } else {
-    lines.push(`<b>CLI destroy failed</b> (agent dir was archived; systemd unit may still exist):`)
-    lines.push(preBlock(formatSwitchroomOutput(cliOutput)))
-  }
-
-  return { replies: [{ text: lines.join('\n'), html: true }] }
-}
-
-// ─── /version handler impl ────────────────────────────────────────────────
-
-export interface VersionResult {
-  replies: Array<{ text: string; html: boolean }>
-}
-
-/**
- * Core /version implementation.
- *
- * Shells out to `switchroom version` and posts the output. Mirrors the
- * /version handler in server.ts and gateway.ts — kept as a pure function
- * here so tests can exercise it without a live bot.
- *
- * @param switchroomExec  Injected CLI exec (combined stdout+stderr) for testability
- */
-export function handleVersionCommand(
-  switchroomExec: SwitchroomExecFn,
-): VersionResult {
-  let output: string
-  try {
-    output = switchroomExec(['version'])
-  } catch (err) {
-    const msg = err as { stderr?: string; stdout?: string; message?: string }
-    const detail = stripAnsi(msg.stderr || msg.stdout || msg.message || 'unknown error').trim()
-    return {
-      replies: [
-        {
-          text: `<b>version failed:</b>\n${preBlock(formatSwitchroomOutput(detail))}`,
-          html: true,
-        },
-      ],
-    }
-  }
-
-  const trimmed = stripAnsi(output).trim()
-  if (!trimmed) {
-    return { replies: [{ text: 'version: no output.', html: false }] }
-  }
-
-  return { replies: [{ text: preBlock(trimmed), html: true }] }
-}
-
-// ─── /update handler impl ─────────────────────────────────────────────────
-
-export interface UpdateResult {
-  replies: Array<{ text: string; html: boolean }>
-}
-
-/**
- * Core /update implementation.
- *
- * Shells out to `switchroom update` via the CLI exec helper. Output is
- * paginated when > 3 KB.
- *
- * @param switchroomExec  Injected CLI exec (combined stdout+stderr) for testability
- */
-export function handleUpdateCommand(
-  switchroomExec: SwitchroomExecFn,
-): UpdateResult {
-  let output: string
-  try {
-    output = switchroomExec(['update'])
-  } catch (err) {
-    const msg = err as { stderr?: string; stdout?: string; message?: string }
-    const detail = stripAnsi(msg.stderr || msg.stdout || msg.message || 'unknown error').trim()
-    return {
-      replies: [
-        {
-          text: `<b>update failed:</b>\n${preBlock(formatSwitchroomOutput(detail))}`,
-          html: true,
-        },
-      ],
-    }
-  }
-
-  const trimmed = stripAnsi(output).trim()
-  if (!trimmed) {
-    return { replies: [{ text: 'Update complete (no output).', html: false }] }
-  }
-
-  if (Buffer.byteLength(trimmed, 'utf8') > LOG_PAGE_BYTES) {
-    const chunks = chunkText(trimmed, 3800)
-    return {
-      replies: chunks.map((chunk, i) => {
-        const label = chunks.length > 1 ? ` (${i + 1}/${chunks.length})` : ''
-        return {
-          text: preBlock(chunk) + (label ? `\n<i>${label}</i>` : ''),
-          html: true,
-        }
-      }),
-    }
-  }
-
-  return { replies: [{ text: preBlock(trimmed), html: true }] }
-}