changeledger 0.3.0

package/src/commands/agent.mjs

@@ -0,0 +1,256 @@
+// Agent-facing commands: safe mutations (status/log/task) and queries
+// (list/show). Files remain the source of truth; these are optional helpers
+// that inject correct timestamps/markers and validate transitions.
+
+import path from 'node:path';
+import { mutateFileAtomic } from '../atomic-write.mjs';
+import { parseChange } from '../change.mjs';
+import { ownerHandle as defaultOwnerHandle } from '../git.mjs';
+import { assertTransition } from '../lifecycle.mjs';
+import { nowUtc } from '../paths.mjs';
+import { loadRepo, resolveChange } from '../repo.mjs';
+import { appendLog, setArchived, setOwner, setStatus, setTask } from '../writer.mjs';
+
+function locate(cwd, id) {
+  const { config, file } = resolveChange(cwd, id);
+  return { config, file };
+}
+
+export function status(
+  id,
+  newStatus,
+  cwd = process.cwd(),
+  { ownerHandle = defaultOwnerHandle } = {},
+) {
+  const { config, file } = locate(cwd, id);
+  if (newStatus === 'discarded') {
+    throw new Error(
+      'to discard a change use `changeledger discard <id> "<reason>"` (a reason is required)',
+    );
+  }
+  if (newStatus === 'done') {
+    throw new Error('to complete a change use human validation in the viewer');
+  }
+  if (!(config.statuses ?? []).includes(newStatus)) {
+    throw new Error(`Invalid status "${newStatus}". Valid: ${(config.statuses ?? []).join(', ')}`);
+  }
+  const autoOwner = newStatus === 'in-progress' ? ownerHandle(path.dirname(file)) : '';
+  mutateFileAtomic(file, (text) => {
+    const fm = parseChange(text).frontmatter;
+    // Validate the move before any in-memory mutation, so an illegal transition
+    // leaves the file byte-for-byte unchanged. The review gate reads review_required
+    // from the change's type.
+    assertTransition(fm.status, newStatus, {
+      type: fm.type,
+      reviewRequired: Boolean(config.types?.[fm.type]?.review_required),
+    });
+    text = setStatus(text, newStatus);
+    text = appendLog(text, nowUtc(), `status: ${fm.status} → ${newStatus}`);
+
+    // Work begins here: assign the owner from the local git identity unless one was
+    // set explicitly (see change 20260614-124047).
+    if (newStatus === 'in-progress' && !fm.owner && autoOwner) {
+      text = setOwner(text, autoOwner);
+      text = appendLog(text, nowUtc(), `owner → ${autoOwner} (auto)`);
+    }
+    return text;
+  });
+  return file;
+}
+
+// Records the verdict of the independent review (run by a delegated subagent
+// with clean context — see AGENTS.md §6). `pass` advances to human validation;
+// `fail` routes it back: `retry` for a defect inside the contract (the
+// implementer fixes), `block` for one that escalates to a human. Requires the
+// change to be in-review.
+export function review(id, verdict, { mode, reason } = {}, cwd = process.cwd()) {
+  const { file } = locate(cwd, id);
+  mutateFileAtomic(file, (text) => {
+    const { status: current } = parseChange(text).frontmatter;
+    if (current !== 'in-review') {
+      throw new Error(`review requires status in-review (current: ${current})`);
+    }
+
+    if (verdict === 'pass') {
+      text = setStatus(text, 'in-validation');
+      text = appendLog(
+        text,
+        nowUtc(),
+        'review → in-validation (delegated subagent, clean context)',
+      );
+    } else if (verdict === 'fail') {
+      if (!reason) {
+        throw new Error(
+          'fail requires a reason — changeledger review <id> fail --retry|--block "<reason>"',
+        );
+      }
+      if (mode === 'retry') {
+        text = setStatus(text, 'in-progress');
+        text = appendLog(text, nowUtc(), `review → in-progress (retry): ${reason}`);
+      } else if (mode === 'block') {
+        text = setStatus(text, 'blocked');
+        text = appendLog(text, nowUtc(), `review → blocked: ${reason}`);
+      } else {
+        throw new Error('fail requires --retry or --block');
+      }
+    } else {
+      throw new Error(`Unknown review verdict "${verdict}" (use pass|fail)`);
+    }
+
+    return text;
+  });
+  return file;
+}
+
+// Records the human verdict for the complete change. This is intentionally
+// separate from `status`: only the human-facing viewer may close a change.
+export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
+  const { config, file } = locate(cwd, id);
+  mutateFileAtomic(file, (text) => {
+    const fm = parseChange(text).frontmatter;
+    const current = fm.status;
+    let target;
+    if (verdict === 'pass') {
+      target = 'done';
+    } else if (verdict === 'fail') {
+      if (!reason) throw new Error('validation fail requires a reason');
+      target = 'in-progress';
+    } else {
+      throw new Error(`Unknown validation verdict "${verdict}" (use pass|fail)`);
+    }
+    if (current !== 'in-validation') {
+      throw new Error(`validation requires status in-validation (current: ${current})`);
+    }
+    assertTransition(current, target, {
+      type: fm.type,
+      reviewRequired: Boolean(config.types?.[fm.type]?.review_required),
+    });
+    text = setStatus(text, target);
+    return appendLog(
+      text,
+      nowUtc(),
+      verdict === 'pass'
+        ? 'validation → done (human accepted)'
+        : `validation → in-progress (human rejected): ${reason}`,
+    );
+  });
+  return file;
+}
+
+// name '-' clears the owner.
+export function owner(id, name, cwd = process.cwd()) {
+  const { file } = locate(cwd, id);
+  const next = name === '-' ? null : name;
+  mutateFileAtomic(file, (text) => {
+    text = setOwner(text, next);
+    return appendLog(text, nowUtc(), next ? `owner → ${next}` : 'owner cleared');
+  });
+  return file;
+}
+
+// Discards a change: a terminal lifecycle move that keeps the file and its
+// reasoning instead of deleting it. The reason is mandatory and recorded in the
+// Log; the transition graph rejects discarding a done or in-review change.
+export function discard(id, reason, cwd = process.cwd()) {
+  if (!reason) {
+    throw new Error('discard requires a reason — changeledger discard <id> "<reason>"');
+  }
+  const { config, file } = locate(cwd, id);
+  mutateFileAtomic(file, (text) => {
+    const fm = parseChange(text).frontmatter;
+    // Validate before any mutation so an illegal discard leaves the file untouched.
+    assertTransition(fm.status, 'discarded', {
+      type: fm.type,
+      reviewRequired: Boolean(config.types?.[fm.type]?.review_required),
+    });
+    text = setStatus(text, 'discarded');
+    return appendLog(text, nowUtc(), `status: ${fm.status} → discarded: ${reason}`);
+  });
+  return file;
+}
+
+export function archive(id, on, cwd = process.cwd()) {
+  const { file } = locate(cwd, id);
+  mutateFileAtomic(file, (text) => {
+    text = setArchived(text, on);
+    return appendLog(text, nowUtc(), on ? 'archived' : 'unarchived');
+  });
+  return file;
+}
+
+export function archiveGraduated({ dryRun = false } = {}, cwd = process.cwd()) {
+  const { changes } = loadRepo(cwd);
+  const selected = changes.filter((c) => isArchivableGraduated(c));
+  if (!dryRun) {
+    for (const c of selected) {
+      mutateFileAtomic(c.file, (text) => {
+        const current = { ...parseChange(text), text };
+        if (!isArchivableGraduated(current)) return undefined;
+        text = setArchived(text, true);
+        return appendLog(text, nowUtc(), 'archived');
+      });
+    }
+  }
+  return selected.map((c) => ({
+    id: c.frontmatter.id,
+    title: c.frontmatter.title,
+    file: c.file,
+  }));
+}
+
+function isArchivableGraduated(c) {
+  return (
+    c.frontmatter.status === 'done' &&
+    c.frontmatter.reviewed === true &&
+    c.frontmatter.archived !== true &&
+    hasGraduationResolution(c)
+  );
+}
+
+function hasGraduationResolution(c) {
+  const logBody = c.stages.find((s) => s.key === 'log')?.body ?? '';
+  return logBody
+    .split('\n')
+    .some((line) => /—\s*(graduado a spec `[^`]+`|graduation skipped\b)/i.test(line));
+}
+
+export function log(id, message, cwd = process.cwd()) {
+  const { file } = locate(cwd, id);
+  mutateFileAtomic(file, (text) => appendLog(text, nowUtc(), message));
+  return file;
+}
+
+export function task(id, action, n, reason, cwd = process.cwd()) {
+  const { file } = locate(cwd, id);
+  mutateFileAtomic(file, (text) => {
+    if (action === 'done') return setTask(text, n, 'done', { iso: nowUtc() });
+    if (action === 'block') return setTask(text, n, 'blocked', { reason });
+    throw new Error(`Unknown task action "${action}" (use done|block)`);
+  });
+  return file;
+}
+
+export function list({ status: byStatus, type: byType } = {}, cwd = process.cwd()) {
+  return loadRepo(cwd)
+    .changes.map((c) => ({
+      id: c.frontmatter.id,
+      title: c.frontmatter.title,
+      type: c.frontmatter.type,
+      status: c.frontmatter.status,
+      owner: c.frontmatter.owner ?? null,
+      progress: c.progress,
+    }))
+    .filter((c) => (!byStatus || c.status === byStatus) && (!byType || c.type === byType));
+}
+
+export function show(id, cwd = process.cwd()) {
+  const c = loadRepo(cwd).changes.find((x) => String(x.frontmatter.id) === String(id));
+  if (!c) throw new Error(`No change with id "${id}"`);
+  return {
+    id: c.frontmatter.id,
+    frontmatter: c.frontmatter,
+    stages: c.stages,
+    tasks: c.tasks,
+    progress: c.progress,
+  };
+}

package/src/commands/check.mjs

@@ -0,0 +1,48 @@
+import { checkRepo } from '../check.mjs';
+import { checkContract } from '../contract.mjs';
+import { loadRepo } from '../repo.mjs';
+
+// Validates the repo (or a single change with `changeledger check <id>`). Prints findings
+// and returns an exit code (1 if errors).
+export function check(args = [], cwd = process.cwd(), output = console) {
+  const json = args.includes('--json');
+  const id = args.find((a) => !a.startsWith('--'));
+
+  let repo;
+  try {
+    repo = loadRepo(cwd);
+  } catch (e) {
+    if (json)
+      output.log(
+        JSON.stringify({ errors: [{ file: '(repo)', message: e.message }], warnings: [] }, null, 2),
+      );
+    else output.error(`  error  (repo): ${e.message}`);
+    return 1;
+  }
+
+  const { errors, warnings } = checkRepo(repo, { id });
+
+  // Discovery validation needs the filesystem (root contract, symlink), so it
+  // lives here, not in the pure validator. Repo-wide only.
+  if (!id) {
+    for (const message of checkContract(repo.repoRoot, repo.changeledgerDir)) {
+      errors.push({ file: 'AGENTS.md', message });
+    }
+  }
+
+  if (json) {
+    output.log(JSON.stringify({ errors, warnings }, null, 2));
+    return errors.length ? 1 : 0;
+  }
+
+  for (const w of warnings) output.warn(`  warn   ${w.file}: ${w.message}`);
+  for (const e of errors) output.error(`  error  ${e.file}: ${e.message}`);
+
+  const scope = id ? `change ${id}` : `${repo.changes.length} change(s)`;
+  if (!errors.length && !warnings.length) {
+    output.log(`✓ ${scope} valid`);
+  } else {
+    output.log(`\n${errors.length} error(s), ${warnings.length} warning(s) — ${scope}`);
+  }
+  return errors.length ? 1 : 0;
+}

package/src/commands/graduate.mjs

@@ -0,0 +1,105 @@
+// Graduates a change to a spec: scaffolds the spec file (frontmatter + a body
+// seeded from the change's Specification/Proposal) and links it back in the
+// change's Log. The final wording stays a manual/agent task.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { mutateFileAtomic, writeFileAtomic } from '../atomic-write.mjs';
+import { parseChange } from '../change.mjs';
+import { findChangeledgerDir, loadConfig, resolveRepoPath, resolveSpecsDir } from '../config.mjs';
+import { nowUtc } from '../paths.mjs';
+import { resolveChange } from '../repo.mjs';
+import { slugify } from '../slug.mjs';
+import { appendLog, setReviewed, setSpecUpdated } from '../writer.mjs';
+import { serializeScalar } from '../yaml.mjs';
+
+// `into: true` graduates into an EXISTING spec — it refreshes the spec's
+// `updated` and links it back, but leaves the body to the agent (who knows what
+// to refine). Without `into`, a new spec is scaffolded and an existing one is an
+// error. Both routes share the same change-side record (marker + reviewed).
+export function graduate(id, slug, cwd = process.cwd(), { into = false } = {}) {
+  const { config, repoRoot, file: changeFile } = resolveChange(cwd, id);
+
+  const specsDir = resolveSpecsDir(repoRoot, config);
+  const specName = `${slugify(slug)}.md`;
+  const specFile = path.join(specsDir, specName);
+
+  // Validate preconditions before acquiring the change file lock — ensures no
+  // write happens at all when the existence check fails (CR1).
+  const exists = fs.existsSync(specFile);
+  if (into && !exists)
+    throw new Error(`Spec "${specName}" does not exist — drop --into to create it`);
+  if (!into && exists) throw new Error(`Spec "${specName}" already exists`);
+
+  mutateFileAtomic(changeFile, (changeText) => {
+    const change = parseChange(changeText);
+    if (change.frontmatter.status !== 'done') {
+      throw new Error('only done changes can be graduated/skipped');
+    }
+
+    if (into) {
+      // Refresh the spec's updated; the body stays the agent's to edit.
+      writeFileAtomic(specFile, setSpecUpdated(fs.readFileSync(specFile, 'utf8'), nowUtc()));
+    } else {
+      const seedStage =
+        change.stages.find((s) => s.key === 'specification') ??
+        change.stages.find((s) => s.key === 'proposal');
+      const seed = seedStage ? seedStage.body : '';
+      const title = change.frontmatter.title;
+
+      const content = `---
+title: ${serializeScalar(title)}
+updated: ${nowUtc()}
+tags: [${change.frontmatter.type}]
+---
+
+# ${title}
+
+> Graduado del change ${id}.
+
+${seed}
+`;
+      fs.mkdirSync(specsDir, { recursive: true });
+      writeFileAtomic(specFile, content);
+    }
+
+    let text = appendLog(changeText, nowUtc(), `graduado a spec \`${specName}\``);
+    text = setReviewed(text, true);
+    return text;
+  });
+  return specFile;
+}
+
+// Marks a done change's graduation as reviewed without creating a spec (e.g. a
+// bug/chore with no persistent truth). Records the reason in the Log.
+export function skipGraduation(id, reason, cwd = process.cwd()) {
+  const { file: changeFile } = resolveChange(cwd, id);
+  const message = reason ? `graduation skipped: ${reason}` : 'graduation skipped';
+  mutateFileAtomic(changeFile, (text) => {
+    const change = parseChange(text);
+    if (change.frontmatter.status !== 'done')
+      throw new Error('only done changes can be graduated/skipped');
+
+    text = appendLog(text, nowUtc(), message);
+    return setReviewed(text, true);
+  });
+  return changeFile;
+}
+
+// Lists done changes whose graduation has not been reviewed yet.
+export function pendingGraduation(cwd = process.cwd()) {
+  const changeledgerDir = findChangeledgerDir(cwd);
+  if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+  const config = loadConfig(changeledgerDir);
+  const repoRoot = path.dirname(changeledgerDir);
+  const changesDir = resolveRepoPath(repoRoot, config.changes_dir, 'changes_dir');
+  if (!fs.existsSync(changesDir)) return [];
+
+  return fs
+    .readdirSync(changesDir)
+    .filter((n) => n.endsWith('.md'))
+    .sort()
+    .map((n) => ({ name: n, ...parseChange(fs.readFileSync(path.join(changesDir, n), 'utf8')) }))
+    .filter((c) => c.frontmatter.status === 'done' && c.frontmatter.reviewed !== true)
+    .map((c) => ({ id: c.frontmatter.id, title: c.frontmatter.title, type: c.frontmatter.type }));
+}

