changeledger 0.4.0 → 0.6.0

package/src/contract.mjs

@@ -1,29 +1,49 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { writeFileAtomic } from './atomic-write.mjs';
-import { agentsTemplate } from './paths.mjs';
 
-// The tool's contract (templates/AGENTS.md) is a tool artifact, not a project
-// artifact. Each repo links to the installed copy via `.changeledger/AGENTS.md` (a
-// per-machine, gitignored symlink) and points its own contract files at that
-// link. We never copy the contract (it would drift) nor commit the symlink (it
-// would dangle on another machine). See change #20260614-151759.
-
-// Project-owned contract files that should reference the linked contract. The
-// root AGENTS.md is required by `init`; CLAUDE.md is referenced when present.
 const CONTRACT_FILES = ['AGENTS.md', 'CLAUDE.md'];
-
 const MARKER = '<!-- changeledger -->';
-const REFERENCE = `${MARKER}
+const LEGACY_ENTRY = '.changeledger/AGENTS.md';
+// Exact SHA-256 digests of every historical templates/AGENTS.md payload. A
+// regular file is removed only when it is byte-identical to a contract version
+// ChangeLedger actually shipped; headings or other heuristics are not enough.
+const LEGACY_CONTRACT_HASHES = new Set([
+  '92a6d22c9985dce2d15724d20e2d5c0f1178d82dc56d28e339b72c7a27574c6f',
+  '4701b260d0cc39098f3b942ed2b1969f00a84e7b77a4e107070fedef0fda7d0d',
+  '30b3ce1768655ebee2be2b88328ba860293d8bbbe55e12a5aacc8177d7d02c9b',
+  'd36d17f99505f2b47a7ceea8f078618f652807463d5d60a83ca95f940d5a9c35',
+  '1175cc4bcc884d792cdde2338b3c72b336bcb66b47555d6e5938d756acdea635',
+  'f605adad9192286bc2cda45aebb5a12dab5b3c199924789398684b79b55811',
+  '05e06c8e9dc45ac41ff38b47075b22492c30f3f1a7019371293be10351aada77',
+  '9816e4d14f70dad268f9b89ad49094665997bf62f0b773a05fe8eed17eebc9de',
+  '1b5439055e52a1bb72f72b99cbd2842b2118776fb80e262175d584a335e07e5f',
+  '6fe7a03f699ffa875c1ef4bc2d59b451058d6ab4c3c8824cc220ae031d068480',
+  'd56ec9ef5c1bd71464d9d9bc2a772c42cce103f336ebba61106855c8011bca6f',
+  '071ed83e79589ec0362e4e99ee80cb4f7a839f2a810cf59dbf056c46e342a09c',
+  '1148a1b69ce035a695c64f0df1aaaedcbeeed669b5b774c52f7b136e9f5fe4f9',
+  '25d4508b0b60aa939e81d1e83383f90e7a41feacb6cb2f12fab6548cebb77ca1',
+  '37e1ffe059c0d26b07566597607c41d42df3e9548830d42413dd8d2afd62aa86',
+  '60519091c785977299725e4f2f3207b83828bfc56d94a989adf13bd0fc9bb174',
+  '6e201bb60337c9b0869c6c769272c82abc466330f82c662bb023a74ad0b8fa92',
+  '80e2560e01cfae87455177b54f77845b657764338d3bf3507119e3e1ff289bcd',
+  '7a126595a0b5de0b58eec9db38ee6d1654caf0b42df29d181692c382abe213c6',
+  '2e839be3ad9458feebcfd8ca979f9173b1f63b514939903ea8f9f03517528f88',
+  'f10407e809fc679d11e442d57c92a4b82d0647f06946bb42c7daccedf76873ec',
+  '99a42380f3835e1f706b986b86e58e33f12d68de4a69d94eb50845e790e05f71',
+]);
+
+export const REFERENCE = `${MARKER}
 > [!IMPORTANT]
-> This repo uses **ChangeLedger**. Read and follow \`.changeledger/AGENTS.md\` (the change
-> contract). If it is missing, run \`changeledger register\`.
+> This repo uses **ChangeLedger**. Before creating or modifying files, run
+> \`changeledger context\` (or \`changeledger context <change-id>\`) and follow its output.
+> If the command is unavailable, stop and restore/install ChangeLedger; do not proceed from memory.
 `;
 
 export const contractLink = (changeledgerDir) => path.join(changeledgerDir, 'AGENTS.md');
 export const rootContract = (repoRoot) => path.join(repoRoot, 'AGENTS.md');
 
