import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, fsyncSync, rmSync, rmdirSync, } from 'node:fs'; import { dirname, join, normalize } from 'node:path'; import { randomUUID } from 'node:crypto'; import { ProjectError, checkedId, documentPath, noLinks, projectRepo, testerProjectArea } from './paths.mjs'; import { git, identity, inspectGit, requireClean } from './git.mjs'; import { validateRecord } from './validate.mjs'; export { ProjectError, projectRepo, testerProjectArea, validateRecord }; export { recordContext } from './paths.mjs'; const DIRECTORIES = ['spec', 'docs', 'requirements', 'decisions', 'templates']; const TEMPLATES = ['project.json', 'requirement.json', 'decision.json', 'document.md', 'north-star.md']; const MAX_BYTES = 1024 * 1024; const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); function readText(path) { const st = lstatSync(path); if (!st.isFile() || st.isSymbolicLink() || st.nlink !== 1 || st.size > MAX_BYTES) throw Error('expected bounded regular file, not a link'); const value = new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(path)); if (value.includes('\0')) throw Error('NUL is forbidden'); return value; } function jsonProblems(kind, text, relative, problems) { try { const value = JSON.parse(text); for (const problem of validateRecord(kind, value)) problems.push(`${relative}: ${problem}`); return value; } catch { problems.push(`${relative}: invalid JSON`); return null; } } async function checkLayout(context) { const repo = projectRepo(context), problems = []; const problem = (path, message) => problems.push(`${path}: ${message}`); try { const top = readdirSync(repo); for (const name of top) if (!['.git', 'project.json', ...DIRECTORIES].includes(name)) problem(name, 'unknown top-level path'); for (const name of ['project.json', '.git', ...DIRECTORIES]) if (!top.includes(name)) problem(name, 'missing required path'); if (top.includes('project.json')) { try { const value = jsonProblems('project', readText(join(repo, 'project.json')), 'project.json', problems); if (value && value.business !== context.business.id) problem('project.json', 'business does not match context'); if (value && value.project !== context.project) problem('project.json', 'project does not match context'); } catch (e) { problem('project.json', e.message); } } for (const directory of DIRECTORIES) { const base = join(repo, directory); try { if (!lstatSync(base).isDirectory() || lstatSync(base).isSymbolicLink()) throw Error('expected directory, never a link'); const visit = (folder, prefix = '') => { for (const name of readdirSync(folder)) { const relative = prefix + name, file = join(folder, name), label = `${directory}/${relative}`; try { const st = lstatSync(file); if (st.isDirectory()) { if (directory !== 'docs') problem(label, 'unexpected nested directory'); else visit(file, relative + '/'); continue; } const text = readText(file); if (['requirements', 'decisions'].includes(directory)) { if (name === '.gitkeep') { if (text !== '') problem(label, 'layout marker must be empty'); continue; } if (!name.endsWith('.json')) { problem(label, 'expected a JSON record'); continue; } const kind = directory === 'requirements' ? 'requirement' : 'decision'; const value = jsonProblems(kind, text, label, problems); if (value && name !== `${value.id}.json`) problem(label, 'file name must match record id'); } else if (directory === 'templates') { if (!TEMPLATES.includes(name)) problem(label, 'unknown template'); else if (name.endsWith('.json')) jsonProblems(name.slice(0, -5), text, label, problems); } else if (directory === 'spec' ? relative !== 'north-star.md' : !name.endsWith('.md')) { problem(label, 'unexpected Markdown path'); } } catch (e) { problem(label, e.message); } } }; visit(base); if (directory === 'spec' && !readdirSync(base).includes('north-star.md')) problem('spec/north-star.md', 'missing'); if (directory === 'templates') for (const name of TEMPLATES) if (!readdirSync(base).includes(name)) problem(`templates/${name}`, 'missing'); } catch (e) { problem(directory, e.message); } } try { await inspectGit(repo); } catch (e) { problem('.git', e.message); } } catch (e) { problem(repo, e.message); } return { ok: problems.length === 0, repo, problems }; } export async function checkProject(context) { const result = await checkLayout(context); if (result.ok) { try { await git(result.repo, ['rev-parse', '--verify', 'HEAD^{commit}']); } catch { throw new ProjectError('project-no-commit', 'project repository has no readable commit'); } } return result; } // Row 175 (#1673): `author` names the layout commit's author and committer; without it the // business human commits, as before. The tester's init passes "tester". export async function initProject(context, { author } = {}) { const repo = projectRepo(context), committer = checkedId(author ?? context.business.human); if (existsSync(repo) && readdirSync(repo).length) throw new ProjectError('project-not-empty', 'refusing existing non-empty directory'); const parents = []; for (let path = repo; !existsSync(path); path = dirname(path)) parents.unshift(path); mkdirSync(repo, { recursive: true, mode: 0o700 }); const created = []; const remember = (path, recursive = false) => { const stat = lstatSync(path); created.push({ path, ino: stat.ino, dev: stat.dev, recursive }); }; const createFile = (path, bytes) => { const fd = openSync(path, 'wx', 0o600); try { remember(path); writeFileSync(fd, bytes); } finally { closeSync(fd); } }; try { // Only the initializer that owns this exclusive directory may clean it up. try { mkdirSync(join(repo, '.git'), { mode: 0o700 }); } catch { throw new ProjectError('project-not-empty', 'another initializer already owns this directory'); } remember(join(repo, '.git'), true); await git(repo, ['init', '--initial-branch=main', '--template=']); for (const directory of DIRECTORIES) { const path = join(repo, directory); mkdirSync(path, { mode: 0o700 }); remember(path); } for (const name of TEMPLATES) createFile(join(repo, 'templates', name), readFileSync(new URL(`../templates/${name}`, import.meta.url))); createFile(join(repo, 'spec/north-star.md'), readFileSync(new URL('../templates/north-star.md', import.meta.url))); createFile(join(repo, 'docs/README.md'), '# Project documentation\n\nKeep project Markdown documents here.\n'); for (const directory of ['requirements', 'decisions']) createFile(join(repo, directory, '.gitkeep'), ''); const metadata = { layoutVersion: 1, business: context.business.id, project: context.project, name: context.project, createdAt: new Date().toISOString() }; createFile(join(repo, 'project.json'), JSON.stringify(metadata, null, 2) + '\n'); const result = await checkLayout(context); if (!result.ok) throw new ProjectError('project-invalid', result.problems.join('\n')); await git(repo, ['add', '--', 'project.json', ...DIRECTORIES]); await git(repo, ['commit', '-m', 'Initialize project layout v1'], identity(committer)); return { repo, commit: await git(repo, ['rev-parse', 'HEAD']) }; } catch (error) { for (const entry of created.reverse()) { let stat; try { stat = lstatSync(entry.path); } catch (e) { if (e.code === 'ENOENT') continue; throw e; } if (stat.ino !== entry.ino || stat.dev !== entry.dev) throw new ProjectError('project-init-cleanup', 'owned path changed; preserve it for reconciliation'); if (stat.isDirectory() && !entry.recursive) { try { rmdirSync(entry.path); } catch (e) { if (!['ENOTEMPTY', 'EEXIST'].includes(e.code)) throw e; } } else rmSync(entry.path, { recursive: entry.recursive, force: true }); } // rmdir never removes unrelated files or a pre-existing empty directory. for (const path of parents.reverse()) { try { rmdirSync(path); } catch (e) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(e.code)) throw e; } } throw error; } } function recordBytes(path, record) { if (typeof path !== 'string' || path.startsWith('/') || normalize(path) !== path || path.includes('\\') || path.includes('\0')) throw new ProjectError('project-record-path', 'expected a canonical relative record path'); if (path === 'spec' || path.startsWith('spec/')) throw new ProjectError('project-spec-human-only', 'agents never write spec/'); const match = /^(docs|requirements|decisions)\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\.(md|json)$/.exec(path); if (!match || (match[1] === 'docs' ? match[3] !== 'md' : match[3] !== 'json')) throw new ProjectError('project-record-path', 'record must be a Markdown doc or a named JSON requirement/decision'); let text; if (match[1] === 'docs') { if (typeof record !== 'string' || !record.length) throw new ProjectError('project-record-invalid', 'document must be nonempty Markdown'); text = record; } else { if (typeof record === 'string') { try { record = JSON.parse(record); } catch { throw new ProjectError('project-record-invalid', 'JSON record must be an object (got unparseable string)'); } if (record === null || typeof record !== 'object' || Array.isArray(record)) { const type = record === null ? 'null' : Array.isArray(record) ? 'array' : typeof record; throw new ProjectError('project-record-invalid', `JSON record must be an object (got ${type})`); } } const kind = match[1] === 'requirements' ? 'requirement' : 'decision'; const problems = validateRecord(kind, record); if (problems.length || record.id !== match[2]) throw new ProjectError('project-record-invalid', problems.join('; ') || 'file name must match record id'); text = JSON.stringify(record, null, 2) + '\n'; } if (text.includes('\0') || Buffer.byteLength(text) > MAX_BYTES) throw new ProjectError('project-record-invalid', 'record exceeds size bound or contains NUL'); return Buffer.from(text, 'utf8'); } function publish(file, bytes) { const temp = join(dirname(file), `.mosaic-record-${randomUUID()}.tmp`); let fd; try { fd = openSync(temp, 'wx', 0o600); writeFileSync(fd, bytes); fsyncSync(fd); closeSync(fd); fd = undefined; renameSync(temp, file); const dir = openSync(dirname(file), 'r'); try { fsyncSync(dir); } finally { closeSync(dir); } } finally { if (fd !== undefined) closeSync(fd); try { unlinkSync(temp); } catch (e) { if (e.code !== 'ENOENT') throw e; } } } // One file, one local commit: the lock, the clean-tree and layout checks, publish, commit and the // rollback. The agent writer and the human writer (row 148) differ only in who authors the commit // and in `guard`, which runs under the lock with the file's current bytes (null when absent). // `around(effect)` (#802) checks freshness after the reads and protects publication through the last git child. async function commitFile({ context, repo, path, bytes, name, subject, guard, around }) { const metadata = lstatSync(join(repo, '.git')); if (!metadata.isDirectory() || metadata.isSymbolicLink()) throw new ProjectError('project-repository', 'expected a local .git directory'); const lock = join(repo, '.git/mosaic-record.lock'); let fd; try { fd = openSync(lock, 'wx', 0o600); } catch (e) { throw new ProjectError(e.code === 'EEXIST' ? 'project-busy' : 'project-repository', 'writer lock unavailable'); } const lockStat = lstatSync(lock); const file = join(repo, path); let before, head, published = false; try { await inspectGit(repo); await requireClean(repo); const checked = await checkProject(context); if (!checked.ok) throw new ProjectError('project-invalid', checked.problems.join('\n')); noLinks(dirname(file)); // readText validates (bounded regular file, UTF-8, no NUL); the raw bytes are what a rollback restores. before = existsSync(file) ? (readText(file), readFileSync(file)) : null; if (guard) await guard({ before }); if (before?.equals(bytes)) throw new ProjectError('project-record-unchanged', 'record already has these bytes'); head = await git(repo, ['rev-parse', 'HEAD']); const effect = async () => { try { publish(file, bytes); published = true; await git(repo, ['add', '--', path]); await git(repo, ['commit', '--only', '-m', subject, '--', path], identity(name)); const commit = await git(repo, ['rev-parse', 'HEAD']); return { repo, path, commit }; } catch (error) { if (published) { const current = await git(repo, ['rev-parse', 'HEAD']); if (current !== head) throw new ProjectError('project-commit-uncertain', 'HEAD changed; preserve evidence for reconciliation'); await git(repo, ['reset', '--quiet', 'HEAD', '--', path]); if (before === null) unlinkSync(file); else publish(file, before); } throw error; } }; return await (around ? around(effect) : effect()); } finally { closeSync(fd); if (lstatSync(lock).ino === lockStat.ino) unlinkSync(lock); } } export async function writeRecord({ path, record, author, ...context }) { const repo = projectRepo(context), bytes = recordBytes(path, record); if (!object(author) || Object.keys(author).sort().join(',') !== 'definition,instance') throw new ProjectError('project-author', 'expected definition and instance'); const name = `${checkedId(author.definition)}.${checkedId(author.instance)}`; if (author.definition === 'human') throw new ProjectError('project-author', 'writer requires an agent author'); return commitFile({ context, repo, path, bytes, name, subject: `Record ${path}` }); } // Row 148: the human's save from the Console. It replaces the whole text of an existing // spec/north-star.md or docs/*.md and makes one commit authored by the business's human. `base` is // the file's last commit as the editor opened it; a newer last commit refuses `stale-base` and // writes nothing. Agents never reach this: only the human bus verb calls it. export async function writeHumanFile({ path, content, base, around, ...context }) { const repo = projectRepo(context); if (!documentPath(path)) throw new ProjectError('project-record-path', 'expected spec/north-star.md or a named Markdown doc'); if (typeof content !== 'string' || !content.length || !content.isWellFormed() || content.includes('\0') || Buffer.byteLength(content) > MAX_BYTES) throw new ProjectError('project-record-invalid', 'expected nonempty UTF-8 text within the size bound, without NUL'); if (typeof base !== 'string' || !/^[0-9a-f]{40}$/.test(base)) throw new ProjectError('project-record-invalid', 'expected the full commit the editor opened'); const name = checkedId(context.business.human); const guard = async ({ before }) => { if (before === null) throw new ProjectError('project-read-missing', 'only an existing document can be saved'); if (await git(repo, ['log', '-1', '--format=%H', 'HEAD', '--', path]) !== base) throw new ProjectError('stale-base', 'the file changed since the editor opened it'); }; return commitFile({ context, repo, path, bytes: Buffer.from(content, 'utf8'), name, subject: `Edit ${path}`, guard, around }); } export { readProjectFile, readSpec, listProjectFiles } from './read.mjs'; export { readPrdCandidate } from './prd.mjs';