package/src/commands/init.mjs

@@ -0,0 +1,43 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeFileAtomic } from '../atomic-write.mjs';
+import { ensureGitignore, ensureReference, linkContract, rootContract } from '../contract.mjs';
+import { templatesDir } from '../paths.mjs';
+import { register } from '../registry.mjs';
+import { serializeScalar } from '../yaml.mjs';
+
+// Sets up `.changeledger/` in the repo, gives it a stable identity, links the installed
+// AGENTS.md contract into `.changeledger/`, references it from the project's root
+// AGENTS.md, and registers the repo in the global registry.
+export function init(cwd = process.cwd()) {
+  const repoRoot = path.resolve(cwd);
+  const changeledgerDir = path.join(repoRoot, '.changeledger');
+  if (fs.existsSync(changeledgerDir)) {
+    throw new Error(
+      '.changeledger/ already exists. Use `changeledger register` to (re)link this repo.',
+    );
+  }
+  // The root AGENTS.md is the project's own contract; we reference the tool's
+  // contract from it but never create it ourselves. Fail before touching .changeledger/.
+  if (!fs.existsSync(rootContract(repoRoot))) {
+    throw new Error('Create AGENTS.md at the repo root first, then re-run `changeledger init`.');
+  }
+
+  fs.mkdirSync(path.join(changeledgerDir, 'changes'), { recursive: true });
+  const configFile = path.join(changeledgerDir, 'config.yml');
+
+  const id = crypto.randomBytes(5).toString('hex');
+  const name = path.basename(repoRoot);
+  writeFileAtomic(
+    configFile,
+    `${fs.readFileSync(path.join(templatesDir, 'config.yml'), 'utf8')}\n# Project identity (stable; the global registry maps it to a path)\nproject_id: "${id}"\nproject_name: ${serializeScalar(name)}\n`,
+  );
+
+  linkContract(changeledgerDir);
+  ensureReference(repoRoot);
+  ensureGitignore(repoRoot);
+
+  register({ id, name, path: repoRoot });
+  return changeledgerDir;
+}

