import { projectRepo, documentPath, ProjectError } from './paths.mjs'; import { git, gitBytes, inspectGit } from './git.mjs'; import { validateRecord } from './validate.mjs'; const MAX_BYTES = 1024 * 1024; const SHA = /^[0-9a-f]{40}$/; const fail = (code, message) => { throw new ProjectError(code, message); }; function argumentsFor(args, allowed) { if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).some(k => !allowed.includes(k))) fail('project-read-path', 'unknown read arguments'); } function text(bytes) { try { const value = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); if (value.includes('\0')) fail('project-read-content', 'NUL in blob'); return value; } catch { fail('project-read-content', 'expected bounded UTF-8 without NUL'); } } async function blob(repo, revision, path) { const entry = await git(repo, ['ls-tree', '-z', revision, '--', path]); if (!entry) fail('project-read-missing', 'file absent at revision'); const match = /^(100644|100755) blob ([0-9a-f]{40})\t([^\0]+)\0$/.exec(entry); if (!match || match[3] !== path) fail('project-read-content', 'expected regular Git blob'); const size = Number(await git(repo, ['cat-file', '-s', match[2]])); if (!Number.isSafeInteger(size) || size < 0 || size > MAX_BYTES) fail('project-read-content', 'blob exceeds size bound'); return text(await gitBytes(repo, ['cat-file', 'blob', match[2]], MAX_BYTES)); } // The repository, its HEAD and the revision to read, with the committed project identity checked // against the caller's business and project. Shared by the file read and the file list. async function openRevision({ business, project, dataRoot, commit }) { const repo = projectRepo({ business, project, dataRoot }); await inspectGit(repo); let head; try { head = await git(repo, ['rev-parse', '--verify', 'HEAD^{commit}']); } catch { fail('project-read-commit', 'repository has no readable HEAD commit'); } const revision = commit === undefined ? head : commit; if (typeof revision !== 'string' || !SHA.test(revision)) fail('project-read-commit', 'expected full commit ID'); try { if (await git(repo, ['cat-file', '-t', revision]) !== 'commit') fail('project-read-commit', 'not a commit'); await git(repo, ['merge-base', '--is-ancestor', revision, head]); } catch { fail('project-read-commit', 'commit is not reachable from HEAD'); } let metadata; try { metadata = JSON.parse(await blob(repo, revision, 'project.json')); } catch { fail('project-invalid', 'missing or invalid committed project metadata'); } if (validateRecord('project', metadata).length || metadata.business !== business.id || metadata.project !== project) fail('project-invalid', 'committed project identity does not match context'); return { repo, head, revision }; } // The documents a person can open in the Console (row 148): the spec and the Markdown directly // under docs/, as committed at HEAD. Names only; a read opens one. export async function listProjectFiles(args) { argumentsFor(args, ['business', 'project', 'dataRoot']); const { head, repo } = await openRevision(args); const listing = await gitBytes(repo, ['ls-tree', '-z', head, '--', 'spec/north-star.md', 'docs/'], 256 * 1024); let entries; try { entries = new TextDecoder('utf-8', { fatal: true }).decode(listing).split('\0'); } catch { fail('project-git', 'invalid UTF-8 Git listing'); } if (entries.pop() !== '') fail('project-git', 'invalid Git listing'); const files = []; for (const entry of entries) { const match = /^(100644|100755) blob [0-9a-f]{40}\t([^\0]+)$/.exec(entry); if (match && documentPath(match[2])) files.push({ path: match[2] }); } files.sort((a, b) => a.path < b.path ? -1 : 1); return { head, files }; } export async function readProjectFile(args) { argumentsFor(args, ['business', 'project', 'dataRoot', 'path', 'commit']); const { business, project, dataRoot, path, commit } = args; if (!documentPath(path)) fail('project-read-path', 'expected spec/north-star.md or a named Markdown doc'); const { repo, head, revision } = await openRevision({ business, project, dataRoot, commit }); const content = await blob(repo, revision, path); const bytes = await gitBytes(repo, ['log', '-z', '--max-count=101', '--format=%H%x00%an%x00%ae%x00%aI%x00%s', revision, '--', path], 256 * 1024); let fields; try { fields = new TextDecoder('utf-8', { fatal: true }).decode(bytes).split('\0'); } catch { fail('project-git', 'invalid UTF-8 Git history'); } if (fields.pop() !== '' || !fields.length || fields.length % 5 !== 0) fail('project-git', 'invalid Git history'); const log = []; for (let i = 0; i < fields.length; i += 5) { const [commit, name, email, at, subject] = fields.slice(i, i + 5); if (!SHA.test(commit) || !Number.isFinite(Date.parse(at))) fail('project-git', 'invalid Git history'); log.push({ commit, author: { name, email }, at: new Date(at).toISOString(), subject }); } return { repo, path, head, revision, commit: log[0].commit, content, author: log[0].author, log: log.slice(0, 100), truncated: log.length > 100 }; } export async function readSpec(args) { argumentsFor(args, ['business', 'project', 'dataRoot', 'commit']); const result = await readProjectFile({ ...args, path: 'spec/north-star.md' }); return { ...result, confirmed: result.author.name === args.business.human }; }