acdev 1.0.0

package/.acdev/.env.example

@@ -0,0 +1,13 @@
+# Optional. Prefer Claude Code subscription auth instead:
+#   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:
+# ANTHROPIC_API_KEY=sk-ant-your-key-here
+#
+# Jira Cloud (only when ticketSource is "jira" in Settings / config.json):
+# JIRA_BASE_URL=https://your-domain.atlassian.net
+# JIRA_EMAIL=you@company.com
+# JIRA_API_TOKEN=your-atlassian-api-token

package/README.md

@@ -0,0 +1,231 @@
+# acdev
+
+Local CLI + web UI for running AI coding agents on GitHub Issues or Jira tickets via isolated git worktrees. Pull requests are always created on the local repo’s GitHub remote with `gh`.
+
+## 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)
+- A git repository with a `develop` branch on `origin` (or configure another base branch)
+- Optional: Jira Cloud credentials when using Jira as the ticket source (see [Jira](#jira-ticket-source))
+
+## Install
+
+```bash
+npm i -g @giangarcia14/acdev
+# or
+npx @giangarcia14/acdev
+```
+
+From a local clone (development):
+
+```bash
+npm install
+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):
+
+### Option A — Claude Pro / Max subscription (browser login)
+
+Best when you already pay for claude.ai and are not allowed to use API keys.
+
+1. Install [Claude Code](https://code.claude.com/docs/en/setup) so the `claude` CLI is on your `PATH`
+2. Sign in with your Claude.ai account:
+
+```bash
+claude auth login
+# verify:
+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)
+
+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`
+```
+
+### Option B — Anthropic API key (Console / pay-as-you-go)
+
+```bash
+cp .acdev/.env.example .acdev/.env
+# edit .acdev/.env and set ANTHROPIC_API_KEY=sk-ant-...
+acdev
+```
+
+Or export the key in your shell (overrides `.env` if both are set):
+
+```bash
+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.
+
+## Jira ticket source
+
+Tickets can come from **GitHub Issues** or **Jira Cloud**. Switch in **Settings → Ticket source**. The server still requires `gh` auth (PRs); Jira credentials are only required when enqueueing Jira issues.
+
+### Connect
+
+1. Create an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. In **Settings**, choose **Jira**, then set:
+   - Base URL — `https://your-domain.atlassian.net`
+   - Email — Atlassian account email
+   - API token
+3. Click **Test connection** (`GET /rest/api/3/myself`), then **Save settings**
+
+Secrets are written to `.acdev/.env` (gitignored):
+
+```bash
+JIRA_BASE_URL=https://your-domain.atlassian.net
+JIRA_EMAIL=you@company.com
+JIRA_API_TOKEN=...
+```
+
+Non-secret settings (`ticketSource`, `jiraBaseUrl`, `jiraPrLinkPhrase`) live in `.acdev/config.json`.
+
+### Enqueue
+
+Paste Jira keys (`PROJ-123`) or browse URLs (`https://…atlassian.net/browse/PROJ-123`). PR bodies use `Relates to PROJ-123` (configurable) instead of `Closes #N`. Approving still pushes the branch and runs `gh pr create`.
+
+Optional **Rules** in Settings can move the Jira ticket to a target status (e.g. `In Review`) after a PR opens, via a best-effort workflow transition. Failures are logged as warnings and never undo a successful PR.
+
+**Limitations:** Jira Cloud REST API v3 only (not Server/Data Center). PRs always target GitHub.
+
+## Usage
+
+From inside a cloned git repository (after authenticating as above):
+
+```bash
+acdev
+```
+
+The tool starts a local server (default port `4848`), opens the browser, and shows the web UI.
+
+### CLI flags
+
+| Flag | Description |
+|------|-------------|
+| `--port <n>` | Override server port (also `ACDEV_PORT`) |
+| `--base-branch <name>` | Override base branch for this run only |
+| `--model <id>` | Override Claude model for this run (e.g. `claude-sonnet-5`) |
+| `--no-open` | Skip automatic browser open |
+| `--stub-agent` | Use a 2s stub agent (no API key needed; for testing UI flow) |
+
+### Workflow
+
+1. Paste GitHub issue URLs or Jira keys/URLs on **Overview** and click **Add to queue**
+2. Jobs process sequentially: sync base branch → create worktree → run agent → await review
+3. Monitor live logs on **Runs**; review diffs on **Review**
+4. **Approve as draft** (draft PR) or **Approve as ready for review** (non-draft PR), or **Reject** (cleanup worktree, keep history as discarded)
+5. **Clear** removes a job from history entirely (so you can re-queue the same issue). Allowed for queued / awaiting review / PR opened / failed / discarded; refused while a job is in-flight
+
+### Web UI views
+
+| View | Purpose |
+|------|---------|
+| **Overview** | Add issue URLs / Jira keys, see queued jobs and metrics; Clear queued jobs |
+| **Runs** | Active / recent jobs with live SSE logs and progress steps; Clear terminal jobs |
+| **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 |
+
+Model selection lives in the sidebar (and Settings). 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.
+
+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.
+
+On first run, creates `.acdev/config.json`:
+
+```json
+{
+  "baseBranch": "develop",
+  "testCommand": null,
+  "maxAgentTurns": 30,
+  "allowedTools": ["Read", "Glob", "Grep", "Edit", "Write", "Bash"],
+  "agentTimeoutMs": 900000,
+  "model": "claude-sonnet-5",
+  "ticketSource": "github",
+  "jiraBaseUrl": "",
+  "jiraPrLinkPhrase": "Relates to",
+  "jiraRules": {
+    "afterPrOpened": { "enabled": false, "targetStatus": "In Review" }
+  },
+  "githubRules": {
+    "afterPrOpened": { "enabled": false, "action": "none", "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).
+
+Supported `model` values (Claude Agent SDK):
+
+| UI label | Model ID |
+|----------|----------|
+| Sonnet 5 (default) | `claude-sonnet-5` |
+| Opus 5 | `claude-opus-5` |
+
+Unknown or removed model IDs in an existing config are migrated to `claude-sonnet-5` on load.
+
+Change via **Settings** / the sidebar model toggle (`PATCH /api/config`) or `--model`. Takes effect for the next agent run without restart.
+
+Job state is persisted in `.acdev/state.json`.
+
+If you previously used **codepilot** or **agent-mcp**, first run migrates `.codepilot/` or `.agent-mcp/` → `.acdev/` (and matching `-worktrees/` dirs → `.acdev-worktrees/` when present) with a one-line console notice. Prefers `.codepilot/` when both legacy dirs exist.
+
+## Tests
+
+```bash
+npm test
+```
+
+## Architecture
+
+- `bin/acdev.js` — CLI entry, startup checks (`gh` always; Jira not required at startup)
+- `src/claude-auth.js` — Anthropic API key / Claude Code subscription auth detection
+- `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/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
+- `src/env.js` — Load/upsert `.acdev/.env` (Anthropic + Jira secrets)
+- `src/paths.js` — Data/worktree paths + legacy `.codepilot` / `.agent-mcp` migration
+- `src/store.js` — JSON persistence
+- `public/` — Vanilla HTML/JS/CSS UI (no build step)
+
+### API (selected)
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/api/jobs` | All jobs |
+| `POST` | `/api/issues` | `{ urls: string[], ticketSource?: 'github'\|'jira' }` — enqueue |
+| `GET` | `/api/jobs/:id/events` | SSE log stream |
+| `POST` | `/api/jobs/:id/approve` | `{ prTitle, prBody, draft?: boolean }` — default draft `true` |
+| `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) |
+| `PATCH` | `/api/config` | Partial update including `ticketSource`, `jiraBaseUrl`; `jiraEmail` / `jiraApiToken` → `.env` |
+| `POST` | `/api/jira/test` | Test Jira credentials (`GET /rest/api/3/myself`) |
+
+### Branch naming
+
+Before the agent runs, acdev fetches the ticket and creates a worktree branch:
+
+- **GitHub:** Bug labels / title keywords → `fix/<slug>`; feature labels → `feat/<slug>`; unclear → `fix/<slug>`
+- **Jira:** issuetype Bug → `fix/<slug>`; Story / Feature / Task / Improvement → `feat/<slug>`; else `fix/<slug>`
+
+Slugs are lowercase, hyphenated, and truncated (~50 chars). If the branch already exists, `-<issueNumber-or-key>` is appended. Worktree directories remain `issue-<N-or-key>` for uniqueness.

