acdev 1.0.0

package/src/claude-auth.js

@@ -0,0 +1,81 @@
+import { execFileSync, execSync } from 'node:child_process';
+
+/** @typedef {'api-key' | 'auth-token' | 'oauth-token' | 'claude-code-login'} ClaudeAuthMethod */
+/** @typedef {{ ok: true, method: ClaudeAuthMethod } | { ok: false, reason: 'missing' | 'claude-not-authenticated' }} ClaudeAuthResult */
+
+/** @type {() => string | null} */
+let claudeBinaryResolver = findClaudeBinary;
+
+/** @type {() => NodeJS.ProcessEnv} */
+let envResolver = () => process.env;
+
+/** @param {() => string | null} fn */
+export function _setClaudeBinaryResolver(fn) {
+  claudeBinaryResolver = fn;
+}
+
+export function _resetClaudeBinaryResolver() {
+  claudeBinaryResolver = findClaudeBinary;
+}
+
+/** @param {() => NodeJS.ProcessEnv} fn */
+export function _setEnvResolver(fn) {
+  envResolver = fn;
+}
+
+export function _resetEnvResolver() {
+  envResolver = () => process.env;
+}
+
+function findClaudeBinary() {
+  try {
+    return execSync('command -v claude', { encoding: 'utf8', shell: true }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether Claude Agent SDK / Claude Code can authenticate without prompting.
+ *
+ * Supported (same precedence as Claude Code docs, simplified for startup checks):
+ * - ANTHROPIC_API_KEY — Console API billing
+ * - ANTHROPIC_AUTH_TOKEN — bearer / gateway
+ * - CLAUDE_CODE_OAUTH_TOKEN — long-lived token from `claude setup-token` (subscription)
+ * - Claude Code CLI login — `claude auth login` (browser / Pro·Max subscription)
+ *
+ * @returns {ClaudeAuthResult}
+ */
+export function checkClaudeAuth() {
+  const env = envResolver();
+
+  if (env.ANTHROPIC_API_KEY) {
+    return { ok: true, method: 'api-key' };
+  }
+  if (env.ANTHROPIC_AUTH_TOKEN) {
+    return { ok: true, method: 'auth-token' };
+  }
+  if (env.CLAUDE_CODE_OAUTH_TOKEN) {
+    return { ok: true, method: 'oauth-token' };
+  }
+
+  const claude = claudeBinaryResolver();
+  if (!claude) {
+    return { ok: false, reason: 'missing' };
+  }
+
+  try {
+    const stdout = execFileSync(claude, ['auth', 'status', '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const status = JSON.parse(stdout);
+    if (status?.loggedIn === true) {
+      return { ok: true, method: 'claude-code-login' };
+    }
+  } catch {
+    // not logged in, or status command failed
+  }
+
+  return { ok: false, reason: 'claude-not-authenticated' };
+}

package/src/config.js

@@ -0,0 +1,426 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { maskSecret } from './env.js';
+import { normalizeJiraBaseUrl } from './jira.js';
+import { dataDir } from './paths.js';
+
+/** Model IDs accepted by the Claude Agent SDK / Claude Code. */
+export const MODEL_OPTIONS = [
+  { id: 'claude-sonnet-5', label: 'Sonnet 5' },
+  { id: 'claude-opus-5', label: 'Opus 5' },
+];
+
+export const DEFAULT_MODEL = 'claude-sonnet-5';
+
+/** Tool names the agent may be granted via config. */
+export const KNOWN_TOOLS = ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'];
+
+export const TICKET_SOURCES = /** @type {const} */ (['github', 'jira']);
+
+/** GitHub post-PR actions (issues have no Jira-like workflow statuses). */
+export const GITHUB_AFTER_PR_ACTIONS = /** @type {const} */ ([
+  'none',
+  'add_label',
+  'close_issue',
+]);
+
+const ALLOWED_MODELS = new Set(MODEL_OPTIONS.map((m) => m.id));
+const ALLOWED_TOOLS_SET = new Set(KNOWN_TOOLS);
+const ALLOWED_TICKET_SOURCES = new Set(TICKET_SOURCES);
+const ALLOWED_GITHUB_AFTER_PR_ACTIONS = new Set(GITHUB_AFTER_PR_ACTIONS);
+
+const DEFAULT_JIRA_RULES = {
+  afterPrOpened: {
+    enabled: false,
+    targetStatus: 'In Review',
+  },
+};
+
+const DEFAULT_GITHUB_RULES = {
+  afterPrOpened: {
+    enabled: false,
+    action: /** @type {'none' | 'add_label' | 'close_issue'} */ ('none'),
+    label: '',
+  },
+};
+
+const DEFAULTS = {
+  baseBranch: 'develop',
+  testCommand: null,
+  maxAgentTurns: 30,
+  allowedTools: [...KNOWN_TOOLS],
+  agentTimeoutMs: 900_000,
+  model: DEFAULT_MODEL,
+  ticketSource: /** @type {'github' | 'jira'} */ ('github'),
+  jiraBaseUrl: '',
+  /** PR body phrase for Jira tickets, e.g. "Relates to PROJ-123". */
+  jiraPrLinkPhrase: 'Relates to',
+  jiraRules: structuredClone(DEFAULT_JIRA_RULES),
+  githubRules: structuredClone(DEFAULT_GITHUB_RULES),
+};
+
+/**
+ * Normalize / validate jiraRules from config or PATCH body.
+ * @param {unknown} raw
+ * @param {{ throwOnInvalid?: boolean }} [opts]
+ * @returns {typeof DEFAULT_JIRA_RULES}
+ */
+export function normalizeJiraRules(raw, opts = {}) {
+  const throwOnInvalid = opts.throwOnInvalid === true;
+  const base = structuredClone(DEFAULT_JIRA_RULES);
+  if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
+    if (throwOnInvalid && raw != null) {
+      throw new Error('jiraRules must be an object');
+    }
+    return base;
+  }
+  /** @type {Record<string, unknown>} */
+  const obj = /** @type {Record<string, unknown>} */ (raw);
+  const after =
+    obj.afterPrOpened != null && typeof obj.afterPrOpened === 'object' && !Array.isArray(obj.afterPrOpened)
+      ? /** @type {Record<string, unknown>} */ (obj.afterPrOpened)
+      : {};
+
+  if (throwOnInvalid && obj.afterPrOpened != null && (typeof obj.afterPrOpened !== 'object' || Array.isArray(obj.afterPrOpened))) {
+    throw new Error('jiraRules.afterPrOpened must be an object');
+  }
+
+  if (after.enabled !== undefined) {
+    if (typeof after.enabled !== 'boolean') {
+      if (throwOnInvalid) throw new Error('jiraRules.afterPrOpened.enabled must be a boolean');
+    } else {
+      base.afterPrOpened.enabled = after.enabled;
+    }
+  }
+
+  if (after.targetStatus !== undefined) {
+    if (typeof after.targetStatus !== 'string') {
+      if (throwOnInvalid) throw new Error('jiraRules.afterPrOpened.targetStatus must be a string');
+    } else {
+      const trimmed = after.targetStatus.trim();
+      if (!trimmed) {
+        if (throwOnInvalid) {
+          throw new Error('jiraRules.afterPrOpened.targetStatus must be a non-empty string');
+        }
+      } else {
+        base.afterPrOpened.targetStatus = trimmed;
+      }
+    }
+  }
+
+  return base;
+}
+
+/**
+ * Normalize / validate githubRules from config or PATCH body.
+ * @param {unknown} raw
+ * @param {{ throwOnInvalid?: boolean }} [opts]
+ * @returns {typeof DEFAULT_GITHUB_RULES}
+ */
+export function normalizeGithubRules(raw, opts = {}) {
+  const throwOnInvalid = opts.throwOnInvalid === true;
+  const base = structuredClone(DEFAULT_GITHUB_RULES);
+  if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
+    if (throwOnInvalid && raw != null) {
+      throw new Error('githubRules must be an object');
+    }
+    return base;
+  }
+  /** @type {Record<string, unknown>} */
+  const obj = /** @type {Record<string, unknown>} */ (raw);
+  const after =
+    obj.afterPrOpened != null && typeof obj.afterPrOpened === 'object' && !Array.isArray(obj.afterPrOpened)
+      ? /** @type {Record<string, unknown>} */ (obj.afterPrOpened)
+      : {};
+
+  if (throwOnInvalid && obj.afterPrOpened != null && (typeof obj.afterPrOpened !== 'object' || Array.isArray(obj.afterPrOpened))) {
+    throw new Error('githubRules.afterPrOpened must be an object');
+  }
+
+  if (after.enabled !== undefined) {
+    if (typeof after.enabled !== 'boolean') {
+      if (throwOnInvalid) throw new Error('githubRules.afterPrOpened.enabled must be a boolean');
+    } else {
+      base.afterPrOpened.enabled = after.enabled;
+    }
+  }
+
+  if (after.action !== undefined) {
+    if (typeof after.action !== 'string' || !ALLOWED_GITHUB_AFTER_PR_ACTIONS.has(after.action)) {
+      if (throwOnInvalid) {
+        throw new Error(
+          `Invalid githubRules.afterPrOpened.action "${after.action}". Allowed: ${GITHUB_AFTER_PR_ACTIONS.join(', ')}`
+        );
+      }
+    } else {
+      base.afterPrOpened.action = /** @type {'none' | 'add_label' | 'close_issue'} */ (after.action);
+    }
+  }
+
+  if (after.label !== undefined) {
+    if (typeof after.label !== 'string') {
+      if (throwOnInvalid) throw new Error('githubRules.afterPrOpened.label must be a string');
+    } else {
+      base.afterPrOpened.label = after.label.trim();
+    }
+  }
+
+  if (
+    throwOnInvalid &&
+    base.afterPrOpened.enabled &&
+    base.afterPrOpened.action === 'add_label' &&
+    !base.afterPrOpened.label
+  ) {
+    throw new Error('githubRules.afterPrOpened.label is required when action is add_label');
+  }
+
+  return base;
+}
+
+/**
+ * Persist config to `.acdev/config.json`.
+ * @param {string} repoRoot
+ * @param {object} config
+ */
+export function saveConfig(repoRoot, config) {
+  const configDir = dataDir(repoRoot);
+  const configPath = path.join(configDir, 'config.json');
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+function persistable(config) {
+  return {
+    baseBranch: config.baseBranch,
+    testCommand: config.testCommand,
+    maxAgentTurns: config.maxAgentTurns,
+    allowedTools: config.allowedTools,
+    agentTimeoutMs: config.agentTimeoutMs,
+    model: config.model,
+    ticketSource: config.ticketSource,
+    jiraBaseUrl: config.jiraBaseUrl || '',
+    jiraPrLinkPhrase: config.jiraPrLinkPhrase || 'Relates to',
+    jiraRules: normalizeJiraRules(config.jiraRules),
+    githubRules: normalizeGithubRules(config.githubRules),
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @returns {number}
+ */
+function positiveInt(value, field) {
+  const n = typeof value === 'number' ? value : Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`${field} must be a positive integer`);
+  }
+  return n;
+}
+
+/**
+ * Load or create `.acdev/config.json` inside the repo root.
+ * Unknown / removed model IDs are mapped to {@link DEFAULT_MODEL}.
+ * @param {string} repoRoot
+ * @returns {typeof DEFAULTS}
+ */
+export function loadConfig(repoRoot) {
+  const configDir = dataDir(repoRoot);
+  const configPath = path.join(configDir, 'config.json');
+
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  if (!fs.existsSync(configPath)) {
+    const initial = {
+      ...DEFAULTS,
+      allowedTools: [...KNOWN_TOOLS],
+      jiraRules: structuredClone(DEFAULT_JIRA_RULES),
+      githubRules: structuredClone(DEFAULT_GITHUB_RULES),
+    };
+    fs.writeFileSync(configPath, JSON.stringify(persistable(initial), null, 2) + '\n', 'utf8');
+    return initial;
+  }
+
+  const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const config = {
+    ...DEFAULTS,
+    ...raw,
+    allowedTools: raw.allowedTools ?? [...KNOWN_TOOLS],
+    jiraRules: normalizeJiraRules(raw.jiraRules),
+    githubRules: normalizeGithubRules(raw.githubRules),
+  };
+
+  if (!ALLOWED_MODELS.has(config.model)) {
+    config.model = DEFAULT_MODEL;
+    saveConfig(repoRoot, persistable(config));
+  }
+
+  if (!ALLOWED_TICKET_SOURCES.has(config.ticketSource)) {
+    config.ticketSource = 'github';
+  }
+
+  if (typeof config.jiraBaseUrl !== 'string') {
+    config.jiraBaseUrl = '';
+  }
+
+  if (typeof config.jiraPrLinkPhrase !== 'string' || !config.jiraPrLinkPhrase.trim()) {
+    config.jiraPrLinkPhrase = 'Relates to';
+  }
+
+  return config;
+}
+
+/**
+ * Apply a partial update, persist, and return the new config.
+ * Mutates `config` in place so the running server picks up changes.
+ * @param {string} repoRoot
+ * @param {object} config
+ * @param {Partial<typeof DEFAULTS>} patch
+ * @returns {typeof DEFAULTS}
+ */
+export function updateConfig(repoRoot, config, patch) {
+  if (patch.model != null) {
+    if (!ALLOWED_MODELS.has(patch.model)) {
+      throw new Error(
+        `Invalid model "${patch.model}". Allowed: ${[...ALLOWED_MODELS].join(', ')}`
+      );
+    }
+    config.model = patch.model;
+  }
+
+  if (patch.baseBranch !== undefined) {
+    if (typeof patch.baseBranch !== 'string' || !patch.baseBranch.trim()) {
+      throw new Error('baseBranch must be a non-empty string');
+    }
+    config.baseBranch = patch.baseBranch.trim();
+  }
+
+  if (patch.testCommand !== undefined) {
+    if (patch.testCommand === null) {
+      config.testCommand = null;
+    } else if (typeof patch.testCommand === 'string') {
+      const trimmed = patch.testCommand.trim();
+      config.testCommand = trimmed === '' ? null : trimmed;
+    } else {
+      throw new Error('testCommand must be a string or null');
+    }
+  }
+
+  if (patch.maxAgentTurns !== undefined && patch.maxAgentTurns !== null) {
+    config.maxAgentTurns = positiveInt(patch.maxAgentTurns, 'maxAgentTurns');
+  }
+
+  if (patch.agentTimeoutMs !== undefined && patch.agentTimeoutMs !== null) {
+    config.agentTimeoutMs = positiveInt(patch.agentTimeoutMs, 'agentTimeoutMs');
+  }
+
+  if (patch.allowedTools !== undefined) {
+    if (!Array.isArray(patch.allowedTools)) {
+      throw new Error('allowedTools must be an array of tool names');
+    }
+    const unknown = patch.allowedTools.filter((t) => !ALLOWED_TOOLS_SET.has(t));
+    if (unknown.length > 0) {
+      throw new Error(
+        `Invalid allowedTools: ${unknown.join(', ')}. Allowed: ${KNOWN_TOOLS.join(', ')}`
+      );
+    }
+    // Preserve known order; drop duplicates
+    const selected = new Set(patch.allowedTools);
+    config.allowedTools = KNOWN_TOOLS.filter((t) => selected.has(t));
+  }
+
+  if (patch.ticketSource !== undefined) {
+    if (!ALLOWED_TICKET_SOURCES.has(patch.ticketSource)) {
+      throw new Error(
+        `Invalid ticketSource "${patch.ticketSource}". Allowed: ${TICKET_SOURCES.join(', ')}`
+      );
+    }
+    config.ticketSource = patch.ticketSource;
+  }
+
+  if (patch.jiraBaseUrl !== undefined) {
+    if (patch.jiraBaseUrl === null || patch.jiraBaseUrl === '') {
+      config.jiraBaseUrl = '';
+    } else if (typeof patch.jiraBaseUrl === 'string') {
+      config.jiraBaseUrl = normalizeJiraBaseUrl(patch.jiraBaseUrl);
+    } else {
+      throw new Error('jiraBaseUrl must be a string');
+    }
+  }
+
+  if (patch.jiraPrLinkPhrase !== undefined) {
+    if (typeof patch.jiraPrLinkPhrase !== 'string' || !patch.jiraPrLinkPhrase.trim()) {
+      throw new Error('jiraPrLinkPhrase must be a non-empty string');
+    }
+    config.jiraPrLinkPhrase = patch.jiraPrLinkPhrase.trim();
+  }
+
+  if (patch.jiraRules !== undefined) {
+    config.jiraRules = normalizeJiraRules(patch.jiraRules, { throwOnInvalid: true });
+  }
+
+  if (patch.githubRules !== undefined) {
+    config.githubRules = normalizeGithubRules(patch.githubRules, { throwOnInvalid: true });
+  }
+
+  saveConfig(repoRoot, persistable(config));
+  return config;
+}
+
+/**
+ * Public-safe config snapshot for the UI / API.
+ * Never returns the full Jira API token.
+ * @param {object} config
+ * @param {{ repoRoot?: string }} [opts]
+ */
+export function publicConfig(config, opts = {}) {
+  const model = ALLOWED_MODELS.has(config.model) ? config.model : DEFAULT_MODEL;
+  const repoName = opts.repoRoot ? path.basename(opts.repoRoot) : undefined;
+  const ticketSource = ALLOWED_TICKET_SOURCES.has(config.ticketSource)
+    ? config.ticketSource
+    : 'github';
+
+  const envBase = (process.env.JIRA_BASE_URL || '').trim();
+  const jiraBaseUrl =
+    (config.jiraBaseUrl || '').trim() ||
+    (envBase ? (() => {
+      try {
+        return normalizeJiraBaseUrl(envBase);
+      } catch {
+        return envBase;
+      }
+    })() : '');
+
+  const jiraEmail = (process.env.JIRA_EMAIL || '').trim();
+  const tokenMask = maskSecret(process.env.JIRA_API_TOKEN);
+  const jiraConfigured = Boolean(
+    jiraBaseUrl && jiraEmail && tokenMask.set
+  );
+
+  return {
+    model,
+    baseBranch: config.baseBranch,
+    testCommand: config.testCommand ?? null,
+    maxAgentTurns: config.maxAgentTurns,
+    agentTimeoutMs: config.agentTimeoutMs,
+    allowedTools: Array.isArray(config.allowedTools)
+      ? [...config.allowedTools]
+      : [...KNOWN_TOOLS],
+    models: MODEL_OPTIONS,
+    knownTools: KNOWN_TOOLS,
+    ticketSource,
+    jiraBaseUrl,
+    jiraPrLinkPhrase: config.jiraPrLinkPhrase || 'Relates to',
+    jiraRules: normalizeJiraRules(config.jiraRules),
+    githubRules: normalizeGithubRules(config.githubRules),
+    jiraEmail: jiraEmail || null,
+    jiraApiTokenSet: tokenMask.set,
+    jiraApiTokenMasked: tokenMask.masked,
+    jiraConfigured,
+    ...(repoName ? { repoName } : {}),
+  };
+}

package/src/env.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+import { dataDir } from './paths.js';
+
+/**
+ * Load environment variables from `.acdev/.env` in the repo root.
+ * Existing process.env values take precedence (standard dotenv behavior).
+ * Loads ANTHROPIC_*, CLAUDE_*, JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN, etc.
+ * @param {string} repoRoot
+ */
+export function loadEnv(repoRoot) {
+  const envPath = path.join(dataDir(repoRoot), '.env');
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+  dotenv.config({ path: envPath, quiet: true });
+}
+
+/**
+ * Path to `.acdev/.env`.
+ * @param {string} repoRoot
+ */
+export function envFilePath(repoRoot) {
+  return path.join(dataDir(repoRoot), '.env');
+}
+
+/**
+ * Upsert key=value pairs in `.acdev/.env` without clobbering unrelated keys.
+ * Updates process.env for the written keys.
+ * @param {string} repoRoot
+ * @param {Record<string, string | null | undefined>} vars
+ *   Pass `null` or `''` to remove a key.
+ */
+export function upsertEnvVars(repoRoot, vars) {
+  const envPath = envFilePath(repoRoot);
+  const dir = path.dirname(envPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  /** @type {Map<string, string>} */
+  const map = new Map();
+  /** @type {string[]} */
+  let preamble = [];
+
+  if (fs.existsSync(envPath)) {
+    const lines = fs.readFileSync(envPath, 'utf8').split(/\r?\n/);
+    /** @type {string[]} */
+    const keptPreamble = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        if (map.size === 0) keptPreamble.push(line);
+        continue;
+      }
+      const eq = trimmed.indexOf('=');
+      if (eq === -1) continue;
+      const key = trimmed.slice(0, eq).trim();
+      let value = trimmed.slice(eq + 1);
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      map.set(key, value);
+    }
+    preamble = keptPreamble;
+  }
+
+  for (const [key, value] of Object.entries(vars)) {
+    if (value == null || value === '') {
+      map.delete(key);
+      delete process.env[key];
+    } else {
+      map.set(key, String(value));
+      process.env[key] = String(value);
+    }
+  }
+
+  const body = [...map.entries()].map(([k, v]) => `${k}=${v}`).join('\n');
+  const header = preamble.length ? preamble.join('\n').replace(/\n+$/, '') + '\n' : '';
+  const content = header + (body ? body + '\n' : '');
+  fs.writeFileSync(envPath, content, 'utf8');
+}
+
+/**
+ * Mask a secret for API responses.
+ * @param {string | undefined | null} value
+ * @returns {{ set: boolean, masked: string | null }}
+ */
+export function maskSecret(value) {
+  const v = String(value || '');
+  if (!v) return { set: false, masked: null };
+  if (v.length <= 4) return { set: true, masked: '••••' };
+  return { set: true, masked: `${'•'.repeat(Math.min(8, v.length - 4))}${v.slice(-4)}` };
+}

package/src/gh-auth.js

@@ -0,0 +1,41 @@
+import { execFileSync, execSync } from 'node:child_process';
+
+/** @type {() => string | null} */
+let ghBinaryResolver = findGhBinary;
+
+/** @param {() => string | null} fn */
+export function _setGhBinaryResolver(fn) {
+  ghBinaryResolver = fn;
+}
+
+export function _resetGhBinaryResolver() {
+  ghBinaryResolver = findGhBinary;
+}
+
+function findGhBinary() {
+  try {
+    return execSync('command -v gh', { encoding: 'utf8', shell: true }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify GitHub CLI is installed and the active github.com account is authenticated.
+ * @returns {{ ok: true } | { ok: false, reason: 'not-found' | 'not-authenticated' }}
+ */
+export function checkGhAuth() {
+  const gh = ghBinaryResolver();
+  if (!gh) {
+    return { ok: false, reason: 'not-found' };
+  }
+
+  try {
+    execFileSync(gh, ['auth', 'status', '--hostname', 'github.com', '--active'], {
+      stdio: 'ignore',
+    });
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: 'not-authenticated' };
+  }
+}