changeledger 0.5.0 → 0.6.1

package/AGENTS.md

@@ -6,8 +6,10 @@ under `.changeledger/changes/`, persistent truth under `.changeledger/specs/`.
 <!-- changeledger -->
 > [!IMPORTANT]
 > 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.
+> `changeledger context`, read its complete output, and follow it.
+> If the output is truncated/incomplete, stop and restore complete context before
+> proceeding. If the command is unavailable, stop and restore/install
+> ChangeLedger; do not proceed from memory.
 
 The canonical ChangeLedger contract is split into task-focused fragments under
 [`templates/contract/`](templates/contract/). The deterministic

package/README.md

@@ -139,8 +139,21 @@ changeledger context review             # explicit task mode
 
 `init` places a small fail-closed bootstrap in the project-owned `AGENTS.md`;
 there is no linked or copied contract under `.changeledger/`. Run
-`changeledger register` after upgrading to refresh that bootstrap and migrate
-legacy repositories.
+`changeledger register` after upgrading to refresh that bootstrap.
+
+### Upgrading an existing repo's configuration
+
+Repos created before ChangeLedger 0.6 may have an older configuration schema.
+Run this to inspect and apply available migrations:
+
+```sh
+changeledger config migrate --dry-run   # preview changes without writing
+changeledger config migrate             # apply atomically
+changeledger check                      # confirm the repo is valid
+```
+
+Migrations are safe to run more than once — if the config is already current,
+the command reports so and exits without modifying any file.
 
 ## Compatibility and security
 