-// A real, non-symlink file we may safely append to.
 function isPlainFile(file) {
   try {
     return fs.lstatSync(file).isFile();
@@ -32,69 +52,85 @@ function isPlainFile(file) {
   }
 }
 
-// Create (or refresh) the `.changeledger/AGENTS.md` symlink to the installed contract.
-// Idempotent and tolerant of a pre-existing/dangling link.
-export function linkContract(changeledgerDir) {
-  const link = contractLink(changeledgerDir);
-  try {
-    fs.lstatSync(link);
-    fs.unlinkSync(link);
-  } catch {
-    // no existing link — nothing to remove
-  }
-  try {
-    fs.symlinkSync(agentsTemplate, link);
-  } catch {
-    // Windows without Developer Mode/admin cannot create symlinks. Fall back to
-    // a copy so the contract is still present; `changeledger register` refreshes it if the
-    // installed contract changes.
-    writeFileAtomic(link, fs.readFileSync(agentsTemplate, 'utf8'));
-  }
-  return link;
+function replaceReference(text) {
+  const start = text.indexOf(MARKER);
+  if (start === -1) return `${text}${text.endsWith('\n') ? '' : '\n'}\n${REFERENCE}`;
+  const tail = text.slice(start).split('\n');
+  let consumed = 1;
+  while (consumed < tail.length && tail[consumed].startsWith('>')) consumed += 1;
+  const before = text.slice(0, start);
+  const after = tail.slice(consumed).join('\n').replace(/^\n+/, '');
+  return `${before}${REFERENCE}${after ? `\n${after}` : ''}`;
 }
 
-// Append the reference block to each present, non-symlink contract file unless
-// already there. Symlinks are skipped (appending would write into their target).
+// Add or replace the managed bootstrap block in project-owned agent files.
 export function ensureReference(repoRoot) {
   const touched = [];
   for (const name of CONTRACT_FILES) {
     const file = path.join(repoRoot, name);
     if (!isPlainFile(file)) continue;
     const text = fs.readFileSync(file, 'utf8');
-    if (text.includes(MARKER)) continue;
-    writeFileAtomic(file, `${text}${text.endsWith('\n') ? '' : '\n'}\n${REFERENCE}`);
+    const updated = replaceReference(text);
+    if (updated === text) continue;
+    writeFileAtomic(file, updated);
     touched.push(name);
   }
   return touched;
 }
 
-// Ensure `.changeledger/AGENTS.md` is gitignored (it is a per-machine artifact).
-export function ensureGitignore(repoRoot) {
+// Remove only artifacts known to be managed by legacy ChangeLedger versions.
+// Unknown regular files fail closed instead of being deleted.
+export function removeLegacyContract(changeledgerDir, knownHashes = LEGACY_CONTRACT_HASHES) {
+  const file = contractLink(changeledgerDir);
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    fs.unlinkSync(file);
+    return true;
+  }
+  if (stat.isFile()) {
+    const digest = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    if (knownHashes.has(digest)) {
+      fs.unlinkSync(file);
+      return true;
+    }
+  }
+  throw new Error(
+    '`.changeledger/AGENTS.md` is not a recognized legacy ChangeLedger contract; move or remove it manually, then run `changeledger register` again',
+  );
+}
+
+export function removeLegacyGitignore(repoRoot) {
   const file = path.join(repoRoot, '.gitignore');
-  const entry = '.changeledger/AGENTS.md';
-  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
-  if (text.split('\n').some((l) => l.trim() === entry)) return false;
-  writeFileAtomic(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${entry}\n`);
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, 'utf8');
+  const lines = text.split('\n');
+  const kept = lines.filter((line) => line !== LEGACY_ENTRY);
+  if (kept.length === lines.length) return false;
+  writeFileAtomic(file, kept.join('\n'));
   return true;
 }
 
-// IO-level discovery validation (repo-wide). Returns a list of error messages.
-export function checkContract(repoRoot, changeledgerDir) {
+export function checkContract(repoRoot) {
   const errors = [];
   const root = rootContract(repoRoot);
   if (!fs.existsSync(root)) {
     errors.push('missing AGENTS.md at the repo root (ChangeLedger contract reference lives here)');
   }
-  // Every present, non-symlink contract file must carry the reference.
   for (const name of CONTRACT_FILES) {
     const file = path.join(repoRoot, name);
     if (!isPlainFile(file)) continue;
-    if (!fs.readFileSync(file, 'utf8').includes(MARKER)) {
+    const text = fs.readFileSync(file, 'utf8');
+    if (!text.includes(MARKER)) {
       errors.push(`${name} has no ChangeLedger reference — run \`changeledger register\``);
+    } else if (!text.includes(REFERENCE.trim())) {
+      errors.push(`${name} has an outdated ChangeLedger reference — run \`changeledger register\``);
     }
   }
-  if (!fs.existsSync(contractLink(changeledgerDir))) {
-    errors.push('`.changeledger/AGENTS.md` is missing or dangling — run `changeledger register`');
-  }
   return errors;
 }

