acdev 1.0.3 → 1.0.5

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`) — required for PRs (and for GitHub Issues when that is the ticket source). Authenticate with `gh auth login` **or** a PAT in Settings / `GH_TOKEN` (see [Authentication](#authentication))
-- 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,7 +29,9 @@ npm link   # optional — makes `acdev` available globally
 
 ## Authentication
 
-Configure GitHub and Claude from **Settings** 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.
+`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.
 
@@ -39,7 +43,7 @@ Configure GitHub and Claude from **Settings** in the web UI (tokens are written
 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.
 
-On a machine with no browser, copy `.acdev/.env.example` to `.acdev/.env`, set `GH_TOKEN`, then start `acdev`. After the UI is running you can update the token in Settings.
+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
 
@@ -121,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
 
@@ -228,7 +232,7 @@ npm test
 
 ## Architecture
 
-- `bin/acdev.js` — CLI entry, startup checks (`gh` always; Jira not required at startup). Tokens in `.acdev/.env` are loaded before auth checks
+- `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

package/bin/acdev.js

@@ -58,18 +58,21 @@ async function main() {
   migrateLegacyWorktreesDir(repoRoot);
   loadEnv(repoRoot);
 
+  // Soft auth: never exit for missing GitHub/Claude credentials.
+  // 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) {
-    console.error(formatGhAuthError(ghAuth));
-    process.exit(1);
+    console.warn(formatGhAuthError(ghAuth));
   }
 
   if (!opts.stubAgent) {
     const claudeAuth = checkClaudeAuth();
     if (!claudeAuth.ok) {
-      console.error(formatClaudeAuthError(claudeAuth));
-      process.exit(1);
+      console.warn(formatClaudeAuthError(claudeAuth));
     }
+  } 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.3",
+  "version": "1.0.5",
   "description": "Local CLI + web UI for running AI agents on GitHub issues via git worktrees",
   "type": "module",
   "bin": {

package/public/app.js

@@ -163,6 +163,7 @@ let ticketSource = 'github';
  *   anthropicApiKeyMasked?: string | null,
  *   claudeOauthTokenSet?: boolean,
  *   claudeOauthTokenMasked?: string | null,
+ *   stubAgent?: boolean,
  * }} */
 let appConfig = {};
 
@@ -178,6 +179,9 @@ const els = {
   navBadgeRuns: document.getElementById('nav-badge-runs'),
   navBadgeReview: document.getElementById('nav-badge-review'),
   navBadgeAlerts: document.getElementById('nav-badge-alerts'),
+  authBanner: document.getElementById('auth-banner'),
+  authBannerText: document.getElementById('auth-banner-text'),
+  authBannerBtn: document.getElementById('auth-banner-btn'),
   issueUrls: document.getElementById('issue-urls'),
   issueUrlsLabel: document.getElementById('issue-urls-label'),
   enqueueFeedback: document.getElementById('enqueue-feedback'),
@@ -3427,11 +3431,33 @@ function applyConfigSnapshot(data) {
   if (els.repoBranch) {
     els.repoBranch.textContent = data?.baseBranch || '—';
   }
+  updateAuthBanner(appConfig);
   if (currentView === 'settings') {
     fillSettingsForm(appConfig);
   }
 }
 
+/**
+ * Surface missing GitHub / Claude auth on Overview so users can open Settings.
+ * @param {typeof appConfig} cfg
+ */
+function updateAuthBanner(cfg) {
+  if (!els.authBanner || !els.authBannerText) return;
+  const missing = [];
+  if (!cfg.ghAuthOk) missing.push('GitHub');
+  if (!cfg.claudeAuthOk && !cfg.stubAgent) missing.push('Claude');
+  if (missing.length === 0) {
+    els.authBanner.classList.add('hidden');
+    els.authBanner.hidden = true;
+    els.authBannerText.textContent = '';
+    return;
+  }
+  const label = missing.join(' and ');
+  els.authBannerText.textContent = `Configure ${label} in Settings → Authentication before starting jobs.`;
+  els.authBanner.classList.remove('hidden');
+  els.authBanner.hidden = false;
+}
+
 async function fetchConfig() {
   try {
     const res = await fetch('/api/config');
@@ -3561,6 +3587,11 @@ document.querySelectorAll('.nav-item').forEach((btn) => {
   btn.addEventListener('click', () => setView(/** @type {ViewId} */ (btn.dataset.view)));
 });
 
+els.authBannerBtn?.addEventListener('click', () => {
+  setView('settings');
+  setSettingsTab('auth');
+});
+
 els.themeToggle.addEventListener('click', () => {
   const next = els.app.dataset.theme === 'dark' ? 'light' : 'dark';
   applyTheme(next);

package/public/index.html

@@ -100,6 +100,12 @@
         <!-- OVERVIEW -->
         <section class="view" id="view-overview" data-view-panel="overview">
           <div class="stack stack-lg max-w-overview">
+            <div id="auth-banner" class="auth-banner hidden" role="status" hidden>
+              <p id="auth-banner-text" class="auth-banner-text"></p>
+              <button type="button" class="btn btn-secondary btn-sm" id="auth-banner-btn">
+                Open Settings
+              </button>
+            </div>
             <section>
               <div class="section-label">Add issues</div>
               <div class="card enqueue-card">

package/public/styles.css

@@ -1907,6 +1907,30 @@ body.diff-fs-open {
   color: var(--danger, #b42318);
 }
 
+.auth-banner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
+  padding: 12px 14px;
+  background: var(--amber-100);
+  color: var(--amber-800);
+  border-radius: 8px;
+  font-size: 13px;
+}
+
+.auth-banner.hidden,
+.auth-banner[hidden] {
+  display: none;
+}
+
+.auth-banner-text {
+  margin: 0;
+  flex: 1;
+  min-width: 12rem;
+}
+
 .auth-clear {
   display: inline-block;
   margin-top: 6px;

package/src/claude-auth.js

@@ -90,22 +90,16 @@ export function publicClaudeAuthMethod(result) {
 }
 
 /**
- * Human-readable startup error for a failed {@link checkClaudeAuth}.
+ * Human-readable startup warning for a failed {@link checkClaudeAuth}.
+ * Soft-auth: this is not fatal — the server still starts so Settings can configure auth.
  * @param {ClaudeAuthResult} [_result]
  */
 export function formatClaudeAuthError(_result) {
   return [
-    '✖ No Anthropic / Claude Code authentication found.',
-    '',
-    'Authenticate with one of:',
-    '  1. Claude Pro/Max subscription (browser): install Claude Code, then run',
-    '     `claude auth login`. Settings cannot complete browser OAuth — that still',
-    '     needs the CLI on this machine.',
-    '  2. Subscription token: `claude setup-token`, then set CLAUDE_CODE_OAUTH_TOKEN',
-    '     in Settings → Claude authentication or `.acdev/.env`',
-    '  3. Anthropic API key (API billing): set ANTHROPIC_API_KEY in Settings or `.acdev/.env`',
-    '',
-    'API keys take precedence over subscription login. For UI-only testing without',
-    'auth: pass `--stub-agent`.',
+    '⚠ Claude is not authenticated — server will still start.',
+    '  Open Settings → Authentication to add an API key or OAuth token',
+    '  (or set ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN in `.acdev/.env`).',
+    '  Browser login still needs `claude auth login` on this machine.',
+    '  For UI-only testing without auth: pass `--stub-agent`.',
   ].join('\n');
 }

package/src/config.js

@@ -391,6 +391,7 @@ export function updateConfig(repoRoot, config, patch) {
  * @param {object} config
  * @param {{
  *   repoRoot?: string,
+ *   stubAgent?: boolean,
  *   ghAuth?: import('./gh-auth.js').GhAuthResult,
  *   claudeAuth?: import('./claude-auth.js').ClaudeAuthResult,
  * }} [opts]
@@ -461,6 +462,7 @@ export function publicConfig(config, opts = {}) {
     anthropicApiKeyMasked: anthropicMask.masked,
     claudeOauthTokenSet: claudeOauthMask.set,
     claudeOauthTokenMasked: claudeOauthMask.masked,
+    stubAgent: opts.stubAgent === true,
     ...(repoName ? { repoName } : {}),
   };
 }

package/src/gh-auth.js

@@ -138,21 +138,22 @@ export function checkGhAuth() {
 }
 
 /**
- * Human-readable startup error for a failed {@link checkGhAuth}.
+ * Human-readable startup warning for a failed {@link checkGhAuth}.
+ * Soft-auth: this is not fatal — the server still starts so Settings can configure auth.
  * @param {GhAuthResult} result
  */
 export function formatGhAuthError(result) {
   if (result.reason === 'not-found') {
-    return '✖ GitHub CLI (gh) not found in PATH. Install it from https://cli.github.com/';
+    return [
+      '⚠ GitHub CLI (gh) not found in PATH — server will still start.',
+      '  Install it from https://cli.github.com/, then open Settings → Authentication',
+      '  (or set GH_TOKEN in `.acdev/.env`) before enqueueing jobs.',
+    ].join('\n');
   }
   return [
-    '✖ GitHub CLI is not authenticated for github.com.',
-    '',
-    'Authenticate with one of:',
-    '  1. Interactive (browser/device): gh auth login -h github.com',
-    '  2. Personal access token: Settings → GitHub / PR auth, or set GH_TOKEN in `.acdev/.env`',
-    '  3. Non-interactive CLI: echo YOUR_PAT | gh auth login --with-token -h github.com',
-    '',
-    'SSH remotes can push/fetch git, but do not authenticate gh for issues or PRs.',
+    '⚠ GitHub is not authenticated — server will still start.',
+    '  Open Settings → Authentication to paste a PAT, or set GH_TOKEN in `.acdev/.env`.',
+    '  Or run: gh auth login -h github.com',
+    '  (SSH remotes push/fetch git but do not authenticate gh for issues/PRs.)',
   ].join('\n');
 }

package/src/server.js

@@ -36,6 +36,8 @@ import { upsertEnvVars } from './env.js';
 import { listModels } from './models.js';
 import { splitIssueUrls } from './urls.js';
 import { usageFromLogs, withJobUsage } from './usage.js';
+import { checkGhAuth } from './gh-auth.js';
+import { checkClaudeAuth } from './claude-auth.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -169,6 +171,8 @@ export function normalizeReviewComments(body) {
  *     addIssueLabel?: Function,
  *     closeIssue?: Function,
  *     resolveJiraCredentials?: Function,
+ *     checkGhAuth?: typeof checkGhAuth,
+ *     checkClaudeAuth?: typeof checkClaudeAuth,
  *   },
  * }} options
  */
@@ -182,6 +186,52 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
   const doGetDiff = deps.getDiff || getDiff;
   const doListChangedFiles = deps.listChangedFiles || listChangedFiles;
   const doApplyFileExclusions = deps.applyFileExclusions || applyFileExclusions;
+  const doCheckGhAuth = deps.checkGhAuth || checkGhAuth;
+  const doCheckClaudeAuth = deps.checkClaudeAuth || checkClaudeAuth;
+
+  /**
+   * Reject enqueue / agent / PR actions when required auth is missing.
+   * @param {{ needGh?: boolean, needClaude?: boolean }} [opts]
+   * @returns {{ status: number, error: string, code: string } | null}
+   */
+  function authGate(opts = {}) {
+    const needGh = opts.needGh !== false;
+    const needClaude = opts.needClaude === true && !useStubAgent;
+
+    if (needGh) {
+      const gh = doCheckGhAuth();
+      if (!gh.ok) {
+        const error =
+          gh.reason === 'not-found'
+            ? 'GitHub CLI (gh) is not installed. Install it from https://cli.github.com/, then restart acdev.'
+            : 'GitHub is not authenticated. Configure a PAT in Settings → Authentication, or run gh auth login.';
+        return { status: 400, error, code: 'gh_auth_required' };
+      }
+    }
+
+    if (needClaude) {
+      const claude = doCheckClaudeAuth();
+      if (!claude.ok) {
+        return {
+          status: 400,
+          error:
+            'Claude is not authenticated. Add an API key or OAuth token in Settings → Authentication, run claude auth login, or start with --stub-agent.',
+          code: 'claude_auth_required',
+        };
+      }
+    }
+
+    return null;
+  }
+
+  function publicConfigPayload() {
+    return publicConfig(config, {
+      repoRoot,
+      stubAgent: useStubAgent,
+      ghAuth: doCheckGhAuth(),
+      claudeAuth: doCheckClaudeAuth(),
+    });
+  }
 
   /** @type {Map<string, Set<import('http').ServerResponse>>} */
   const subscribers = new Map();
@@ -221,6 +271,17 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
     let job = store.getJob(jobId);
     if (!job) return;
 
+    const gate = authGate({ needGh: true, needClaude: true });
+    if (gate) {
+      appendLog(job, 'error', gate.error);
+      store.updateJob(jobId, { status: 'failed', error: gate.error });
+      const updated = store.getJob(jobId);
+      if (updated?.logs?.length) {
+        emitEvent(jobId, updated.logs[updated.logs.length - 1]);
+      }
+      return;
+    }
+
     try {
       job = setStatus(jobId, 'syncing');
       if (!job) return;
@@ -349,6 +410,21 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
     let job = store.getJob(jobId);
     if (!job || job.status !== 'applying_feedback') return;
 
+    const gate = authGate({ needGh: false, needClaude: true });
+    if (gate) {
+      appendLog(job, 'error', gate.error);
+      store.updateJob(jobId, {
+        status: 'failed',
+        error: gate.error,
+        pendingReviewFeedback: undefined,
+      });
+      const updated = store.getJob(jobId);
+      if (updated?.logs?.length) {
+        emitEvent(jobId, updated.logs[updated.logs.length - 1]);
+      }
+      return;
+    }
+
     const feedback = job.pendingReviewFeedback;
     if (!feedback || (!feedback.generalComment && !(feedback.lineComments || []).length)) {
       const message = 'Missing review feedback payload';
@@ -461,7 +537,7 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
 
   app.get('/api/config', (_req, res) => {
     try {
-      res.json(publicConfig(config, { repoRoot }));
+      res.json(publicConfigPayload());
     } catch (err) {
       res.status(500).json({ error: err.message });
     }
@@ -517,7 +593,7 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
         ...configPatch
       } = patch;
       updateConfig(repoRoot, config, configPatch);
-      res.json(publicConfig(config, { repoRoot }));
+      res.json(publicConfigPayload());
     } catch (err) {
       res.status(400).json({ error: err.message });
     }
@@ -547,6 +623,11 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
 
   app.post('/api/issues', (req, res) => {
     try {
+      const gate = authGate({ needGh: true, needClaude: true });
+      if (gate) {
+        return res.status(gate.status).json({ error: gate.error, code: gate.code });
+      }
+
       const urls = splitIssueUrls(req.body?.urls);
       if (urls.length === 0) {
         return res.status(400).json({
@@ -722,6 +803,11 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
 
   app.post('/api/jobs/:id/review', (req, res) => {
     try {
+      const gate = authGate({ needGh: false, needClaude: true });
+      if (gate) {
+        return res.status(gate.status).json({ error: gate.error, code: gate.code });
+      }
+
       const job = store.getJob(req.params.id);
       if (!job) {
         return res.status(404).json({ error: 'Job not found' });
@@ -767,6 +853,11 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
 
   app.post('/api/jobs/:id/approve', async (req, res) => {
     try {
+      const gate = authGate({ needGh: true, needClaude: false });
+      if (gate) {
+        return res.status(gate.status).json({ error: gate.error, code: gate.code });
+      }
+
       const job = store.getJob(req.params.id);
       if (!job) {
         return res.status(404).json({ error: 'Job not found' });
@@ -945,6 +1036,11 @@ export function createServer({ repoRoot, config, store, useStubAgent = false, de
 
   app.post('/api/jobs/:id/retry', (req, res) => {
     try {
+      const gate = authGate({ needGh: true, needClaude: true });
+      if (gate) {
+        return res.status(gate.status).json({ error: gate.error, code: gate.code });
+      }
+
       const job = store.getJob(req.params.id);
       if (!job) {
         return res.status(404).json({ error: 'Job not found' });