issue-flow 0.12.0 → 0.13.0

package/README.md

@@ -1,310 +1,115 @@
 # issue-flow
 
-> This is the npm package README. For full project documentation, see the [root README](../../README.md).
+**Turn an issue into a reviewed Pull Request, without sitting in front of it.**
 
-Unified CLI that orchestrates the full issue-to-PR pipeline via [Claude Code](https://docs.anthropic.com/en/docs/claude-code) Headless mode. Analyzes issues, generates PRDs, creates task plans, implements code iteratively, reviews results, and opens pull requests -- all programmatically, without interactive sessions.
-
-Built on the [Ralph pattern](https://ghuntley.com/ralph/) for autonomous AI agent loops.
-
-## Pipeline Flow
-
-```mermaid
-flowchart LR
-    subgraph "issue-flow run 42"
-        A["init"] --> B["analyze"]
-        B --> C["prd"]
-        C --> D["plan"]
-        D --> E["execute"]
-        E --> F["review"]
-        F --> G{PASS?}
-        G -- Yes --> H["pr"]
-        G -- No --> I{"Retries\n< max?"}
-        I -- Yes --> E
-        I -- No --> J["Stop"]
-    end
-```
-
-## Requirements
-
-- **Node.js** >= 18.0.0
-- **git** installed and available in PATH
-- **Claude Code** (`npm install -g @anthropic-ai/claude-code`)
-- **GitHub CLI** (`gh`) authenticated (`gh auth login`)
-
-Run `npx issue-flow init` to verify all prerequisites.
-
-## Installation
+A CLI that orchestrates the whole path — analyse, plan, implement, verify,
+review, deliver — by driving a coding agent in headless mode:
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) (the default),
+[Codex CLI](https://developers.openai.com/codex/noninteractive), Cursor CLI or
+[Antigravity CLI](https://antigravity.google/docs/cli/getting-started/), one
+agent per phase if you want.
 
 ```bash
-# Run directly via npx (no install needed)
-npx issue-flow run 42
-
-# Or install globally
-npm install -g issue-flow
-issue-flow run 42
+npx issue-flow init           # check prerequisites and repository conventions
+npx issue-flow run 42         # prd → plan → execute → review → pr
+npx issue-flow run 42 --web   # …and watch it live at http://localhost:3737
 ```
 
-## Global Options
-
-All commands support the following options:
-
-| Flag | Description |
-|------|-------------|
-| `-v, --verbose` | Show Claude progress output in real time |
-| `-t, --timeout <seconds>` | Override headless timeout in seconds (0 = no limit) |
+> **Full documentation lives in the repository:**
+> [README](https://github.com/fabioassuncao/issue-flow#readme) ·
+> [Commands](https://github.com/fabioassuncao/issue-flow/blob/main/docs/commands.md) ·
+> [Configuration](https://github.com/fabioassuncao/issue-flow/blob/main/docs/configuration.md) ·
+> [Agents](https://github.com/fabioassuncao/issue-flow/blob/main/docs/agents.md) ·
+> [Storage](https://github.com/fabioassuncao/issue-flow/blob/main/docs/storage.md) ·
+> [Web monitoring](https://github.com/fabioassuncao/issue-flow/blob/main/docs/web-monitor.md) ·
+> [Resilience](https://github.com/fabioassuncao/issue-flow/blob/main/docs/resilience.md)
 
-```bash
-# Run with verbose output
-npx issue-flow analyze 42 --verbose
-
-# Override timeout to 10 minutes
-npx issue-flow analyze 42 --timeout 600
-
-# Disable timeout entirely
-npx issue-flow run 42 --timeout 0
-
-# Combine flags
-npx issue-flow analyze 42 -v -t 600
-```
+## Requirements
 
-Every phase that invokes Claude once (`analyze`, `prd`, `plan`, `review`, `pr`, `pr-review`, `generate`) shares a default limit of **15 minutes** per invocation; `execute` has no limit, since its iteration budget is what bounds it. Use `--timeout` to raise it on a large issue, or `--timeout 0` to remove it. When an invocation is cut short the phase reports it as a timeout and retries with backoff, so the limit is the first thing to raise if a phase keeps dying at the same elapsed time.
+- **Node.js** ≥ 22
+- **Git**, available in `PATH`, inside a repository
+- **A coding agent** — `npm install -g @anthropic-ai/claude-code` for the default
+- **GitHub CLI** (`gh`), authenticated — only for GitHub issues; a run on local
+  issues does not need it
+
+## What it does
+
+- The full pipeline `prd` → `plan` → `execute` → `review` → `pr`, plus an
+  optional whole-PR review. Every phase is also a standalone command.
+- An iterative execute loop: each iteration is a fresh agent instance that picks
+  the highest-priority pending user story, implements it, runs quality checks and
+  commits.
+- An objective acceptance contract (typecheck, lint, tests) before the LLM
+  judges. An empty contract finishes `unverified`, never green.
+- Per-phase agent selection, resolved explicitly and never inferred from which
+  binary happens to be installed.
+- Resilience for long unattended runs: a failure taxonomy, per-kind retry
+  budgets, provider failover with circuit breakers, an inactivity watchdog and an
+  append-only event journal.
+- Multi-issue queues discovered from sub-issues and dependencies: one branch, one
+  Pull Request.
+- A read-only live web monitor, one card per active run across every project.
+- Issues from GitHub or from plain files — the local provider needs nothing
+  beyond git.
+- Repository conventions (templates, labels, base branch, commit and branch
+  format) discovered rather than imposed.
 
 ## Commands
 
-### `run` -- Full pipeline (end-to-end)
-
-```bash
-# Run the complete pipeline for an issue
-npx issue-flow run 42
-
-# Resume from a specific phase
-npx issue-flow run 42 --from execute
-
-# Manual mode (artifacts only, no execution)
-npx issue-flow run 42 --mode manual
-
-# Watch the run live in the browser (see "Web Monitoring" below)
-npx issue-flow run 42 --web
+| Command | What it does |
+|---------|--------------|
+| `run <issues...>` | The full pipeline, for one issue or a queue |
+| `resume [issue]` | Continue an interrupted pipeline, explicitly |
+| `generate` | Draft and create an issue on GitHub, locally, or both |
+| `init` | Check prerequisites and report (or create) missing conventions |
+| `analyze`, `prd`, `plan`, `execute`, `review`, `pr`, `pr-review` | The phases, standalone |
+| `status`, `ps`, `runs`, `logs`, `usage`, `pause`, `cancel` | Operate a running pipeline |
+| `agent`, `policy`, `conventions`, `routing` | Inspect what was resolved, and why |
+| `web serve`, `web stop` | The monitoring server |
 
-# Continue User Story numbering from the last used in this project
-npx issue-flow run 42 --continue
+Run `issue-flow <command> --help` for the flags, or read the
+[command reference](https://github.com/fabioassuncao/issue-flow/blob/main/docs/commands.md).
 
-# Force User Story numbering to start at a specific number
-npx issue-flow run 42 --start-us 27
-```
-
-Executes all phases in order: **init** → **analyze** → **prd** → **plan** → **execute** → **review** → **pr**. Automatically resumes from the last incomplete phase if pipeline state exists. On review failure, its findings are saved verbatim to `lastReviewFindings` in `tasks.json`, and a correction cycle (re-execute + re-review) runs up to `maxCorrectionCycles`. The re-execute step reads `lastReviewFindings` and treats the issue as unresolved even if every user story already has `passes: true`, until the findings are addressed and the field is cleared back to `null`.
-
-`--continue` and `--start-us <n>` control User Story (`US-NNN`) numbering continuity across `plan` runs of the same project — see [`plan`](#plan----convert-prd-to-task-plan) below.
-
-### `init` -- Check prerequisites
-
-```bash
-npx issue-flow init
-```
-
-Verifies that `claude`, `gh` (authenticated), and `git` (inside a repo) are available. Reports pass/fail for each with install hints.
+## Where things are written
 
-### `analyze` -- Analyze an issue
-
-```bash
-npx issue-flow analyze 42
-```
-
-Invokes Claude headlessly to fetch issue data, analyze the codebase, and produce a structured analysis saved to `~/.issue-flow/…/issues/42/analysis.md` (see [Pipeline State](#pipeline-state)).
-
-### `prd` -- Generate a PRD
-
-```bash
-npx issue-flow prd 42
-```
-
-Generates a Product Requirements Document from the issue analysis. Reads `analysis.md` from the same directory as context if available. Saves to `~/.issue-flow/…/issues/42/prd.md`.
-
-### `plan` -- Convert PRD to task plan
-
-```bash
-npx issue-flow plan 42
-
-# Continue User Story numbering from the last used in this project
-npx issue-flow plan 42 --continue
-
-# Force numbering to start at a specific number, ignoring history
-npx issue-flow plan 42 --start-us 27
-```
-
-Converts the PRD into a structured `~/.issue-flow/…/issues/42/tasks.json` with ordered user stories, acceptance criteria, and pipeline state. Validates the output with zod schemas.
-
-`US-NNN` numbering continues automatically across `plan` runs of the same project: the highest number already used in any of the project's `tasks.json` files is recovered and the next story continues from there, falling back to `US-001` when the project has no history yet. `--continue` names that automatic recovery explicitly; `--start-us <n>` forces a specific starting number instead, ignoring history — the two flags are mutually exclusive. The decision is always printed to the terminal and recorded in the project's `metadata.json` (`userStoryNumbering`) for audit. See the root [README](https://github.com/fabioassuncao/issue-flow#user-story-numbering-continuity) for the full cascade.
-
-### `execute` -- Run the story execution loop
-
-```bash
-npx issue-flow execute --issue 42
-npx issue-flow execute --issue 42 --max-iterations 15
-npx issue-flow execute --issue 42 --retry-forever
-```
-
-Runs the iterative agent loop. Each iteration is a fresh Claude instance that picks the next pending story, implements it, runs quality checks, and commits.
-
-| Flag | Description |
-|------|-------------|
-| `--issue N` | Issue number -- reads artifacts from `~/.issue-flow/…/issues/N/` |
-| `--max-iterations N` | Stop after N iterations (default: unlimited) |
-| `--retry-limit N` | Retry transient Claude failures up to N consecutive times (default: 10) |
-| `--retry-forever` | Retry transient Claude failures indefinitely |
-
-### `review` -- Validate the implementation
-
-```bash
-npx issue-flow review 42
-```
-
-Invokes Claude headlessly to verify acceptance criteria, run tests, and check for regressions. Outputs `PASS` or `FAIL` with findings.
-
-### `pr` -- Create a pull request
-
-```bash
-npx issue-flow pr 42
-```
-
-Creates a well-structured PR referencing the issue, with summary and test plan.
-
-### `generate` -- Create a new issue
-
-```bash
-npx issue-flow generate --prompt "Add dark mode support to the settings page"
-```
-
-Analyzes the project and creates a detailed GitHub issue via Claude headless.
-
-## Web Monitoring
-
-`run` and `execute` support an optional (off by default) real-time monitoring mode: a local HTTP server (plain `node:http`, zero new dependencies) serves a self-contained, read-only web UI with live progress -- current phase and activity, user stories, commits, pull requests, logs, and time estimates.
-
-```bash
-# Enable with defaults -- binds to 0.0.0.0:3737, reachable from your LAN/VPN
-npx issue-flow run 42 --web
-
-# Restrict to this machine only
-npx issue-flow run 42 --web --host 127.0.0.1
-```
-
-Each setting resolves with the precedence **CLI flag > environment variable > `.issue-flow.json` > default**:
-
-| CLI flag | Environment variable | `.issue-flow.json` key | Default |
-|----------|----------------------|------------------------|---------|
-| `--web` / `--serve` | `ISSUE_FLOW_WEB` | `web.enabled` | `false` |
-| `--port <n>` | `ISSUE_FLOW_WEB_PORT` | `web.port` | `3737` |
-| `--host <h>` | `ISSUE_FLOW_WEB_HOST` | `web.host` | `0.0.0.0` |
-| `--refresh <s>` | `ISSUE_FLOW_WEB_REFRESH` | `web.refreshSeconds` | `5` |
-| `--web-log-limit <n>` | `ISSUE_FLOW_WEB_LOG_LIMIT` | `web.logLimit` | `200` |
-| `--web-no-logs` | -- | `web.includeLogs` | logs included |
-
-Monitoring never affects the pipeline: with `--web` off the behavior is byte-for-byte identical, a busy port just skips the server with a warning, and killing the server mid-run has no effect on the execution. While enabled, the snapshot served at `/api/status` is also persisted to `~/.issue-flow/…/issues/N/session.json` -- outside your working tree, so there is nothing to add to `.gitignore`.
-
-For the full documentation (endpoints, `session.json` format, Tailscale setup), see the [root README](../../README.md#web-monitoring).
-
-## Pipeline State
-
-Each issue's state is tracked in a directory of its own under `~/.issue-flow`, keyed by a deterministic project id and the issue identifier:
+Nothing is written inside your repository. Artifacts live in a machine-wide tree
+keyed by a deterministic project id:
 
 ```
 ~/.issue-flow/projects/<project-id>/issues/42/
-  analysis.md    # Issue analysis
-  prd.md         # Product requirements
-  tasks.json     # Task plan with pipeline state and user stories
-  progress.txt   # Execution log
-  session.json   # Live session snapshot (web monitoring only)
-  pr-review/     # PR review reports and index
+  prd.md   tasks.json   progress.txt   session.json   events.jsonl   pr-review/
 ```
 
-Nothing is written to your repository. A `<projectRoot>/issues/` tree left by an earlier release is copied here automatically on first use and then treated as read-only -- see the [root README](../../README.md#global-storage) for the full layout, the project id derivation and the migration.
-
-The `pipeline` field tracks which phases have completed, enabling resume from any point:
-
-```json
-{
-  "pipeline": {
-    "analyzeCompleted": true,
-    "prdCompleted": true,
-    "jsonCompleted": true,
-    "executionCompleted": false,
-    "reviewCompleted": false,
-    "prCreated": false
-  }
-}
-```
+`ISSUE_FLOW_HOME` relocates the whole tree. A legacy `<projectRoot>/issues/`
+directory from an earlier release is copied in automatically on first use and
+then left read-only.
 
-The top-level `lastReviewFindings` field (`string | null`) holds the verbatim findings of the most recent failed `review` phase. Non-null overrides the "issue already complete" check even when every user story has `passes: true`, so a correction cycle's re-execute step is guaranteed to run instead of exiting immediately — see `core/engine.ts`.
+## Configuration
 
-## Architecture
-
-```
-src/
-  cli.ts                  # Entry point, subcommand registration (commander)
-  config.ts               # Configuration resolution and defaults
-  types.ts                # Shared TypeScript interfaces
-  schemas.ts              # Zod validation schemas
-  commands/
-    init.ts               # Prerequisite verification
-    generate.ts           # Headless issue creation
-    run.ts                # Full pipeline orchestrator
-    analyze.ts            # Headless issue analysis
-    prd.ts                # Headless PRD generation
-    plan.ts               # Headless PRD-to-JSON conversion
-    execute.ts            # Iterative story execution (engine wrapper)
-    review.ts             # Headless implementation review
-    pr.ts                 # Headless PR creation
-  core/
-    engine.ts             # Main agent loop
-    executor.ts           # Claude CLI invocation via execa
-    headless.ts           # Typed wrapper for claude -p invocations
-    pipeline.ts           # Pipeline state machine
-    state-manager.ts      # Typed CRUD for tasks.json
-    prompt-resolver.ts    # Prompt resolution and templating
-    session-state.ts      # Session snapshot reducer and publishers
-    session-publisher.ts  # Global session publisher slot
-    session-git.ts        # Commit/PR enrichment for the snapshot
-  web/
-    server.ts             # Web monitoring HTTP server (assets in web/public/)
-  ui/
-    logger.ts             # Colored logging utilities
-    progress.ts           # Progress bar and iteration headers
-    summary.ts            # Box drawing and summary display
-  utils/
-    shell.ts              # Shell command execution
-    git.ts                # Git operations
-    retry.ts              # Transient failure detection and backoff
-```
+Everything resolves through **CLI flag > environment variable >
+`.issue-flow.json` > `~/.issue-flow/config.json` > default**. Nothing is
+mandatory. See the
+[configuration reference](https://github.com/fabioassuncao/issue-flow/blob/main/docs/configuration.md).
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Build
-npm run build
-
-# Type check
+npm run build       # tsup → dist/
 npm run typecheck
-
-# Run tests
 npm test
-
-# Watch mode
-npm run dev
+npm run smoke       # end-to-end, against deterministic stand-ins for claude and gh
+npm run check       # biome + typecheck
 ```
 
-For the full development setup and local testing guide, see [CONTRIBUTING.md](CONTRIBUTING.md).
-The official release procedure (changelog, version bump, tag, `npm publish`, GitHub
-Release) is documented in [CONTRIBUTING.md → Release process](CONTRIBUTING.md#release-process).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full setup and the release
+process.
 
 ## Credits
 
-Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/) and the [snarktank/ralph](https://github.com/snarktank/ralph) repository.
+Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/) and the
+[snarktank/ralph](https://github.com/snarktank/ralph) repository.
 
-## See Also
+## License
 
-- [Skills & Sub-Agent Architecture](../../docs/skills-and-agents.md) -- Using Issue Flow interactively via Claude Code skills and the `resolve-issue` sub-agent.
+[MIT](LICENSE)

package/dist/agent-BXRIEKVM.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+import {
+  GLOBAL_CONFIG_FILENAME,
+  PROJECT_CONFIG_FILENAME,
+  describeRunAgents,
+  loadAgentConfig,
+  probeAgent
+} from "./chunk-CNBYCMSU.js";
+import "./chunk-HQAHNIAR.js";
+import {
+  printError,
+  printSuccess
+} from "./chunk-IYV6KNVF.js";
+import "./chunk-6FDFRNXZ.js";
+import "./chunk-P3LRUNC6.js";
+import "./chunk-DIG5XKQQ.js";
+import {
+  AGENT_PHASES,
+  AGENT_SCHEMA_VERSION,
+  isAgentPhase,
+  isAgentProviderId
+} from "./chunk-NEZZ6KDR.js";
+import {
+  getGlobalRoot
+} from "./chunk-TX5WIVYP.js";
+import {
+  getProjectRoot
+} from "./chunk-KQHB7ZT3.js";
+import {
+  writeFileAtomic
+} from "./chunk-7Z4Y3VKM.js";
+import "./chunk-XEYH6ZZI.js";
+
+// src/commands/agent.ts
+import { mkdir, readFile } from "fs/promises";
+import { dirname, join } from "path";
+var AGENT_COMMAND_SCHEMA_VERSION = AGENT_SCHEMA_VERSION;
+function originLabel(origin) {
+  switch (origin) {
+    case "default":
+      return "default";
+    case "global":
+      return "~/.issue-flow/config.json";
+    case "project":
+      return ".issue-flow.json";
+    case "env":
+      return "ISSUE_FLOW_*";
+    case "cli":
+      return "CLI";
+    default:
+      return origin;
+  }
+}
+function formatPhaseLine(phase, provider, model, origin, inherited) {
+  const modelBit = model ? ` \xB7 ${model}` : "";
+  const source = inherited ? "herdado do padr\xE3o" : originLabel(origin);
+  return `${`  ${phase.padEnd(12)} ${provider}${modelBit}`.padEnd(40)}(${source})`;
+}
+async function runAgent(options = {}) {
+  const config = await loadAgentConfig();
+  const summary = await describeRunAgents();
+  const [claude, codex, cursor, antigravity] = await Promise.all([
+    probeAgent("claude"),
+    probeAgent("codex"),
+    probeAgent("cursor"),
+    probeAgent("antigravity")
+  ]);
+  if (options.json === true) {
+    const phases = {};
+    for (const phase of AGENT_PHASES) {
+      const resolved = summary.byPhase[phase];
+      const inherited = config.phases[phase] === void 0;
+      phases[phase] = {
+        provider: resolved.provider,
+        model: resolved.model,
+        inherited
+      };
+    }
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: AGENT_COMMAND_SCHEMA_VERSION,
+          default: {
+            provider: summary.defaultProvider,
+            model: summary.defaultModel
+          },
+          phases,
+          availability: [
+            {
+              id: "claude",
+              installed: claude.installed,
+              version: claude.version,
+              authenticated: claude.authenticated
+            },
+            {
+              id: "codex",
+              installed: codex.installed,
+              version: codex.version,
+              authenticated: codex.authenticated
+            },
+            {
+              id: "cursor",
+              installed: cursor.installed,
+              version: cursor.version,
+              authenticated: cursor.authenticated
+            },
+            {
+              id: "antigravity",
+              installed: antigravity.installed,
+              version: antigravity.version,
+              authenticated: antigravity.authenticated,
+              authProbe: "none"
+            }
+          ]
+        },
+        null,
+        2
+      )
+    );
+    return 0;
+  }
+  const modelLabel = summary.defaultModel ?? "(default do provider)";
+  console.log(`Agente padr\xE3o   ${summary.defaultProvider.padEnd(22)} (${originLabel("default")})`);
+  console.log(`Modelo          ${modelLabel}`);
+  console.log("");
+  console.log("Por fase");
+  for (const phase of AGENT_PHASES) {
+    const resolved = summary.byPhase[phase];
+    const inherited = config.phases[phase] === void 0;
+    console.log(
+      formatPhaseLine(
+        phase,
+        resolved.provider,
+        resolved.model,
+        inherited ? "default" : "project",
+        inherited
+      )
+    );
+  }
+  console.log("");
+  console.log("Disponibilidade");
+  console.log(`  claude        ${(claude.version ?? "\u2014").padEnd(16)} ${claude.detail}`);
+  console.log(`  codex         ${(codex.version ?? "\u2014").padEnd(16)} ${codex.detail}`);
+  console.log(`  cursor        ${(cursor.version ?? "\u2014").padEnd(16)} ${cursor.detail}`);
+  console.log(
+    `  antigravity   ${(antigravity.version ?? "\u2014").padEnd(16)} ${antigravity.detail} (no auth probe)`
+  );
+  if (antigravity.installed) {
+    console.log(
+      "  Warning: every Antigravity invocation passes --dangerously-skip-permissions. --mode plan is the write containment."
+    );
+  }
+  return 0;
+}
+async function runAgentUse(providerRaw, options = {}) {
+  if (!isAgentProviderId(providerRaw)) {
+    printError(
+      `Unknown agent provider '${providerRaw}'. Valid providers: claude, codex, cursor, antigravity.`
+    );
+    return 1;
+  }
+  const provider = providerRaw;
+  let phase;
+  if (options.phase !== void 0) {
+    if (!isAgentPhase(options.phase)) {
+      printError(
+        `Unknown agent phase '${options.phase}'. Valid phases: ${AGENT_PHASES.join(", ")}.`
+      );
+      return 1;
+    }
+    phase = options.phase;
+  }
+  const target = options.project === true ? "project" : "global";
+  try {
+    const path = await writeAgentPreference({
+      target,
+      provider,
+      model: options.model,
+      phase
+    });
+    printSuccess(`Wrote agent preference to ${path}`);
+    return 0;
+  } catch (err) {
+    printError(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+async function writeAgentPreference(input) {
+  const path = input.target === "global" ? join(getGlobalRoot(), GLOBAL_CONFIG_FILENAME) : join(input.projectRoot ?? await getProjectRoot(), PROJECT_CONFIG_FILENAME);
+  let existing = {};
+  try {
+    const raw = await readFile(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      existing = parsed;
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw new Error(`Could not read ${path}: ${err.message}`);
+    }
+  }
+  const currentAgent = existing.agent !== null && typeof existing.agent === "object" && !Array.isArray(existing.agent) ? { ...existing.agent } : {};
+  if (input.phase) {
+    const phases = currentAgent.phases !== null && typeof currentAgent.phases === "object" && !Array.isArray(currentAgent.phases) ? { ...currentAgent.phases } : {};
+    phases[input.phase] = {
+      provider: input.provider,
+      ...input.model ? { model: input.model } : {}
+    };
+    currentAgent.phases = phases;
+  } else {
+    currentAgent.provider = input.provider;
+    if (input.model) currentAgent.model = input.model;
+    else delete currentAgent.model;
+  }
+  existing.agent = currentAgent;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFileAtomic(path, `${JSON.stringify(existing, null, 2)}
+`);
+  if (input.provider === "cursor") {
+    const { ensureCursorStorageGrant } = await import("./permissions-7NMDFU27.js");
+    await ensureCursorStorageGrant({
+      mode: input.target === "project" ? "project" : "global",
+      ...input.projectRoot === void 0 ? {} : { projectRoot: input.projectRoot }
+    });
+  }
+  return path;
+}
+async function persistFirstAgentChoice(provider) {
+  return writeAgentPreference({ target: "global", provider });
+}
+export {
+  AGENT_COMMAND_SCHEMA_VERSION,
+  persistFirstAgentChoice,
+  runAgent,
+  runAgentUse,
+  writeAgentPreference
+};
+//# sourceMappingURL=agent-BXRIEKVM.js.map

package/dist/agent-BXRIEKVM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/agent.ts"],"sourcesContent":["import { mkdir, readFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { probeAgent } from '../agents/availability.js';\nimport { describeRunAgents } from '../agents/resolve.js';\nimport {\n  AGENT_PHASES,\n  AGENT_SCHEMA_VERSION,\n  type AgentPhase,\n  type AgentProviderId,\n  isAgentPhase,\n  isAgentProviderId,\n} from '../agents/types.js';\nimport { GLOBAL_CONFIG_FILENAME, loadAgentConfig, PROJECT_CONFIG_FILENAME } from '../config.js';\nimport { getGlobalRoot } from '../storage/paths.js';\nimport { printError, printSuccess } from '../ui/logger.js';\nimport { writeFileAtomic } from '../utils/fs.js';\nimport { getProjectRoot } from '../utils/git.js';\n\nexport const AGENT_COMMAND_SCHEMA_VERSION = AGENT_SCHEMA_VERSION;\n\nexport interface AgentCommandOptions {\n  json?: boolean;\n}\n\nexport interface AgentUseOptions {\n  model?: string;\n  global?: boolean;\n  project?: boolean;\n  phase?: string;\n}\n\nfunction originLabel(origin: string): string {\n  switch (origin) {\n    case 'default':\n      return 'default';\n    case 'global':\n      return '~/.issue-flow/config.json';\n    case 'project':\n      return '.issue-flow.json';\n    case 'env':\n      return 'ISSUE_FLOW_*';\n    case 'cli':\n      return 'CLI';\n    default:\n      return origin;\n  }\n}\n\nfunction formatPhaseLine(\n  phase: AgentPhase,\n  provider: string,\n  model: string | null,\n  origin: string,\n  inherited: boolean,\n): string {\n  const modelBit = model ? ` · ${model}` : '';\n  const source = inherited ? 'herdado do padrão' : originLabel(origin);\n  return `${`  ${phase.padEnd(12)} ${provider}${modelBit}`.padEnd(40)}(${source})`;\n}\n\nexport async function runAgent(options: AgentCommandOptions = {}): Promise<number> {\n  const config = await loadAgentConfig();\n  const summary = await describeRunAgents();\n  const [claude, codex, cursor, antigravity] = await Promise.all([\n    probeAgent('claude'),\n    probeAgent('codex'),\n    probeAgent('cursor'),\n    probeAgent('antigravity'),\n  ]);\n\n  if (options.json === true) {\n    const phases: Record<string, unknown> = {};\n    for (const phase of AGENT_PHASES) {\n      const resolved = summary.byPhase[phase];\n      const inherited = config.phases[phase] === undefined;\n      phases[phase] = {\n        provider: resolved.provider,\n        model: resolved.model,\n        inherited,\n      };\n    }\n    console.log(\n      JSON.stringify(\n        {\n          schemaVersion: AGENT_COMMAND_SCHEMA_VERSION,\n          default: {\n            provider: summary.defaultProvider,\n            model: summary.defaultModel,\n          },\n          phases,\n          availability: [\n            {\n              id: 'claude',\n              installed: claude.installed,\n              version: claude.version,\n              authenticated: claude.authenticated,\n            },\n            {\n              id: 'codex',\n              installed: codex.installed,\n              version: codex.version,\n              authenticated: codex.authenticated,\n            },\n            {\n              id: 'cursor',\n              installed: cursor.installed,\n              version: cursor.version,\n              authenticated: cursor.authenticated,\n            },\n            {\n              id: 'antigravity',\n              installed: antigravity.installed,\n              version: antigravity.version,\n              authenticated: antigravity.authenticated,\n              authProbe: 'none',\n            },\n          ],\n        },\n        null,\n        2,\n      ),\n    );\n    return 0;\n  }\n\n  const modelLabel = summary.defaultModel ?? '(default do provider)';\n  console.log(`Agente padrão   ${summary.defaultProvider.padEnd(22)} (${originLabel('default')})`);\n  console.log(`Modelo          ${modelLabel}`);\n  console.log('');\n  console.log('Por fase');\n  for (const phase of AGENT_PHASES) {\n    const resolved = summary.byPhase[phase];\n    const inherited = config.phases[phase] === undefined;\n    console.log(\n      formatPhaseLine(\n        phase,\n        resolved.provider,\n        resolved.model,\n        inherited ? 'default' : 'project',\n        inherited,\n      ),\n    );\n  }\n  console.log('');\n  console.log('Disponibilidade');\n  console.log(`  claude        ${(claude.version ?? '—').padEnd(16)} ${claude.detail}`);\n  console.log(`  codex         ${(codex.version ?? '—').padEnd(16)} ${codex.detail}`);\n  console.log(`  cursor        ${(cursor.version ?? '—').padEnd(16)} ${cursor.detail}`);\n  console.log(\n    `  antigravity   ${(antigravity.version ?? '—').padEnd(16)} ${antigravity.detail} (no auth probe)`,\n  );\n  if (antigravity.installed) {\n    console.log(\n      '  Warning: every Antigravity invocation passes --dangerously-skip-permissions. --mode plan is the write containment.',\n    );\n  }\n  return 0;\n}\n\nexport async function runAgentUse(\n  providerRaw: string,\n  options: AgentUseOptions = {},\n): Promise<number> {\n  if (!isAgentProviderId(providerRaw)) {\n    printError(\n      `Unknown agent provider '${providerRaw}'. Valid providers: claude, codex, cursor, antigravity.`,\n    );\n    return 1;\n  }\n  const provider = providerRaw as AgentProviderId;\n\n  let phase: AgentPhase | undefined;\n  if (options.phase !== undefined) {\n    if (!isAgentPhase(options.phase)) {\n      printError(\n        `Unknown agent phase '${options.phase}'. Valid phases: ${AGENT_PHASES.join(', ')}.`,\n      );\n      return 1;\n    }\n    phase = options.phase;\n  }\n\n  const target: 'global' | 'project' = options.project === true ? 'project' : 'global';\n  try {\n    const path = await writeAgentPreference({\n      target,\n      provider,\n      model: options.model,\n      phase,\n    });\n    printSuccess(`Wrote agent preference to ${path}`);\n    return 0;\n  } catch (err) {\n    printError(err instanceof Error ? err.message : String(err));\n    return 1;\n  }\n}\n\nexport async function writeAgentPreference(input: {\n  target: 'global' | 'project';\n  provider: AgentProviderId;\n  model?: string;\n  phase?: AgentPhase;\n  projectRoot?: string;\n}): Promise<string> {\n  const path =\n    input.target === 'global'\n      ? join(getGlobalRoot(), GLOBAL_CONFIG_FILENAME)\n      : join(input.projectRoot ?? (await getProjectRoot()), PROJECT_CONFIG_FILENAME);\n\n  let existing: Record<string, unknown> = {};\n  try {\n    const raw = await readFile(path, 'utf-8');\n    const parsed: unknown = JSON.parse(raw);\n    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      existing = parsed as Record<string, unknown>;\n    }\n  } catch (err: unknown) {\n    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {\n      throw new Error(`Could not read ${path}: ${(err as Error).message}`);\n    }\n  }\n\n  const currentAgent =\n    existing.agent !== null && typeof existing.agent === 'object' && !Array.isArray(existing.agent)\n      ? { ...(existing.agent as Record<string, unknown>) }\n      : {};\n\n  if (input.phase) {\n    const phases =\n      currentAgent.phases !== null &&\n      typeof currentAgent.phases === 'object' &&\n      !Array.isArray(currentAgent.phases)\n        ? { ...(currentAgent.phases as Record<string, unknown>) }\n        : {};\n    phases[input.phase] = {\n      provider: input.provider,\n      ...(input.model ? { model: input.model } : {}),\n    };\n    currentAgent.phases = phases;\n  } else {\n    currentAgent.provider = input.provider;\n    if (input.model) currentAgent.model = input.model;\n    else delete currentAgent.model;\n  }\n\n  existing.agent = currentAgent;\n  await mkdir(dirname(path), { recursive: true });\n  await writeFileAtomic(path, `${JSON.stringify(existing, null, 2)}\\n`);\n  if (input.provider === 'cursor') {\n    const { ensureCursorStorageGrant } = await import('../agents/permissions.js');\n    await ensureCursorStorageGrant({\n      mode: input.target === 'project' ? 'project' : 'global',\n      ...(input.projectRoot === undefined ? {} : { projectRoot: input.projectRoot }),\n    });\n  }\n  return path;\n}\n\n/** Used by init to persist a first-run choice without touching other keys. */\nexport async function persistFirstAgentChoice(provider: AgentProviderId): Promise<string> {\n  return writeAgentPreference({ target: 'global', provider });\n}\n"],"mappings":"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","names":[]}