package/src/paths.mjs

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 
 export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const templatesDir = path.join(packageRoot, 'templates');
-export const agentsTemplate = path.join(templatesDir, 'AGENTS.md');
+export const contractTemplatesDir = path.join(templatesDir, 'contract');
 export const publicDir = path.join(packageRoot, 'src', 'viewer', 'public');
 
 // ISO 8601 UTC at second precision, matching the change `created`/task convention.

package/src/viewer/domain.mjs

@@ -1,10 +1,16 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { parseDocument } from 'yaml';
 import { mutateFileAtomic } from '../atomic-write.mjs';
 import { checkRepo } from '../check.mjs';
 import { status as applyStatusCmd, validation as applyValidation } from '../commands/agent.mjs';
 import { findChangeledgerDir, loadConfig, resolveRepoPath, resolveSpecsDir } from '../config.mjs';
+import {
+  buildMigration,
+  getSchemaVersion,
+  SUPPORTED_SCHEMA_VERSION,
+} from '../config-migration.mjs';
 import { computeMetrics } from '../metrics.mjs';
 import { nowUtc } from '../paths.mjs';
 import { listProjects, remove, update } from '../registry.mjs';
@@ -209,12 +215,21 @@ export function saveProjectConfig(projects, payload, { mutateConfig = mutateFile
       if (revision(before) !== payload.revision) {
         throw new Error('configuration changed on disk; reload before saving');
       }
+      const currentSchema = getSchemaVersion(parseYaml(before));
+      if (currentSchema > SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(
+          `config schema ${currentSchema} is newer than supported schema ${SUPPORTED_SCHEMA_VERSION}`,
+        );
+      }
       return payload.content;
     });
   } catch (error) {
     if (error.message === 'configuration changed on disk; reload before saving') {
       return { code: 409, body: { error: error.message } };
     }
+    if (/^config schema \d+ is newer than supported schema \d+$/.test(error.message)) {
+      return { code: 400, body: { error: error.message } };
+    }
     return { code: 400, body: { error: 'unable to save project configuration' } };
   }
   return {
@@ -264,3 +279,268 @@ export function unregisterProject(projects, payload, { localOnly = false } = {})
   }
   return { code: 200, body: { ok: true } };
 }
