changeledger 0.3.0

package/src/registry.mjs

@@ -0,0 +1,55 @@
+// Global project registry: maps a stable project_id to its absolute path on this
+// machine. Identity lives in the repo's config (committed); the path is local,
+// so moved/cloned repos just re-register. Override the home with
+// CHANGELEDGER_HOME (used by tests).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { withFileLock, writeFileAtomic } from './atomic-write.mjs';
+
+export function registryDir() {
+  return path.join(process.env.CHANGELEDGER_HOME || os.homedir(), '.changeledger');
+}
+
+export function registryPath() {
+  return path.join(registryDir(), '.registry.json');
+}
+
+export function readRegistry() {
+  const file = registryPath();
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new Error('.registry.json is not valid JSON');
+  }
+}
+
+export function writeRegistry(reg) {
+  fs.mkdirSync(registryDir(), { recursive: true });
+  writeFileAtomic(registryPath(), `${JSON.stringify(reg, null, 2)}\n`);
+}
+
+export function register({ id, name, path: repoPath }) {
+  fs.mkdirSync(registryDir(), { recursive: true });
+  return withFileLock(registryPath(), () => {
+    const reg = readRegistry();
+    reg[id] = { name, path: repoPath };
+    writeRegistry(reg);
+    return reg;
+  });
+}
+
+export function listProjects() {
+  return Object.entries(readRegistry()).map(([id, v]) => ({ id, name: v.name, path: v.path }));
+}
+
+export function remove(id) {
+  fs.mkdirSync(registryDir(), { recursive: true });
+  withFileLock(registryPath(), () => {
+    const reg = readRegistry();
+    delete reg[id];
+    writeRegistry(reg);
+  });
+}

