feat(agents): expand AR CLI surface

docs/index.md

@@ -20,14 +20,25 @@ netlify [command] help
 <!-- AUTO-GENERATED-CONTENT:START (GENERATE_COMMANDS_LIST) -->
 ### [agents](/commands/agents)
 
-Manage Netlify AI agent tasks
+Manage Netlify AI agent runs
 
 | Subcommand | description  |
 |:--------------------------- |:-----|
-| [`agents:create`](/commands/agents#agentscreate) | Create and run a new agent task on your site  |
-| [`agents:list`](/commands/agents#agentslist) | List agent tasks for the current site  |
-| [`agents:show`](/commands/agents#agentsshow) | Show details of a specific agent task  |
-| [`agents:stop`](/commands/agents#agentsstop) | Stop a running agent task  |
+| [`agents:archive`](/commands/agents#agentsarchive) | Archive an agent run  |
+| [`agents:commit`](/commands/agents#agentscommit) | Commit an agent run’s changes directly to a branch  |
+| [`agents:create`](/commands/agents#agentscreate) | Create and start a new agent run on your site  |
+| [`agents:diff`](/commands/agents#agentsdiff) | Print the code changes produced by an agent run  |
+| [`agents:follow-up`](/commands/agents#agentsfollow-up) | Send a follow-up prompt to an existing agent run  |
+| [`agents:list`](/commands/agents#agentslist) | List agent runs for the current site  |
+| [`agents:open`](/commands/agents#agentsopen) | Open the agent run preview, dashboard, or pull request in a browser  |
+| [`agents:pr`](/commands/agents#agentspr) | Open a pull request for an agent run  |
+| [`agents:publish`](/commands/agents#agentspublish) | Publish an agent run’s changes to production  |
+| [`agents:redeploy`](/commands/agents#agentsredeploy) | Redeploy an agent run by reapplying its existing changes (no AI inference)  |
+| [`agents:rename`](/commands/agents#agentsrename) | Rename an agent run  |
+| [`agents:revert`](/commands/agents#agentsrevert) | Revert an agent run to a specific session (sessions after it are discarded)  |
+| [`agents:show`](/commands/agents#agentsshow) | Show details of a specific agent run  |
+| [`agents:stop`](/commands/agents#agentsstop) | Stop a running agent run  |
+| [`agents:sync`](/commands/agents#agentssync) | Bring an agent run up to date with the latest code from its base branch  |
 
 
 ### [api](/commands/api)

src/commands/agents/agents-archive.ts

@@ -0,0 +1,54 @@
+import type { OptionValues } from 'commander'
+import inquirer from 'inquirer'
+
+import { chalk, exit, log, logAndThrowError, logJson } from '../../utils/command-helpers.js'
+import { startSpinner, stopSpinner } from '../../lib/spinner.js'
+import type BaseCommand from '../base-command.js'
+import { createAgentsApi } from './api.js'
+
+interface AgentArchiveOptions extends OptionValues {
+  json?: boolean
+  yes?: boolean
+}
+
+export const agentsArchive = async (id: string, options: AgentArchiveOptions, command: BaseCommand) => {
+  if (!id) return logAndThrowError('Agent run ID is required')
+  await command.authenticate()
+  const api = createAgentsApi(command.netlify)
+
+  if (!options.yes && !options.json) {
+    if (!process.stdin.isTTY) {
+      return logAndThrowError('Refusing to archive without --yes when stdin is not a TTY')
+    }
+    const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
+      {
+        type: 'confirm',
+        name: 'confirmed',
+        message: `Archive agent run ${id}?`,
+        default: false,
+      },
+    ])
+    if (!confirmed) return exit()
+  }
+
+  const spinner = startSpinner({ text: 'Archiving agent run...' })
+  try {
+    await api.archiveAgentRunner(id)
+    stopSpinner({ spinner })
+
+    const result = { success: true, id }
+    if (options.json) {
+      logJson(result)
+      return result
+    }
+
+    log(`${chalk.green('✓')} Agent run archived.`)
+    log(`  Run ID: ${chalk.cyan(id)}`)
+    return result
+  } catch (error_) {
+    stopSpinner({ spinner, error: true })
+    const error = error_ as Error & { status?: number }
+    if (error.status === 404) return logAndThrowError(`Agent run not found: ${id}`)
+    return logAndThrowError(`Failed to archive: ${error.message}`)
+  }
+}

src/commands/agents/agents-commit.ts

@@ -0,0 +1,99 @@
+import type { OptionValues } from 'commander'
+import inquirer from 'inquirer'
+
+import { chalk, log, logAndThrowError, logJson } from '../../utils/command-helpers.js'
+import { startSpinner, stopSpinner } from '../../lib/spinner.js'
+import type BaseCommand from '../base-command.js'
+import { createAgentsApi } from './api.js'
+import type { AgentRunner } from './types.js'
+
+interface AgentCommitOptions extends OptionValues {
+  branch?: string
+  json?: boolean
+}
+
+const pickDefaultBranch = (runner: AgentRunner): { branch: string; reason: string } | null => {
+  const prState = runner.pr_state
+  const hasOpenPr = runner.pr_url && (prState === 'open' || prState === 'draft')
+  if (hasOpenPr && runner.pr_branch) {
+    return { branch: runner.pr_branch, reason: 'updating the existing pull request' }
+  }
+  if (runner.branch) {
+    return { branch: runner.branch, reason: "committing to this agent run's branch" }
+  }
+  return null
+}
+
+export const agentsCommit = async (id: string, options: AgentCommitOptions, command: BaseCommand) => {
+  if (!id) return logAndThrowError('Agent run ID is required')
+  await command.authenticate()
+  const { siteInfo } = command.netlify
+  if (!siteInfo.build_settings?.repo_url) {
+    return logAndThrowError(
+      'This project is not connected to a git repository. Commits are only available for git-backed projects.',
+    )
+  }
+  const api = createAgentsApi(command.netlify)
+
+  let targetBranch = options.branch?.trim()
+
+  if (!targetBranch) {
+    const lookupSpinner = startSpinner({ text: 'Looking up agent run...' })
+    let runner: AgentRunner
+    try {
+      runner = await api.getAgentRunner(id)
+      stopSpinner({ spinner: lookupSpinner })
+    } catch (error_) {
+      stopSpinner({ spinner: lookupSpinner, error: true })
+      const error = error_ as Error & { status?: number }
+      if (error.status === 404) return logAndThrowError(`Agent run not found: ${id}`)
+      return logAndThrowError(`Failed to fetch agent run: ${error.message}`)
+    }
+
+    const suggestion = pickDefaultBranch(runner)
+    if (!suggestion) {
+      return logAndThrowError('Could not determine a target branch. Pass --branch <name>.')
+    }
+
+    if (options.json || !process.stdin.isTTY) {
+      targetBranch = suggestion.branch
+    } else {
+      log(chalk.dim(`Default: ${suggestion.branch} (${suggestion.reason})`))
+      const { branchInput } = await inquirer.prompt<{ branchInput: string }>([
+        {
+          type: 'input',
+          name: 'branchInput',
+          message: 'Which branch should the agent commit to?',
+          default: suggestion.branch,
+          validate: (input: string) => (input.trim().length > 0 ? true : 'Branch name is required'),
+        },
+      ])
+      targetBranch = branchInput.trim()
+    }
+  }
+
+  const spinner = startSpinner({ text: `Committing to ${targetBranch}...` })
+  try {
+    const runner = await api.agentRunnerCommitToBranch(id, targetBranch)
+    stopSpinner({ spinner })
+
+    if (options.json) {
+      logJson(runner)
+      return runner
+    }
+
+    if (runner.merge_commit_error) {
+      log(`${chalk.red('✗')} Commit failed: ${runner.merge_commit_error}`)
+      return runner
+    }
+
+    log(`${chalk.green('✓')} Committed to ${chalk.cyan(targetBranch)}`)
+    log()
+    if (runner.merge_commit_sha) log(`  SHA: ${chalk.cyan(runner.merge_commit_sha)}`)
+    return runner
+  } catch (error_) {
+    stopSpinner({ spinner, error: true })
+    const error = error_ as Error
+    return logAndThrowError(`Failed to commit: ${error.message}`)
+  }
+}