forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/activation/ensure-forge-home.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * Lazy `.forge/` home creation (activation foundation).
+ *
+ * Discovery ≠ initialization. The global Forge plugin (SessionStart hook +
+ * `activation` skill) must create NOTHING in a user's repo. The FIRST verb that
+ * performs a real MUTATION (e.g. `forge claim`, `forge create`, `forge
+ * remember`) is what lazily materializes the bare-minimum `.forge/` skeleton.
+ * Read-only verbs (`ready`, `show`, `status`, `recap`, …) never call this, so a
+ * bare repo stays untouched until the user actually changes state.
+ *
+ * "Bare-minimum" here is strictly LESS than `forge init --minimal`: this writes
+ * ONLY `.forge/config.yaml` with every gate disabled (the `minimal` adoption
+ * profile). It installs NO git hooks, NO lefthook.yml, NO protected-paths
+ * manifest, NO `.mcp.json`, and NO scripts tree — those remain the opt-in
+ * payload of `forge setup`, never forced. Progressive growth: heavier slices
+ * initialize themselves on first use.
+ *
+ * @module activation/ensure-forge-home
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { renderAdoptionConfigYaml } = require('../adoption-profiles');
+
+/**
+ * Core verbs that MUTATE project state and therefore need `.forge/` to exist.
+ *
+ * Deliberately excludes `init`/`setup` — they own `.forge/` creation with their
+ * own (richer) logic, and pre-creating a minimal config would trip their
+ * no-clobber guard. Also excludes every read-only verb, so those write nothing.
+ *
+ * Deliberately EXCLUDES `gate` and `stage`: each has read-only subcommands
+ * (`gate status`/`gate check`, `stage --list`/`--current`) that must not create
+ * `.forge/` — a verb-level trigger would violate the foundation's own
+ * "read-only writes nothing" invariant. Their genuinely-mutating forms
+ * self-manage without ensureForgeHome: `gate enable|disable` and `role` write
+ * via the config writer (which creates `.forge/config.yaml` if absent), while
+ * `gate approve|reject` and `stage --start|--complete` write kernel events/runs
+ * through the broker (which lazily creates its own store). Subcommand-level
+ * granularity is deferred; excluding the whole verb is the correct, safe default
+ * because the read-only forms are the common case. `role` is retained: it has NO
+ * read-only form (every valid invocation writes config), so it violates nothing.
+ *
+ * A command module may override membership by exporting `mutating: true|false`;
+ * this Set is the default classification for the foundation.
+ */
+const MUTATING_VERBS = new Set([
+  'claim',
+  'close',
+  'create',
+  'comment',
+  'update',
+  'add',
+  'new',
+  'remember',
+  'role',
+  'patch',
+]);
+
+/**
+ * Decide whether a verb should lazily ensure the `.forge/` home.
+ *
+ * A command module's explicit `mutating` boolean wins; otherwise fall back to
+ * the default {@link MUTATING_VERBS} classification.
+ *
+ * @param {string} name - Command/verb name being dispatched.
+ * @param {object} [command] - The resolved command module (may declare `mutating`).
+ * @returns {boolean}
+ */
+function isMutatingVerb(name, command) {
+  if (command && typeof command === 'object' && typeof command.mutating === 'boolean') {
+    return command.mutating;
+  }
+  return MUTATING_VERBS.has(name);
+}
+
+/**
+ * Render the bare-minimum, gates-disabled config body.
+ *
+ * Reuses the canonical `minimal` adoption profile so the produced YAML is
+ * schema-valid and identical in spirit to `forge init --minimal` (minus the
+ * hooks/protected-paths side effects). Overridable via `deps.renderConfig` for
+ * tests that don't want to depend on the profile renderer.
+ *
+ * @param {object} [deps]
+ * @returns {string} config.yaml contents
+ */
+function renderMinimalConfig(deps = {}) {
+  const render = deps.renderConfig || (() => renderAdoptionConfigYaml('minimal'));
+  return render();
+}
+
+/**
+ * Idempotently create the bare-minimum `.forge/` skeleton for a mutating verb.
+ *
+ * No-clobber by construction: if `.forge/` already exists (inited repo, or a
+ * partially-created home), this is a NO-OP and never touches the user's files.
+ * The kernel/issue store (`.forge/kernel/…`) is created lazily by the broker on
+ * the mutating verb itself — this function only guarantees the config skeleton.
+ *
+ * @param {string} [projectRoot=process.cwd()] - Repo root to initialize.
+ * @param {object} [deps] - Injectable seams: `fs`, `renderConfig`.
+ * @returns {{ created: boolean, reason?: string, configPath: string }}
+ */
+function ensureForgeHome(projectRoot = process.cwd(), deps = {}) {
+  const fsImpl = deps.fs || fs;
+  const forgeDir = path.join(projectRoot, '.forge');
+  const configPath = path.join(forgeDir, 'config.yaml');
+
+  // Idempotent + self-healing. The presence of `config.yaml` — NOT the `.forge/`
+  // directory alone — is what marks the home as initialized. Keying the
+  // no-clobber check on the config FILE means a half-init (dir created but config
+  // never written: disk full, permission error, or the process killed between
+  // mkdir and write) is COMPLETED on the next call instead of being permanently
+  // stuck behind a dir-exists early-return. We only ever ADD a missing
+  // config.yaml and never overwrite an existing one, so a real inited repo is
+  // still never clobbered. `mkdirSync({recursive})` is a no-op if the dir exists.
+  if (fsImpl.existsSync(configPath)) {
+    return { created: false, reason: 'config-exists', configPath };
+  }
+
+  fsImpl.mkdirSync(forgeDir, { recursive: true });
+  fsImpl.writeFileSync(configPath, renderMinimalConfig(deps), 'utf8');
+  return { created: true, configPath };
+}
+
+module.exports = {
+  ensureForgeHome,
+  isMutatingVerb,
+  renderMinimalConfig,
+  MUTATING_VERBS,
+};