+
+// Returns config content + schema metadata without mutating anything.
+export function readProjectConfigStructured(projects, id) {
+  const found = projectFor(projects, id);
+  if (!found.project) return found;
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+  const content = fs.readFileSync(file, 'utf8');
+  const config = parseYaml(content);
+  const schemaVersion = getSchemaVersion(config);
+  return {
+    code: 200,
+    body: {
+      content,
+      revision: revision(content),
+      schemaVersion,
+      supported: SUPPORTED_SCHEMA_VERSION,
+      config,
+    },
+  };
+}
+
+// Applies a semantic patch (allowlisted fields only) to the YAML AST, preserving
+// comments, unknown keys and fields the form does not represent.
+export function patchProjectConfig(projects, payload, { mutateConfig = mutateFileAtomic } = {}) {
+  const found = projectFor(projects, payload.project);
+  if (!found.project) return found;
+  if (!payload.patch || typeof payload.patch !== 'object' || Array.isArray(payload.patch)) {
+    return { code: 400, body: { error: 'patch must be an object' } };
+  }
+  if (typeof payload.revision !== 'string') {
+    return { code: 400, body: { error: 'revision is required' } };
+  }
+  // Explicitly reject attempts to change identity fields via patch.
+  if ('project_id' in payload.patch) {
+    return { code: 400, body: { error: 'project_id cannot be changed from the viewer' } };
+  }
+  if ('schema_version' in payload.patch) {
+    return { code: 400, body: { error: 'schema_version cannot be changed via patch' } };
+  }
+
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+
+  let result;
+  try {
+    mutateConfig(file, (before) => {
+      if (revision(before) !== payload.revision) {
+        throw new Error('configuration changed on disk; reload before saving');
+      }
+
+      const doc = parseDocument(before, { merge: false });
+      const config = doc.toJS() ?? {};
+
+      // Fail closed for future schema
+      const schemaVersion = getSchemaVersion(config);
+      if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(
+          `config schema ${schemaVersion} is newer than supported schema ${SUPPORTED_SCHEMA_VERSION}`,
+        );
+      }
+
+      applyPatch(doc, payload.patch, config);
+
+      const patched = doc.toString();
+      const candidate = parseYaml(patched);
+
+      // Identity guard
+      if (String(candidate.project_id ?? '') !== String(found.project.id)) {
+        throw new Error('project_id cannot be changed from the viewer');
+      }
+
+      // Structural validation
+      const repo = loadRepo(found.project.path);
+      resolveRepoPath(repo.repoRoot, candidate.changes_dir, 'changes_dir');
+      resolveSpecsDir(repo.repoRoot, candidate);
+      const candidateRepo = loadRepoWithConfig(repo.repoRoot, repo.changeledgerDir, candidate);
+      const { errors } = checkRepo(candidateRepo);
+      if (errors.length) throw new Error(errors[0].message);
+
+      result = { content: patched, rev: revision(patched) };
+      return patched;
+    });
+  } catch (error) {
+    if (error.message === 'configuration changed on disk; reload before saving') {
+      return { code: 409, body: { error: error.message } };
+    }
+    return { code: 400, body: { error: error.message } };
+  }
+
+  return { code: 200, body: { ok: true, revision: result.rev } };
+}
+
+// Preview the migration without writing. Returns summary + candidate YAML.
+export function previewConfigMigration(projects, id, rev) {
+  const found = projectFor(projects, id);
+  if (!found.project) return found;
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+  const content = fs.readFileSync(file, 'utf8');
+  if (rev && revision(content) !== rev) {
+    return { code: 409, body: { error: 'configuration changed on disk; reload before saving' } };
+  }
+  let migrationResult;
+  try {
+    migrationResult = buildMigration(content);
+  } catch (e) {
+    return { code: 400, body: { error: e.message } };
+  }
+  if (!migrationResult) {
+    return {
+      code: 200,
+      body: {
+        already_current: true,
+        message: `Config is already at schema ${SUPPORTED_SCHEMA_VERSION}`,
+      },
+    };
+  }
+  return {
+    code: 200,
+    body: {
+      summary: `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION} (dry run)`,
+      changes: migrationResult.changes,
+      yaml: migrationResult.yaml,
+    },
+  };
+}
+
+// Apply the migration atomically. Uses the same engine as `changeledger config migrate`.
+// Revision check and write are inside mutateFileAtomic to avoid TOCTOU races.
+export function applyConfigMigration(projects, payload, { mutateConfig = mutateFileAtomic } = {}) {
+  const found = projectFor(projects, payload.project);
+  if (!found.project) return found;
+  if (typeof payload.revision !== 'string') {
+    return { code: 400, body: { error: 'revision is required' } };
+  }
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+
+  let result;
+  try {
+    mutateConfig(file, (before) => {
+      if (revision(before) !== payload.revision) {
+        throw new Error('configuration changed on disk; reload before saving');
+      }
+      let migrationResult;
+      try {
+        migrationResult = buildMigration(before);
+      } catch (e) {
+        throw new Error(e.message);
+      }
+      if (!migrationResult) {
+        result = { already_current: true, rev: payload.revision };
+        return undefined; // no write needed
+      }
+      result = { ok: true, rev: revision(migrationResult.yaml) };
+      return migrationResult.yaml;
+    });
+  } catch (error) {
+    if (error.message === 'configuration changed on disk; reload before saving') {
+      return { code: 409, body: { error: error.message } };
+    }
+    return { code: 400, body: { error: error.message } };
+  }
+
+  if (result.already_current) {
+    return { code: 200, body: { already_current: true, revision: result.rev } };
+  }
+  return { code: 200, body: { ok: true, revision: result.rev } };
+}
+
+// Allowlisted fields the form patch may update.
+const PATCH_ALLOWED = new Set([
+  'project_name',
+  'language',
+  'tdd',
+  'changes_dir',
+  'specs_dir',
+  'statuses',
+  'stages',
+  'readiness',
+  'types',
+  'release',
+]);
+
+const CANONICAL_STATUSES_REQUIRED = new Set([
+  'draft',
+  'approved',
+  'in-progress',
+  'in-review',
+  'in-validation',
+  'blocked',
+  'done',
+  'discarded',
+]);
+
+const CANONICAL_STAGES_REQUIRED = new Set([
+  'request',
+  'investigation',
+  'proposal',
+  'specification',
+  'plan',
+  'log',
+]);
+
+function applyPatch(doc, patch, currentConfig) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (!PATCH_ALLOWED.has(key)) continue;
+
+    if (key === 'types') {
+      applyTypesPatch(doc, value, currentConfig.types ?? {});
+    } else if (key === 'release') {
+      applyReleasePatch(doc, value);
+    } else if (key === 'readiness') {
+      applyReadinessPatch(doc, value);
+    } else if (key === 'statuses') {
+      applyRequiredListPatch(doc, 'statuses', value, CANONICAL_STATUSES_REQUIRED);
+    } else if (key === 'stages') {
+      applyRequiredListPatch(doc, 'stages', value, CANONICAL_STAGES_REQUIRED);
+    } else {
+      doc.set(key, value);
+    }
+  }
+}
+
+function applyRequiredListPatch(doc, key, proposed, required) {
+  if (!Array.isArray(proposed) || proposed.some((value) => typeof value !== 'string')) {
+    throw new Error(`${key} must be a list of strings`);
+  }
+  const duplicate = proposed.find((value, index) => proposed.indexOf(value) !== index);
+  if (duplicate) throw new Error(`${key} contains duplicate value "${duplicate}"`);
+  const missing = [...required].find((value) => !proposed.includes(value));
+  if (missing) throw new Error(`${key} cannot remove required value "${missing}"`);
+  doc.set(key, proposed);
+}
+
+function applyTypesPatch(doc, typesPatch, currentTypes) {
+  for (const [typeName, typeDef] of Object.entries(typesPatch)) {
+    if (!Object.hasOwn(currentTypes, typeName)) continue; // don't add new types
+    if (!typeDef || typeof typeDef !== 'object') continue;
+    if (Array.isArray(typeDef.stages)) {
+      doc.setIn(['types', typeName, 'stages'], typeDef.stages);
+    }
+    if (typeof typeDef.review_required === 'boolean') {
+      doc.setIn(['types', typeName, 'review_required'], typeDef.review_required);
+    } else if (typeDef.review_required === null) {
+      doc.deleteIn(['types', typeName, 'review_required']);
+    }
+  }
+}
+
+function applyReleasePatch(doc, releasePatch) {
+  if (releasePatch.impacts && typeof releasePatch.impacts === 'object') {
+    for (const [type, impact] of Object.entries(releasePatch.impacts)) {
+      if (impact === null) doc.deleteIn(['release', 'impacts', type]);
+      else doc.setIn(['release', 'impacts', type], impact);
+    }
+  }
+}
+
+function applyReadinessPatch(doc, readinessPatch) {
+  if (!readinessPatch || typeof readinessPatch !== 'object') return;
+  if (Array.isArray(readinessPatch.target_patterns)) {
+    doc.setIn(['readiness', 'target_patterns'], readinessPatch.target_patterns);
+  }
+  if (Array.isArray(readinessPatch.verification_patterns)) {
+    doc.setIn(['readiness', 'verification_patterns'], readinessPatch.verification_patterns);
+  }
+}

