@really-knows-ai/foundry 2.3.2 → 3.0.0

package/dist/.opencode/plugins/foundry-tools/config-law-tools.js

@@ -0,0 +1,380 @@
+// Tools for reading, adding, and editing laws
+// foundry_config_read_law: read-only, returns full markdown (no branch guard)
+// foundry_config_add_law: write + commit on config/* branch
+// foundry_config_edit_law: update body and commit on config/* branch
+
+import { join, dirname } from 'path';
+import { validate as validateLaw } from '../../../scripts/lib/config-validators/law.js';
+import { requireGitRepo, requireFoundryRoot } from '../../../scripts/lib/foundational-guards.js';
+import { requireOnConfigBranch } from '../../../scripts/lib/branch-guard.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { UnexpectedFilesError, commitWithPolicy } from '../../../scripts/lib/git-bridge.js';
+import { makeIO, makeExec, makeAsyncIO, errorJson, branchIoFactory, asyncIoFactory } from './helpers.js';
+import { execFileSync } from 'child_process';
+
+// --- utility functions -------------------------------------------------------
+
+function contentContainsLaw(content, lawId) {
+  const pattern = new RegExp(`^## ${lawId}(?:\\s|$)`, 'm');
+  return pattern.test(content);
+}
+
+function findLawStart(lines, lawId) {
+  for (let i = 0; i < lines.length; i++) {
+    const heading = lines[i].match(/^## (.+)/);
+    if (heading && heading[1].trim() === lawId) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+function findLawEnd(lines, startIdx) {
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i].match(/^## (.+)/)) {
+      return i;
+    }
+  }
+  return lines.length;
+}
+
+// Extract full markdown for a single law from file content
+function extractLawMarkdown(content, lawId) {
+  const lines = content.split('\n');
+  const startIdx = findLawStart(lines, lawId);
+
+  if (startIdx < 0) return null;
+
+  const endIdx = findLawEnd(lines, startIdx);
+  const lawLines = lines.slice(startIdx, endIdx);
+  
+  while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') {
+    lawLines.pop();
+  }
+  
+  return lawLines.join('\n') + '\n';
+}
+
+async function searchGlobalLaws(io, foundryDir, lawId) {
+  const globalLawsDir = join(foundryDir, 'laws');
+  if (!(await io.exists(globalLawsDir))) {
+    return null;
+  }
+
+  const files = await io.readDir(globalLawsDir);
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    const path = join(globalLawsDir, file);
+    const content = await io.readFile(path);
+    if (contentContainsLaw(content, lawId)) {
+      return { path, fullMarkdown: content, source: 'global' };
+    }
+  }
+
+  return null;
+}
+
+async function searchTypeSpecificLaws(io, foundryDir, lawId) {
+  const artefactsDir = join(foundryDir, 'artefacts');
+  if (!(await io.exists(artefactsDir))) {
+    return null;
+  }
+
+  const types = await io.readDir(artefactsDir);
+  for (const typeId of types) {
+    const typeLawsPath = join(artefactsDir, typeId, 'laws.md');
+    if (!(await io.exists(typeLawsPath))) continue;
+
+    const content = await io.readFile(typeLawsPath);
+    if (contentContainsLaw(content, lawId)) {
+      return { path: typeLawsPath, fullMarkdown: content, source: `type:${typeId}` };
+    }
+  }
+
+  return null;
+}
+
+async function findLawByID(io, foundryDir, lawId) {
+  let result = await searchGlobalLaws(io, foundryDir, lawId);
+  if (result) {
+    return { found: true, ...result };
+  }
+
+  result = await searchTypeSpecificLaws(io, foundryDir, lawId);
+  if (result) {
+    return { found: true, ...result };
+  }
+
+  return { found: false };
+}
+
+// --- guard helpers ---------------------------------------------------------
+
+function gitRepoGuard(_args, context) {
+  return requireGitRepo(makeIO(context.worktree));
+}
+
+function foundryRootGuard(_args, context) {
+  return requireFoundryRoot(makeIO(context.worktree));
+}
+
+function configBranchGuard(_args, context) {
+  return requireOnConfigBranch({ exec: makeExec(context.worktree) });
+}
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+const GIT_COMMAND = 'git';
+
+function makeExecFile(cwd) {
+  return (argv) => execFileSync(GIT_COMMAND, argv, { cwd, encoding: 'utf8', stdio: 'pipe' });
+}
+
+const READ_GUARDS = [gitRepoGuard, foundryRootGuard];
+const CREATE_GUARDS = [gitRepoGuard, foundryRootGuard, configBranchGuard, gateNotFailed];
+const EDIT_GUARDS = [gitRepoGuard, foundryRootGuard, configBranchGuard, gateNotFailed];
+
+// --- read law executor -------------------------------------------------------
+
+async function executeReadLaw(args, context) {
+  try {
+    const io = makeAsyncIO(context.worktree);
+    const result = await findLawByID(io, 'foundry', args.id);
+    if (!result.found) {
+      return JSON.stringify({
+        ok: false,
+        errors: [`Law "${args.id}" not found`],
+      });
+    }
+    const markdown = extractLawMarkdown(result.fullMarkdown, args.id);
+    if (!markdown) {
+      return JSON.stringify({
+        ok: false,
+        errors: [`Could not extract law "${args.id}" from file`],
+      });
+    }
+    return JSON.stringify({
+      ok: true,
+      id: args.id,
+      markdown,
+      source: result.source,
+    });
+  } catch (err) {
+    return errorJson(err);
+  }
+}
+
+// --- add law validation helpers -------------------------------------------------------
+
+function validateAddLawTarget(target) {
+  const err = validateAddLawTargetStruct(target);
+  if (err) return err;
+  return target.kind === 'global' ? validateGlobalLawTarget(target) : validateTypeSpecLawTarget(target);
+}
+
+function validateAddLawTargetStruct(target) {
+  if (!target || typeof target !== 'object') {
+    return 'target argument is required (object with kind + locator)';
+  }
+  const kinds = ['global', 'type-specific'];
+  if (!kinds.includes(target.kind)) return `unknown target.kind: ${target.kind}`;
+  return null;
+}
+
+function validateGlobalLawTarget(target) {
+  if (typeof target.file !== 'string' || !target.file.trim()) {
+    return 'target.file is required for kind: "global"';
+  }
+  return null;
+}
+
+function validateTypeSpecLawTarget(target) {
+  if (typeof target.typeId !== 'string' || !target.typeId.trim()) {
+    return 'target.typeId is required for kind: "type-specific"';
+  }
+  return null;
+}
+
+function computeTargetPath(target) {
+  if (target?.kind === 'global') {
+    return join('foundry', 'laws', target.file);
+  }
+  return join('foundry', 'artefacts', target.typeId, 'laws.md');
+}
+
+// --- add law executor --------------------------------------------------------
+
+async function validateAddLawPrerequisites(io, args) {
+  const targetError = validateAddLawTarget(args.target);
+  if (targetError) {
+    return { error: targetError };
+  }
+
+  const path = computeTargetPath(args.target);
+  const validation = await validateLaw({ body: args.body, io });
+  if (!validation.ok) {
+    return validation;
+  }
+
+  if (await io.exists(path)) {
+    return {
+      ok: false,
+      errors: [`${path} already exists; use foundry_config_edit_law to update an existing law in place`],
+    };
+  }
+
+  return { ok: true, path };
+}
+
+async function executeAddLaw(args, context) {
+  const io = makeAsyncIO(context.worktree);
+  const execFile = makeExecFile(context.worktree);
+
+  try {
+    const prereq = await validateAddLawPrerequisites(io, args);
+    if (prereq.error) {
+      return JSON.stringify({ ok: false, errors: [prereq.error] });
+    }
+    if (!prereq.ok) {
+      return JSON.stringify(prereq);
+    }
+
+    const path = prereq.path;
+
+    await io.mkdirp(dirname(path));
+    await io.writeFile(path, args.body);
+
+    const sha = commitWithPolicy({
+      message: `config: add law ${args.name}\n\nvia foundry_config_add_law`,
+      allowedPatterns: ['foundry/**'],
+      execFile,
+    });
+
+    return JSON.stringify({ ok: true, path, sha });
+  } catch (err) {
+    if (err instanceof UnexpectedFilesError) {
+      return JSON.stringify({ error: err.message, affected_files: err.files });
+    }
+    return errorJson(err);
+  }
+}
+
+// --- helper for preserving sibling laws -------------------------------------------------------
+
+// Replace a law in file content while preserving other laws
+function replaceLawInContent(content, lawId, newLawMarkdown) {
+  const lines = content.split('\n');
+  const startIdx = findLawStart(lines, lawId);
+  if (startIdx < 0) return content.trimEnd() + '\n\n' + newLawMarkdown;
+  
+  const endIdx = findLawEnd(lines, startIdx);
+  const before = lines.slice(0, startIdx);
+  const after = lines.slice(endIdx);
+  
+  // Trim trailing empty lines from before
+  const beforeEnd = before.findLastIndex(l => l !== '') + 1;
+  before.length = beforeEnd;
+  
+  // Trim leading empty lines from after  
+  const afterStart = after.findIndex(l => l !== '');
+  if (afterStart > 0) after.splice(0, afterStart);
+  
+  // newLawMarkdown includes trailing newline; split and rejoin without final empty string
+  const newLines = newLawMarkdown.trimEnd().split('\n');
+  return before.concat(newLines, after).join('\n') + '\n';
+}
+
+// --- edit law executor -------------------------------------------------------
+
+async function executeEditLaw(args, context) {
+  const io = makeAsyncIO(context.worktree);
+  const execFile = makeExecFile(context.worktree);
+
+  try {
+    const result = await findLawByID(io, 'foundry', args.id);
+    if (!result.found) {
+      return JSON.stringify({
+        ok: false,
+        errors: [`Law "${args.id}" not found`],
+      });
+    }
+
+    const validation = await validateLaw({ body: args.body, io });
+    if (!validation.ok) {
+      return JSON.stringify(validation);
+    }
+
+    const fileContent = replaceLawInContent(result.fullMarkdown, args.id, args.body);
+    await io.writeFile(result.path, fileContent);
+    execFile(['add', result.path]);
+    execFile(['commit', '-m', `config: edit law ${args.id}\n\nvia foundry_config_edit_law`]);
+
+    return JSON.stringify({
+      ok: true,
+      id: args.id,
+      path: result.path.replace(/^foundry\//, 'foundry/'),
+      source: result.source,
+    });
+  } catch (err) {
+    if (err instanceof UnexpectedFilesError) {
+      return JSON.stringify({ error: err.message, affected_files: err.files });
+    }
+    return errorJson(err);
+  }
+}
+
+// --- tool factories -------------------------------------------------------
+
+function makeReadLawTool(tool) {
+  return tool({
+    description: 'Read a law by ID, returning the full markdown including validators block.',
+    args: {
+      id: tool.schema.string().describe('Law ID to read'),
+    },
+    execute: guarded('foundry_config_read_law', READ_GUARDS, executeReadLaw, {
+      branchIo: branchIoFactory,
+      io: asyncIoFactory,
+    }),
+  });
+}
+
+function makeAddLawTool(tool) {
+  return tool({
+    description: 'Add a new law (config-tier; requires a config/* branch). Target must be {kind:"global", file:"<name>.md"} or {kind:"type-specific", typeId:"<id>"}.',
+    args: {
+      name: tool.schema.string(),
+      body: tool.schema.string(),
+      target: tool.schema.object({
+        kind: tool.schema.string(),
+        file: tool.schema.string().optional(),
+        typeId: tool.schema.string().optional(),
+      }),
+    },
+    execute: guarded('foundry_config_add_law', CREATE_GUARDS, executeAddLaw, {
+      branchIo: branchIoFactory,
+      io: asyncIoFactory,
+    }),
+  });
+}
+
+function makeEditLawTool(tool) {
+  return tool({
+    description: 'Edit an existing law by ID. Validates the new body, updates the file, and commits on the current config/* branch.',
+    args: {
+      id: tool.schema.string().describe('Law ID to edit'),
+      body: tool.schema.string().describe('Full new markdown body for the law'),
+    },
+    execute: guarded('foundry_config_edit_law', EDIT_GUARDS, executeEditLaw, {
+      branchIo: branchIoFactory,
+      io: asyncIoFactory,
+    }),
+  });
+}
+
+export function createConfigLawTools({ tool }) {
+  return {
+    foundry_config_read_law: makeReadLawTool(tool),
+    foundry_config_add_law: makeAddLawTool(tool),
+    foundry_config_edit_law: makeEditLawTool(tool),
+  };
+}

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

@@ -0,0 +1,43 @@
+import { getCycleDefinition, getArtefactType, getLaws, getAppraisers, getFlow } from '../../../scripts/lib/config.js';
+import { makeIO } from './helpers.js';
+
+function makeConfigTool(tool, description, argSchema, invoke) {
+  return tool({
+    description,
+    args: argSchema,
+    async execute(args, context) {
+      const io = makeIO(context.worktree);
+      return JSON.stringify(await invoke(args, io));
+    },
+  });
+}
+
+export function createConfigTools({ tool }) {
+  return {
+    foundry_config_cycle: makeConfigTool(
+      tool, 'Get a cycle definition from foundry config',
+      { cycleId: tool.schema.string().describe('Cycle ID') },
+      (args, io) => getCycleDefinition('foundry', args.cycleId, io),
+    ),
+    foundry_config_artefact_type: makeConfigTool(
+      tool, 'Get an artefact type definition',
+      { typeId: tool.schema.string().describe('Artefact type ID') },
+      (args, io) => getArtefactType('foundry', args.typeId, io),
+    ),
+    foundry_config_laws: makeConfigTool(
+      tool, 'Get laws, optionally filtered by artefact type',
+      { typeId: tool.schema.string().optional().describe('Artefact type ID') },
+      (args, io) => getLaws('foundry', io, { typeId: args.typeId }),
+    ),
+    foundry_config_appraisers: makeConfigTool(
+      tool, 'List all appraisers',
+      {},
+      (_args, io) => getAppraisers('foundry', io),
+    ),
+    foundry_config_flow: makeConfigTool(
+      tool, 'Get a flow definition',
+      { flowId: tool.schema.string().describe('Flow ID') },
+      (args, io) => getFlow('foundry', args.flowId, io),
+    ),
+  };
+}

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

@@ -0,0 +1,234 @@
+import { openFeedbackStore } from '../../../scripts/lib/feedback-store.js';
+import { parseFrontmatter } from '../../../scripts/lib/workfile.js';
+import { requireActiveStage, stageBaseOf } from '../../../scripts/lib/stage-guard.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+function readCycle(io) {
+  if (!io.exists('WORK.md')) return null;
+  const fm = parseFrontmatter(io.readFile('WORK.md'));
+  return fm.cycle || null;
+}
+
+// Shared guard preamble for stage-bound feedback tools.
+// Returns {ok:true, activeStage, stageBase, cycle} or {ok:false, error}.
+// Caller is responsible for any tool-specific stage-base / tag checks.
+function preflight(io, toolName) {
+  const guard = requireActiveStage(io);
+  if (!guard.ok) return { ok: false, error: `${toolName} requires active stage; ${guard.error}` };
+  const activeStage = guard.active.stage;
+  const stageBase = stageBaseOf(activeStage);
+  const cycle = readCycle(io);
+  if (!cycle) return { ok: false, error: `${toolName}: WORK.md cycle not found` };
+  return { ok: true, activeStage, stageBase, cycle };
+}
+
+// Stages that are forbidden from adding feedback entirely.
+const FEEDBACK_ADD_FORBIDDEN = {
+  forge: 'foundry_feedback_add: forge stages do not add feedback',
+  assay: 'foundry_feedback_add: assay stages do not add feedback (extractor failure marks the workfile failed)',
+};
+
+// Per-stage tag validators for stages that allow feedback with restrictions.
+const FEEDBACK_ADD_TAG_VALIDATORS = {
+  quench: {
+    test: tag => tag.startsWith('law:'),
+    message: tag => `foundry_feedback_add: quench may only add tags starting with "law:"; got "${tag}"`,
+  },
+  appraise: {
+    test: tag => tag.startsWith('law:'),
+    message: tag => `foundry_feedback_add: appraise tag must start with "law:"; got "${tag}"`,
+  },
+  'human-appraise': {
+    test: tag => tag === 'human',
+    message: tag => `foundry_feedback_add: human-appraise may only add tag "human"; got "${tag}"`,
+  },
+};
+
+// Validate that the given tag is allowed for the current stage base.
+// Returns {ok: true} or {ok: false, error}.
+function validateFeedbackAddTag(stageBase, tag) {
+  const forbiddenMsg = FEEDBACK_ADD_FORBIDDEN[stageBase];
+  if (forbiddenMsg) return { ok: false, error: forbiddenMsg };
+  const rule = FEEDBACK_ADD_TAG_VALIDATORS[stageBase];
+  if (!rule) return { ok: true };
+  if (rule.test(tag)) return { ok: true };
+  return { ok: false, error: rule.message(tag) };
+}
+
+async function executeFeedbackAdd(args, context) {
+  const io = makeIO(context.worktree);
+  const pre = preflight(io, 'foundry_feedback_add');
+  if (!pre.ok) return JSON.stringify({ error: pre.error });
+  const { activeStage, stageBase, cycle } = pre;
+
+  const tagCheck = validateFeedbackAddTag(stageBase, args.tag);
+  if (!tagCheck.ok) return JSON.stringify({ error: tagCheck.error });
+
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    const { id, deduped } = store.add({
+      file: args.file,
+      tag: args.tag,
+      text: args.text,
+      source: activeStage,
+      cycle,
+    });
+    return JSON.stringify({ ok: true, id, deduped });
+  } catch (err) {
+    return JSON.stringify({ error: `foundry_feedback_add: ${err.message}` });
+  }
+}
+
+async function executeFeedbackAction(args, context) {
+  const io = makeIO(context.worktree);
+  const pre = preflight(io, 'foundry_feedback_action');
+  if (!pre.ok) return JSON.stringify({ error: pre.error });
+  const { activeStage, stageBase, cycle } = pre;
+  if (stageBase !== 'forge') {
+    return JSON.stringify({ error: `foundry_feedback_action requires active forge stage; current: ${activeStage}` });
+  }
+
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    const r = store.transition({
+      id: args.id,
+      target: 'actioned',
+      stage: activeStage,
+      cycle,
+    });
+    if (!r.ok) return JSON.stringify({ error: r.error });
+    return JSON.stringify({ ok: true });
+  } catch (err) {
+    return JSON.stringify({ error: `foundry_feedback_action: ${err.message}` });
+  }
+}
+
+async function executeFeedbackWontfix(args, context) {
+  const io = makeIO(context.worktree);
+  const pre = preflight(io, 'foundry_feedback_wontfix');
+  if (!pre.ok) return JSON.stringify({ error: pre.error });
+  const { activeStage, stageBase, cycle } = pre;
+  if (stageBase !== 'forge') {
+    return JSON.stringify({ error: `foundry_feedback_wontfix requires active forge stage; current: ${activeStage}` });
+  }
+
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    const r = store.transition({
+      id: args.id,
+      target: 'wont-fix',
+      stage: activeStage,
+      cycle,
+      reason: args.reason,
+    });
+    if (!r.ok) return JSON.stringify({ error: r.error });
+    return JSON.stringify({ ok: true });
+  } catch (err) {
+    return JSON.stringify({ error: `foundry_feedback_wontfix: ${err.message}` });
+  }
+}
+
+function resolveTargetFromResolution(resolution) {
+  return resolution === 'approved' ? 'resolved' : 'rejected';
+}
+
+async function executeFeedbackResolve(args, context) {
+  const io = makeIO(context.worktree);
+  const pre = preflight(io, 'foundry_feedback_resolve');
+  if (!pre.ok) return JSON.stringify({ error: pre.error });
+  const { activeStage, stageBase, cycle } = pre;
+  const allowedStages = ['quench', 'appraise', 'human-appraise'];
+  if (!allowedStages.includes(stageBase)) {
+    return JSON.stringify({ error: `foundry_feedback_resolve requires active quench|appraise|human-appraise stage; current: ${activeStage}` });
+  }
+
+  const target = resolveTargetFromResolution(args.resolution);
+
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    const r = store.transition({
+      id: args.id,
+      target,
+      stage: activeStage,
+      cycle,
+      reason: args.reason,
+    });
+    if (!r.ok) return JSON.stringify({ error: r.error });
+    return JSON.stringify({ ok: true });
+  } catch (err) {
+    return JSON.stringify({ error: `foundry_feedback_resolve: ${err.message}` });
+  }
+}
+
+async function executeFeedbackList(args, context) {
+  const io = makeIO(context.worktree);
+  if (!io.exists('WORK.md')) {
+    return JSON.stringify({ error: 'foundry_feedback_list: WORK.md cycle not found' });
+  }
+  try {
+    const store = openFeedbackStore('WORK.feedback.yaml', io);
+    const items = store.list()
+      .filter(it => !args.file || it.file === args.file)
+      .map(it => {
+        const head = it.history[0];
+        const base = {
+          id: it.id,
+          file: it.file,
+          tag: it.tag,
+          text: it.text,
+          source: it.source,
+          state: head.state,
+          depth: it.history.length,
+        };
+        if (head.reason) base.reason = head.reason;
+        return base;
+      });
+    return JSON.stringify(items);
+  } catch (err) {
+    return JSON.stringify({ error: `foundry_feedback_list: ${err.message}` });
+  }
+}
+
+export function createFeedbackTools({ tool }) {
+  return {
+    foundry_feedback_add: tool({ description: 'Add a feedback item to WORK.feedback.yaml',
+      args: {
+        file: tool.schema.string().describe('Artefact file path'),
+        text: tool.schema.string().describe('Feedback text'),
+        tag: tool.schema.string().describe('Tag for the feedback item'),
+      },
+      execute: guarded('foundry_feedback_add', [flowBranchGuard, gateNotFailed], executeFeedbackAdd, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+    foundry_feedback_action: tool({ description: 'Mark a feedback item as actioned (forge stages only)',
+      args: {
+        id: tool.schema.string().describe('Feedback item id (ULID)'),
+      },
+      execute: guarded('foundry_feedback_action', [flowBranchGuard, gateNotFailed], executeFeedbackAction, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+    foundry_feedback_wontfix: tool({ description: 'Mark a feedback item as wont-fix with reason (forge stages only)',
+      args: {
+        id: tool.schema.string().describe('Feedback item id (ULID)'),
+        reason: tool.schema.string().describe('Reason for wont-fix'),
+      },
+      execute: guarded('foundry_feedback_wontfix', [flowBranchGuard, gateNotFailed], executeFeedbackWontfix, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+    foundry_feedback_resolve: tool({
+      description: 'Resolve a feedback item (approved or rejected). In human-appraise stages, this tool can override deadlocked items by providing a reason.',
+      args: {
+        id: tool.schema.string().describe('Feedback item id (ULID)'),
+        resolution: tool.schema.enum(['approved', 'rejected']).describe('Resolution type'),
+        reason: tool.schema.string().optional().describe('Reason (required if rejected, or for deadlock override)'),
+      },
+      execute: guarded('foundry_feedback_resolve', [flowBranchGuard, gateNotFailed], executeFeedbackResolve, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+    foundry_feedback_list: tool({ description: 'List feedback items, optionally filtered by file',
+      args: {
+        file: tool.schema.string().optional().describe('Filter by artefact file path'),
+      },
+      execute: executeFeedbackList,
+    }),
+  };
+}