@zyaiting/keelson 0.4.0

package/src/lib/paths.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { exists } from './fs.js';
+import { loadConfig } from './config.js';
+import { runtimeDir } from './runtime-path.js';
+
+export const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const KEELSON_DIR = '.keelson';
+export const USER_HOME = path.join(os.homedir(), '.keelson');
+
+/** A project root is a directory whose .keelson/ holds config.yaml or INTENT.md. The user-level ~/.keelson never counts. */
+export const isProjectRoot = (dir) => {
+  const k = path.join(dir, KEELSON_DIR);
+  if (path.resolve(k) === path.resolve(USER_HOME)) return false;
+  return exists(path.join(k, 'config.yaml')) || exists(path.join(k, 'INTENT.md'));
+};
+
+/** Walk up from cwd to find the project root containing .keelson/. */
+export function findProjectRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (isProjectRoot(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function requireProjectRoot(start) {
+  const root = findProjectRoot(start);
+  if (!root) throw new Error('no .keelson/ found here or in any parent directory. Run `keelson init` first.');
+  return root;
+}
+
+/** Resolve writable project data without following links out of the project. */
+export function resolveWithin(root, relative) {
+  if (typeof relative !== 'string' || !relative || path.isAbsolute(relative)) throw new Error('project data path must be relative');
+  const absolute = path.resolve(root, relative);
+  const rel = path.relative(root, absolute);
+  if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error(`project data path escapes its root: ${relative}`);
+  let current = root;
+  for (const part of rel.split(path.sep)) {
+    current = path.join(current, part);
+    // A single lstat also sees dangling links and tolerates an atomic-write
+    // temporary file disappearing between directory enumeration and this scan.
+    if (fs.lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink()) throw new Error(`project data path must not be a symlink: ${current}`);
+  }
+  return absolute;
+}
+
+/** Resolve every path Keelson uses. `paths.specs` in config.yaml may relocate the contracts. */
+export const projectPaths = (root, cfg = null) => {
+  const k = resolveWithin(root, KEELSON_DIR);
+  const config = path.join(k, 'config.yaml');
+  const c = cfg ?? (exists(config) ? loadConfig(config) : null);
+  const specsRel = c?.paths?.specs ?? '.keelson/specs';
+  return {
+    root,
+    keelson: k,
+    config,
+    readme: path.join(k, 'README.md'),
+    intent: path.join(k, 'INTENT.md'),
+    now: path.join(k, 'NOW.md'),
+    roadmap: path.join(k, 'ROADMAP.md'),
+    glossary: path.join(k, 'GLOSSARY.md'),
+    workflow: path.join(k, 'workflow.md'),
+    skill: path.join(k, 'skill'),
+    specs: resolveWithin(root, specsRel),
+    specsRel,
+    rules: resolveWithin(root, '.keelson/rules'),
+    rulesIndex: resolveWithin(root, '.keelson/rules/index.md'),
+    changes: resolveWithin(root, '.keelson/changes'),
+    archive: resolveWithin(root, '.keelson/changes/archive'),
+    hooks: resolveWithin(root, '.keelson/hooks'),
+    runtime: runtimeDir(root),
+    sessions: path.join(runtimeDir(root), 'sessions'),
+    evidence: path.join(runtimeDir(root), 'evidence'),
+    legacyLocal: path.join(k, '.local'),
+  };
+};

package/src/lib/rules.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { readOr, exists } from './fs.js';
+import { globMatch } from './glob.js';
+
+/** rules/index.md lines: "- `src/api/**` → api.md" (also accepts "->" and ":") */
+export function parseRulesIndex(text) {
+  const entries = [];
+  for (const line of text.split('\n')) {
+    const m = line.match(/^\s*[-*]\s+`([^`]+)`\s*(?:→|->|:)\s*`?([^`\s]+)`?\s*(?:[—-]\s*(.*))?$/);
+    if (m) entries.push({ glob: m[1].trim(), file: m[2].trim(), note: (m[3] ?? '').trim() });
+  }
+  return entries;
+}
+
+export function matchRules(rulesDir, paths) {
+  const index = parseRulesIndex(readOr(path.join(rulesDir, 'index.md')));
+  const hits = new Map();
+  for (const e of index) {
+    const always = e.glob === '**' || e.glob === '*';
+    const matched = always || paths.some((p) => globMatch(e.glob, p));
+    if (!matched) continue;
+    const f = path.join(rulesDir, e.file);
+    if (!hits.has(e.file)) hits.set(e.file, { file: e.file, globs: [], exists: exists(f), content: readOr(f) });
+    hits.get(e.file).globs.push(e.glob);
+  }
+  return [...hits.values()];
+}

package/src/lib/runtime-path.js

@@ -0,0 +1,22 @@
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+const resolved = new Map();
+
+/** Private state never requires changing the user's ignore rules. */
+export function runtimeDir(root) {
+  const key = path.resolve(root);
+  if (resolved.has(key)) return resolved.get(key);
+  let runtime;
+  try {
+    const gitPath = execFileSync('git', ['rev-parse', '--git-path', 'keelson-runtime'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    runtime = path.resolve(root, gitPath);
+  } catch {
+    const fallback = crypto.createHash('sha256').update(key).digest('hex');
+    runtime = path.join(os.homedir(), '.cache', 'keelson', fallback);
+  }
+  resolved.set(key, runtime);
+  return runtime;
+}

package/src/lib/session.js

@@ -0,0 +1,100 @@
+import crypto from 'node:crypto';
+import { exists, listFiles, readJson, rmrf, withLock, writeJson } from './fs.js';
+import path from 'node:path';
+import { runtimeDir } from './runtime-path.js';
+
+const SCHEMA = 1;
+
+export const sessionsDir = (root) => path.join(runtimeDir(root), 'sessions');
+
+export function resolveSessionIdentity(env = process.env) {
+  const sources = [
+    ['KEELSON_SESSION_ID', env.KEELSON_SESSION_ID],
+    ['CODEX_THREAD_ID', env.CODEX_THREAD_ID],
+    // Pi exposes the current session to every shell tool invocation.
+    ['PI_SESSION_ID', env.PI_SESSION_ID],
+  ];
+  for (const [source, value] of sources) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    if (!raw) continue;
+    const opaque = source === 'KEELSON_SESSION_ID'
+      ? raw
+      : crypto.createHash('sha256').update(`${source.toLowerCase()}:${raw}`).digest('hex').slice(0, 32);
+    const key = crypto.createHash('sha256').update(opaque).digest('hex').slice(0, 24);
+    return { key, source };
+  }
+  return null;
+}
+
+export function sessionFile(root, key) {
+  return path.join(sessionsDir(root), `${key}.json`);
+}
+
+export function readSession(root, env = process.env) {
+  const id = resolveSessionIdentity(env);
+  if (!id) return { available: false, key: null, source: null, state: null };
+  const state = readJson(sessionFile(root, id.key), null);
+  return { available: true, key: id.key, source: id.source, state };
+}
+
+export function writeSession(root, patch, env = process.env) {
+  const id = resolveSessionIdentity(env);
+  if (!id) return null;
+  const file = sessionFile(root, id.key);
+  const next = withLock(file, () => {
+    const prev = readJson(file, {}) ?? {};
+    const state = {
+      schema: SCHEMA,
+      change: null,
+      createdAt: prev.createdAt ?? new Date().toISOString(),
+      ...prev,
+      ...patch,
+      updatedAt: new Date().toISOString(),
+    };
+    writeJson(file, state);
+    return state;
+  });
+  return { key: id.key, file, state: next };
+}
+
+export function bindSession(root, change, { branch = null, source = 'cli', env = process.env } = {}) {
+  return writeSession(root, { change, branch, source }, env);
+}
+
+export function touchSession(root, { env = process.env, source = 'cli' } = {}) {
+  return writeSession(root, { source }, env);
+}
+
+export function clearSession(root, env = process.env) {
+  const id = resolveSessionIdentity(env);
+  if (!id) return false;
+  const file = sessionFile(root, id.key);
+  if (!exists(file)) return false;
+  rmrf(file);
+  return true;
+}
+
+export function clearChangeBindings(root, change) {
+  const dir = sessionsDir(root);
+  let removed = 0;
+  for (const file of listFiles(dir)) {
+    if (!file.endsWith('.json')) continue;
+    const full = path.join(dir, file);
+    const state = readJson(full, null);
+    if (state?.change !== change) continue;
+    rmrf(full);
+    removed += 1;
+  }
+  return removed;
+}
+
+export function listSessionStates(root) {
+  const dir = sessionsDir(root);
+  const out = [];
+  for (const file of listFiles(dir)) {
+    if (!file.endsWith('.json')) continue;
+    const state = readJson(path.join(dir, file), null);
+    if (state) out.push({ key: file.replace(/\.json$/, ''), ...state });
+  }
+  return out.sort((a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+}

package/src/lib/specs.js

@@ -0,0 +1,345 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { exists, read, readOr, write, walk, rmrf } from './fs.js';
+import { markdownHeadings, parseFrontmatter, parseSpec, renderSpec } from './markdown.js';
+import { resolveWithin } from './paths.js';
+
+const lineCount = (text) => String(text ?? '').split('\n').length;
+
+const hasText = (lines) => lines.some((line) => line.trim());
+const requirementTitle = (title) => /^Requirement:\s*(.+)$/i.test(title);
+
+/**
+ * Sharded storage can represent the title, purpose, requirements, and decision
+ * bullets.  Do not use a byte-for-byte comparison with canonical output here:
+ * ordinary specs have harmless choices in blank lines and heading order.  We
+ * instead reject only source material for which the shard index has no owner.
+ */
+function hasUnmanagedSpecContent(capability, spec) {
+  const source = spec.source;
+  const { body } = parseFrontmatter(source);
+  // The shard index owns its own layout frontmatter. Any source frontmatter,
+  // including an otherwise empty block, would be discarded by that index.
+  if (body !== source || spec.name !== capability) return true;
+
+  const lines = body.split('\n');
+  const headings = markdownHeadings(body);
+  const names = headings.filter((heading) => heading.level === 1);
+  if (names.length !== 1 || hasText(lines.slice(0, names[0].line))) return true;
+
+  const h2 = headings.filter((heading) => heading.level === 2);
+  let cursor = names[0].line + 1;
+  let purposeCount = 0;
+  for (const heading of h2) {
+    // Text between structural sections is not parsed into any owned field.
+    if (hasText(lines.slice(cursor, heading.line))) return true;
+    const next = headings.find((candidate) => candidate.line > heading.line && candidate.level <= 2);
+    const end = next ? next.line : lines.length;
+    const content = lines.slice(heading.line + 1, end);
+
+    if (/^Purpose$/i.test(heading.title)) {
+      if (++purposeCount > 1) return true;
+    } else if (requirementTitle(heading.title)) {
+      // A legacy requirement's complete body is written into its own shard.
+    } else if (/^Requirements$/i.test(heading.title)) {
+      const h3 = headings.filter((candidate) => candidate.level === 3
+        && candidate.line > heading.line && candidate.line < end);
+      if (h3.some((candidate) => !requirementTitle(candidate.title))) return true;
+      // Preamble prose under an nested container is not part of any
+      // requirement and would disappear when the container becomes a folder.
+      if (h3.length && hasText(lines.slice(heading.line + 1, h3[0].line))) return true;
+      if (!h3.length && hasText(content)) return true;
+    } else if (/^Decisions?$/i.test(heading.title)) {
+      // parseSpec owns decision bullets only. Keep comments, prose, headings,
+      // and fenced examples in the original document rather than silently
+      // converting or dropping them.
+      if (content.some((line) => line.trim() && !/^\s*[-*]\s+/.test(line))) return true;
+    } else {
+      return true;
+    }
+    cursor = end;
+  }
+  return hasText(lines.slice(cursor));
+}
+export const slugify = (s) => Array.from(String(s)
+  .normalize('NFKD')
+  .replace(/\p{Mark}/gu, '')
+  .toLocaleLowerCase()
+  .replace(/[^\p{Letter}\p{Number}]+/gu, '-')
+  .replace(/^-+|-+$/g, ''))
+  .slice(0, 60)
+  .join('') || 'requirement';
+
+export const specFingerprint = (text) => crypto.createHash('sha1').update(text).digest('hex').slice(0, 10);
+
+export function capabilityDir(specsDir, capability) {
+  return resolveWithin(specsDir, capability);
+}
+
+function capabilityStorageRoot(specsDir, capability) {
+  const dir = capabilityDir(specsDir, capability);
+  if (exists(dir) && fs.lstatSync(dir).isSymbolicLink()) throw new Error(`capability storage root must not be a symlink: ${dir}`);
+  return dir;
+}
+
+/** Keep sharding metadata from escaping its capability directory. */
+function storagePath(dir, rel) {
+  if (typeof rel !== 'string' || !rel || path.isAbsolute(rel)) throw new Error('capability storage path must be relative');
+  if (exists(dir) && fs.lstatSync(dir).isSymbolicLink()) throw new Error(`capability storage root must not be a symlink: ${dir}`);
+  const absolute = path.resolve(dir, rel);
+  const relative = path.relative(dir, absolute);
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`capability storage path escapes its root: ${rel}`);
+  let current = dir;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    if (exists(current) && fs.lstatSync(current).isSymbolicLink()) throw new Error(`capability storage path must not be a symlink: ${current}`);
+  }
+  return absolute;
+}
+
+const safeStorageRel = (dir, rel) => {
+  storagePath(dir, rel);
+  return rel;
+};
+
+const firstFree = (dir, preferred, fallback) => {
+  if (!exists(path.join(dir, preferred))) return preferred;
+  if (!exists(path.join(dir, fallback))) return fallback;
+  for (let i = 2; ; i++) {
+    const dot = fallback.lastIndexOf('.');
+    const candidate = dot > 0
+      ? `${fallback.slice(0, dot)}-${i}${fallback.slice(dot)}`
+      : `${fallback}-${i}`;
+    if (!exists(path.join(dir, candidate))) return candidate;
+  }
+};
+
+export function capabilityStorageOptions(specsDir, capability) {
+  const dir = capabilityStorageRoot(specsDir, capability);
+  const main = readOr(storagePath(dir, 'spec.md'), '');
+  const { data } = parseFrontmatter(main);
+  if (data.layout === 'sharded') {
+    return {
+      requirementsDir: safeStorageRel(dir, data.requirements_dir || 'requirements'),
+      // Older Keelson layouts used one decisions_file. New writes migrate that
+      // representation to a directory without touching an unmanaged decisions/
+      // neighbor that the project may already own.
+      decisionsDir: data.decisions_dir
+        ? safeStorageRel(dir, data.decisions_dir)
+        : firstFree(dir, 'decisions', 'keelson-decisions'),
+      decisionsFile: null,
+    };
+  }
+  return {
+    requirementsDir: firstFree(dir, 'requirements', 'keelson-requirements'),
+    decisionsDir: firstFree(dir, 'decisions', 'keelson-decisions'),
+    decisionsFile: null,
+  };
+}
+
+export function readCapabilitySpec(specsDir, capability) {
+  const dir = capabilityStorageRoot(specsDir, capability);
+  const mainPath = storagePath(dir, 'spec.md');
+  const main = readOr(mainPath, '');
+  if (!main) return '';
+
+  const { data } = parseFrontmatter(main);
+  if (data.layout !== 'sharded') return main;
+
+  const index = parseSpec(main);
+  const requirements = [];
+  const reqDir = storagePath(dir, data.requirements_dir || 'requirements');
+  for (const rel of walk(reqDir)) {
+    if (!rel.endsWith('.md')) continue;
+    requirements.push(...parseSpec(read(storagePath(reqDir, rel))).requirements);
+  }
+  const decisions = [];
+  if (data.decisions_dir) {
+    const decisionsDir = storagePath(dir, data.decisions_dir);
+    for (const rel of walk(decisionsDir)) {
+      if (!rel.endsWith('.md')) continue;
+      decisions.push(...parseSpec(read(storagePath(decisionsDir, rel))).decisions);
+    }
+  } else {
+    const decisionsPath = storagePath(dir, data.decisions_file || 'decisions.md');
+    if (exists(decisionsPath)) decisions.push(...parseSpec(read(decisionsPath)).decisions);
+  }
+  return renderSpec({
+    name: capability,
+    purpose: index.purpose,
+    requirements,
+    decisions,
+  });
+}
+
+function uniqueRequirementFiles(requirements, requirementsDir) {
+  const used = new Set();
+  return requirements.map((r, i) => {
+    let base = slugify(r.name);
+    if (used.has(base)) base = `${base}-${i + 1}`;
+    used.add(base);
+    return {
+      rel: `${requirementsDir}/${base}.md`,
+      name: r.name,
+      text: `# ${r.name}\n\n## Requirement: ${r.name}\n\n${r.body.trim()}\n`,
+    };
+  });
+}
+
+function uniqueDecisionFiles(decisions, decisionsDir) {
+  return decisions.map((decision, i) => {
+    const digest = crypto.createHash('sha1').update(decision).digest('hex').slice(0, 8);
+    const words = decision
+      .replace(/^[^:]+:\s*/, '')
+      .split(/\s+/)
+      .slice(0, 6)
+      .join('-');
+    const stem = slugify(words) || 'decision';
+    return {
+      rel: `${decisionsDir}/${String(i + 1).padStart(3, '0')}-${stem}-${digest}.md`,
+      text: `# Decision\n\n## Decisions\n\n- ${decision}\n`,
+    };
+  });
+}
+
+function renderIndex(capability, spec, reqFiles, { requirementsDir, decisionsDir, decisionsFile, decisionCount }) {
+  const parts = [
+    '---',
+    'layout: sharded',
+    `requirements_dir: ${requirementsDir}`,
+    ...(decisionsDir ? [`decisions_dir: ${decisionsDir}`] : decisionsFile ? [`decisions_file: ${decisionsFile}`] : []),
+    '---',
+    `# ${capability}`,
+    '',
+  ];
+  if (spec.purpose) parts.push('## Purpose', '', spec.purpose.trim(), '');
+  parts.push(`- \`${requirementsDir}/\` — ${reqFiles.length} current requirement file(s); read only relevant files`);
+  if (decisionCount) {
+    const location = decisionsDir ? `${decisionsDir}/` : decisionsFile;
+    parts.push(`- \`${location}\` — ${decisionCount} capability-local durable decision file(s)`);
+  }
+  parts.push('');
+  return parts.join('\n');
+}
+
+/**
+ * Choose a bounded physical representation for one logical capability contract.
+ * Total capability knowledge may grow; individual frequently-read files stay bounded.
+ */
+export function planCapabilityStorage(capability, logicalText, budget = 0, {
+  requirementsDir = 'requirements',
+  decisionsDir = 'decisions',
+  decisionsFile = null,
+} = {}) {
+  const spec = parseSpec(logicalText);
+  const canonical = renderSpec(spec);
+  const soft = Number(budget) || 0;
+  // A shard index has room only for the parsed ownership model. Keep a single
+  // file when source content has no shard owner, but accept harmless canonical
+  // layout differences in otherwise fully-modelled legacy/nested documents.
+  const mustKeepSingle = hasUnmanagedSpecContent(capability, spec);
+  if (!soft || lineCount(canonical) <= soft || mustKeepSingle) {
+    return {
+      mode: 'single',
+      logicalText: canonical,
+      files: [{ rel: 'spec.md', text: canonical }],
+      hardOver: [],
+    };
+  }
+
+  const reqFiles = uniqueRequirementFiles(spec.requirements, requirementsDir);
+  const decisionFiles = spec.decisions.length
+    ? uniqueDecisionFiles(spec.decisions, decisionsDir)
+    : [];
+  const indexText = renderIndex(capability, spec, reqFiles, {
+    requirementsDir,
+    decisionsDir,
+    decisionsFile,
+    decisionCount: decisionFiles.length,
+  });
+  const files = [
+    { rel: 'spec.md', text: indexText },
+    ...reqFiles.map(({ rel, text }) => ({ rel, text })),
+    ...decisionFiles,
+  ];
+  const hardLimit = soft * 2;
+  const hardOver = files
+    .map((f) => ({ rel: f.rel, lines: lineCount(f.text) }))
+    .filter((f) => f.lines > hardLimit);
+
+  return {
+    mode: 'sharded',
+    logicalText: canonical,
+    files,
+    hardLimit,
+    hardOver,
+    requirementsDir,
+    decisionsDir,
+    decisionsFile,
+  };
+}
+
+export function writeCapabilityStorage(specsDir, capability, plan) {
+  const dir = capabilityStorageRoot(specsDir, capability);
+  const currentMain = readOr(storagePath(dir, 'spec.md'), '');
+  const { data } = parseFrontmatter(currentMain);
+  if (data.layout === 'sharded') {
+    rmrf(storagePath(dir, data.requirements_dir || 'requirements'));
+    if (data.decisions_dir) rmrf(storagePath(dir, data.decisions_dir));
+    if (data.decisions_file) rmrf(storagePath(dir, data.decisions_file));
+  }
+  if (plan.mode === 'sharded') {
+    rmrf(storagePath(dir, plan.requirementsDir));
+    if (plan.decisionsDir) rmrf(storagePath(dir, plan.decisionsDir));
+    if (plan.decisionsFile) rmrf(storagePath(dir, plan.decisionsFile));
+  }
+  for (const file of plan.files) write(storagePath(dir, file.rel), file.text);
+}
+
+export function capabilityPhysicalDocs(specsDir, capability) {
+  const dir = capabilityStorageRoot(specsDir, capability);
+  const out = [];
+  const main = readOr(storagePath(dir, 'spec.md'), '');
+  if (main) out.push({ rel: 'spec.md', file: storagePath(dir, 'spec.md') });
+  const { data } = parseFrontmatter(main);
+  if (data.layout !== 'sharded') return out;
+  if (data.decisions_dir) {
+    const decisionsDir = storagePath(dir, data.decisions_dir);
+    for (const rel of walk(decisionsDir)) {
+      if (rel.endsWith('.md')) out.push({ rel: `${data.decisions_dir}/${rel}`, file: storagePath(decisionsDir, rel) });
+    }
+  } else {
+    const decisionsRel = data.decisions_file || 'decisions.md';
+    const decisions = storagePath(dir, decisionsRel);
+    if (exists(decisions)) out.push({ rel: decisionsRel, file: decisions });
+  }
+  const requirementsRel = data.requirements_dir || 'requirements';
+  const reqDir = storagePath(dir, requirementsRel);
+  for (const rel of walk(reqDir)) {
+    if (rel.endsWith('.md')) out.push({ rel: `${requirementsRel}/${rel}`, file: storagePath(reqDir, rel) });
+  }
+  return out;
+}
+
+export function changeSpecDrift(change, specsDir) {
+  const out = [];
+  for (const df of change.deltaFiles ?? []) {
+    const cap = path.dirname(df).replace(/\\/g, '/');
+    if (cap === '.' || cap.includes('<')) continue;
+    const deltaPath = path.join(change.dir, 'specs', df);
+    const { data } = parseFrontmatter(read(deltaPath));
+    if (!data.base) continue;
+    const logical = readCapabilitySpec(specsDir, cap);
+    const current = logical ? specFingerprint(logical) : 'new';
+    if (current !== data.base) {
+      out.push({
+        capability: cap,
+        expected: data.base,
+        current,
+        detail: `specs/${cap} changed since this delta was written (base ${data.base}, now ${current}); re-read and reconcile the delta`,
+      });
+    }
+  }
+  return out;
+}

package/src/lib/transaction.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { exists, readJson, writeJson } from './fs.js';
+import { runtimeDir } from './runtime-path.js';
+import { resolveWithin } from './paths.js';
+
+function targetLocation(root, target) {
+  const runtime = runtimeDir(root);
+  const absolute = path.resolve(target);
+  if (absolute === path.join(runtime, 'sessions')) return { scope: 'runtime', target: 'sessions' };
+  const relative = path.relative(root, absolute);
+  resolveWithin(root, relative);
+  if (relative.split(path.sep)[0] === '.git') throw new Error('transaction target must not overwrite Git metadata');
+  return { scope: 'project', target: relative };
+}
+
+function resolveEntries(root, dir, journal, { requireBackups = true } = {}) {
+  if (!journal || !['prepared', 'committed'].includes(journal.phase) || !Array.isArray(journal.entries)
+    || (journal.version !== undefined && journal.version !== 2)) throw new Error('invalid landing journal; preserve it for manual recovery');
+  // Validate the entire journal before the first removal. In particular, old
+  // absolute paths cannot be trusted after a project directory has moved.
+  return journal.entries.map((entry, i) => {
+    if (!entry || typeof entry.existed !== 'boolean') throw new Error('invalid landing journal entry');
+    let location;
+    if (journal.version === 2) {
+      location = { scope: entry.scope, target: entry.target };
+      if (entry.backup !== String(i)) throw new Error('invalid landing backup path');
+    } else {
+      if (typeof entry.target !== 'string' || !path.isAbsolute(entry.target)
+        || entry.backup !== path.join(dir, String(i))) throw new Error('legacy landing journal paths changed; preserve it for manual recovery');
+      location = targetLocation(root, entry.target);
+    }
+    let target;
+    if (location.scope === 'runtime' && location.target === 'sessions') {
+      target = resolveWithin(runtimeDir(root), 'sessions');
+    } else if (location.scope === 'project') {
+      target = resolveWithin(root, location.target);
+      const checked = targetLocation(root, target);
+      if (checked.scope !== 'project') throw new Error('invalid project transaction target');
+    } else throw new Error('invalid landing target scope');
+    const backup = resolveWithin(dir, String(i));
+    if (requireBackups && entry.existed && !exists(backup)) throw new Error(`missing landing backup: ${backup}; preserve the journal for manual recovery`);
+    return { target, backup, existed: entry.existed };
+  });
+}
+
+function restore(root, dir, journal) {
+  const entries = resolveEntries(root, dir, journal);
+  for (const entry of entries) {
+    fs.rmSync(entry.target, { force: true, recursive: true });
+    if (entry.existed) {
+      fs.mkdirSync(path.dirname(entry.target), { recursive: true });
+      fs.cpSync(entry.backup, entry.target, { recursive: true, preserveTimestamps: true });
+    }
+  }
+}
+
+// Caller holds the project landing lock. An interrupted transaction is restored
+// before another landing can start. Backups are private, never project content.
+export function recoverLanding(root) {
+  const dir = path.join(runtimeDir(root), 'landing-transaction');
+  const journal = readJson(path.join(dir, 'journal.json'));
+  if (!journal) return false;
+  resolveEntries(root, dir, journal, { requireBackups: journal.phase !== 'committed' });
+  if (journal.phase !== 'committed') restore(root, dir, journal);
+  fs.rmSync(dir, { recursive: true, force: true });
+  return journal.phase !== 'committed';
+}
+
+export function landingTransaction(root, targets, mutate) {
+  const dir = path.join(runtimeDir(root), 'landing-transaction');
+  if (exists(path.join(dir, 'journal.json'))) throw new Error('landing journal already exists; recover it before starting another transaction');
+  fs.mkdirSync(dir, { recursive: true });
+  const entries = [...new Set(targets)].map((target, i) => ({ ...targetLocation(root, target), backup: String(i), existed: exists(target) }));
+  const journal = { version: 2, phase: 'prepared', entries };
+  try {
+    for (const e of resolveEntries(root, dir, journal, { requireBackups: false })) if (e.existed) fs.cpSync(e.target, e.backup, { recursive: true, preserveTimestamps: true });
+    writeJson(path.join(dir, 'journal.json'), journal);
+    try {
+      const result = mutate();
+      writeJson(path.join(dir, 'journal.json'), { ...journal, phase: 'committed' });
+      return result;
+    } catch (error) {
+      restore(root, dir, journal);
+      writeJson(path.join(dir, 'journal.json'), { ...journal, phase: 'committed' });
+      throw error;
+    }
+  } finally {
+    // Preserve backups if restoration itself fails, so the next run can retry.
+    const journal = readJson(path.join(dir, 'journal.json'));
+    if (!journal || journal.phase === 'committed') fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/platforms/index.js

@@ -0,0 +1,3 @@
+export * from './registry.js';
+export * from './runtime.js';
+export * from './integration.js';