package/bin/changeledger.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import {
   archive,
@@ -20,8 +21,12 @@ import { newChange } from '../src/commands/new.mjs';
 import { registerRepo } from '../src/commands/register.mjs';
 import { initReleaseHistory, recordRelease, releasePlan } from '../src/commands/release.mjs';
 import { view } from '../src/commands/view.mjs';
+import { findChangeledgerDir } from '../src/config.mjs';
+import { applyMigration, SUPPORTED_SCHEMA_VERSION } from '../src/config-migration.mjs';
 import { nowUtc } from '../src/paths.mjs';
 
+const { version } = createRequire(import.meta.url)('../package.json');
+
 const USAGE = `ChangeLedger (changeledger)
 
   changeledger init                          set up .changeledger/ in the current repo (+ register it)
@@ -45,6 +50,7 @@ const USAGE = `ChangeLedger (changeledger)
   changeledger graduate <change-id> <spec-slug> --into   graduate into an existing spec
   changeledger graduate <change-id> --skip [reason]   mark graduation reviewed, no spec
   changeledger graduate --pending                 list done changes not yet reviewed
+  changeledger config migrate [--dry-run]          migrate .changeledger/config.yml to schema ${SUPPORTED_SCHEMA_VERSION}
   changeledger release init <version>             initialize release history at X.Y.Z
   changeledger release plan [--json]              calculate the next portable SemVer release
   changeledger release record <version>           record the calculated release manifest`;
@@ -65,6 +71,7 @@ function action(fn) {
 program
   .name('changeledger')
   .description('ChangeLedger (changeledger)')
+  .version(version, '-v, --version', 'output the installed version (-V also accepted)')
   .helpOption('-h, --help', 'display help for command')
   .addHelpText('after', `\n${USAGE}`);
 
@@ -326,6 +333,24 @@ program
     }),
   );
 
+const configCommand = program
+  .command('config')
+  .description('inspect and manage the repo configuration');
+
+configCommand
+  .command('migrate')
+  .description('migrate .changeledger/config.yml to the current schema')
+  .option('--dry-run', 'show the migration plan and candidate YAML without writing')
+  .action(
+    action((options) => {
+      const changeledgerDir = findChangeledgerDir();
+      if (!changeledgerDir) throw new Error('Not a ChangeLedger repo.');
+      const configFile = `${changeledgerDir}/config.yml`;
+      const result = applyMigration(configFile, { dryRun: options.dryRun ?? false });
+      console.log(result);
+    }),
+  );
+
 const releaseCommand = program
   .command('release')
   .description('plan and record portable SemVer releases');
@@ -376,8 +401,10 @@ releaseCommand
     }),
   );
 
-if (process.argv.length <= 2) {
+// Normalize -V to --version so both short aliases work identically.
+const argv = process.argv.map((a) => (a === '-V' ? '--version' : a));
+if (argv.length <= 2) {
   console.log(USAGE);
 } else {
-  program.parse();
+  program.parse(argv);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changeledger",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Turn conversations into buildable changes.",
   "type": "module",
   "bin": {

package/src/commands/check.mjs

@@ -1,4 +1,5 @@
 import { checkRepo } from '../check.mjs';
+import { getSchemaVersion, SUPPORTED_SCHEMA_VERSION } from '../config-migration.mjs';
 import { checkContract } from '../contract.mjs';
 import { loadRepo } from '../repo.mjs';
 
@@ -22,6 +23,15 @@ export function check(args = [], cwd = process.cwd(), output = console) {
 
   const { errors, warnings } = checkRepo(repo, { id });
 
+  // Schema version detection — warn without mutating.
+  const schemaVersion = getSchemaVersion(repo.config);
+  if (!id && schemaVersion < SUPPORTED_SCHEMA_VERSION) {
+    warnings.push({
+      file: '.changeledger/config.yml',
+      message: `config schema ${schemaVersion} is outdated; run \`changeledger config migrate --dry-run\``,
+    });
+  }
+
   // Discovery validation needs the filesystem (root contract bootstrap), so it
   // lives here, not in the pure validator. Repo-wide only.
   if (!id) {

package/src/commands/register.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { findChangeledgerDir, loadConfig } from '../config.mjs';
+import { getSchemaVersion, SUPPORTED_SCHEMA_VERSION } from '../config-migration.mjs';
 import {
   ensureReference,
   removeLegacyContract,
@@ -11,7 +12,7 @@ import { register } from '../registry.mjs';
 
 // Refreshes the repo bootstrap and registry path. Also migrates the per-machine
 // contract artifact left by legacy versions.
-export function registerRepo(cwd = process.cwd()) {
+export function registerRepo(cwd = process.cwd(), output = console) {
   const changeledgerDir = findChangeledgerDir(cwd);
   if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
 
@@ -20,6 +21,13 @@ export function registerRepo(cwd = process.cwd()) {
     throw new Error('config.yml has no project_id. Run `changeledger init` to create one.');
   }
 
+  const schemaVersion = getSchemaVersion(config);
+  if (schemaVersion < SUPPORTED_SCHEMA_VERSION) {
+    output.warn(
+      `warn  .changeledger/config.yml: config schema ${schemaVersion} is outdated; run \`changeledger config migrate --dry-run\``,
+    );
+  }
+
   const repoRoot = path.dirname(changeledgerDir);
   const name = config.project_name || path.basename(repoRoot);
 

package/src/commands/view.mjs

@@ -6,8 +6,12 @@ import { createRequestListener, staticFile } from '../viewer/server/router.mjs';
 import { hostnameOf, isAuthorizedWrite, isLocalHost } from '../viewer/server/security.mjs';
 
 export {
+  applyConfigMigration,
   changeStatus,
+  patchProjectConfig,
+  previewConfigMigration,
   readProjectConfig,
+  readProjectConfigStructured,
   repairProjectPath,
   resolveProjects,
   saveProjectConfig,

package/src/config-migration.mjs

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+import { writeFileAtomic } from './atomic-write.mjs';
+import { templatesDir } from './paths.mjs';
+
+export const SUPPORTED_SCHEMA_VERSION = 1;
+
+const CANONICAL_STATUSES = [
+  'draft',
+  'approved',
+  'in-progress',
+  'in-review',
+  'in-validation',
+  'blocked',
+  'done',
+  'discarded',
+];
+
+const BUILTIN_TYPES = ['feature', 'bug', 'refactor'];
+
+const BUILTIN_IMPACTS = {
+  feature: 'minor',
+  bug: 'patch',
+  audit: 'none',
+  refactor: 'none',
+  chore: 'none',
+};
+
+export function getSchemaVersion(config) {
+  const v = config.schema_version;
+  return typeof v === 'number' ? v : 0;
+}
+
+// Returns null when no migration needed; throws on invalid/future schema.
+// Otherwise returns { yaml: string, changes: string[] }.
+export function buildMigration(originalText) {
+  let doc;
+  try {
+    doc = parseDocument(originalText, { merge: false });
+  } catch (e) {
+    throw new Error(`Invalid YAML: ${e.message}`);
+  }
+  if (doc.errors.length) {
+    throw new Error(`Invalid YAML: ${doc.errors[0].message}`);
+  }
+
+  const config = doc.toJS() ?? {};
+  const current = getSchemaVersion(config);
+
+  if (current > SUPPORTED_SCHEMA_VERSION) {
+    throw new Error(
+      `config schema ${current} is newer than supported schema ${SUPPORTED_SCHEMA_VERSION}`,
+    );
+  }
+  if (current === SUPPORTED_SCHEMA_VERSION) {
+    return null;
+  }
+
+  const changes = [];
+
+  // schema_version: 1 — remove any existing value, then prepend to appear first
+  if (Object.hasOwn(config, 'schema_version')) {
+    doc.delete('schema_version');
+  }
+  doc.contents.items.unshift(doc.createPair('schema_version', 1));
+  changes.push('added schema_version: 1');
+
+  // tdd: true if absent
+  if (!Object.hasOwn(config, 'tdd')) {
+    doc.set('tdd', true);
+    changes.push('added tdd: true');
+  }
+
+  // specs_dir if absent
+  if (!Object.hasOwn(config, 'specs_dir')) {
+    doc.set('specs_dir', '.changeledger/specs');
+    changes.push('added specs_dir: .changeledger/specs');
+  }
+
+  // Canonical statuses — insert missing ones in canonical order
+  const statusesNode = doc.get('statuses', true);
+  if (statusesNode) {
+    const current_statuses = statusesNode.items.map((n) => String(n.value));
+    for (const status of CANONICAL_STATUSES) {
+      if (current_statuses.includes(status)) continue;
+      const insertBefore = findInsertBefore(current_statuses, CANONICAL_STATUSES, status);
+      const newNode = doc.createNode(status);
+      if (insertBefore === -1) {
+        statusesNode.items.push(newNode);
+        current_statuses.push(status);
+      } else {
+        statusesNode.items.splice(insertBefore, 0, newNode);
+        current_statuses.splice(insertBefore, 0, status);
+      }
+      changes.push(`added status: ${status}`);
+    }
+  }
+
+  // review_required: true for built-in types where key is absent
+  const configTypes = config.types ?? {};
+  for (const typeName of BUILTIN_TYPES) {
+    if (!Object.hasOwn(configTypes, typeName)) continue;
+    if (Object.hasOwn(configTypes[typeName], 'review_required')) continue;
+    doc.setIn(['types', typeName, 'review_required'], true);
+    changes.push(`added types.${typeName}.review_required: true`);
+  }
+
+  // release.impacts defaults for built-in types that exist in config.types
+  const currentImpacts = config.release?.impacts ?? {};
+  for (const [type, impact] of Object.entries(BUILTIN_IMPACTS)) {
+    if (!Object.hasOwn(configTypes, type)) continue;
+    if (Object.hasOwn(currentImpacts, type)) continue;
+    doc.setIn(['release', 'impacts', type], impact);
+    changes.push(`added release.impacts.${type}: ${impact}`);
+  }
+
+  // Remove legacy id_digits
+  if (Object.hasOwn(config, 'id_digits')) {
+    doc.delete('id_digits');
+    changes.push('removed legacy id_digits');
+  }
+
+  // Refresh managed comments from the current template, preserving custom comments.
+  const templateComments = loadTemplateComments();
+  const commentChanges = refreshManagedComments(doc, templateComments);
+  changes.push(...commentChanges);
+
+  return { yaml: doc.toString(), changes };
+}
+
+// Apply migration to a file (or dry-run). Returns summary string.
+export function applyMigration(configFile, { dryRun = false } = {}) {
+  let original;
+  try {
+    original = fs.readFileSync(configFile, 'utf8');
+  } catch (e) {
+    throw new Error(`Cannot read config: ${e.message}`);
+  }
+
+  const result = buildMigration(original);
+
+  if (!result) {
+    return `Config is already at schema ${SUPPORTED_SCHEMA_VERSION}. No changes needed.`;
+  }
+
+  const header = dryRun
+    ? `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION} (dry run)`
+    : `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION}`;
+
+  const summary = [header, ...result.changes.map((c) => `  - ${c}`)].join('\n');
+
+  if (!dryRun) {
+    writeFileAtomic(configFile, result.yaml);
+    return summary;
+  }
+
+  return `${summary}\n\n--- candidate YAML ---\n${result.yaml}`;
+}
+
+// Find the index in currentList where `status` should be inserted, based on
+// canonical order. Returns -1 to append at end.
+function findInsertBefore(currentList, canonicalOrder, status) {
+  const canonIdx = canonicalOrder.indexOf(status);
+  for (let i = canonIdx + 1; i < canonicalOrder.length; i++) {
+    const pos = currentList.indexOf(canonicalOrder[i]);
+    if (pos !== -1) return pos;
+  }
+  return -1;
+}
+
+// Reads the current template and returns a map of top-level key → commentBefore string.
+// Returns an empty map if the template is unreadable (comment refresh is optional).
+function loadTemplateComments() {
+  try {
+    const templateText = fs.readFileSync(path.join(templatesDir, 'config.yml'), 'utf8');
+    const templateDoc = parseDocument(templateText, { merge: false });
+    const comments = new Map();
+    for (const pair of templateDoc.contents.items) {
+      const key = pair.key?.value;
+      const comment = pair.key?.commentBefore;
+      if (key && comment !== undefined) {
+        comments.set(key, comment);
+      }
+    }
+    return comments;
+  } catch {
+    return new Map();
+  }
+}
+
+// Replace managed comments (those defined in the template) on existing keys,
+// preserving comments on custom/unknown keys.
+// doc.set() creates keys as plain strings (not Scalar nodes), so commentBefore
+// cannot be set on them directly. Convert string keys to Scalar nodes first.
+function refreshManagedComments(doc, templateComments) {
+  const changes = [];
+  for (const pair of doc.contents.items) {
+    // Normalise string-primitive keys to Scalar nodes so commentBefore is writable.
+    if (typeof pair.key === 'string') {
+      pair.key = doc.createNode(pair.key);
+    }
+    const key = pair.key?.value;
+    if (!key) continue;
+    if (!templateComments.has(key)) continue; // custom key — preserve its comment
+    const templateComment = templateComments.get(key);
+    const currentComment = pair.key?.commentBefore;
+    if (currentComment === templateComment) continue; // already matches
+    pair.key.commentBefore = templateComment;
+    changes.push(`refreshed comment for ${key}`);
+  }
+  return changes;
+}

package/src/contract.mjs

@@ -37,8 +37,10 @@ const LEGACY_CONTRACT_HASHES = new Set([
 export const REFERENCE = `${MARKER}
 > [!IMPORTANT]
 > 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.
+> \`changeledger context\`, read its complete output, and follow it.
+> If the output is truncated/incomplete, stop and restore complete context before
+> proceeding. If the command is unavailable, stop and restore/install
+> ChangeLedger; do not proceed from memory.
 `;
 
 export const contractLink = (changeledgerDir) => path.join(changeledgerDir, 'AGENTS.md');