package/src/viewer/public/api.js

@@ -41,9 +41,37 @@ const postProject = (route, body) =>
     body: JSON.stringify(body),
   });
 
+const jsonOrThrow = async (response) => {
+  const body = await response.json();
+  if (!response.ok) throw new Error(body.error || `HTTP ${response.status}`);
+  return body;
+};
+
 export const postProjectConfig = (project, content, revision) =>
   postProject('/api/project-config', { project, content, revision });
 
+export const getProjectConfigStructured = (project) =>
+  fetch(`/api/project-config-structured?project=${encodeURIComponent(project)}`).then(async (r) => {
+    const body = await r.json();
+    if (!r.ok) throw new Error(body.error || `HTTP ${r.status}`);
+    return body;
+  });
+
+export const patchProjectConfigApi = (project, patch, revision) =>
+  postProject('/api/project-config-patch', { project, patch, revision });
+
+export const getConfigMigrationPreview = (project, revision) =>
+  fetch(
+    `/api/project-config-migrate-preview?project=${encodeURIComponent(project)}&revision=${encodeURIComponent(revision ?? '')}`,
+  ).then(async (r) => {
+    const body = await r.json();
+    if (!r.ok) throw new Error(body.error || `HTTP ${r.status}`);
+    return body;
+  });
+
+export const postConfigMigrationApply = (project, revision) =>
+  postProject('/api/project-config-migrate-apply', { project, revision }).then(jsonOrThrow);
+
 export const postProjectPath = (project, path) =>
   postProject('/api/project-path', { project, path });