package/bin/acdev.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+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 { loadConfig } from '../src/config.js';
+import { loadEnv } from '../src/env.js';
+import { migrateLegacyDataDir, migrateLegacyWorktreesDir } from '../src/paths.js';
+import { Store } from '../src/store.js';
+import { createServer, listen } from '../src/server.js';
+
+function parseArgs(argv) {
+  const opts = {
+    port: Number(process.env.ACDEV_PORT) || 4848,
+    baseBranch: null,
+    model: null,
+    noOpen: false,
+    stubAgent: process.env.ACDEV_STUB === '1',
+  };
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--port') {
+      opts.port = Number(argv[++i]);
+    } else if (arg === '--base-branch') {
+      opts.baseBranch = argv[++i];
+    } else if (arg === '--model') {
+      opts.model = argv[++i];
+    } else if (arg === '--no-open') {
+      opts.noOpen = true;
+    } else if (arg === '--stub-agent') {
+      opts.stubAgent = true;
+    }
+  }
+
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  let repoRoot;
+  try {
+    repoRoot = execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+    }).trim();
+  } catch {
+    console.error(
+      '✖ Not inside a git repository. cd into your repo and re-run `acdev`.'
+    );
+    process.exit(1);
+  }
+
+  migrateLegacyDataDir(repoRoot);
+  migrateLegacyWorktreesDir(repoRoot);
+  loadEnv(repoRoot);
+
+  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);
+  }
+
+  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')
+      );
+      process.exit(1);
+    }
+  }
+
+  const config = loadConfig(repoRoot);
+  if (opts.baseBranch) {
+    config.baseBranch = opts.baseBranch;
+  }
+  if (opts.model) {
+    config.model = opts.model;
+  }
+
+  const store = new Store(repoRoot);
+  store.reconcileStaleJobs();
+
+  const { app, processQueue } = createServer({
+    repoRoot,
+    config,
+    store,
+    useStubAgent: opts.stubAgent,
+  });
+
+  const server = http.createServer(app);
+
+  try {
+    await listen(server, opts.port);
+  } catch (err) {
+    console.error(`✖ ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log(`✓ acdev running at http://localhost:${opts.port}`);
+
+  if (!opts.noOpen) {
+    try {
+      await open(`http://localhost:${opts.port}`);
+    } catch {
+      // headless — URL already printed
+    }
+  }
+
+  processQueue().catch((err) => console.error('[acdev] processQueue failed:', err));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "acdev",
+  "version": "1.0.0",
+  "description": "Local CLI + web UI for running AI agents on GitHub issues via git worktrees",
+  "type": "module",
+  "bin": {
+    "acdev": "./bin/acdev.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "README.md",
+    ".acdev/.env.example"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "start": "node bin/acdev.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.1.77",
+    "dotenv": "^17.4.2",
+    "express": "^4.21.2",
+    "open": "^10.1.0",
+    "simple-git": "^3.27.0",
+    "uuid": "^11.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SftwreDev/agent-mcp.git"
+  },
+  "keywords": [
+    "agent",
+    "acdev",
+    "claude",
+    "github",
+    "cli"
+  ],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/SftwreDev/agent-mcp/issues"
+  },
+  "homepage": "https://github.com/SftwreDev/agent-mcp#readme",
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "devDependencies": {}
+}

