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 on9e74925c2(three commits to989699f7c, manifest 2e30f2a1...29d5f), approved by Filbert in round 3 (#1673 comment 29279), Sage's gate green on716ddcf1eplus the patch.
264 lines
15 KiB
JavaScript
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';
|