package/src/release.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveRepoPath } from './config.mjs';
+import { parseYaml } from './yaml.mjs';
+
+export const RELEASE_IMPACTS = ['none', 'patch', 'minor', 'major'];
+export const DEFAULT_RELEASES_DIR = '.changeledger/releases';
+
+const STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+export function parseVersion(value) {
+  const match = String(value ?? '').match(STABLE_SEMVER);
+  if (!match) throw new Error(`Invalid stable SemVer "${value}" (expected X.Y.Z)`);
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+export function compareVersions(a, b) {
+  const av = parseVersion(a);
+  const bv = parseVersion(b);
+  return av.major - bv.major || av.minor - bv.minor || av.patch - bv.patch;
+}
+
+export function bumpVersion(version, impact) {
+  const current = parseVersion(version);
+  if (!RELEASE_IMPACTS.includes(impact) || impact === 'none') {
+    throw new Error(`Cannot bump version with release impact "${impact}"`);
+  }
+  if (impact === 'major') return `${current.major + 1}.0.0`;
+  if (impact === 'minor') return `${current.major}.${current.minor + 1}.0`;
+  return `${current.major}.${current.minor}.${current.patch + 1}`;
+}
+
+export function resolveReleasesDir(repoRoot) {
+  return resolveRepoPath(repoRoot, DEFAULT_RELEASES_DIR, 'releases_dir');
+}
+
+export function loadReleases(repoRoot) {
+  const releasesDir = resolveReleasesDir(repoRoot);
+  const releases = [];
+  if (!fs.existsSync(releasesDir)) return releases;
+  for (const name of fs.readdirSync(releasesDir).sort()) {
+    if (!name.endsWith('.yml')) continue;
+    const file = path.join(releasesDir, name);
+    try {
+      releases.push({ file, name, ...parseYaml(fs.readFileSync(file, 'utf8')) });
+    } catch (error) {
+      throw new Error(`Invalid release manifest "${name}": ${error.message}`);
+    }
+  }
+  return releases;
+}
+
+export async function loadReleasesAsync(repoRoot) {
+  const releasesDir = resolveReleasesDir(repoRoot);
+  const releases = [];
+  try {
+    const names = (await fs.promises.readdir(releasesDir)).sort();
+    for (const name of names) {
+      if (!name.endsWith('.yml')) continue;
+      const file = path.join(releasesDir, name);
+      try {
+        releases.push({ file, name, ...parseYaml(await fs.promises.readFile(file, 'utf8')) });
+      } catch (error) {
+        throw new Error(`Invalid release manifest "${name}": ${error.message}`);
+      }
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return releases;
+}

package/src/repo.mjs

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseChange } from './change.mjs';
+import { findChangeledgerDir, loadConfig, resolveRepoPath, resolveSpecsDir } from './config.mjs';
+import { loadReleases, loadReleasesAsync } from './release.mjs';
+import { parseSpec } from './spec.mjs';
+
+// Single authority for resolving a change id to its file. Matches by EXACT
+// frontmatter.id equality — never by filename prefix — so a partial or ambiguous
+// id (timestamp ids share prefixes) cannot silently target the first file that
+// happens to share it, and a misleading filename cannot stand in for a change
+// whose frontmatter id differs. A file that fails to parse cannot be the exact
+// match, so it is skipped rather than aborting the search. Shared by every
+// mutating and locating command.
+export function resolveChange(start, id) {
+  const changeledgerDir = findChangeledgerDir(start);
+  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)) {
+    for (const name of fs.readdirSync(changesDir).sort()) {
+      if (!name.endsWith('.md')) continue;
+      const file = path.join(changesDir, name);
+      let frontmatter;
+      try {
+        ({ frontmatter } = parseChange(fs.readFileSync(file, 'utf8')));
+      } catch {
+        continue; // unparseable file can't be the exact match
+      }
+      if (String(frontmatter.id) === String(id)) return { config, repoRoot, changesDir, file };
+    }
+  }
+  throw new Error(
+    `No change with id "${id}" (use the exact id; run \`changeledger check\` if a filename's id looks wrong)`,
+  );
+}
+
+// Loads a ChangeLedger repo: locates .changeledger/, reads config and every change file.
+// Shared by `changeledger view` and `changeledger check`.
+export function loadRepo(start = process.cwd()) {
+  const changeledgerDir = findChangeledgerDir(start);
+  if (!changeledgerDir) {
+    throw new Error(
+      'Not a ChangeLedger repo (no .changeledger/ found). Run `changeledger init` first.',
+    );
+  }
+  const repoRoot = path.dirname(changeledgerDir);
+  const config = loadConfig(changeledgerDir);
+  const changesDir = resolveRepoPath(repoRoot, config.changes_dir, 'changes_dir');
+
+  const changes = [];
+  if (fs.existsSync(changesDir)) {
+    for (const name of fs.readdirSync(changesDir).sort()) {
+      if (!name.endsWith('.md')) continue;
+      const file = path.join(changesDir, name);
+      const text = fs.readFileSync(file, 'utf8');
+      changes.push({ file, name, text, ...parseChange(text) });
+    }
+  }
+  changes.sort((a, b) => String(a.frontmatter.id).localeCompare(String(b.frontmatter.id)));
+
+  const specs = [];
+  const specsDir = resolveSpecsDir(repoRoot, config);
+  if (fs.existsSync(specsDir)) {
+    for (const name of fs.readdirSync(specsDir).sort()) {
+      if (!name.endsWith('.md')) continue;
+      const file = path.join(specsDir, name);
+      specs.push({ file, name, ...parseSpec(fs.readFileSync(file, 'utf8')) });
+    }
+  }
+
+  const releases = loadReleases(repoRoot);
+
+  return { changeledgerDir, repoRoot, config, changes, specs, releases };
+}
+
+// Async equivalent for HTTP paths that should not monopolize the Node event
+// loop while reading large change/spec histories. The synchronous loader remains
+// the command API for CLI code.
+export async function loadRepoAsync(start = process.cwd()) {
+  const changeledgerDir = findChangeledgerDir(start);
+  if (!changeledgerDir) {
+    throw new Error(
+      'Not a ChangeLedger repo (no .changeledger/ found). Run `changeledger init` first.',
+    );
+  }
+  const repoRoot = path.dirname(changeledgerDir);
+  const config = loadConfig(changeledgerDir);
+  const changesDir = resolveRepoPath(repoRoot, config.changes_dir, 'changes_dir');
+
+  const changes = [];
+  try {
+    const names = (await fs.promises.readdir(changesDir)).sort();
+    for (const name of names) {
+      if (!name.endsWith('.md')) continue;
+      const file = path.join(changesDir, name);
+      const text = await fs.promises.readFile(file, 'utf8');
+      changes.push({ file, name, text, ...parseChange(text) });
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  changes.sort((a, b) => String(a.frontmatter.id).localeCompare(String(b.frontmatter.id)));
+
+  const specs = [];
+  const specsDir = resolveSpecsDir(repoRoot, config);
+  try {
+    const names = (await fs.promises.readdir(specsDir)).sort();
+    for (const name of names) {
+      if (!name.endsWith('.md')) continue;
+      const file = path.join(specsDir, name);
+      specs.push({ file, name, ...parseSpec(await fs.promises.readFile(file, 'utf8')) });
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  const releases = await loadReleasesAsync(repoRoot);
+
+  return { changeledgerDir, repoRoot, config, changes, specs, releases };
+}

package/src/slug.mjs

@@ -0,0 +1,12 @@
+const EMPTY_SLUG = 'slug must contain at least one ASCII letter or number';
+
+export function slugify(value) {
+  const slug = String(value ?? '')
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!slug) throw new Error(EMPTY_SLUG);
+  return slug;
+}

package/src/spec.mjs

@@ -0,0 +1,12 @@
+// Parses a spec file: the persistent-truth layer. Unlike changes, specs have no
+// lifecycle — just frontmatter (title, updated, tags) plus a free markdown body.
+
+import { parseYaml } from './yaml.mjs';
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/;
+
+export function parseSpec(text) {
+  const fm = text.match(FRONTMATTER);
+  if (!fm) throw new Error('Spec is missing its frontmatter block');
+  return { frontmatter: parseYaml(fm[1]), body: text.slice(fm[0].length).trim() };
+}

package/src/viewer/domain.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { status as applyStatusCmd, validation as applyValidation } from '../commands/agent.mjs';
+import { findChangeledgerDir, loadConfig } from '../config.mjs';
+import { computeMetrics } from '../metrics.mjs';
+import { nowUtc } from '../paths.mjs';
+import { listProjects } from '../registry.mjs';
+import { loadRepo } from '../repo.mjs';
+
+// Serializes a loaded repo into the flat shape the UI consumes.
+export function serialize(repo) {
+  return {
+    language: repo.config.language ?? 'en',
+    statuses: repo.config.statuses ?? [],
+    types: Object.keys(repo.config.types ?? {}),
+    metrics: computeMetrics(repo.changes, { now: nowUtc() }),
+    changes: repo.changes.map((c) => ({
+      id: c.frontmatter.id,
+      title: c.frontmatter.title,
+      type: c.frontmatter.type,
+      status: c.frontmatter.status,
+      owner: c.frontmatter.owner ?? null,
+      archived: c.frontmatter.archived === true,
+      created: c.frontmatter.created,
+      depends_on: c.frontmatter.depends_on ?? [],
+      stages: c.stages,
+      tasks: c.tasks,
+      progress: c.progress,
+    })),
+    specs: (repo.specs ?? []).map((s) => ({
+      name: s.name,
+      title: s.frontmatter.title,
+      updated: s.frontmatter.updated,
+      tags: s.frontmatter.tags ?? [],
+      body: s.body,
+    })),
+  };
+}
+
+const isAlive = (p) => fs.existsSync(path.join(p, '.changeledger', 'config.yml'));
+
+// The project list and which one is "current" (the repo the command ran in).
+export function resolveProjects(cwd, localOnly) {
+  const changeledgerDir = findChangeledgerDir(cwd);
+  const repoRoot = changeledgerDir ? path.dirname(changeledgerDir) : null;
+
+  if (localOnly) {
+    if (!repoRoot) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+    const config = loadConfig(changeledgerDir);
+    const id = config.project_id ?? 'local';
+    const name = config.project_name ?? path.basename(repoRoot);
+    return { projects: [{ id, name, path: repoRoot, alive: true }], current: id };
+  }
+
+  const projects = listProjects().map((p) => ({ ...p, alive: isAlive(p.path) }));
+  let current = null;
+  if (repoRoot) {
+    const match = projects.find((p) => path.resolve(p.path) === repoRoot);
+    if (match) current = match.id;
+  }
+  return { projects, current };
+}
+
+// Full-text search across the given (alive) projects. `load` maps a project path
+// to a loaded repo (loadRepo by default). Returns groups with at least one match.
+export function searchProjects(projects, q, load = loadRepo) {
+  const needle = String(q ?? '')
+    .trim()
+    .toLowerCase();
+  if (!needle) return [];
+  const groups = [];
+  for (const p of projects) {
+    if (!p.alive) continue;
+    let repo;
+    try {
+      repo = load(p.path);
+    } catch {
+      continue;
+    }
+    const matches = repo.changes
+      .filter((c) => `${c.text ?? ''} ${c.frontmatter?.title ?? ''}`.toLowerCase().includes(needle))
+      .map((c) => ({
+        id: c.frontmatter.id,
+        title: c.frontmatter.title,
+        type: c.frontmatter.type,
+        status: c.frontmatter.status,
+      }));
+    if (matches.length) groups.push({ project: { id: p.id, name: p.name }, matches });
+  }
+  return groups;
+}
+
+// Applies a status move requested from the viewer. Returns { code, body } so the
+// HTTP handler stays thin and the logic is testable. Reuses the `status` command
+// (enum validation + setStatus + appendLog).
+export function changeStatus(projects, { project, id, status, reason }) {
+  // A write must target an exact project; never silently fall back to the first
+  // registered one.
+  const proj = projects.find((p) => p.id === project);
+  if (!proj) return { code: 404, body: { error: `no project "${project}"` } };
+  if (!proj.alive) return { code: 410, body: { error: 'project path is gone' } };
+  if (!id || !status) return { code: 400, body: { error: 'id and status are required' } };
+
+  // The viewer is the human's surface. Enforce the human/agent boundary here —
+  // the UI is bypassable.
+  let current;
+  try {
+    const change = loadRepo(proj.path).changes.find((c) => String(c.frontmatter.id) === String(id));
+    if (!change) return { code: 404, body: { error: `no change with id "${id}"` } };
+    current = change.frontmatter.status;
+  } catch (e) {
+    return { code: 400, body: { error: e.message } };
+  }
+  try {
+    if (current === 'draft' && status === 'approved') {
+      applyStatusCmd(id, status, proj.path);
+    } else if (current === 'in-validation' && status === 'done') {
+      applyValidation(id, 'pass', {}, proj.path);
+    } else if (current === 'in-validation' && status === 'in-progress') {
+      applyValidation(id, 'fail', { reason }, proj.path);
+    } else {
+      return {
+        code: 403,
+        body: {
+          error: 'the viewer only allows draft → approved and in-validation → done|in-progress',
+        },
+      };
+    }
+    return { code: 200, body: { ok: true, id, status } };
+  } catch (e) {
+    return { code: 400, body: { error: e.message } };
+  }
+}

package/src/viewer/public/api.js

@@ -0,0 +1,25 @@
+export const getProjects = () => fetch('/api/projects').then((r) => r.json());
+
+export const getRepo = async (project) => {
+  const res = await fetch(`/api/repo?project=${encodeURIComponent(project)}`);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.text();
+};
+
+export const getGitRefs = (project, id) =>
+  fetch(`/api/git?project=${encodeURIComponent(project)}&id=${encodeURIComponent(id)}`).then((r) =>
+    r.json(),
+  );
+
+export const searchAllProjects = (query) =>
+  fetch(`/api/search?q=${encodeURIComponent(query)}`).then((r) => r.json());
+
+export const postStatus = (project, id, status, reason) =>
+  fetch('/api/status', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-changeledger-token': window.__CHANGELEDGER_TOKEN__,
+    },
+    body: JSON.stringify({ project, id, status, ...(reason ? { reason } : {}) }),
+  });

package/src/viewer/public/app-state.js

@@ -0,0 +1,87 @@
+export const state = {
+  repo: null,
+  lastJson: '',
+  filters: {
+    text: '',
+    type: 'all',
+    owner: 'all',
+    statuses: new Set(),
+    showArchived: false,
+    showDiscarded: false,
+  },
+  currentView: 'board',
+  sortKey: 'id',
+  sortDir: 1,
+  currentProject: null,
+  projectsList: [],
+  globalMode: false,
+};
+
+export function setRepo(json) {
+  state.lastJson = json;
+  state.repo = JSON.parse(json);
+}
+
+export function invalidateCache() {
+  state.lastJson = '';
+}
+
+export function setTextFilter(text) {
+  state.filters.text = text;
+}
+
+export function setTypeFilter(type) {
+  state.filters.type = type;
+}
+
+export function setOwnerFilter(owner) {
+  state.filters.owner = owner;
+}
+
+export function toggleStatusFilter(status) {
+  if (state.filters.statuses.has(status)) state.filters.statuses.delete(status);
+  else state.filters.statuses.add(status);
+  return state.filters.statuses.has(status);
+}
+
+export function clearStatusFilters() {
+  state.filters.statuses.clear();
+  state.filters.showArchived = false;
+  state.filters.showDiscarded = false;
+}
+
+export function toggleShowArchived() {
+  state.filters.showArchived = !state.filters.showArchived;
+  return state.filters.showArchived;
+}
+
+export function toggleShowDiscarded() {
+  state.filters.showDiscarded = !state.filters.showDiscarded;
+  return state.filters.showDiscarded;
+}
+
+export function setView(v) {
+  state.currentView = v;
+  state.globalMode = false;
+}
+
+export function selectProject(id) {
+  state.currentProject = id;
+  state.lastJson = '';
+  state.filters.type = 'all';
+  state.filters.owner = 'all';
+  state.filters.statuses.clear();
+}
+
+export function setSortKey(key) {
+  if (state.sortKey === key) state.sortDir = -state.sortDir;
+  else {
+    state.sortKey = key;
+    state.sortDir = 1;
+  }
+}
+
+export function toggleGlobalMode() {
+  state.globalMode = !state.globalMode;
+  return state.globalMode;
+}