package/lib/adapter-cli.js

@@ -0,0 +1,307 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { GreptileReviewAdapter } = require('./adapters/greptile-review-adapter');
+const { validateReviewAdapter } = require('./review-adapter');
+
+const RESERVED_ADAPTER_NAMES = new Set(['greptile']);
+const REQUIRED_NORMALIZED_THREAD_KEYS = ['id', 'commentId', 'file', 'line', 'body', 'author', 'isResolved', 'raw'];
+
+function parseOption(args, name, fallback = undefined) {
+  const prefix = `--${name}=`;
+  const inline = args.find((arg) => arg.startsWith(prefix));
+  if (inline) {
+    return inline.slice(prefix.length);
+  }
+  const index = args.indexOf(`--${name}`);
+  if (index !== -1 && args[index + 1] && !args[index + 1].startsWith('--')) {
+    return args[index + 1];
+  }
+  if (index !== -1) {
+    return '';
+  }
+  return fallback;
+}
+
+function validateAdapterName(name) {
+  if (!name || typeof name !== 'string') {
+    return 'Adapter name is required';
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    return 'Adapter name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens';
+  }
+  return null;
+}
+
+function assertValidAdapterName(name) {
+  const error = validateAdapterName(name);
+  if (error) {
+    throw new Error(error);
+  }
+}
+
+function isReservedAdapterName(name) {
+  return RESERVED_ADAPTER_NAMES.has(name);
+}
+
+function adapterNameToClassName(name) {
+  return `${name
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')}ReviewAdapter`;
+}
+
+function getReviewAdapterDir(projectRoot) {
+  return path.join(projectRoot, '.forge', 'adapters', 'review');
+}
+
+function getAdapterPath(projectRoot, name, kind = 'review') {
+  assertValidAdapterName(name);
+  const adapterDir = path.resolve(projectRoot, '.forge', 'adapters', kind);
+  const adapterPath = path.resolve(adapterDir, `${name}.js`);
+  if (!adapterPath.startsWith(`${adapterDir}${path.sep}`)) {
+    throw new Error('Adapter path must stay under .forge/adapters');
+  }
+  return adapterPath;
+}
+
+function renderReviewAdapterScaffold(name, template) {
+  const className = adapterNameToClassName(name);
+  return `'use strict';
+
+class ${className} {
+  constructor(options = {}) {
+    this.id = options.id || '${name}';
+    this.kind = 'review';
+    this.name = options.name || '${className}';
+  }
+
+  async fetchThreads(_context) {
+    throw new Error('${name}.fetchThreads must connect to the review provider');
+  }
+
+  parse(_payload) {
+    // Start from the ${template} template and normalize provider payloads into:
+    // { id, commentId, file, line, body, author, isResolved, raw }
+    throw new Error('${name}.parse must normalize provider payloads before use');
+  }
+
+  async reply(_context) {
+    throw new Error('${name}.reply must post a review-thread reply');
+  }
+
+  async resolve(_context) {
+    throw new Error('${name}.resolve must mark a review thread resolved');
+  }
+
+  score(threads) {
+    return threads.map((thread) => ({ ...thread, resolved: false, reason: 'not scored' }));
+  }
+}
+
+module.exports = { ${className} };
+`;
+}
+
+function scaffoldAdapter(args, projectRoot) {
+  const subcommand = args[0];
+  const name = args[1];
+  const kind = parseOption(args, 'kind', 'review');
+  const template = parseOption(args, 'template', 'greptile');
+
+  if (subcommand !== 'adapter' || !name) {
+    return { success: false, error: 'Usage: forge new adapter <name> --kind=review --template=greptile' };
+  }
+  const nameError = validateAdapterName(name);
+  if (nameError) {
+    return { success: false, error: nameError };
+  }
+  if (isReservedAdapterName(name)) {
+    return { success: false, error: `Adapter name is reserved: ${name}` };
+  }
+  if (kind !== 'review') {
+    return { success: false, error: 'Only --kind=review is supported in this foundation PR' };
+  }
+  if (template !== 'greptile') {
+    return { success: false, error: 'Only --template=greptile is supported in this foundation PR' };
+  }
+
+  const adapterDir = getReviewAdapterDir(projectRoot);
+  const adapterPath = getAdapterPath(projectRoot, name, kind);
+  fs.mkdirSync(adapterDir, { recursive: true });
+
+  if (fs.existsSync(adapterPath)) {
+    return { success: false, error: `Adapter already exists: ${path.relative(projectRoot, adapterPath)}` };
+  }
+
+  fs.writeFileSync(adapterPath, renderReviewAdapterScaffold(name, template));
+
+  return {
+    success: true,
+    output: `Created review adapter scaffold: ${path.relative(projectRoot, adapterPath).split(path.sep).join('/')}`,
+  };
+}
+
+function loadAdapter(name, projectRoot) {
+  if (name === 'greptile') {
+    return new GreptileReviewAdapter();
+  }
+
+  const adapterPath = getAdapterPath(projectRoot, name);
+  if (!fs.existsSync(adapterPath)) {
+    throw new Error(`Adapter not found: ${name}`);
+  }
+
+  const mod = require(adapterPath);
+  const exported = mod.default || mod[adapterNameToClassName(name)] || mod.adapter || mod;
+  return typeof exported === 'function' ? new exported() : exported;
+}
+
+function hasNormalizedReviewThreadShape(thread) {
+  return Boolean(thread)
+    && REQUIRED_NORMALIZED_THREAD_KEYS.every((key) => Object.prototype.hasOwnProperty.call(thread, key));
+}
+
+async function runFixtureReplay(args, projectRoot) {
+  const name = args[1];
+  const fixturePath = parseOption(args, 'fixture');
+
+  if (!name || !fixturePath) {
+    return { success: false, error: 'Usage: forge adapter test <name> --fixture=<path>' };
+  }
+
+  let adapter;
+  try {
+    adapter = loadAdapter(name, projectRoot);
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+  const validation = validateReviewAdapter(adapter);
+  if (!validation.valid) {
+    return { success: false, error: validation.errors.join('; ') };
+  }
+
+  const absoluteFixturePath = path.isAbsolute(fixturePath)
+    ? fixturePath
+    : path.join(projectRoot, fixturePath);
+  let fixture;
+  let parsed;
+  let scores;
+  try {
+    fixture = JSON.parse(fs.readFileSync(absoluteFixturePath, 'utf8'));
+    const fixtureInput = Object.prototype.hasOwnProperty.call(fixture, 'input')
+      ? fixture.input
+      : fixture;
+    parsed = adapter.parse(fixtureInput);
+    if (!Array.isArray(parsed)) {
+      throw new Error('Adapter parse must return an array');
+    }
+    if (!parsed.every(hasNormalizedReviewThreadShape)) {
+      throw new Error('Adapter parse must return normalized review threads');
+    }
+    scores = await adapter.score(parsed, {
+      projectRoot,
+      sinceCommit: fixture.sinceCommit || null,
+      _exec: fixture.gitOutput ? () => fixture.gitOutput : () => '',
+    });
+    if (!Array.isArray(scores)) {
+      throw new Error('Adapter score must return an array');
+    }
+  } catch (error) {
+    return { success: false, error: `Fixture replay failed: ${error.message}` };
+  }
+
+  if (fixture.expect?.threads !== undefined && parsed.length !== fixture.expect.threads) {
+    return {
+      success: false,
+      error: `Expected ${fixture.expect.threads} parsed threads, got ${parsed.length}`,
+    };
+  }
+
+  return {
+    success: true,
+    output: `Adapter ${name} fixture replay passed: ${parsed.length} parsed thread${parsed.length === 1 ? '' : 's'}, ${scores.length} scored result${scores.length === 1 ? '' : 's'}`,
+  };
+}
+
+function listAdapters(projectRoot) {
+  const adapterDir = getReviewAdapterDir(projectRoot);
+  const local = fs.existsSync(adapterDir)
+    ? fs.readdirSync(adapterDir)
+      .filter((file) => file.endsWith('.js'))
+      .map((file) => file.replace(/\.js$/, ''))
+      .filter((name) => !isReservedAdapterName(name))
+    : [];
+  return ['greptile', ...local].sort((left, right) => left.localeCompare(right));
+}
+
+function setAdapterEnabled(args, projectRoot, enabled) {
+  const name = args[1];
+  if (!name) {
+    return { success: false, error: `Usage: forge adapter ${enabled ? 'enable' : 'disable'} <name>` };
+  }
+  const nameError = validateAdapterName(name);
+  if (nameError) {
+    return { success: false, error: nameError };
+  }
+  let config;
+  try {
+    const configDir = path.join(projectRoot, '.forge');
+    const configPath = path.join(configDir, 'adapters.json');
+    fs.mkdirSync(configDir, { recursive: true });
+    const parsedConfig = fs.existsSync(configPath)
+      ? JSON.parse(fs.readFileSync(configPath, 'utf8'))
+      : null;
+    config = parsedConfig && typeof parsedConfig === 'object' && !Array.isArray(parsedConfig)
+      ? parsedConfig
+      : { review: {} };
+    config.review = config.review && typeof config.review === 'object' && !Array.isArray(config.review)
+      ? config.review
+      : {};
+    config.review[name] = { ...(config.review[name] || {}), enabled };
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  } catch (error) {
+    return { success: false, error: `Failed to update adapter config: ${error.message}` };
+  }
+  return {
+    success: true,
+    output: `${enabled ? 'Enabled' : 'Disabled'} review adapter: ${name}`,
+  };
+}
+
+async function handleAdapterCommand(args, projectRoot) {
+  const action = args[0];
+
+  if (action === 'test') {
+    return runFixtureReplay(args, projectRoot);
+  }
+  if (action === 'list') {
+    return { success: true, output: listAdapters(projectRoot).join('\n') };
+  }
+  if (action === 'enable') {
+    return setAdapterEnabled(args, projectRoot, true);
+  }
+  if (action === 'disable') {
+    return setAdapterEnabled(args, projectRoot, false);
+  }
+
+  return {
+    success: false,
+    error: 'Usage: forge adapter <test|list|enable|disable> ...',
+  };
+}
+
+module.exports = {
+  adapterNameToClassName,
+  getAdapterPath,
+  handleAdapterCommand,
+  hasNormalizedReviewThreadShape,
+  isReservedAdapterName,
+  listAdapters,
+  runFixtureReplay,
+  scaffoldAdapter,
+  setAdapterEnabled,
+  validateAdapterName,
+};

package/lib/adapters/beads-issue-adapter.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const {
+  IssueAdapter,
+  decideIssueAuthority,
+  normalizeIssueStatus,
+} = require('../issue-adapter.js');
+
+class BeadsIssueAdapter extends IssueAdapter {
+  constructor(options = {}) {
+    super({
+      id: options.id || 'beads',
+      kind: 'issue',
+      name: options.name || 'Beads Issue Adapter',
+      version: options.version || '0.1.0',
+    });
+    this.runBeadsOperation = options.runBeadsOperation;
+  }
+
+  run(operation, args = [], context = {}) {
+    if (typeof this.runBeadsOperation !== 'function') {
+      throw new TypeError('runBeadsOperation is not configured on this adapter');
+    }
+
+    return this.runBeadsOperation(operation, args, context, context.deps || {});
+  }
+
+  list(args = [], context = {}) {
+    return this.run('list', args, context);
+  }
+
+  ready(args = [], context = {}) {
+    return this.run('ready', args, context);
+  }
+
+  read(args = [], context = {}) {
+    return this.run('show', args, context);
+  }
+
+  show(args = [], context = {}) {
+    return this.read(args, context);
+  }
+
+  create(args = [], context = {}) {
+    return this.run('create', args, context);
+  }
+
+  search(args = [], context = {}) {
+    return this.run('search', args, context);
+  }
+
+  stats(args = [], context = {}) {
+    return this.run('stats', args, context);
+  }
+
+  update(args = [], context = {}) {
+    return this.run('update', args, context);
+  }
+
+  close(args = [], context = {}) {
+    return this.run('close', args, context);
+  }
+
+  comment(args = [], context = {}) {
+    return this.run('comment', args, context);
+  }
+
+  depAdd(args = [], context = {}) {
+    return this.run('dep.add', args, context);
+  }
+
+  depRemove(args = [], context = {}) {
+    return this.run('dep.remove', args, context);
+  }
+
+  // De-bead parity: claim/release and the KAP-7/KAP-12 derived reads now route
+  // through the backend abstraction (the translations moved out of _issue.js). The
+  // beads layer maps claim -> `update <id> --claim`; release has no bd equivalent
+  // and returns the Kernel-only contract error (handled in runBeadsOperation).
+  claim(args = [], context = {}) {
+    return this.run('claim', args, context);
+  }
+
+  release(args = [], context = {}) {
+    return this.run('release', args, context);
+  }
+
+  blocked(args = [], context = {}) {
+    return this.run('blocked', args, context);
+  }
+
+  stale(args = [], context = {}) {
+    return this.run('stale', args, context);
+  }
+
+  orphans(args = [], context = {}) {
+    return this.run('orphans', args, context);
+  }
+
+  lint(args = [], context = {}) {
+    return this.run('lint', args, context);
+  }
+
+  // Lease ownership is Kernel-only; the beads layer returns the Kernel-only contract
+  // error (handled in runBeadsOperation), matching the release passthrough.
+  owns(args = [], context = {}) {
+    return this.run('owns', args, context);
+  }
+
+  // Active-lease listing is Kernel-only (kernel_claims); the beads layer returns the
+  // Kernel-only contract error (handled in runBeadsOperation), matching owns/release.
+  claims(args = [], context = {}) {
+    return this.run('claims', args, context);
+  }
+
+  mapStatus(status, context = {}) {
+    return normalizeIssueStatus(status, context);
+  }
+
+  decideAuthority(change = {}, context = {}) {
+    return decideIssueAuthority(change, context);
+  }
+}
+
+module.exports = {
+  BeadsIssueAdapter,
+};