Files
stack/packages/project/src/index.mjs
T
jason.woltje 98d29769e2 bus, cli: tester reads and the W1-W7 tester writes, recorded as tester; scripts/mosaic sends plugins, name and names to the CLI (row 175, #1673)
TESTER_VERBS gains usage, names, limits, plugins, instances, project.list,
thread.list, name.set and project.create. A tester reads limits, plugins
and instances and sends plugins.set, instances.set and routes.set, each
logged with actor tester. The project file verbs refuse a tester
tester-refused. The broker and CLI drop the [mos test]
prefix rule (mos-0872 Q1). The CLI takes --tester on the seven reads and
the W1-W7 write forms and refuses it (exit 4) elsewhere, bus start and
stop included.

project init --tester checks the project area, refuses the area root
itself, binds the tester with one agents read, then commits the layout as
tester (mos-0872 Q2). scripts/mosaic sends plugins, name, names, follow,
threads and thread to packages/cli (sage-1081). The row 164 pins are
untouched.

Built by Dewey on 9e74925c2 (three commits to 989699f7c, manifest
2e30f2a1...29d5f), approved by Filbert in round 3 (#1673 comment 29279),
Sage's gate green on 716ddcf1e plus the patch.
2026-10-19 19:04:50 -05:00

264 lines
15 KiB
JavaScript

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 };
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 (e) { problems.push(`${relative}: invalid JSON (${e.message})`); 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 {
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).
async function commitFile({ context, repo, path, bytes, name, subject, guard }) {
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']);
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;
} 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, ...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 });
}
export { readProjectFile, readSpec, listProjectFiles } from './read.mjs';