package/public/acdev_wordmark_logo.svg

@@ -0,0 +1,10 @@
+<svg width="100%" viewBox="0 0 680 220" role="img" xmlns="http://www.w3.org/2000/svg" style="">
+<title style="fill:rgb(0, 0, 0);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:anthropic-sans, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto">Acdev wordmark logo</title>
+<desc style="fill:rgb(0, 0, 0);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:anthropic-sans, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto">A minimalist geometric text-only wordmark reading "acdev" styled as a terminal prompt, with a leading chevron in purple</desc>
+
+<g transform="translate(140,140)" style="fill:rgb(0, 0, 0);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:anthropic-sans, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto">
+<text x="0" y="0" font-size="72" style="fill:rgb(108, 92, 231);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Courier New&quot;, monospace;font-size:72px;font-weight:700;text-anchor:start;dominant-baseline:auto">&gt;</text>
+<text x="58" y="0" font-size="72" style="fill:rgb(22, 24, 29);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:Arial, sans-serif;font-size:72px;font-weight:700;text-anchor:start;dominant-baseline:auto">acdev</text>
+</g>
+<line x1="140" y1="168" x2="400" y2="168" stroke-width="3" style="fill:rgb(0, 0, 0);stroke:rgb(108, 92, 231);color:rgb(11, 11, 11);stroke-width:3px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:anthropic-sans, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+</svg>