changeledger 0.3.0 → 0.4.0

package/package.json

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

package/src/check.mjs

@@ -15,9 +15,9 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
 
   checkConfig(config, (c, message) => err(c ?? { name: '.changeledger/config.yml' }, message));
 
-  const statuses = config.statuses ?? [];
-  const types = config.types ?? {};
-  const canonical = config.stages ?? [];
+  const statuses = Array.isArray(config.statuses) ? config.statuses : [];
+  const types = isMapping(config.types) ? config.types : {};
+  const canonical = Array.isArray(config.stages) ? config.stages : [];
 
   // Scope: a single change (fast, post-write check) or the whole repo.
   let targets = changes;
@@ -64,7 +64,8 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
     const ordered = [...known].sort((a, b) => canonical.indexOf(a) - canonical.indexOf(b));
     if (known.join(',') !== ordered.join(',')) err(c, 'stages are out of canonical order');
 
-    const active = types[fm.type]?.stages;
+    const typeDefinition = isMapping(types[fm.type]) ? types[fm.type] : null;
+    const active = Array.isArray(typeDefinition?.stages) ? typeDefinition.stages : null;
     if (active) {
       for (const k of active)
         if (!present.includes(k)) err(c, `missing active stage "## ${k}" for type ${fm.type}`);
@@ -365,9 +366,20 @@ function misplacedVerificationSuffix(task, config) {
 }
 
 function readinessConfig(config) {
+  const readiness = isMapping(config?.readiness) ? config.readiness : null;
   return {
-    target_patterns: config?.readiness?.target_patterns ?? ['src/**'],
-    verification_patterns: config?.readiness?.verification_patterns ?? ['test/**'],
+    target_patterns:
+      readiness && 'target_patterns' in readiness
+        ? Array.isArray(readiness.target_patterns)
+          ? readiness.target_patterns
+          : []
+        : ['src/**'],
+    verification_patterns:
+      readiness && 'verification_patterns' in readiness
+        ? Array.isArray(readiness.verification_patterns)
+          ? readiness.verification_patterns
+          : []
+        : ['test/**'],
   };
 }
 
@@ -445,11 +457,21 @@ function checkConfig(config, err) {
   }
   if ('statuses' in c && !Array.isArray(c.statuses)) err(null, 'config "statuses" must be a list');
   if ('stages' in c && !Array.isArray(c.stages)) err(null, 'config "stages" must be a list');
+  if ('types' in c && !isMapping(c.types)) err(null, 'config "types" must be a mapping');
   if ('readiness' in c) checkReadinessConfig(c.readiness, err);
-  if ('release' in c) checkReleaseConfig(c.release, c.types ?? {}, err);
+  const configuredTypes = isMapping(c.types) ? c.types : {};
+  if ('release' in c) checkReleaseConfig(c.release, configuredTypes, err);
   const canonical = Array.isArray(c.stages) ? c.stages : [];
-  for (const [type, def] of Object.entries(c.types ?? {})) {
-    for (const s of def?.stages ?? []) {
+  for (const [type, def] of Object.entries(configuredTypes)) {
+    if (!isMapping(def)) {
+      err(null, `config type "${type}" must be a mapping`);
+      continue;
+    }
+    if (!Array.isArray(def.stages)) {
+      err(null, `config type "${type}": stages must be a list`);
+      continue;
+    }
+    for (const s of def.stages) {
       if (!canonical.includes(s))
         err(null, `config type "${type}" references unknown stage "${s}"`);
     }
@@ -458,6 +480,10 @@ function checkConfig(config, err) {
   }
 }
 
+function isMapping(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
 function checkReleaseConfig(release, types, err) {
   if (!release || typeof release !== 'object' || Array.isArray(release)) {
     err(null, 'config "release" must be a mapping');

package/src/commands/view.mjs

@@ -5,7 +5,16 @@ import { resolveProjects } from '../viewer/domain.mjs';
 import { createRequestListener, staticFile } from '../viewer/server/router.mjs';
 import { hostnameOf, isAuthorizedWrite, isLocalHost } from '../viewer/server/security.mjs';
 
-export { changeStatus, resolveProjects, searchProjects, serialize } from '../viewer/domain.mjs';
+export {
+  changeStatus,
+  readProjectConfig,
+  repairProjectPath,
+  resolveProjects,
+  saveProjectConfig,
+  searchProjects,
+  serialize,
+  unregisterProject,
+} from '../viewer/domain.mjs';
 export { createRequestListener, hostnameOf, isAuthorizedWrite, isLocalHost, staticFile };
 
 export async function view(args = [], cwd = process.cwd()) {

package/src/config.mjs

@@ -2,13 +2,16 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from './yaml.mjs';
 
-// Walk up from `start` looking for a `.changeledger/` directory. Returns its absolute path
-// or null if none is found.
+// Walk up from `start` looking for a project `.changeledger/config.yml`. The
+// config file is the marker: `~/.changeledger/` may exist only as global state
+// and must not be mistaken for a repository (notably when Windows temp dirs
+// live below the user's home). Returns the project data directory or null.
 export function findChangeledgerDir(start = process.cwd()) {
   let dir = path.resolve(start);
   for (;;) {
     const candidate = path.join(dir, '.changeledger');
-    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+    const config = path.join(candidate, 'config.yml');
+    if (fs.existsSync(config) && fs.statSync(config).isFile()) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) return null;
     dir = parent;

package/src/registry.mjs

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { withFileLock, writeFileAtomic } from './atomic-write.mjs';
+import { loadConfig } from './config.mjs';
 
 export function registryDir() {
   return path.join(process.env.CHANGELEDGER_HOME || os.homedir(), '.changeledger');
@@ -42,7 +43,18 @@ export function register({ id, name, path: repoPath }) {
 }
 
 export function listProjects() {
-  return Object.entries(readRegistry()).map(([id, v]) => ({ id, name: v.name, path: v.path }));
+  return Object.entries(readRegistry()).map(([id, value]) => {
+    let name = value.name;
+    try {
+      const config = loadConfig(path.join(value.path, '.changeledger'));
+      if (String(config.project_id) === id && typeof config.project_name === 'string') {
+        name = config.project_name;
+      }
+    } catch {
+      // Missing projects keep their last registered display name.
+    }
+    return { id, name, path: value.path };
+  });
 }
 
 export function remove(id) {
@@ -53,3 +65,14 @@ export function remove(id) {
     writeRegistry(reg);
   });
 }
+
+export function update(id, values) {
+  fs.mkdirSync(registryDir(), { recursive: true });
+  return withFileLock(registryPath(), () => {
+    const reg = readRegistry();
+    if (!reg[id]) throw new Error(`no registered project "${id}"`);
+    reg[id] = { ...reg[id], ...values };
+    writeRegistry(reg);
+    return reg[id];
+  });
+}

package/src/repo.mjs

@@ -47,6 +47,13 @@ export function loadRepo(start = process.cwd()) {
   }
   const repoRoot = path.dirname(changeledgerDir);
   const config = loadConfig(changeledgerDir);
+  return loadRepoWithConfig(repoRoot, changeledgerDir, config);
+}
+
+// Loads repository content using an already parsed candidate config. The viewer
+// uses this before replacing config.yml so changes to configured directories are
+// validated against the content they would actually expose after the save.
+export function loadRepoWithConfig(repoRoot, changeledgerDir, config) {
   const changesDir = resolveRepoPath(repoRoot, config.changes_dir, 'changes_dir');
 
   const changes = [];

package/src/viewer/domain.mjs

@@ -1,11 +1,15 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+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 } from '../config.mjs';
+import { findChangeledgerDir, loadConfig, resolveRepoPath, resolveSpecsDir } from '../config.mjs';
 import { computeMetrics } from '../metrics.mjs';
 import { nowUtc } from '../paths.mjs';
-import { listProjects } from '../registry.mjs';
-import { loadRepo } from '../repo.mjs';
+import { listProjects, remove, update } from '../registry.mjs';
+import { loadRepo, loadRepoWithConfig } from '../repo.mjs';
+import { parseYaml } from '../yaml.mjs';
 
 // Serializes a loaded repo into the flat shape the UI consumes.
 export function serialize(repo) {
@@ -131,3 +135,132 @@ export function changeStatus(projects, { project, id, status, reason }) {
     return { code: 400, body: { error: e.message } };
   }
 }
+
+const revision = (text) => crypto.createHash('sha256').update(text).digest('hex');
+
+function projectFor(projects, id) {
+  const project = projects.find((item) => item.id === id);
+  if (!project) return { code: 404, body: { error: `no project "${id}"` } };
+  if (!project.alive) return { code: 410, body: { error: 'project path is gone' } };
+  return { project };
+}
+
+export function readProjectConfig(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');
+  return { code: 200, body: { content, revision: revision(content) } };
+}
+
+export function saveProjectConfig(projects, payload, { mutateConfig = mutateFileAtomic } = {}) {
+  const found = projectFor(projects, payload.project);
+  if (!found.project) return found;
+  if (typeof payload.content !== 'string' || typeof payload.revision !== 'string') {
+    return { code: 400, body: { error: 'content and revision are required' } };
+  }
+
+  let candidate;
+  try {
+    candidate = parseYaml(payload.content);
+  } catch (error) {
+    return { code: 400, body: { error: error.message } };
+  }
+  if (String(candidate.project_id ?? '') !== String(found.project.id)) {
+    return { code: 400, body: { error: 'project_id cannot be changed from the viewer' } };
+  }
+
+  let repo;
+  try {
+    repo = loadRepo(found.project.path);
+  } catch {
+    return { code: 400, body: { error: 'unable to load the current project configuration' } };
+  }
+  try {
+    resolveRepoPath(repo.repoRoot, candidate.changes_dir, 'changes_dir');
+    resolveSpecsDir(repo.repoRoot, candidate);
+  } catch (error) {
+    return { code: 400, body: { error: error.message } };
+  }
+  let candidateRepo;
+  try {
+    candidateRepo = loadRepoWithConfig(repo.repoRoot, repo.changeledgerDir, candidate);
+  } catch {
+    return { code: 400, body: { error: 'candidate configuration cannot load the repository' } };
+  }
+  let errors;
+  try {
+    ({ errors } = checkRepo(candidateRepo));
+  } catch {
+    return {
+      code: 400,
+      body: { error: 'candidate configuration violates the ChangeLedger contract' },
+    };
+  }
+  if (errors.length) return { code: 400, body: { error: errors[0].message } };
+
+  const file = path.join(repo.changeledgerDir, 'config.yml');
+  const projectName =
+    typeof candidate.project_name === 'string' && candidate.project_name.trim()
+      ? candidate.project_name
+      : found.project.name;
+  try {
+    mutateConfig(file, (before) => {
+      if (revision(before) !== payload.revision) {
+        throw new Error('configuration changed on disk; reload before saving');
+      }
+      return payload.content;
+    });
+  } catch (error) {
+    if (error.message === 'configuration changed on disk; reload before saving') {
+      return { code: 409, body: { error: error.message } };
+    }
+    return { code: 400, body: { error: 'unable to save project configuration' } };
+  }
+  return {
+    code: 200,
+    body: { ok: true, name: projectName, revision: revision(payload.content) },
+  };
+}
+
+export function repairProjectPath(projects, payload, { localOnly = false } = {}) {
+  if (localOnly)
+    return { code: 403, body: { error: 'registry management is unavailable in local mode' } };
+  const project = projects.find((item) => item.id === payload.project);
+  if (!project) return { code: 404, body: { error: `no project "${payload.project}"` } };
+  if (typeof payload.path !== 'string' || !path.isAbsolute(payload.path)) {
+    return { code: 400, body: { error: 'project path must be absolute' } };
+  }
+  const root = path.resolve(payload.path);
+  let config;
+  try {
+    config = loadConfig(path.join(root, '.changeledger'));
+  } catch {
+    return { code: 400, body: { error: 'project path is not a ChangeLedger repository' } };
+  }
+  if (String(config.project_id ?? '') !== String(project.id)) {
+    return { code: 400, body: { error: 'project path belongs to a different project_id' } };
+  }
+  try {
+    update(project.id, { name: config.project_name ?? project.name, path: root });
+  } catch {
+    return { code: 400, body: { error: 'unable to update project registry' } };
+  }
+  return { code: 200, body: { ok: true } };
+}
+
+export function unregisterProject(projects, payload, { localOnly = false } = {}) {
+  if (localOnly)
+    return { code: 403, body: { error: 'registry management is unavailable in local mode' } };
+  const project = projects.find((item) => item.id === payload.project);
+  if (!project) return { code: 404, body: { error: `no project "${payload.project}"` } };
+  if (payload.confirm !== project.name) {
+    return { code: 400, body: { error: `type "${project.name}" to confirm` } };
+  }
+  try {
+    remove(project.id);
+  } catch {
+    return { code: 400, body: { error: 'unable to update project registry' } };
+  }
+  return { code: 200, body: { ok: true } };
+}

package/src/viewer/public/api.js

@@ -1,5 +1,12 @@
 export const getProjects = () => fetch('/api/projects').then((r) => r.json());
 
+export const getProjectConfig = (project) =>
+  fetch(`/api/project-config?project=${encodeURIComponent(project)}`).then(async (response) => {
+    const body = await response.json();
+    if (!response.ok) throw new Error(body.error || `HTTP ${response.status}`);
+    return body;
+  });
+
 export const getRepo = async (project) => {
   const res = await fetch(`/api/repo?project=${encodeURIComponent(project)}`);
   if (!res.ok) throw new Error(`HTTP ${res.status}`);
@@ -23,3 +30,22 @@ export const postStatus = (project, id, status, reason) =>
     },
     body: JSON.stringify({ project, id, status, ...(reason ? { reason } : {}) }),
   });
+
+const postProject = (route, body) =>
+  fetch(route, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-changeledger-token': window.__CHANGELEDGER_TOKEN__,
+    },
+    body: JSON.stringify(body),
+  });
+
+export const postProjectConfig = (project, content, revision) =>
+  postProject('/api/project-config', { project, content, revision });
+
+export const postProjectPath = (project, path) =>
+  postProject('/api/project-path', { project, path });
+
+export const postProjectRemove = (project, confirm) =>
+  postProject('/api/project-remove', { project, confirm });

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

@@ -1,3 +1,17 @@
+export const VIEWER_STATE_KEY = 'changeledger.viewer-state.v1';
+
+const VALID_VIEWS = new Set(['board', 'table', 'graph', 'specs', 'metrics', 'projects']);
+const VALID_SORT_KEYS = new Set(['id', 'title', 'type', 'status', 'progress', 'deps']);
+let storage = null;
+
+const emptyProjectFilters = () => ({
+  type: 'all',
+  owner: 'all',
+  statuses: [],
+  showArchived: false,
+  showDiscarded: false,
+});
+
 export const state = {
   repo: null,
   lastJson: '',
@@ -9,14 +23,129 @@ export const state = {
     showArchived: false,
     showDiscarded: false,
   },
+  projectFilters: {},
   currentView: 'board',
   sortKey: 'id',
   sortDir: 1,
   currentProject: null,
   projectsList: [],
+  localOnly: false,
   globalMode: false,
 };
 
+function currentProjectFilters() {
+  return {
+    type: state.filters.type,
+    owner: state.filters.owner,
+    statuses: [...state.filters.statuses],
+    showArchived: state.filters.showArchived,
+    showDiscarded: state.filters.showDiscarded,
+  };
+}
+
+function saveCurrentProjectFilters() {
+  if (state.currentProject) state.projectFilters[state.currentProject] = currentProjectFilters();
+}
+
+function applyProjectFilters(id) {
+  const filters = state.projectFilters[id] ?? emptyProjectFilters();
+  state.filters.type = typeof filters.type === 'string' ? filters.type : 'all';
+  state.filters.owner = typeof filters.owner === 'string' ? filters.owner : 'all';
+  state.filters.statuses = new Set(
+    Array.isArray(filters.statuses)
+      ? filters.statuses.filter((value) => typeof value === 'string')
+      : [],
+  );
+  state.filters.showArchived = filters.showArchived === true;
+  state.filters.showDiscarded = filters.showDiscarded === true;
+}
+
+export function serializeViewerState() {
+  saveCurrentProjectFilters();
+  return {
+    version: 1,
+    currentProject: state.currentProject,
+    currentView: state.currentView,
+    globalMode: state.globalMode,
+    text: state.filters.text,
+    sortKey: state.sortKey,
+    sortDir: state.sortDir,
+    projects: state.projectFilters,
+  };
+}
+
+export function persistViewerState() {
+  if (!storage) return false;
+  try {
+    storage.setItem(VIEWER_STATE_KEY, JSON.stringify(serializeViewerState()));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function restoreViewerState(storageLike) {
+  storage = storageLike;
+  let snapshot;
+  try {
+    snapshot = JSON.parse(storage.getItem(VIEWER_STATE_KEY) || 'null');
+  } catch {
+    return false;
+  }
+  if (snapshot?.version !== 1 || typeof snapshot !== 'object') return false;
+  if (typeof snapshot.currentProject === 'string') state.currentProject = snapshot.currentProject;
+  if (typeof snapshot.currentView === 'string') state.currentView = snapshot.currentView;
+  state.globalMode = snapshot.globalMode === true;
+  if (typeof snapshot.text === 'string') state.filters.text = snapshot.text;
+  if (typeof snapshot.sortKey === 'string') state.sortKey = snapshot.sortKey;
+  if (snapshot.sortDir === 1 || snapshot.sortDir === -1) state.sortDir = snapshot.sortDir;
+  if (
+    snapshot.projects &&
+    typeof snapshot.projects === 'object' &&
+    !Array.isArray(snapshot.projects)
+  ) {
+    state.projectFilters = snapshot.projects;
+  }
+  if (state.currentProject) applyProjectFilters(state.currentProject);
+  return true;
+}
+
+export function initializeProjects(projects, serverCurrent) {
+  state.projectsList = projects;
+  const alive = new Set(projects.filter((project) => project.alive).map((project) => project.id));
+  const selected = alive.has(state.currentProject)
+    ? state.currentProject
+    : alive.has(serverCurrent)
+      ? serverCurrent
+      : (projects.find((project) => project.alive)?.id ?? null);
+  if (selected !== state.currentProject) {
+    saveCurrentProjectFilters();
+    state.currentProject = selected;
+    if (selected) applyProjectFilters(selected);
+  }
+  if (!selected) state.globalMode = false;
+  persistViewerState();
+  return selected;
+}
+
+export function normalizeRepoState(repo) {
+  if (!VALID_VIEWS.has(state.currentView)) state.currentView = 'board';
+  if (!VALID_SORT_KEYS.has(state.sortKey)) {
+    state.sortKey = 'id';
+    state.sortDir = 1;
+  }
+  if (state.sortDir !== 1 && state.sortDir !== -1) state.sortDir = 1;
+  if (!repo.types.includes(state.filters.type)) state.filters.type = 'all';
+  const owners = new Set(repo.changes.map((change) => change.owner).filter(Boolean));
+  if (state.filters.owner !== 'all' && !owners.has(state.filters.owner))
+    state.filters.owner = 'all';
+  const statuses = new Set(repo.statuses);
+  state.filters.statuses = new Set(
+    [...state.filters.statuses].filter((status) => statuses.has(status)),
+  );
+  persistViewerState();
+}
+
 export function setRepo(json) {
   state.lastJson = json;
   state.repo = JSON.parse(json);
@@ -28,19 +157,23 @@ export function invalidateCache() {
 
 export function setTextFilter(text) {
   state.filters.text = text;
+  persistViewerState();
 }
 
 export function setTypeFilter(type) {
   state.filters.type = type;
+  persistViewerState();
 }
 
 export function setOwnerFilter(owner) {
   state.filters.owner = owner;
+  persistViewerState();
 }
 
 export function toggleStatusFilter(status) {
   if (state.filters.statuses.has(status)) state.filters.statuses.delete(status);
   else state.filters.statuses.add(status);
+  persistViewerState();
   return state.filters.statuses.has(status);
 }
 
@@ -48,29 +181,33 @@ export function clearStatusFilters() {
   state.filters.statuses.clear();
   state.filters.showArchived = false;
   state.filters.showDiscarded = false;
+  persistViewerState();
 }
 
 export function toggleShowArchived() {
   state.filters.showArchived = !state.filters.showArchived;
+  persistViewerState();
   return state.filters.showArchived;
 }
 
 export function toggleShowDiscarded() {
   state.filters.showDiscarded = !state.filters.showDiscarded;
+  persistViewerState();
   return state.filters.showDiscarded;
 }
 
-export function setView(v) {
-  state.currentView = v;
+export function setView(view) {
+  state.currentView = view;
   state.globalMode = false;
+  persistViewerState();
 }
 
 export function selectProject(id) {
+  saveCurrentProjectFilters();
   state.currentProject = id;
   state.lastJson = '';
-  state.filters.type = 'all';
-  state.filters.owner = 'all';
-  state.filters.statuses.clear();
+  applyProjectFilters(id);
+  persistViewerState();
 }
 
 export function setSortKey(key) {
@@ -79,9 +216,11 @@ export function setSortKey(key) {
     state.sortKey = key;
     state.sortDir = 1;
   }
+  persistViewerState();
 }
 
 export function toggleGlobalMode() {
   state.globalMode = !state.globalMode;
+  persistViewerState();
   return state.globalMode;
 }

package/src/viewer/public/app.js

@@ -1,7 +1,20 @@
-import { getGitRefs, getProjects, getRepo, postStatus, searchAllProjects } from './api.js';
+import {
+  getGitRefs,
+  getProjectConfig,
+  getProjects,
+  getRepo,
+  postProjectConfig,
+  postProjectPath,
+  postProjectRemove,
+  postStatus,
+  searchAllProjects,
+} from './api.js';
 import {
   clearStatusFilters,
+  initializeProjects,
   invalidateCache,
+  normalizeRepoState,
+  restoreViewerState,
   selectProject,
   setOwnerFilter,
   setRepo,
@@ -47,8 +60,9 @@ const $ = (sel) => document.querySelector(sel);
 initMermaid();
 
 async function loadProjects() {
-  const { projects, current } = await getProjects();
+  const { projects, current, localOnly } = await getProjects();
   state.projectsList = projects;
+  state.localOnly = localOnly;
   const sel = $('#project');
   litRender(
     projects.map(
@@ -57,7 +71,7 @@ async function loadProjects() {
     ),
     sel,
   );
-  state.currentProject = current ?? projects.find((p) => p.alive)?.id ?? null;
+  initializeProjects(projects, current);
   if (state.currentProject) sel.value = state.currentProject;
   sel.style.display = projects.length > 1 ? '' : 'none';
   await load();
@@ -65,23 +79,34 @@ async function loadProjects() {
 
 async function load() {
   if (!state.currentProject) {
-    litRender(
-      html`<p class="empty" style="padding:20px">No projects registered. Run <code>changeledger init</code> in a repo.</p>`,
-      $('#board'),
-    );
+    if (state.currentView === 'projects') {
+      syncViewerShell();
+      return;
+    }
+    showNoProjects();
     return;
   }
   try {
     const text = await getRepo(state.currentProject);
     if (text === state.lastJson) return;
     setRepo(text);
+    normalizeRepoState(state.repo);
     hydrateFilters();
-    render();
+    syncViewerShell();
   } catch (e) {
     litRender(html`<p style="color:var(--bug);padding:20px">${e.message}</p>`, $('#board'));
   }
 }
 
+export function showNoProjects(root = document) {
+  setView('board');
+  litRender(
+    html`<p class="empty" style="padding:20px">No projects registered. Run <code>changeledger init</code> in a repo.</p>`,
+    root.querySelector('#board'),
+  );
+  syncViewerShell(root, false);
+}
+
 // Rebuilt on each project load (types/statuses can differ per project).
 function hydrateFilters() {
   litRender(
@@ -176,6 +201,7 @@ function render() {
   else if (state.currentView === 'table') renderTable();
   else if (state.currentView === 'specs') renderSpecs();
   else if (state.currentView === 'metrics') renderMetrics();
+  else if (state.currentView === 'projects') renderProjects();
   else renderBoard();
 }
 
@@ -576,12 +602,242 @@ function openSpec(s) {
   renderExpandableMermaid($('#detail'));
 }
 
-const VIEWS = ['board', 'table', 'graph', 'specs', 'metrics'];
+const VIEWS = ['board', 'table', 'graph', 'specs', 'metrics', 'projects'];
 
 function renderMetrics() {
   litRender(metricsHtml(state.repo.metrics || {}), $('#metrics'));
 }
 
+export function syncViewerShell(root = document, renderContent = true) {
+  root.querySelector('#search').value = state.filters.text;
+  root.querySelector('#toggle-global').classList.toggle('active', state.globalMode);
+  for (const name of VIEWS) {
+    root.querySelector(`#view-${name}`).classList.toggle('active', name === state.currentView);
+    root
+      .querySelector(`#${name}`)
+      .classList.toggle('hidden', state.globalMode || name !== state.currentView);
+  }
+  root.querySelector('#global').classList.toggle('hidden', !state.globalMode);
+  if (!renderContent) return;
+  if (state.globalMode) renderGlobal();
+  else render();
+}
+
+export function restoreInitialViewerShell(root = document, getStorage = () => window.localStorage) {
+  let browserStorage = null;
+  try {
+    browserStorage = getStorage();
+  } catch {
+    // Storage access itself may be forbidden (opaque origins/privacy policy).
+  }
+  restoreViewerState(browserStorage);
+  syncViewerShell(root, false);
+}
+
+let managedProject = null;
+let managedConfig = null;
+
+export function projectsViewTemplate(projects, selected, config, localOnly) {
+  const project = projects.find((item) => item.id === selected);
+  return html`<div class="projects-shell">
+    <div class="projects-list">
+      <div class="projects-heading">
+        <div><span class="eyebrow">Registry</span><h1>Projects</h1></div>
+        <span class="count">${projects.length}</span>
+      </div>
+      ${
+        projects.length
+          ? html`<div class="project-rows">${projects.map(
+              (
+                item,
+              ) => html`<button type="button" class=${`project-row${item.id === selected ? ' active' : ''}`} data-manage-project=${item.id}>
+              <span class=${`health-dot ${item.alive ? 'available' : 'missing'}`} aria-hidden="true"></span>
+              <span class="project-summary"><strong>${item.name}</strong><small>${item.path}</small></span>
+              <span class="mono project-id">${item.id}</span>
+              <span class=${`project-health ${item.alive ? 'available' : 'missing'}`}>${item.alive ? 'Available' : 'Missing'}</span>
+            </button>`,
+            )}</div>`
+          : html`<p class="empty">No projects registered.</p>`
+      }
+    </div>
+    <div class="project-editor">
+      ${
+        !project
+          ? html`<div class="project-placeholder"><span class="eyebrow">Configuration</span><h2>Select a project</h2><p>Inspect its registry entry and edit its ChangeLedger configuration.</p></div>`
+          : html`<div class="project-editor-head">
+              <div><span class="eyebrow">${project.id}</span><h2>${project.name}</h2><p>${project.path}</p></div>
+              <span class=${`project-health ${project.alive ? 'available' : 'missing'}`}>${project.alive ? 'Available' : 'Missing'}</span>
+            </div>
+            ${
+              !localOnly
+                ? html`<form class="project-path-form">
+                  <label for="project-path">Registered path</label>
+                  <div><input id="project-path" name="path" .value=${project.path} /><button class="button secondary" type="submit">Repair path</button></div>
+                </form>`
+                : nothing
+            }
+            ${
+              project.alive
+                ? config?.loading
+                  ? html`<p class="empty">Loading configuration…</p>`
+                  : html`<form class="config-form">
+                    <div class="config-label"><label for="project-config">.changeledger/config.yml</label><button type="button" class="text-button" data-reload-config>Reload</button></div>
+                    <textarea id="project-config" spellcheck="false" .value=${config?.content ?? ''}></textarea>
+                    <p class="project-error" ?hidden=${!config?.error}>${config?.error ?? ''}</p>
+                    <div class="project-actions"><button class="button" type="submit">Save configuration</button></div>
+                  </form>`
+                : html`<div class="missing-config"><h3>Configuration unavailable</h3><p>Repair the registered path to edit this project.</p></div>`
+            }
+            ${
+              !localOnly
+                ? html`<div class="danger-zone"><div><strong>Unregister project</strong><p>Removes this local registry entry. Repository files are never deleted.</p></div><button type="button" class="button danger" data-unregister>Unregister</button></div>`
+                : nothing
+            }`
+      }
+    </div>
+  </div>`;
+}
+
+async function openManagedProject(id, { reload = false } = {}) {
+  managedProject = id;
+  const project = state.projectsList.find((item) => item.id === id);
+  if (!project?.alive) {
+    managedConfig = null;
+    renderProjects();
+    return;
+  }
+  if (!reload && managedConfig?.id === id && !managedConfig.error) {
+    renderProjects();
+    return;
+  }
+  managedConfig = { id, loading: true };
+  renderProjects();
+  try {
+    managedConfig = { id, ...(await getProjectConfig(id)) };
+  } catch (error) {
+    managedConfig = { id, content: '', revision: '', error: error.message };
+  }
+  renderProjects();
+}
+
+export function setProjectFormPending(root, pending) {
+  root.querySelectorAll('button, input, textarea').forEach((control) => {
+    control.disabled = pending;
+  });
+  root.classList.toggle('is-pending', pending);
+}
+
+export async function projectMutation(root, request, onSuccess) {
+  setProjectFormPending(root, true);
+  const error = root.querySelector('.project-error');
+  if (error) error.hidden = true;
+  try {
+    const response = await request();
+    const body = await response.json();
+    if (!response.ok) throw new Error(body.error || 'Project update failed.');
+    await onSuccess(body);
+  } catch (failure) {
+    if (error) {
+      error.textContent = failure.message;
+      error.hidden = false;
+    } else alert(failure.message);
+  } finally {
+    setProjectFormPending(root, false);
+  }
+}
+
+export function requestUnregisterConfirmation(project, ask = prompt) {
+  return ask(
+    `Type "${project.name}" to unregister this project. No repository files will be deleted.`,
+  );
+}
+
+async function refreshProjectRegistry() {
+  const { projects, current, localOnly } = await getProjects();
+  state.localOnly = localOnly;
+  initializeProjects(projects, current);
+  const select = $('#project');
+  litRender(
+    projects.map(
+      (item) =>
+        html`<option value=${item.id} ?disabled=${!item.alive}>${item.name}${item.alive ? '' : ' (missing)'}</option>`,
+    ),
+    select,
+  );
+  if (state.currentProject) select.value = state.currentProject;
+  select.style.display = projects.length > 1 ? '' : 'none';
+}
+
+function renderProjects() {
+  const root = $('#projects');
+  litRender(
+    projectsViewTemplate(state.projectsList, managedProject, managedConfig, state.localOnly),
+    root,
+  );
+  bindProjectViewActions(root, {
+    select: (id) => openManagedProject(id),
+    reload: () => openManagedProject(managedProject, { reload: true }),
+    save: (content, configForm) =>
+      projectMutation(
+        configForm,
+        () => postProjectConfig(managedProject, content, managedConfig.revision),
+        async (body) => {
+          managedConfig = { id: managedProject, content, revision: body.revision };
+          await refreshProjectRegistry();
+          renderProjects();
+        },
+      ),
+    repair: (projectPath, pathForm) =>
+      projectMutation(
+        pathForm,
+        () => postProjectPath(managedProject, projectPath),
+        async () => {
+          await refreshProjectRegistry();
+          await openManagedProject(managedProject, { reload: true });
+        },
+      ),
+    unregister: (editor) => {
+      const project = state.projectsList.find((item) => item.id === managedProject);
+      const confirm = requestUnregisterConfirmation(project);
+      if (confirm === null) return;
+      projectMutation(
+        editor,
+        () => postProjectRemove(managedProject, confirm),
+        async () => {
+          managedProject = null;
+          managedConfig = null;
+          await refreshProjectRegistry();
+          if (state.currentProject) await load();
+          renderProjects();
+        },
+      );
+    },
+  });
+}
+
+export function bindProjectViewActions(root, handlers) {
+  root.querySelectorAll('[data-manage-project]').forEach((button) => {
+    button.onclick = () => handlers.select(button.dataset.manageProject);
+  });
+  const reload = root.querySelector('[data-reload-config]');
+  if (reload) reload.onclick = () => handlers.reload();
+  const configForm = root.querySelector('.config-form');
+  if (configForm)
+    configForm.onsubmit = (event) => {
+      event.preventDefault();
+      handlers.save(configForm.querySelector('textarea').value, configForm);
+    };
+  const pathForm = root.querySelector('.project-path-form');
+  if (pathForm)
+    pathForm.onsubmit = (event) => {
+      event.preventDefault();
+      handlers.repair(pathForm.elements.path.value, pathForm);
+    };
+  const unregister = root.querySelector('[data-unregister]');
+  if (unregister)
+    unregister.onclick = () => handlers.unregister(root.querySelector('.project-editor'));
+}
+
 function activateView(v) {
   setView(v);
   $('#toggle-global').classList.remove('active');
@@ -660,6 +916,7 @@ const fmtDate = (iso) => {
 // Wire the DOM and start polling. Guarded below so importing this module (tests)
 // has no side effects; only a real browser page bootstraps.
 function bootstrap() {
+  restoreInitialViewerShell();
   diagramLightbox = createDiagramLightbox({
     overlay: $('#diagram-overlay'),
     canvas: $('#diagram-canvas'),
@@ -692,6 +949,7 @@ function bootstrap() {
   $('#view-graph').onclick = () => activateView('graph');
   $('#view-specs').onclick = () => activateView('specs');
   $('#view-metrics').onclick = () => activateView('metrics');
+  $('#view-projects').onclick = () => activateView('projects');
   $('#project').onchange = (e) => {
     selectProject(e.target.value);
     load();

package/src/viewer/public/index.html

@@ -36,6 +36,7 @@
         <button type="button" id="view-graph" class="tab">Graph</button>
         <button type="button" id="view-specs" class="tab">Specs</button>
         <button type="button" id="view-metrics" class="tab">Metrics</button>
+        <button type="button" id="view-projects" class="tab">Projects</button>
       </div>
     </header>
 
@@ -45,6 +46,7 @@
     <section id="specs" class="specs-view hidden"></section>
     <section id="global" class="global-view hidden"></section>
     <section id="metrics" class="metrics-view hidden"></section>
+    <section id="projects" class="projects-view hidden"></section>
 
     <div id="overlay" class="overlay hidden">
       <div id="detail" class="detail"></div>

package/src/viewer/public/styles.css

@@ -90,6 +90,208 @@ body {
   gap: 4px;
 }
 
+/* Project management */
+.projects-view {
+  padding: 18px;
+}
+.projects-shell {
+  display: grid;
+  grid-template-columns: minmax(320px, 0.8fr) minmax(460px, 1.2fr);
+  gap: 16px;
+  max-width: 1500px;
+  margin: 0 auto;
+}
+.projects-list,
+.project-editor {
+  min-width: 0;
+  border: 1px solid var(--line);
+  border-radius: 14px;
+  background: var(--panel);
+}
+.projects-heading,
+.project-editor-head,
+.danger-zone {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+.projects-heading,
+.project-editor-head {
+  padding: 18px 20px;
+  border-bottom: 1px solid var(--line);
+}
+.projects-heading h1,
+.project-editor-head h2,
+.project-placeholder h2 {
+  margin: 2px 0 0;
+}
+.project-editor-head p,
+.project-placeholder p,
+.danger-zone p,
+.missing-config p {
+  margin: 4px 0 0;
+  color: var(--muted);
+}
+.eyebrow {
+  color: var(--accent);
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+.project-rows {
+  padding: 8px;
+}
+.project-row {
+  width: 100%;
+  display: grid;
+  grid-template-columns: 10px minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: 10px;
+  padding: 11px 12px;
+  border: 1px solid transparent;
+  border-radius: 9px;
+  background: transparent;
+  color: var(--text);
+  text-align: left;
+  cursor: pointer;
+}
+.project-row:hover,
+.project-row.active {
+  border-color: var(--line);
+  background: var(--panel-2);
+}
+.health-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--muted);
+}
+.health-dot.available {
+  background: var(--done);
+}
+.health-dot.missing {
+  background: var(--blocked);
+}
+.project-summary {
+  min-width: 0;
+  display: grid;
+}
+.project-summary small {
+  overflow: hidden;
+  color: var(--muted);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.project-health {
+  padding: 3px 8px;
+  border-radius: 999px;
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+.project-health.available {
+  color: var(--done);
+  background: rgba(63, 185, 80, 0.1);
+}
+.project-health.missing {
+  color: var(--blocked);
+  background: rgba(248, 81, 73, 0.1);
+}
+.project-placeholder,
+.missing-config {
+  padding: 28px 20px;
+}
+.project-path-form,
+.config-form {
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--line);
+}
+.project-path-form label,
+.config-label label {
+  color: var(--muted);
+  font-size: 11px;
+  font-weight: 600;
+}
+.project-path-form > div {
+  display: flex;
+  gap: 8px;
+  margin-top: 7px;
+}
+.project-path-form input {
+  flex: 1;
+  min-width: 0;
+  padding: 8px 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--bg);
+  color: var(--text);
+}
+.config-label {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 7px;
+}
+.config-form textarea {
+  width: 100%;
+  min-height: 430px;
+  resize: vertical;
+  padding: 14px;
+  border: 1px solid var(--line);
+  border-radius: 9px;
+  background: #0b0d11;
+  color: #d9e1ea;
+  font:
+    12px / 1.55 ui-monospace,
+    monospace;
+  tab-size: 2;
+}
+.project-actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: 10px;
+}
+.project-error {
+  margin: 8px 0 0;
+  color: #ff8078;
+  font-size: 12px;
+}
+.text-button {
+  border: 0;
+  background: transparent;
+  color: var(--accent);
+  cursor: pointer;
+}
+.danger-zone {
+  margin: 20px;
+  padding: 14px;
+  border: 1px solid rgba(248, 81, 73, 0.35);
+  border-radius: 10px;
+}
+.danger-zone p {
+  font-size: 12px;
+}
+.button.danger {
+  border-color: var(--bug);
+  color: #ff8078;
+}
+.is-pending {
+  opacity: 0.65;
+  cursor: wait;
+}
+@media (max-width: 900px) {
+  .projects-shell {
+    grid-template-columns: 1fr;
+  }
+  .project-row {
+    grid-template-columns: 10px minmax(0, 1fr) auto;
+  }
+  .project-id {
+    display: none;
+  }
+}
+
 .chip {
   font-size: 12px;
   padding: 5px 10px;

package/src/viewer/server/router.mjs

@@ -4,7 +4,16 @@ import path from 'node:path';
 import { gitRefs } from '../../git.mjs';
 import { publicDir } from '../../paths.mjs';
 import { loadRepoAsync } from '../../repo.mjs';
-import { changeStatus, resolveProjects, searchProjects, serialize } from '../domain.mjs';
+import {
+  changeStatus,
+  readProjectConfig,
+  repairProjectPath,
+  resolveProjects,
+  saveProjectConfig,
+  searchProjects,
+  serialize,
+  unregisterProject,
+} from '../domain.mjs';
 import { isAuthorizedWrite, isLocalHost } from './security.mjs';
 
 const require = createRequire(import.meta.url);
@@ -78,7 +87,12 @@ export function createRequestListener(cwd, localOnly, token) {
       const route = url.pathname;
       const params = url.searchParams;
 
-      if (req.method === 'POST' && route === '/api/status') {
+      if (
+        req.method === 'POST' &&
+        ['/api/status', '/api/project-config', '/api/project-path', '/api/project-remove'].includes(
+          route,
+        )
+      ) {
         if (!isAuthorizedWrite(req, token)) {
           send(res, 403, MIME['.json'], JSON.stringify({ error: 'unauthorized write' }));
           req.destroy();
@@ -97,22 +111,47 @@ export function createRequestListener(cwd, localOnly, token) {
         });
         req.on('end', () => {
           if (aborted) return;
-          let payload;
           try {
-            payload = JSON.parse(raw || '{}');
-          } catch {
-            send(res, 400, MIME['.json'], JSON.stringify({ error: 'invalid JSON body' }));
-            return;
+            let payload;
+            try {
+              payload = JSON.parse(raw || '{}');
+            } catch {
+              send(res, 400, MIME['.json'], JSON.stringify({ error: 'invalid JSON body' }));
+              return;
+            }
+            const { projects } = resolveProjects(cwd, localOnly);
+            const options = { localOnly };
+            const result =
+              route === '/api/status'
+                ? changeStatus(projects, payload)
+                : route === '/api/project-config'
+                  ? saveProjectConfig(projects, payload, options)
+                  : route === '/api/project-path'
+                    ? repairProjectPath(projects, payload, options)
+                    : unregisterProject(projects, payload, options);
+            const { code, body } = result;
+            send(res, code, MIME['.json'], JSON.stringify(body));
+          } catch (error) {
+            process.stderr.write(`[changeledger-viewer] ${error.message}\n`);
+            send(res, 500, MIME['.json'], JSON.stringify({ error: 'Internal server error' }));
           }
-          const { projects } = resolveProjects(cwd, localOnly);
-          const { code, body } = changeStatus(projects, payload);
-          send(res, code, MIME['.json'], JSON.stringify(body));
         });
         return;
       }
 
       if (route === '/api/projects') {
-        send(res, 200, MIME['.json'], JSON.stringify(resolveProjects(cwd, localOnly)));
+        send(
+          res,
+          200,
+          MIME['.json'],
+          JSON.stringify({ ...resolveProjects(cwd, localOnly), localOnly }),
+        );
+        return;
+      }
+      if (route === '/api/project-config') {
+        const { projects } = resolveProjects(cwd, localOnly);
+        const { code, body } = readProjectConfig(projects, params.get('project'));
+        send(res, code, MIME['.json'], JSON.stringify(body));
         return;
       }
       if (route === '/api/git') {