forge-workflow 0.0.9 → 0.1.0-beta.2

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,
+};