@work-graph/cli 0.2.0

package/vendor/src/workItemTraceEnvelope.mjs

@@ -0,0 +1,158 @@
+const CODE_FILE_PATTERN = /\.(?:js|mjs|cjs|ts|tsx|jsx|step|json|yaml|yml|os)$/iu;
+const TRACE_REF_LABELS = ['trace.code_refs', 'trace.artifact_refs', 'trace.evidence_refs', 'trace.links'];
+const DONE_TRACE_STATUSES = new Set(['linked', 'verified']);
+const VERIFY_TRACE_STATUSES = new Set(['linked', 'verified', 'pending', 'needs_review']);
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+function parseList(value) {
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return [];
+  }
+
+  return String(value)
+    .split(/\s*,\s*/u)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function isCodeFacingWorkItem(item) {
+  if (item === undefined || item === null) {
+    throw new TypeError('item is required');
+  }
+
+  const sourceStep = item.labels?.['trace.source_step'] ?? item.labels?.['work.source_step'] ?? '';
+  if (String(sourceStep).trim() !== '') {
+    return true;
+  }
+
+  if (TRACE_REF_LABELS.some((labelKey) => parseList(item.labels?.[labelKey]).length > 0)) {
+    return true;
+  }
+
+  return (item.targetFiles ?? []).some((path) => CODE_FILE_PATTERN.test(String(path)));
+}
+
+export function buildWorkItemTraceEnvelope(item) {
+  if (item === undefined || item === null) {
+    throw new TypeError('item is required');
+  }
+
+  const traceRefs = Object.fromEntries(
+    TRACE_REF_LABELS.map((labelKey) => [labelKey, parseList(item.labels?.[labelKey]).sort(compareText)]),
+  );
+  const sourceStep = String(item.labels?.['trace.source_step'] ?? item.labels?.['work.source_step'] ?? '').trim();
+
+  return {
+    schema: 'workitem.trace-envelope.v1',
+    workId: item.id,
+    codeFacing: isCodeFacingWorkItem(item),
+    sourceStep,
+    targetFiles: [...(item.targetFiles ?? [])].sort(compareText),
+    traceRefs,
+    traceStatus: String(item.traceStatus ?? item.labels?.['trace.status'] ?? 'pending').trim() || 'pending',
+    evidence: [...(item.evidence ?? [])].sort(compareText),
+    intentPath: String(item.labels?.['intent.path'] ?? '').trim(),
+  };
+}
+
+export function evaluateTraceVerifyGate(item, options = {}) {
+  const envelope = buildWorkItemTraceEnvelope(item);
+  const targetStatus = options.targetStatus ?? item.status;
+  const diagnostics = [];
+
+  if (!envelope.codeFacing) {
+    return { ok: true, envelope, diagnostics };
+  }
+
+  const hasTraceRefs = TRACE_REF_LABELS.some((labelKey) => envelope.traceRefs[labelKey].length > 0);
+  const hasSourceStep = envelope.sourceStep !== '';
+
+  if (!hasTraceRefs && !hasSourceStep) {
+    const onlyTargetFiles = envelope.targetFiles.length > 0 && targetStatus === 'done';
+    if (!onlyTargetFiles) {
+      diagnostics.push({
+        severity: envelope.targetFiles.length > 0 ? 'warning' : 'error',
+        code: 'trace.envelope.missing_refs',
+        message: `WorkItem ${envelope.workId} is code-facing but has no trace refs or source step.`,
+        actionable: 'Add trace.code_refs, trace.artifact_refs or trace.source_step.',
+      });
+    }
+  }
+
+  if (envelope.traceStatus === 'missing' || envelope.traceStatus === 'orphaned') {
+    diagnostics.push({
+      severity: 'error',
+      code: 'trace.envelope.invalid_status',
+      message: `WorkItem ${envelope.workId} has trace.status=${envelope.traceStatus}.`,
+      actionable: 'Fix trace links or downgrade task scope before verify.',
+    });
+  }
+
+  if (targetStatus === 'verify' && envelope.traceStatus === 'missing') {
+    diagnostics.push({
+      severity: 'error',
+      code: 'trace.envelope.verify_blocked',
+      message: `WorkItem ${envelope.workId} cannot enter verify with trace.status=missing.`,
+      actionable: 'Author trace refs and set trace.status to pending or linked.',
+    });
+  }
+
+  if (targetStatus === 'done') {
+    if (envelope.evidence.length === 0) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'trace.envelope.done_without_evidence',
+        message: `WorkItem ${envelope.workId} cannot be done without evidence.`,
+        actionable: 'Add Свидетельства section entries.',
+      });
+    }
+
+    if (!DONE_TRACE_STATUSES.has(envelope.traceStatus) && hasTraceRefs) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'trace.envelope.done_without_verified_trace',
+        message: `WorkItem ${envelope.workId} has trace refs but trace.status=${envelope.traceStatus}.`,
+        actionable: 'Set trace.status to linked or verified after validator pass.',
+      });
+    }
+
+    if (envelope.targetFiles.length > 0 && !hasTraceRefs) {
+      diagnostics.push({
+        severity: 'warning',
+        code: 'trace.weak_target_files_only',
+        message: `WorkItem ${envelope.workId} has target_files but no Trace Links v1 labels.`,
+        actionable: `Add trace.code_refs or trace.artifact_refs for ${envelope.targetFiles[0]}.`,
+      });
+    }
+  }
+
+  if (targetStatus === 'verify' && hasTraceRefs && !VERIFY_TRACE_STATUSES.has(envelope.traceStatus)) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'trace.envelope.verify_status',
+      message: `WorkItem ${envelope.workId} cannot enter verify with trace.status=${envelope.traceStatus}.`,
+      actionable: 'Set trace.status to pending, linked or needs_review.',
+    });
+  }
+
+  const ok = diagnostics.every((diagnostic) => diagnostic.severity !== 'error');
+  return { ok, envelope, diagnostics: diagnostics.sort((left, right) => compareText(`${left.severity}\0${left.code}`, `${right.severity}\0${right.code}`)) };
+}
+
+export function buildTraceEnvelopeSnapshot(items) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const envelopes = items
+    .map((item) => buildWorkItemTraceEnvelope(item))
+    .filter((envelope) => envelope.codeFacing)
+    .sort((left, right) => compareText(left.workId, right.workId));
+
+  return {
+    schema: 'workitem.trace-envelope.snapshot.v1',
+    count: envelopes.length,
+    envelopes,
+  };
+}

