@really-knows-ai/foundry 2.3.2 → 3.0.1

package/dist/.opencode/plugins/foundry-tools/git-helpers.js

@@ -0,0 +1,354 @@
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
+import { slugify } from '../../../scripts/lib/slug.js';
+import { CONFIG_RE, DRY_RUN_RE } from '../../../scripts/lib/branch-guard.js';
+import { finishWorkBranchWithArchive } from '../../../scripts/lib/git-finish/work-finish.js';
+import { finishDryRun } from '../../../scripts/lib/snapshot/finish.js';
+import { asyncIoFactory } from './helpers.js';
+
+const WORK_FILES = ['WORK.md', 'WORK.history.yaml', 'WORK.feedback.yaml'];
+
+export const KIND_CONFIG  = 'config';
+export const KIND_WORK    = 'work';
+export const KIND_DRY_RUN = 'dry-run';
+export const KINDS = [KIND_CONFIG, KIND_WORK, KIND_DRY_RUN];
+
+const WORK_RE           = /^work\/.+$/;
+const DRY_RUN_DEEPER_RE = /^dry-run\/[^/]+\/[^/]+\/.+$/;
+
+// -- Shared: stderr extraction --
+
+function extractStderr(err) {
+  if (!err) return '';
+  const text = err.stderr || err.stdout;
+  return text ? String(text).trim() : '';
+}
+
+// -- Kind argument validation --
+
+function validateConfigArgs(args) {
+  if (args.flowId !== undefined && args.flowId !== null && args.flowId !== '')
+    return `flowId is not valid for kind="config"; supply only { kind, description }.`;
+  if (!args.description)
+    return `description is required for kind="config".`;
+  return null;
+}
+
+function validateFlowArgs(kind, args) {
+  if (!args.flowId)
+    return `flowId is required for kind="${kind}".`;
+  if (!args.description)
+    return `description is required for kind="${kind}".`;
+  return null;
+}
+
+export function validateKindArgs(kind, args) {
+  if (kind === KIND_CONFIG) return validateConfigArgs(args);
+  if (kind === KIND_WORK || kind === KIND_DRY_RUN) return validateFlowArgs(kind, args);
+  return `unknown kind "${kind}"; expected one of: ${KINDS.join(', ')}.`;
+}
+
+// -- Starting branch validation --
+
+function validateDryRunDepth(branch) {
+  if (branch && (DRY_RUN_RE.test(branch) || DRY_RUN_DEEPER_RE.test(branch)))
+    return `cannot nest deeper than one dry-run level; you are on '${branch}'.`;
+  return null;
+}
+
+function validateConfigStartBranch(branch) {
+  if (branch && CONFIG_RE.test(branch))
+    return `already on a config/* branch ('${branch}'); edit here directly or finish first.`;
+  if (branch && WORK_RE.test(branch))
+    return `cannot start a config branch from a work branch ('${branch}'); finish or abandon it first.`;
+  return null;
+}
+
+function validateWorkStartBranch(branch) {
+  if (branch && CONFIG_RE.test(branch))
+    return `cannot start a work branch from a config branch ('${branch}'); ` +
+           `use kind="dry-run" to dry-run the in-progress config, or finish config first.`;
+  if (branch && WORK_RE.test(branch))
+    return `already on a work branch ('${branch}'); finish or abandon it first.`;
+  return null;
+}
+
+function validateDryRunStartBranch(branch) {
+  if (!branch || !CONFIG_RE.test(branch))
+    return `kind="dry-run" requires a config/<description> branch as starting point; ` +
+           `currently on ${branch ? "'" + branch + "'" : 'detached HEAD'}.`;
+  return null;
+}
+
+export function validateStartingBranch(kind, branch) {
+  const depthErr = validateDryRunDepth(branch);
+  if (depthErr) return depthErr;
+  if (kind === KIND_CONFIG) return validateConfigStartBranch(branch);
+  if (kind === KIND_WORK) return validateWorkStartBranch(branch);
+  if (kind === KIND_DRY_RUN) return validateDryRunStartBranch(branch);
+  return null;
+}
+
+// -- Branch name construction --
+
+function buildConfigBranchName(descSlug) {
+  return { name: `config/${descSlug}` };
+}
+
+function buildWorkBranchName(flowSlug, descSlug) {
+  return { name: `work/${flowSlug}-${descSlug}` };
+}
+
+function buildDryRunBranchName(parentBranch, flowSlug, descSlug) {
+  const parentSlug = parentBranch.replace(/^config\//, '');
+  return { name: `dry-run/${parentSlug}/${flowSlug}-${descSlug}` };
+}
+
+function requireFlowSlug(args) {
+  const flowSlug = slugify(args.flowId);
+  if (!flowSlug) return { error: 'flowId slug is empty after normalisation.' };
+  return { flowSlug };
+}
+
+function buildFlowBranch(kind, parentBranch, flowSlug, descSlug) {
+  if (kind === KIND_WORK) return buildWorkBranchName(flowSlug, descSlug);
+  if (kind === KIND_DRY_RUN) return buildDryRunBranchName(parentBranch, flowSlug, descSlug);
+  return { error: 'internal: unhandled kind' };
+}
+
+export function buildBranchName(kind, args, parentBranch) {
+  const descSlug = slugify(args.description);
+  if (!descSlug) return { error: 'description slug is empty after normalisation.' };
+  if (kind === KIND_CONFIG) return buildConfigBranchName(descSlug);
+  const flowResult = requireFlowSlug(args);
+  if (flowResult.error) return flowResult;
+  return buildFlowBranch(kind, parentBranch, flowResult.flowSlug, descSlug);
+}
+
+// -- Branch classification --
+
+export function classifyBranch(branch) {
+  if (!branch) return 'detached';
+  if (DRY_RUN_RE.test(branch)) return 'dry-run';
+  if (CONFIG_RE.test(branch)) return 'config';
+  if (WORK_RE.test(branch)) return 'work';
+  return 'other';
+}
+
+// -- Dirty-file detection --
+
+export function dirtyTrackedFiles(cwd) {
+  const out = execFileSync('git',
+    ['status', '--porcelain', '--untracked-files=no'],
+    { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
+  return out ? out.split('\n').map((l) => l.slice(3)) : [];
+}
+
+// -- finishBranchCommon helpers --
+
+function computeFinishPlan(opts) {
+  const { branchName, branchType, base, args, cwd } = opts;
+  const shouldDelete = branchType === 'work';
+  const filesToDelete = shouldDelete
+    ? WORK_FILES.filter((f) => existsSync(path.join(cwd, f)))
+    : [];
+  const action = shouldDelete
+    ? 'delete-work-files, commit-cleanup, checkout-base, squash-merge, commit, delete-work-branch'
+    : `checkout-base, squash-merge, commit, delete-${branchType}-branch`;
+  return { workBranch: branchName, baseBranch: base, filesToDelete, action, commitMessage: args.message };
+}
+
+function makeConfirmRefusal(planned) {
+  return JSON.stringify({
+    ok: false,
+    error: 'foundry_git_finish requires {confirm: true} to perform destructive operations. Re-invoke with confirm:true to apply the plan.',
+    planned,
+  });
+}
+
+function makeDirtyRefusal(dirty) {
+  return JSON.stringify({
+    ok: false,
+    error: 'foundry_git_finish refuses to run on a dirty worktree (uncommitted changes to tracked files). Commit or stash them first.',
+    dirty,
+  });
+}
+
+function mergeErrorLabel(branchType) {
+  return branchType === 'work' ? 'Work' : 'Config';
+}
+
+function formatMergeError(branchName, branchType, err) {
+  const branchLabel = mergeErrorLabel(branchType);
+  const stderr = extractStderr(err);
+  const suffix = stderr ? ' ' + stderr : '';
+  return `foundry_git_finish: squash merge failed (likely a conflict). ${branchLabel} branch '${branchName}' preserved.${suffix}`;
+}
+
+function bestEffortReset(opts) {
+  try { execFileSync('git', ['reset', '--hard', 'HEAD'], opts); } catch { /* best-effort */ }
+}
+
+function bestEffortCheckout(branchName, opts) {
+  try { execFileSync('git', ['checkout', branchName], opts); } catch { /* best-effort */ }
+}
+
+function squashMergeIntoBase(base, branchName, branchType, opts) {
+  execFileSync('git', ['checkout', base], opts);
+  try {
+    execFileSync('git', ['merge', '--squash', branchName], opts);
+  } catch (err) {
+    bestEffortReset(opts);
+    bestEffortCheckout(branchName, opts);
+    return JSON.stringify({ ok: false, error: formatMergeError(branchName, branchType, err) });
+  }
+  return null;
+}
+
+function commitAndDeleteBranch(message, branchName, opts) {
+  execFileSync('git', ['commit', '--no-gpg-sign', '-m', message], opts);
+  const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], opts).trim();
+  execFileSync('git', ['branch', '-D', branchName], opts);
+  return { hash };
+}
+
+function deleteWorkFilesAndCommit(filesToDelete, cwd, branchName) {
+  for (const f of filesToDelete) {
+    const p = path.join(cwd, f);
+    if (existsSync(p)) unlinkSync(p);
+  }
+  try {
+    const opts = { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+    execFileSync('git', ['add', '-A'], opts);
+    const status = execFileSync('git', ['status', '--porcelain'], opts).trim();
+    if (status) {
+      const cleanupMsg = `[${branchName.replace('work/', '')}] cleanup: remove work files`;
+      execFileSync('git', ['commit', '-m', cleanupMsg], opts);
+    }
+  } catch { /* no changes to commit */ }
+}
+
+export function finishBranchCommon({ branchName, branchType, base, cwd, args }) {
+  const opts = { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+  const planned = computeFinishPlan({ branchName, branchType, base, args, cwd });
+  if (args.confirm !== true) return makeConfirmRefusal(planned);
+  const dirty = dirtyTrackedFiles(cwd);
+  if (dirty.length) return makeDirtyRefusal(dirty);
+  if (branchType === 'work') deleteWorkFilesAndCommit(planned.filesToDelete, cwd, branchName);
+  const mergeErr = squashMergeIntoBase(base, branchName, branchType, opts);
+  if (mergeErr) return mergeErr;
+  const { hash } = commitAndDeleteBranch(args.message, branchName, opts);
+  return JSON.stringify({ ok: true, hash, branch: base });
+}
+
+// -- finishWorkBranch helpers --
+
+function makeExecGit(cwd, opts) {
+  return (argv) => {
+    if (argv[0] === 'diff')
+      return execFileSync('git', argv, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    return execFileSync('git', argv, opts);
+  };
+}
+
+function makeWriteTempMessage(cwd, opts) {
+  return (content) => {
+    const gitDir = execFileSync('git', ['rev-parse', '--git-dir'], opts).trim();
+    const gitDirAbsolute = path.isAbsolute(gitDir) ? gitDir : path.join(cwd, gitDir);
+    const tmpPath = path.join(gitDirAbsolute, `COMMIT_EDITMSG_${Date.now()}`);
+    writeFileSync(tmpPath, content, 'utf8');
+    return tmpPath;
+  };
+}
+
+function makeWorkFinishPlanned(workBranch, base) {
+  return {
+    workBranch,
+    baseBranch: base,
+    action: 'verify-attest, checkout-base, squash-merge, signed-commit',
+  };
+}
+
+function formatWorkFinishError(err) {
+  const stderr = extractStderr(err);
+  if (stderr) return `foundry_git_finish: attested work finish failed. ${stderr}`;
+  return `foundry_git_finish: attested work finish failed. ${err.message ?? String(err)}`;
+}
+
+export async function finishWorkBranch({ workBranch, base, cwd, args }) {
+  const opts = { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+  if (args.confirm !== true) {
+    return JSON.stringify({
+      ok: false,
+      error: 'foundry_git_finish requires {confirm: true}.',
+      planned: makeWorkFinishPlanned(workBranch, base),
+    });
+  }
+  const dirty = dirtyTrackedFiles(cwd);
+  if (dirty.length) {
+    return JSON.stringify({ ok: false, error: 'foundry_git_finish: dirty tracked files.', dirty });
+  }
+  const execGit = makeExecGit(cwd, opts);
+  const writeTempMessage = makeWriteTempMessage(cwd, opts);
+  try {
+    const result = await finishWorkBranchWithArchive({
+      branchName: workBranch,
+      baseBranch: base,
+      confirm: args.confirm,
+      execGit,
+      fileExists: (p) => existsSync(p),
+      readAttest: (p) => readFileSync(p, 'utf8'),
+      deleteFile: (p) => { if (existsSync(p)) unlinkSync(p); },
+      writeTempMessage,
+      cwd,
+    });
+    return JSON.stringify(result);
+  } catch (err) {
+    return JSON.stringify({ ok: false, error: formatWorkFinishError(err) });
+  }
+}
+
+// -- finishConfigBranch --
+
+export function finishConfigBranch({ configBranch, base, cwd, args }) {
+  return finishBranchCommon({
+    branchName: configBranch,
+    branchType: 'config',
+    base,
+    cwd,
+    args,
+  });
+}
+
+// -- finishDryRunBranch --
+
+export async function finishDryRunBranch({ branch, args, cwd }) {
+  const io = asyncIoFactory({ worktree: cwd });
+  const exec = (argv) => execFileSync('git', argv,
+    { cwd, encoding: 'utf8', stdio: 'pipe' });
+
+  if (args.confirm !== true) {
+    return JSON.stringify({
+      ok: false,
+      error: 'foundry_git_finish requires {confirm: true} to perform destructive operations. Re-invoke with confirm:true to apply the plan.',
+      planned: {
+        branch,
+        action: 'snapshot + discard (dry-run finish)',
+        snapshotPath: '.snapshots/<runId> (computed at apply time)',
+      },
+    });
+  }
+
+  try {
+    const out = await finishDryRun({
+      message: args.message, branch, io, execFile: exec,
+    });
+    return JSON.stringify(out);
+  } catch (err) {
+    return JSON.stringify({
+      ok: false,
+      error: `foundry_git_finish: dry-run finish failed: ${err.message ?? String(err)}`,
+    });
+  }
+}

package/dist/.opencode/plugins/foundry-tools/git-tools.js

@@ -0,0 +1,181 @@
+import { execFileSync } from 'child_process';
+import {
+  validateKindArgs,
+  validateStartingBranch,
+  buildBranchName,
+  classifyBranch,
+  finishWorkBranch,
+  finishConfigBranch,
+  finishDryRunBranch,
+  KIND_DRY_RUN,
+  KINDS,
+} from './git-helpers.js';
+import { makeIO, makeExec, asyncIoFactory } from './helpers.js';
+import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
+import { currentBranch } from '../../../scripts/lib/branch-guard.js';
+import { truncateTrace } from '../../../scripts/lib/tracing.js';
+
+function refuse(error) { return JSON.stringify({ error }); }
+
+// -- foundry_git_branch helpers --
+
+function validateBranchCreationArgs(args) {
+  if (!args.kind)
+    return 'foundry_git_branch: kind is required (one of: config, work, dry-run)';
+  if (!KINDS.includes(args.kind))
+    return `foundry_git_branch: unknown kind "${args.kind}" ` +
+           `(expected one of: ${KINDS.join(', ')})`;
+  const argErr = validateKindArgs(args.kind, args);
+  if (argErr) return `foundry_git_branch: ${argErr}`;
+  return null;
+}
+
+function refuseBranchCreate(branchName, err) {
+  if (!err) return refuse(`foundry_git_branch: failed to create branch '${branchName}'.`);
+  const text = err.stderr || err.stdout;
+  if (!text) return refuse(`foundry_git_branch: failed to create branch '${branchName}'.`);
+  return refuse(`foundry_git_branch: failed to create branch '${branchName}'. ${String(text).trim()}`);
+}
+
+async function tryCreateBranch(name, cwd) {
+  try {
+    execFileSync('git', ['checkout', '-b', name],
+      { cwd, encoding: 'utf8', stdio: 'pipe' });
+    return null;
+  } catch (err) {
+    return refuseBranchCreate(name, err);
+  }
+}
+
+async function tryTruncateTrace(branch, worktree) {
+  try {
+    await truncateTrace({
+      branch,
+      io: asyncIoFactory({ worktree }),
+    });
+  } catch { /* swallow */ }
+}
+
+async function createAndFinaliseBranch(kind, built, worktree) {
+  const createErr = await tryCreateBranch(built.name, worktree);
+  if (createErr) return createErr;
+  if (kind === KIND_DRY_RUN)
+    await tryTruncateTrace(built.name, worktree);
+  return JSON.stringify({ ok: true, branch: built.name });
+}
+
+async function executeGitBranch(args, context) {
+  const io = makeIO(context.worktree);
+  const stageGuard = requireNoActiveStage(io);
+  if (!stageGuard.ok)
+    return refuse(`foundry_git_branch ${stageGuard.error}`);
+
+  const validationErr = validateBranchCreationArgs(args);
+  if (validationErr) return refuse(validationErr);
+
+  const branch = currentBranch({ exec: makeExec(context.worktree) });
+  const startErr = validateStartingBranch(args.kind, branch);
+  if (startErr) return refuse(`foundry_git_branch: ${startErr}`);
+
+  const built = buildBranchName(args.kind, args, branch);
+  if (built.error) return refuse(`foundry_git_branch: ${built.error}`);
+
+  return createAndFinaliseBranch(args.kind, built, context.worktree);
+}
+
+// -- foundry_git_finish helpers --
+
+function refuseBaseBranchForDryRun() {
+  return refuse(
+    'foundry_git_finish: baseBranch is not valid for a dry-run ' +
+    'finish; the parent config branch is determined by the dry-run ' +
+    'branch name.');
+}
+
+function makeNoopResult(base) {
+  return JSON.stringify({
+    ok: true,
+    noop: true,
+    message: `Already on ${base} — nothing to merge`,
+    branch: base,
+  });
+}
+
+function refuseUnknownFinishBranch(branch) {
+  return refuse(
+    `foundry_git_finish: nothing to finish on '${branch || 'detached HEAD'}' ` +
+    `(expected work/<x>, config/<x>, or dry-run/<x>/<y>).`);
+}
+
+function routeDryRunFinish(branch, args, cwd) {
+  if (args.baseBranch !== undefined)
+    return refuseBaseBranchForDryRun();
+  return finishDryRunBranch({ branch, args, cwd });
+}
+
+function routeBranchFinish(kind, branch, base, cwd, args) {
+  if (kind === 'work')
+    return finishWorkBranch({ workBranch: branch, base, cwd, args });
+  if (kind === 'config')
+    return finishConfigBranch({ configBranch: branch, base, cwd, args });
+  return refuseUnknownFinishBranch(branch);
+}
+
+async function executeGitFinish(args, context) {
+  const io = makeIO(context.worktree);
+  const stageGuard = requireNoActiveStage(io);
+  if (!stageGuard.ok)
+    return refuse(`foundry_git_finish ${stageGuard.error}`);
+
+  const cwd = context.worktree;
+  const branch = currentBranch({ exec: makeExec(cwd) });
+  const kind = classifyBranch(branch);
+
+  if (kind === 'dry-run')
+    return routeDryRunFinish(branch, args, cwd);
+
+  const base = args.baseBranch || 'main';
+  if (branch === base) return makeNoopResult(base);
+  return routeBranchFinish(kind, branch, base, cwd, args);
+}
+
+// -- Tool definitions --
+
+export function createGitTools({ tool }) {
+  return {
+    foundry_git_branch: tool({
+      description:
+        'Create and checkout a foundry branch. Requires `kind`: ' +
+        '"config" (schema work, off main), "work" (flow run, off main), ' +
+        'or "dry-run" (flow run off a config/* branch).',
+      args: {
+        kind: tool.schema.string().describe('config | work | dry-run'),
+        flowId: tool.schema.string().optional()
+          .describe('Flow ID. Required for kind="work" and "dry-run"; not valid for kind="config".'),
+        description: tool.schema.string()
+          .describe('Slugified description suffix.'),
+      },
+      async execute(args, context) {
+        return executeGitBranch(args, context);
+      },
+    }),
+
+    foundry_git_finish: tool({
+      description:
+        'Finish the current foundry branch. ' +
+        'work/<x>: squash-merge + WORK cleanup. ' +
+        'config/<x>: squash-merge. ' +
+        'dry-run/<x>/<y>: snapshot + discard.',
+      args: {
+        message: tool.schema.string().describe('Squash merge / snapshot message'),
+        baseBranch: tool.schema.string().optional()
+          .describe('Target branch (default: main). Not valid for dry-run finish.'),
+        confirm: tool.schema.boolean().optional()
+          .describe('Must be true to perform destructive operations; otherwise returns a plan'),
+      },
+      async execute(args, context) {
+        return executeGitFinish(args, context);
+      },
+    }),
+  };
+}