package/src/commands/new.mjs

@@ -0,0 +1,164 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findChangeledgerDir, loadConfig, resolveRepoPath } from '../config.mjs';
+import { slugify } from '../slug.mjs';
+import { serializeScalar } from '../yaml.mjs';
+
+// Applied only when JSON parse fails — governs mtime-based staleness fallback.
+// Not the primary timeout: the main strategy is PID liveness (process.kill 0),
+// which is more robust for id-collision prevention than a wall-clock timeout.
+const LOCK_MTIME_STALE_MS = 30_000;
+
+// Scaffolds a new change file with the active stages for its type.
+// `slug` is the English filename slug (structure); `title` is the content title
+// (repo language). See AGENTS.md §7-§8.
+export function newChange({ type, slug, title, owner, now }, cwd = process.cwd()) {
+  const changeledgerDir = findChangeledgerDir(cwd);
+  if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+
+  const config = loadConfig(changeledgerDir);
+  const typeDef = config.types?.[type];
+  if (!typeDef) {
+    throw new Error(`Unknown type "${type}". Valid: ${Object.keys(config.types ?? {}).join(', ')}`);
+  }
+
+  const repoRoot = path.dirname(changeledgerDir);
+  const changesDir = resolveRepoPath(repoRoot, config.changes_dir, 'changes_dir');
+  fs.mkdirSync(changesDir, { recursive: true });
+  const normalizedSlug = slugify(slug);
+
+  // Guarantee a unique id even for changes created within the same second
+  // (an agent creating several in a loop). Bump by 1s until free; keep created
+  // coherent with the id. The final reservation is atomic (`wx`), so two
+  // separate `changeledger new` processes racing in the same second cannot both win the
+  // same id.
+  let created = now;
+  let id = idFromTimestamp(created);
+  for (;;) {
+    if (idTaken(changesDir, id)) {
+      created = bumpSecond(created);
+      id = idFromTimestamp(created);
+      continue;
+    }
+    const lock = acquireIdLock(changesDir, id);
+    if (!lock) {
+      created = bumpSecond(created);
+      id = idFromTimestamp(created);
+      continue;
+    }
+
+    // Re-check after acquiring the lock: another process may have written a
+    // file with this id between our idTaken() check and acquireIdLock().
+    if (idTaken(changesDir, id)) {
+      releaseIdLock(lock);
+      created = bumpSecond(created);
+      id = idFromTimestamp(created);
+      continue;
+    }
+
+    const file = path.join(changesDir, `${id}-${normalizedSlug}.md`);
+    try {
+      fs.writeFileSync(
+        file,
+        render({ id, title, type, owner, stages: typeDef.stages, now: created }),
+        {
+          flag: 'wx',
+        },
+      );
+      return file;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      created = bumpSecond(created);
+      id = idFromTimestamp(created);
+    } finally {
+      releaseIdLock(lock);
+    }
+  }
+}
+
+function acquireIdLock(changesDir, id) {
+  const lock = path.join(changesDir, `.${id}.lock`);
+  let attempts = 0;
+  for (;;) {
+    try {
+      const fd = fs.openSync(lock, 'wx');
+      fs.writeFileSync(
+        fd,
+        JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }),
+      );
+      return { fd, path: lock };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      if (!isStaleLock(lock)) return null;
+      if (++attempts > 5) return null;
+      fs.rmSync(lock, { force: true });
+    }
+  }
+}
+
+function releaseIdLock(lock) {
+  fs.closeSync(lock.fd);
+  fs.rmSync(lock.path, { force: true });
+}
+
+function isStaleLock(lock) {
+  try {
+    const raw = fs.readFileSync(lock, 'utf8');
+    const data = JSON.parse(raw);
+    return !Number.isInteger(data.pid) || !processIsAlive(data.pid);
+  } catch {
+    try {
+      return Date.now() - fs.statSync(lock).mtimeMs > LOCK_MTIME_STALE_MS;
+    } catch (e) {
+      if (e.code === 'ENOENT') return true;
+      throw e;
+    }
+  }
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+function idTaken(changesDir, id) {
+  return fs.readdirSync(changesDir).some((name) => name.startsWith(`${id}-`));
+}
+
+function bumpSecond(iso) {
+  const t = new Date(iso).getTime() + 1000;
+  return new Date(t).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+// Derives the canonical id from an ISO 8601 UTC timestamp: YYYYMMDD-HHMMSS.
+export function idFromTimestamp(iso) {
+  const m = iso.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})/);
+  if (!m) throw new Error(`Invalid ISO timestamp: ${iso}`);
+  const [, y, mo, d, h, mi, s] = m;
+  return `${y}${mo}${d}-${h}${mi}${s}`;
+}
+
+function heading(stageKey) {
+  return stageKey.charAt(0).toUpperCase() + stageKey.slice(1);
+}
+
+function render({ id, title, type, owner, stages, now }) {
+  const fm = [
+    '---',
+    `id: "${id}"`,
+    `title: ${serializeScalar(title)}`,
+    `type: ${type}`,
+    'status: draft',
+    `created: ${now}`,
+    'depends_on: []',
+    ...(owner ? [`owner: ${serializeScalar(owner)}`] : []),
+    '---',
+    '',
+  ].join('\n');
+  const body = stages.map((s) => `## ${heading(s)}\n`).join('\n');
+  return `${fm}\n${body}`;
+}

package/src/commands/register.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findChangeledgerDir, loadConfig } from '../config.mjs';
+import { ensureGitignore, ensureReference, linkContract, rootContract } from '../contract.mjs';
+import { register } from '../registry.mjs';
+
+// (Re)links the current repo's path to its config project_id in the global
+// registry, and regenerates the per-machine `.changeledger/AGENTS.md` contract link. Use
+// after moving the repo or cloning it on another machine.
+export function registerRepo(cwd = process.cwd()) {
+  const changeledgerDir = findChangeledgerDir(cwd);
+  if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+
+  const config = loadConfig(changeledgerDir);
+  if (!config.project_id) {
+    throw new Error('config.yml has no project_id. Run `changeledger init` to create one.');
+  }
+
+  const repoRoot = path.dirname(changeledgerDir);
+  const name = config.project_name || path.basename(repoRoot);
+
+  linkContract(changeledgerDir);
+  ensureGitignore(repoRoot);
+  if (fs.existsSync(rootContract(repoRoot))) ensureReference(repoRoot);
+
+  register({ id: config.project_id, name, path: repoRoot });
+  return { id: config.project_id, name, path: repoRoot };
+}