acdev 1.0.2 → 1.0.4

package/.acdev/.env.example

@@ -1,10 +1,16 @@
-# Optional. Prefer Claude Code subscription auth instead:
+# Optional. GitHub CLI for issues/PRs — alternatives to interactive `gh auth login`:
+# GH_TOKEN=ghp_your_personal_access_token
+# GITHUB_TOKEN is also honored if GH_TOKEN is unset.
+# SSH remotes can push/fetch git but do not authenticate gh for issues/PRs.
+#
+# Claude — prefer Claude Code subscription auth:
 #   claude auth login
 # Or a long-lived subscription token:
 #   claude setup-token
 #   CLAUDE_CODE_OAUTH_TOKEN=...
 #
-# API Console billing (pay-as-you-go) — only if you have an Anthropic API key:
+# API Console billing (pay-as-you-go) — only if you have an Anthropic API key.
+# An API key takes precedence over subscription login:
 # ANTHROPIC_API_KEY=sk-ant-your-key-here
 #
 # Jira Cloud (only when ticketSource is "jira" in Settings / config.json):

package/README.md

@@ -5,11 +5,13 @@ Local CLI + web UI for running AI coding agents on GitHub Issues or Jira tickets
 ## Prerequisites
 
 - Node.js 20+
-- [GitHub CLI](https://cli.github.com/) (`gh`) authenticated (`gh auth login`) — required for PRs (and for GitHub Issues when that is the ticket source)
-- Claude authentication (see [Authentication](#authentication) below)
+- [GitHub CLI](https://cli.github.com/) (`gh`) on your `PATH` — required to fetch GitHub issues and open PRs. You can install `gh` first and authenticate later (see below).
 - A git repository with a `develop` branch on `origin` (or configure another base branch)
+- Optional: Claude authentication for real agent runs (or use `--stub-agent` for UI-only testing)
 - Optional: Jira Cloud credentials when using Jira as the ticket source (see [Jira](#jira-ticket-source))
 
+You do **not** need GitHub or Claude tokens before starting `acdev`. The server always starts (as long as you are inside a git repo); configure auth in **Settings → Authentication**, then enqueue jobs.
+
 ## Install
 
 ```bash
@@ -27,9 +29,27 @@ npm link   # optional — makes `acdev` available globally
 
 ## Authentication
 
-`acdev` uses the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), which shares credentials with [Claude Code](https://code.claude.com/docs/en/authentication). You need **one** of the following (`.env` is optional):
+`acdev` starts even when auth is missing and prints a warning. Configure GitHub and Claude from **Settings → Authentication** in the web UI (tokens are written to `.acdev/.env`, gitignored) or by editing that file directly. Leave a Settings field blank to keep the current secret. Shell environment variables override `.env` on startup; saving in Settings updates the running process immediately so status refreshes without a restart.
+
+Enqueueing issues, retrying jobs, and applying review feedback require Claude (unless `--stub-agent`). Opening a PR always requires GitHub auth. The Overview banner prompts you when auth is incomplete.
+
+`.env` is optional when you already use `gh auth login` and `claude auth login` on the machine.
+
+### GitHub (issues / PRs)
+
+`acdev` talks to GitHub through `gh`. **Any one** of these is enough:
+
+1. **Existing CLI login** — `gh auth login` (browser/device). Settings shows this as authenticated.
+2. **Personal access token** — paste a PAT in **Settings → GitHub / PR auth**, or set `GH_TOKEN` (or `GITHUB_TOKEN`) in `.acdev/.env`. `gh` reads those env vars, so no interactive login is required. Non-interactive CLI equivalent: `echo YOUR_PAT | gh auth login --with-token -h github.com`.
+3. **SSH remotes are not a substitute.** An SSH `origin` can push/fetch git, but it does **not** authenticate `gh` for issues or PRs. Settings may show the origin URL as read-only info.
 
-### Option A — Claude Pro / Max subscription (browser login)
+On a fresh machine: install `gh`, start `acdev`, then paste a PAT in Settings (or set `GH_TOKEN` in `.acdev/.env`). You can also copy `.acdev/.env.example` to `.acdev/.env` before starting.
+
+### Claude
+
+`acdev` uses the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), which shares credentials with [Claude Code](https://code.claude.com/docs/en/authentication). You need **one** of the following (API key wins if more than one is set):
+
+#### Option A — Claude Pro / Max subscription (browser login)
 
 Best when you already pay for claude.ai and are not allowed to use API keys.
 
@@ -44,14 +64,18 @@ claude auth status
 
 3. Run `acdev` with **no** `ANTHROPIC_API_KEY` set (an API key would take precedence and bill the Console instead of your subscription)
 
+Settings cannot complete browser OAuth — that still needs `claude auth login` on the host. Detected method in Settings: `claude-code-login`.
+
 For CI / non-interactive shells, generate a long-lived subscription token instead:
 
 ```bash
 claude setup-token
-export CLAUDE_CODE_OAUTH_TOKEN=...   # or put it in `.acdev/.env`
+export CLAUDE_CODE_OAUTH_TOKEN=...   # or paste it in Settings → Claude authentication
 ```
 
-### Option B — Anthropic API key (Console / pay-as-you-go)
+#### Option B — Anthropic API key (Console / pay-as-you-go)
+
+Paste the key in **Settings → Claude authentication**, or:
 
 ```bash
 cp .acdev/.env.example .acdev/.env
@@ -66,7 +90,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 acdev
 ```
 
-A Claude.ai browser-only subscription does **not** give you an API key. API keys come from the [Claude Console](https://platform.claude.com/) and are billed separately from Pro/Max.
+A Claude.ai browser-only subscription does **not** give you an API key. API keys come from the [Claude Console](https://platform.claude.com/) and are billed separately from Pro/Max. To switch back to subscription login, clear the saved API key in Settings (or omit it from `.env`).
 
 ## Jira ticket source
 
@@ -101,13 +125,13 @@ Optional **Rules** in Settings can move the Jira ticket to a target status (e.g.
 
 ## Usage
 
-From inside a cloned git repository (after authenticating as above):
+From inside a cloned git repository:
 
 ```bash
 acdev
 ```
 
-The tool starts a local server (default port `4848`), opens the browser, and shows the web UI.
+The tool starts a local server (default port `4848`), opens the browser, and shows the web UI. If GitHub or Claude auth is missing, the CLI warns and the UI shows a banner — open **Settings → Authentication** to add tokens, then enqueue jobs.
 
 ### CLI flags
 
@@ -136,13 +160,13 @@ The tool starts a local server (default port `4848`), opens the browser, and sho
 | **Review** | Edit PR title/body, colored diff, approve draft or ready, reject, or Clear |
 | **Logs** | Cross-job activity log with job filter |
 | **Alerts** | Failures / warnings with Retry, Clear, and dismiss |
-| **Settings** | Ticket source (GitHub / Jira), Jira connection, post-PR rules, and `.acdev/config.json` fields |
+| **Settings** | Ticket source (GitHub / Jira), GitHub + Claude authentication, Jira connection, post-PR rules, and `.acdev/config.json` fields |
 
-Model selection lives in the sidebar (and Settings). Default is **Sonnet 5** (`claude-sonnet-5`).
+Model selection lives in **Settings → Configuration**. The sidebar shows the current model as a read-only label. Default is **Sonnet 5** (`claude-sonnet-5`).
 
 ## Configuration
 
-Optional secrets go in `.acdev/.env` (copy from `.acdev/.env.example`). The file is gitignored and not required when using `claude auth login` with GitHub Issues only.
+Optional secrets go in `.acdev/.env` (copy from `.acdev/.env.example`), or paste them in **Settings**. The file is gitignored and not required when using `gh auth login` and `claude auth login` with GitHub Issues only.
 
 Prefer **Settings** in the web UI to change runtime config — values persist to `.acdev/config.json` and apply to the next job without restart. You can still edit the file by hand if you prefer.
 
@@ -160,26 +184,41 @@ On first run, creates `.acdev/config.json`:
   "jiraBaseUrl": "",
   "jiraPrLinkPhrase": "Relates to",
   "jiraRules": {
-    "afterPrOpened": { "enabled": false, "targetStatus": "In Review" }
+    "afterPrOpened": {
+      "enabled": false,
+      "action": "none",
+      "targetStatus": "In Review",
+      "label": ""
+    }
   },
   "githubRules": {
-    "afterPrOpened": { "enabled": false, "action": "none", "label": "" }
+    "afterPrOpened": {
+      "enabled": false,
+      "action": "none",
+      "targetStatus": "In Review",
+      "label": ""
+    }
   }
 }
 ```
 
-`jiraRules.afterPrOpened` transitions the issue to a workflow status whose name matches `targetStatus` (case-insensitive). `githubRules.afterPrOpened.action` is `none`, `add_label`, or `close_issue` (GitHub issues have no built-in board statuses; Projects API is not used).
+`jiraRules.afterPrOpened` and `githubRules.afterPrOpened` share the same shape: `enabled`, `action` (`none` | `set_status` | `add_label` | `close_issue`), `targetStatus`, and `label`.
+
+| Action | Jira | GitHub |
+|--------|------|--------|
+| `set_status` | Workflow transition to a status whose name matches `targetStatus` (case-insensitive) | Applies a label named after `targetStatus` via `gh issue edit --add-label` (Projects board API is not used) |
+| `add_label` | Adds the Jira label via REST `update.labels` `{ add }` | Adds the issue label via `gh` |
+| `close_issue` | Transitions to a Done-category status, or else a Done/Closed/Resolved-like name | Closes the GitHub issue |
 
-Supported `model` values (Claude Agent SDK):
+Legacy Jira configs that only had `enabled` + `targetStatus` (no `action`) still work: when enabled, they migrate to `action: "set_status"`.
+Supported `model` values are Claude Agent SDK / Claude Code model ids (aliases like `claude-sonnet-5` / `claude-opus-5` / `sonnet`, or Anthropic API model ids). The Settings dropdown is populated by `GET /api/models`:
 
-| UI label | Model ID |
-|----------|----------|
-| Sonnet 5 (default) | `claude-sonnet-5` |
-| Opus 5 | `claude-opus-5` |
+1. When `ANTHROPIC_API_KEY` (or `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN`) is set — or Claude Code browser login credentials are readable from the local store — acdev calls Anthropic’s Models API (`GET /v1/models`) and merges results with curated Claude Code aliases.
+2. Otherwise (or if the live fetch fails), the UI falls back to a curated list (Sonnet/Opus/Fable/Haiku generations + common Code aliases such as `sonnet` / `opus`) so the dropdown stays useful without an API key. The Settings hint notes when the list is static (`source: "fallback"`).
 
-Unknown or removed model IDs in an existing config are migrated to `claude-sonnet-5` on load.
+Empty or malformed model IDs in an existing config are migrated to `claude-sonnet-5` on load. Other valid ids are kept as-is.
 
-Change via **Settings** / the sidebar model toggle (`PATCH /api/config`) or `--model`. Takes effect for the next agent run without restart.
+Change via **Settings → Configuration** (`PATCH /api/config`) or `--model`. Takes effect for the next agent run without restart.
 
 Job state is persisted in `.acdev/state.json`.
 
@@ -193,11 +232,13 @@ npm test
 
 ## Architecture
 
-- `bin/acdev.js` — CLI entry, startup checks (`gh` always; Jira not required at startup)
+- `bin/acdev.js` — CLI entry; soft-checks `gh` / Claude auth (warns, does not exit). Tokens in `.acdev/.env` are loaded before auth checks. Job APIs reject until auth is OK.
 - `src/claude-auth.js` — Anthropic API key / Claude Code subscription auth detection
+- `src/gh-auth.js` — GitHub CLI auth (`gh auth login` or `GH_TOKEN`)
 - `src/server.js` — Express API, SSE logs, job queue, config + Jira test endpoints
 - `src/git.js` — Worktree lifecycle (`issue-<id>` paths), `feat/`/`fix/` branch naming, diff, push
 - `src/agent.js` — Claude Agent SDK integration (`options.model`); GitHub vs Jira prompts
+- `src/models.js` — `GET /api/models` list (Anthropic Models API + curated fallback)
 - `src/github.js` — Issue URL parsing, issue fetch via `gh`, `createPr({ draft })`
 - `src/jira.js` — Jira Cloud parse/fetch/test + issuetype → feat/fix
 - `src/config.js` — Load/save `.acdev/config.json` including ticket source
@@ -217,7 +258,8 @@ npm test
 | `POST` | `/api/jobs/:id/reject` | Discard worktree (keeps job as `discarded`) |
 | `DELETE` | `/api/jobs/:id` | Clear job from history (worktree best-effort); 409 if in-flight |
 | `POST` | `/api/jobs/:id/retry` | Re-queue failed/discarded |
-| `GET` | `/api/config` | Editable config + models + Jira status (token masked) |
+| `GET` | `/api/config` | Editable config + curated models + Jira status (token masked) |
+| `GET` | `/api/models` | `{ models, selected, source }` — live Anthropic list or curated fallback |
 | `PATCH` | `/api/config` | Partial update including `ticketSource`, `jiraBaseUrl`; `jiraEmail` / `jiraApiToken` → `.env` |
 | `POST` | `/api/jira/test` | Test Jira credentials (`GET /rest/api/3/myself`) |
 

package/bin/acdev.js

@@ -3,8 +3,8 @@
 import { execSync } from 'node:child_process';
 import http from 'node:http';
 import open from 'open';
-import { checkClaudeAuth } from '../src/claude-auth.js';
-import { checkGhAuth } from '../src/gh-auth.js';
+import { checkClaudeAuth, formatClaudeAuthError } from '../src/claude-auth.js';
+import { checkGhAuth, formatGhAuthError } from '../src/gh-auth.js';
 import { loadConfig } from '../src/config.js';
 import { loadEnv } from '../src/env.js';
 import { migrateLegacyDataDir, migrateLegacyWorktreesDir } from '../src/paths.js';
@@ -58,38 +58,26 @@ async function main() {
   migrateLegacyWorktreesDir(repoRoot);
   loadEnv(repoRoot);
 
+  // Soft auth: always start the server so Settings can add tokens.
+  // Job endpoints reject with a clear 4xx until auth is configured.
   const ghAuth = checkGhAuth();
   if (!ghAuth.ok) {
-    if (ghAuth.reason === 'not-found') {
-      console.error(
-        '✖ GitHub CLI (gh) not found in PATH. Install it from https://cli.github.com/'
-      );
-    } else {
-      console.error(
-        '✖ GitHub CLI not authenticated for github.com. Run `gh auth login -h github.com` first.'
-      );
-    }
-    process.exit(1);
+    console.warn(formatGhAuthError(ghAuth).replace(/^✖/m, '⚠'));
+    console.warn(
+      '⚠ Continuing without GitHub auth — configure in Settings → Authentication, then enqueue jobs.'
+    );
   }
 
   if (!opts.stubAgent) {
     const claudeAuth = checkClaudeAuth();
     if (!claudeAuth.ok) {
-      console.error(
-        [
-          '✖ No Anthropic / Claude Code authentication found.',
-          '',
-          'Authenticate with one of:',
-          '  1. Claude Pro/Max subscription (browser): install Claude Code, then run',
-          '     `claude auth login` (or `claude setup-token` and set CLAUDE_CODE_OAUTH_TOKEN)',
-          '  2. Anthropic API key (API billing): set ANTHROPIC_API_KEY in the environment',
-          '     or in `.acdev/.env` (optional file; copy from `.acdev/.env.example`)',
-          '',
-          'For UI-only testing without auth: pass `--stub-agent`.',
-        ].join('\n')
+      console.warn(formatClaudeAuthError(claudeAuth).replace(/^✖/m, '⚠'));
+      console.warn(
+        '⚠ Continuing without Claude auth — configure in Settings → Authentication (or pass --stub-agent).'
       );
-      process.exit(1);
     }
+  } else {
+    console.log('✓ Stub agent enabled (Claude auth not required)');
   }
 
   const config = loadConfig(repoRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acdev",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Local CLI + web UI for running AI agents on GitHub issues via git worktrees",
   "type": "module",
   "bin": {