package/vendor/src/workItemUiReferences.mjs

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import {
+  applyAtomInspectorProposalToBacklogFile,
+  importStepAtomDraftForWorkItem,
+} from './atomInspector.mjs';
+import { readWorkItemAtomFromRepo, readWorkItemsFromRepo } from './intentTreeWorkItems.mjs';
+export const UI_REFERENCES_MANIFEST_SCHEMA = 'workitem.ui-references.v1';
+export const DEFAULT_UI_REFERENCES_DIR = 'work/ui-references';
+export const UI_REFERENCE_MAX_BYTES = 5 * 1024 * 1024;
+export const UI_REFERENCE_ALLOWED_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+export function isUiFacingWorkItem(item) {
+  if (!item) {
+    return false;
+  }
+
+  if (String(item.labels?.['work.ui_task'] ?? '').trim().toLowerCase() === 'true') {
+    return true;
+  }
+
+  const haystack = [
+    item.title,
+    item.basis,
+    item.vector,
+    item.goal,
+    item.department,
+    item.ownerRole,
+    ...(item.targetFiles ?? []),
+  ].join('\n');
+
+  if (/dashboard|operator|интерфейс|экран|макет|wireframe|figma|скрин|ui panel|ui task|ui-dashboard|backlog ui|ui server|ui-refs|ui refs/iu.test(haystack)) {
+    return true;
+  }
+
+  if (String(item.department ?? '').toLowerCase().includes('ui')) {
+    return true;
+  }
+
+  return (item.targetFiles ?? []).some((path) =>
+    /BacklogUi|dashboard|\.css|\.html|operator|panel|view/i.test(path),
+  );
+}
+
+export function resolveUiReferencesDir(cwd, workId, rootDir = DEFAULT_UI_REFERENCES_DIR) {
+  const normalizedWorkId = String(workId ?? '').trim();
+  if (normalizedWorkId === '' || normalizedWorkId.includes('..') || normalizedWorkId.includes('/')) {
+    throw new Error('invalid workId for ui references');
+  }
+
+  return resolve(cwd, rootDir, normalizedWorkId);
+}
+
+export function manifestPathForWorkItem(cwd, workId, rootDir = DEFAULT_UI_REFERENCES_DIR) {
+  return join(resolveUiReferencesDir(cwd, workId, rootDir), 'manifest.v1.json');
+}
+
+export function emptyUiReferencesManifest(workId) {
+  return {
+    schema: UI_REFERENCES_MANIFEST_SCHEMA,
+    workId,
+    items: [],
+  };
+}
+
+export async function readUiReferencesManifest(cwd, workId, rootDir = DEFAULT_UI_REFERENCES_DIR) {
+  const path = manifestPathForWorkItem(cwd, workId, rootDir);
+
+  try {
+    const raw = await readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed?.schema !== UI_REFERENCES_MANIFEST_SCHEMA || !Array.isArray(parsed.items)) {
+      return emptyUiReferencesManifest(workId);
+    }
+
+    return {
+      ...parsed,
+      workId,
+      items: parsed.items.sort((left, right) => compareText(left.file ?? '', right.file ?? '')),
+    };
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return emptyUiReferencesManifest(workId);
+    }
+
+    throw error;
+  }
+}
+
+async function writeUiReferencesManifest(cwd, workId, manifest, rootDir = DEFAULT_UI_REFERENCES_DIR) {
+  const path = manifestPathForWorkItem(cwd, workId, rootDir);
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  await rename(tempPath, path);
+  return path;
+}
+
+export function validateUiReferenceUpload({ filename, buffer }) {
+  const name = String(filename ?? '').trim();
+  if (name === '' || name.includes('..') || name.includes('/') || name.includes('\\')) {
+    return { ok: false, error: 'invalid_filename' };
+  }
+
+  const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+  if (!UI_REFERENCE_ALLOWED_EXT.has(ext)) {
+    return { ok: false, error: 'unsupported_image_type' };
+  }
+
+  const bytes = buffer instanceof Buffer ? buffer : Buffer.from(buffer ?? []);
+  if (bytes.length === 0) {
+    return { ok: false, error: 'empty_file' };
+  }
+
+  if (bytes.length > UI_REFERENCE_MAX_BYTES) {
+    return { ok: false, error: 'file_too_large' };
+  }
+
+  return { ok: true, filename: name, buffer: bytes, ext };
+}
+
+function stableReferenceFileName(originalName, buffer) {
+  const ext = originalName.slice(originalName.lastIndexOf('.')).toLowerCase();
+  const hash = createHash('sha256').update(buffer).digest('hex').slice(0, 12);
+  const stem = originalName.slice(0, originalName.lastIndexOf('.')).replace(/[^a-zA-Z0-9._-]+/gu, '-').slice(0, 40);
+  return `${stem || 'ref'}-${hash}${ext}`;
+}
+
+export async function syncUiRefsLabelOnWorkItemAtom(workId, manifest, options = {}) {
+  const paths = manifest.items.map((entry) =>
+    join(DEFAULT_UI_REFERENCES_DIR, workId, entry.file).replace(/\\/g, '/'),
+  );
+
+  const sourceAtom = await readWorkItemAtomFromRepo(workId, options);
+  const source = importStepAtomDraftForWorkItem(sourceAtom.atomText, workId);
+  const draft = {
+    ...source.draft,
+    labels: {
+      ...(source.draft.labels ?? {}),
+      'work.ui_refs': paths.join(', '),
+      'work.ui_refs.count': String(paths.length),
+    },
+  };
+
+  if (paths.length > 0) {
+    draft.uiRefs = manifest.items.map((entry) =>
+      `${entry.file}${entry.caption ? ` | ${entry.caption}` : ''}`,
+    );
+  }
+
+  return applyAtomInspectorProposalToBacklogFile({
+    ...options,
+    workId,
+    draft,
+  });
+}
+
+export async function attachUiReference(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const workId = String(options.workId ?? '').trim();
+  if (workId === '') {
+    return { ok: false, error: 'work_id_required' };
+  }
+
+  const items = await readWorkItemsFromRepo({ ...options, cwd });
+  const item = items.find((entry) => entry.id === workId);
+  if (!item) {
+    return { ok: false, error: 'work_item_not_found', workId };
+  }
+
+  if (!isUiFacingWorkItem(item) && options.force !== true) {
+    return { ok: false, error: 'not_ui_facing_task', workId, hint: 'Set work.ui_task: true to allow refs on non-UI tasks' };
+  }
+
+  let buffer = options.buffer;
+  if (options.contentBase64 !== undefined) {
+    buffer = Buffer.from(String(options.contentBase64), 'base64');
+  }
+
+  const validated = validateUiReferenceUpload({ filename: options.filename, buffer });
+  if (!validated.ok) {
+    return { ok: false, error: validated.error, workId };
+  }
+
+  const storedName = stableReferenceFileName(validated.filename, validated.buffer);
+  const dir = resolveUiReferencesDir(cwd, workId, options.rootDir);
+  await mkdir(dir, { recursive: true });
+  const filePath = join(dir, storedName);
+  await writeFile(filePath, validated.buffer);
+
+  const manifest = await readUiReferencesManifest(cwd, workId, options.rootDir);
+  const entry = {
+    file: storedName,
+    caption: String(options.caption ?? '').trim(),
+    uploadedAt: options.uploadedAt ?? new Date().toISOString(),
+    originalName: validated.filename,
+    bytes: validated.buffer.length,
+    mime: mimeForExt(validated.ext),
+  };
+
+  manifest.items = [...manifest.items.filter((candidate) => candidate.file !== storedName), entry]
+    .sort((left, right) => compareText(left.file, right.file));
+
+  await writeUiReferencesManifest(cwd, workId, manifest, options.rootDir);
+  const labelSync = await syncUiRefsLabelOnWorkItemAtom(workId, manifest, { ...options, cwd });
+
+  return {
+    ok: true,
+    workId,
+    entry,
+    relativePath: join(DEFAULT_UI_REFERENCES_DIR, workId, storedName).replace(/\\/g, '/'),
+    manifest,
+    labelSyncOk: labelSync.ok === true,
+  };
+}
+
+export async function listUiReferences(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const workId = String(options.workId ?? '').trim();
+  if (workId === '') {
+    return { ok: false, error: 'work_id_required' };
+  }
+
+  const items = await readWorkItemsFromRepo({ ...options, cwd });
+  const item = items.find((entry) => entry.id === workId) ?? null;
+  const manifest = await readUiReferencesManifest(cwd, workId, options.rootDir);
+
+  return {
+    ok: true,
+    schema: UI_REFERENCES_MANIFEST_SCHEMA,
+    workId,
+    uiFacing: item ? isUiFacingWorkItem(item) : false,
+    items: manifest.items.map((entry) => ({
+      ...entry,
+      url: `/api/work-item/ui-refs/file?workId=${encodeURIComponent(workId)}&file=${encodeURIComponent(entry.file)}`,
+    })),
+  };
+}
+
+export function resolveUiReferenceFilePath(cwd, workId, fileName, rootDir = DEFAULT_UI_REFERENCES_DIR) {
+  const normalizedFile = String(fileName ?? '').trim();
+  if (normalizedFile === '' || normalizedFile.includes('..') || normalizedFile.includes('/') || normalizedFile.includes('\\')) {
+    throw new Error('invalid ui reference file name');
+  }
+
+  return join(resolveUiReferencesDir(cwd, workId, rootDir), normalizedFile);
+}
+
+function mimeForExt(ext) {
+  switch (ext) {
+    case '.png':
+      return 'image/png';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.webp':
+      return 'image/webp';
+    case '.gif':
+      return 'image/gif';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+export function mimeTypeForUiReferenceFileName(fileName) {
+  const ext = String(fileName ?? '').slice(String(fileName).lastIndexOf('.')).toLowerCase();
+  return mimeForExt(ext);
+}

package/vendor/src/workflowEpicGrouping.mjs

@@ -0,0 +1,67 @@
+const workflowEpicCompareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+const WORKFLOW_EPIC_DONE_STATUSES = new Set(['done', 'verified']);
+
+/**
+ * @param {Array<{ id: string, title?: string, status?: string, parentId?: string, itemKind?: string }>} items
+ */
+export function buildWorkflowEpicGroups(items) {
+  if (!Array.isArray(items)) {
+    return { epicGroups: [], orphans: [] };
+  }
+
+  const epics = items
+    .filter((item) => item.itemKind === 'epic')
+    .sort((left, right) => workflowEpicCompareText(left.title ?? left.id, right.title ?? right.id));
+  const epicIds = new Set(epics.map((epic) => epic.id));
+  /** @type {Map<string, Array<object>>} */
+  const childrenByEpicId = new Map();
+  /** @type {Set<string>} */
+  const assignedChildIds = new Set();
+
+  for (const item of items) {
+    if (item.itemKind === 'epic') {
+      continue;
+    }
+    const parentId = String(item.parentId ?? '').trim();
+    if (parentId === '' || !epicIds.has(parentId)) {
+      continue;
+    }
+    if (!childrenByEpicId.has(parentId)) {
+      childrenByEpicId.set(parentId, []);
+    }
+    childrenByEpicId.get(parentId).push(item);
+    assignedChildIds.add(item.id);
+  }
+
+  for (const children of childrenByEpicId.values()) {
+    children.sort((left, right) => workflowEpicCompareText(left.title ?? left.id, right.title ?? right.id));
+  }
+
+  const epicGroups = epics.map((epic) => {
+    const children = childrenByEpicId.get(epic.id) ?? [];
+    const doneChildCount = children.filter((child) => WORKFLOW_EPIC_DONE_STATUSES.has(String(child.status ?? ''))).length;
+    return {
+      epic,
+      children,
+      childCount: children.length,
+      doneChildCount,
+    };
+  });
+
+  const orphans = items
+    .filter((item) => item.itemKind !== 'epic' && !assignedChildIds.has(item.id))
+    .sort((left, right) => workflowEpicCompareText(left.title ?? left.id, right.title ?? right.id));
+
+  return { epicGroups, orphans };
+}
+
+/**
+ * @param {Array<object>} items
+ */
+export function buildWorkflowDisplayUnits(items) {
+  const { epicGroups, orphans } = buildWorkflowEpicGroups(items);
+  return [
+    ...epicGroups.map((group) => ({ type: 'epic', group })),
+    ...orphans.map((item) => ({ type: 'orphan', item })),
+  ];
+}

package/vendor/src/workflowTreeProjection.mjs

@@ -0,0 +1,53 @@
+const workflowTreeCompareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+/**
+ * @param {Array<{ id: string, title?: string, parentId?: string, itemKind?: string }>} items
+ */
+export function buildWorkflowTreeForest(items) {
+  if (!Array.isArray(items)) {
+    return [];
+  }
+
+  const visibleIds = new Set(items.map((item) => item.id));
+  /** @type {Map<string, Array<object>>} */
+  const childrenByParentId = new Map();
+
+  for (const item of items) {
+    let parentId = String(item.parentId ?? '').trim();
+    if (parentId !== '' && !visibleIds.has(parentId)) {
+      parentId = '';
+    }
+    if (!childrenByParentId.has(parentId)) {
+      childrenByParentId.set(parentId, []);
+    }
+    childrenByParentId.get(parentId).push(item);
+  }
+
+  for (const children of childrenByParentId.values()) {
+    children.sort((left, right) => workflowTreeCompareText(left.title ?? left.id, right.title ?? right.id));
+  }
+
+  /**
+   * @param {object} item
+   * @param {number} depth
+   */
+  function buildNode(item, depth) {
+    const children = (childrenByParentId.get(item.id) ?? []).map((child) => buildNode(child, depth + 1));
+    return {
+      item,
+      depth,
+      childCount: children.length,
+      children,
+    };
+  }
+
+  const roots = childrenByParentId.get('') ?? [];
+  return roots.map((root) => buildNode(root, 0));
+}
+
+/**
+ * @param {Array<object>} forest
+ */
+export function buildWorkflowTreeDisplayUnits(forest) {
+  return forest.map((root) => ({ type: 'tree-root', root }));
+}

package/vendor/src/workspaceRegistry.mjs

@@ -0,0 +1,150 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, resolve } from 'node:path';
+
+export const WORKSPACES_SCHEMA = 'workspaces.v1';
+export const DEFAULT_REGISTRY_DIR = resolve(homedir(), '.work-graph');
+export const DEFAULT_REGISTRY_PATH = resolve(DEFAULT_REGISTRY_DIR, 'workspaces.json');
+
+function compareText(left, right) {
+  return String(left).localeCompare(String(right), 'ru', { sensitivity: 'variant' });
+}
+
+export function defaultRegistryPath(options = {}) {
+  return resolve(options.registryPath ?? DEFAULT_REGISTRY_PATH);
+}
+
+export function normalizeWorkspaceRoot(root) {
+  return resolve(String(root ?? '').trim());
+}
+
+export function slugFromRoot(root) {
+  const base = basename(normalizeWorkspaceRoot(root));
+  return base
+    .toLowerCase()
+    .replace(/[^a-z0-9а-яё]+/giu, '-')
+    .replace(/^-+|-+$/gu, '')
+    || 'project';
+}
+
+export function emptyRegistry() {
+  return {
+    schema: WORKSPACES_SCHEMA,
+    activeProjectId: null,
+    workspaces: [],
+  };
+}
+
+export function normalizeRegistry(raw) {
+  const registry = raw && typeof raw === 'object' ? raw : emptyRegistry();
+  const workspaces = Array.isArray(registry.workspaces)
+    ? registry.workspaces.map((entry) => ({
+      id: String(entry.id ?? '').trim(),
+      root: normalizeWorkspaceRoot(entry.root),
+      label: String(entry.label ?? entry.id ?? '').trim(),
+      lastOpenedAt: entry.lastOpenedAt ? String(entry.lastOpenedAt) : null,
+    })).filter((entry) => entry.id !== '' && entry.root !== '')
+    : [];
+
+  workspaces.sort((left, right) => compareText(left.label || left.id, right.label || right.id));
+
+  const activeProjectId = String(registry.activeProjectId ?? '').trim() || null;
+  const activeExists = activeProjectId && workspaces.some((entry) => entry.id === activeProjectId);
+
+  return {
+    schema: WORKSPACES_SCHEMA,
+    activeProjectId: activeExists ? activeProjectId : (workspaces[0]?.id ?? null),
+    workspaces,
+  };
+}
+
+export async function readWorkspaceRegistry(options = {}) {
+  const registryPath = defaultRegistryPath(options);
+
+  try {
+    const text = await readFile(registryPath, 'utf8');
+    return normalizeRegistry(JSON.parse(text));
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return emptyRegistry();
+    }
+    throw error;
+  }
+}
+
+export async function writeWorkspaceRegistry(registry, options = {}) {
+  const registryPath = defaultRegistryPath(options);
+  await mkdir(dirname(registryPath), { recursive: true });
+  const normalized = normalizeRegistry(registry);
+  const tempPath = `${registryPath}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+  await rename(tempPath, registryPath);
+  return normalized;
+}
+
+export function findWorkspace(registry, projectId) {
+  const id = String(projectId ?? '').trim();
+  return registry.workspaces.find((entry) => entry.id === id) ?? null;
+}
+
+export function resolveWorkspaceRoot(registry, projectId) {
+  const workspace = findWorkspace(registry, projectId);
+  return workspace?.root ?? null;
+}
+
+export async function registerWorkspace(input = {}, options = {}) {
+  const root = normalizeWorkspaceRoot(input.root ?? input.path ?? options.cwd);
+  const id = String(input.id ?? input.projectId ?? slugFromRoot(root)).trim();
+  const label = String(input.label ?? input.name ?? basename(root)).trim() || id;
+  const registry = await readWorkspaceRegistry(options);
+  const now = new Date().toISOString();
+  const existing = findWorkspace(registry, id);
+
+  const nextEntry = {
+    id,
+    root,
+    label,
+    lastOpenedAt: now,
+  };
+
+  const workspaces = existing
+    ? registry.workspaces.map((entry) => (entry.id === id ? { ...entry, ...nextEntry } : entry))
+    : [...registry.workspaces, nextEntry];
+
+  return writeWorkspaceRegistry({
+    ...registry,
+    workspaces,
+    activeProjectId: registry.activeProjectId ?? id,
+  }, options);
+}
+
+export async function setActiveWorkspace(projectId, options = {}) {
+  const id = String(projectId ?? '').trim();
+  if (id === '') {
+    throw new Error('projectId is required');
+  }
+
+  const registry = await readWorkspaceRegistry(options);
+  const workspace = findWorkspace(registry, id);
+  if (!workspace) {
+    throw new Error(`unknown projectId: ${id}`);
+  }
+
+  const now = new Date().toISOString();
+  return writeWorkspaceRegistry({
+    ...registry,
+    activeProjectId: id,
+    workspaces: registry.workspaces.map((entry) => (
+      entry.id === id ? { ...entry, lastOpenedAt: now } : entry
+    )),
+  }, options);
+}
+
+export async function listWorkspaces(options = {}) {
+  const registry = await readWorkspaceRegistry(options);
+  return {
+    schema: 'workgraph.workspaces.list.v1',
+    activeProjectId: registry.activeProjectId,
+    workspaces: registry.workspaces,
+  };
+}