@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/dispatch/projection.ts

@@ -0,0 +1,293 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+import type { OperationalDecision } from './decision';
+import type { OperationalDispatchRecord } from './record';
+
+export const HOSTED_RECEIPT_STATUSES = ['success', 'partial', 'blocked', 'failed'] as const;
+
+export type HostedReceiptStatus = typeof HOSTED_RECEIPT_STATUSES[number];
+
+export interface HostedReceiptMetadataProjection {
+  schema: 'hosted-receipt-metadata-projection.v0';
+  projection_id: string;
+  source_schema: 'operational-dispatch-record.v0';
+  source_record_id: string;
+  hosted_payload: {
+    task_id: string;
+    seat_id: string;
+    status: HostedReceiptStatus;
+    artifact_ref?: string;
+    receipt_ref: string;
+    validation_summary: string;
+  };
+  authority_boundary: {
+    hosted_plane_can_execute: false;
+    hosted_plane_can_authorize: false;
+    hosted_plane_can_attach_grant: false;
+    hosted_plane_can_change_local_ledger: false;
+  };
+  projection_boundary: {
+    metadata_only: true;
+    raw_receipt_body_included: false;
+    source_decision_included: false;
+    local_paths_included: false;
+  };
+}
+
+const PATH_FRAGMENTS = [
+  '/U' + 'sers/',
+  '/h' + 'ome/',
+  '$H' + 'OME',
+  '/pr' + 'ivate/',
+  '/t' + 'mp/',
+] as const;
+
+function trimString(value: unknown, name: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`${name} must be a string`);
+  }
+  return value.trim();
+}
+
+function hasPathShape(value: string): boolean {
+  return PATH_FRAGMENTS.some((fragment) => value.includes(fragment))
+    || /^[A-Za-z]:[\\/]/.test(value)
+    || value.startsWith('/')
+    || value.startsWith('\\');
+}
+
+function hasLeakagePathShape(value: string): boolean {
+  return PATH_FRAGMENTS.some((fragment) => value.includes(fragment))
+    || /^[A-Za-z]:[\\/]/.test(value);
+}
+
+function hasHostnameShape(value: string): boolean {
+  return /\.(local|lan|internal|intranet|localdomain)(\/.*)?$/i.test(value)
+    || /^[0-9]{1,3}(\.[0-9]{1,3}){3}/.test(value)
+    || /\b[0-9a-f]{1,4}:[0-9a-f]{1,4}:/i.test(value);
+}
+
+function hasCredentialShape(value: string): boolean {
+  return /(api[_-]?key|secret|token|password|credential)/i.test(value);
+}
+
+function hasPromptOrToolShape(value: string): boolean {
+  return /(raw[_ -]?prompt|tool[_ -]?output|tool_use|assistant_thought|chain[_ -]?of[_ -]?thought)/i.test(value);
+}
+
+function assertCleanSharedString(value: string, name: string): void {
+  if (value.length === 0) {
+    throw new Error(`${name} must not be empty`);
+  }
+  if (/[\s\x00-\x1f\x7f]/.test(value)) {
+    throw new Error(`${name} must not contain whitespace or control characters`);
+  }
+  if (hasLeakagePathShape(value)) {
+    throw new Error(`${name} must not contain local path markers`);
+  }
+  if (hasHostnameShape(value)) {
+    throw new Error(`${name} must not contain hostnames or IP addresses`);
+  }
+  if (hasCredentialShape(value)) {
+    throw new Error(`${name} must not contain credential-shaped text`);
+  }
+  if (hasPromptOrToolShape(value)) {
+    throw new Error(`${name} must not contain prompt/tool-output markers`);
+  }
+}
+
+function sanitizeOpaqueRef(value: unknown, name: string, maxLength: number): string {
+  const v = trimString(value, name);
+  if (v.length > maxLength) {
+    throw new Error(`${name} length must be <= ${maxLength}`);
+  }
+  assertCleanSharedString(v, name);
+  if (/[^A-Za-z0-9._:-]/.test(v)) {
+    throw new Error(`${name} contains unsafe characters`);
+  }
+  return v;
+}
+
+function sanitizeRepoRelative(value: unknown, name: string): string {
+  const v = trimString(value, name);
+  if (v.length > 256) {
+    throw new Error(`${name} length must be <= 256`);
+  }
+  if (hasPathShape(v)) {
+    throw new Error(`${name} must be repo-relative and must not contain local path markers`);
+  }
+  if (hasHostnameShape(v)) {
+    throw new Error(`${name} must not contain hostnames or IP addresses`);
+  }
+  if (hasCredentialShape(v) || hasPromptOrToolShape(v)) {
+    throw new Error(`${name} must not contain sensitive markers`);
+  }
+  return v;
+}
+
+function sanitizeArtifactRef(value: unknown, name: string): string {
+  const v = trimString(value, name);
+  if (v.length > 128) {
+    throw new Error(`${name} length must be <= 128`);
+  }
+  if (hasPathShape(v)) {
+    throw new Error(`${name} must not be an absolute path or local path marker`);
+  }
+  if (hasHostnameShape(v)) {
+    throw new Error(`${name} must not contain hostnames or IP addresses`);
+  }
+  if (hasCredentialShape(v) || hasPromptOrToolShape(v)) {
+    throw new Error(`${name} must not contain sensitive markers`);
+  }
+  return v;
+}
+
+function sanitizeSummary(value: string): string {
+  const trimmed = value.trim().slice(0, 200);
+  if (hasLeakagePathShape(trimmed) || hasHostnameShape(trimmed)) {
+    throw new Error('--validation-summary must not contain path or hostname markers');
+  }
+  if (hasCredentialShape(trimmed) || hasPromptOrToolShape(trimmed)) {
+    throw new Error('--validation-summary must not contain sensitive markers');
+  }
+  return trimmed;
+}
+
+function assertStringArray(value: unknown, name: string): string[] {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+    throw new Error(`${name} must be a string array`);
+  }
+  return value;
+}
+
+function assertOperationalDecision(value: unknown): OperationalDecision {
+  if (
+    value !== 'dispatch_ready'
+    && value !== 'hold_for_grant'
+    && value !== 'blocked_by_capability'
+    && value !== 'blocked_by_validation'
+    && value !== 'quarantine_hold'
+  ) {
+    throw new Error('record.decision must be an operational dispatch decision');
+  }
+  return value;
+}
+
+function assertRecordAuthorityBoundary(value: unknown): OperationalDispatchRecord['authority_boundary'] {
+  if (!value || typeof value !== 'object') {
+    throw new Error('record.authority_boundary must be an object');
+  }
+  const boundary = value as Record<string, unknown>;
+  const expectedFalse = [
+    'can_dispatch',
+    'can_authorize',
+    'can_attach_grant',
+    'can_execute',
+    'consumer_is_engine',
+  ];
+  for (const key of expectedFalse) {
+    if (boundary[key] !== false) {
+      throw new Error(`record.authority_boundary.${key} must be false`);
+    }
+  }
+  return boundary as OperationalDispatchRecord['authority_boundary'];
+}
+
+function assertHostedReceiptStatus(value: string): HostedReceiptStatus {
+  if (!(HOSTED_RECEIPT_STATUSES as readonly string[]).includes(value)) {
+    throw new Error(`--status must be one of: ${HOSTED_RECEIPT_STATUSES.join(', ')}`);
+  }
+  return value as HostedReceiptStatus;
+}
+
+function defaultHostedStatus(decision: OperationalDecision): HostedReceiptStatus {
+  return decision === 'dispatch_ready' ? 'success' : 'blocked';
+}
+
+function defaultValidationSummary(record: OperationalDispatchRecord): string {
+  const reasons = record.reasons.join(',') || 'none';
+  const warnings = record.warnings.join(',') || 'none';
+  return sanitizeSummary(`dispatch=${record.decision}; reasons=${reasons}; warnings=${warnings}; authority=advisory-only`);
+}
+
+function projectionId(payload: HostedReceiptMetadataProjection['hosted_payload'], recordId: string): string {
+  return `hosted-receipt:${createHash('sha256')
+    .update(JSON.stringify({ recordId, payload }))
+    .digest('hex')
+    .slice(0, 12)}`;
+}
+
+function parseOperationalDispatchRecord(raw: unknown): OperationalDispatchRecord {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('record must be a YAML object');
+  }
+  const record = raw as Record<string, unknown>;
+  if (record.schema !== 'operational-dispatch-record.v0') {
+    throw new Error('record schema must be operational-dispatch-record.v0');
+  }
+  return {
+    schema: 'operational-dispatch-record.v0',
+    record_id: sanitizeOpaqueRef(record.record_id, 'record.record_id', 128),
+    recorded_at: trimString(record.recorded_at, 'record.recorded_at'),
+    recorded_by: sanitizeOpaqueRef(record.recorded_by, 'record.recorded_by', 64),
+    task_ref: sanitizeOpaqueRef(record.task_ref, 'record.task_ref', 128),
+    seat: sanitizeOpaqueRef(record.seat, 'record.seat', 64),
+    decision: assertOperationalDecision(record.decision),
+    reasons: assertStringArray(record.reasons, 'record.reasons'),
+    warnings: assertStringArray(record.warnings, 'record.warnings'),
+    profile_hint: record.profile_hint as OperationalDispatchRecord['profile_hint'],
+    receipt_ref: sanitizeRepoRelative(record.receipt_ref, 'record.receipt_ref'),
+    ledger_ref: sanitizeRepoRelative(record.ledger_ref, 'record.ledger_ref'),
+    authority_boundary: assertRecordAuthorityBoundary(record.authority_boundary),
+    source_decision: record.source_decision as OperationalDispatchRecord['source_decision'],
+  };
+}
+
+export async function loadOperationalDispatchRecord(path: string): Promise<OperationalDispatchRecord> {
+  return parseOperationalDispatchRecord(parseYaml(await readFile(path, 'utf-8')));
+}
+
+export function projectDispatchRecordToHostedReceipt(options: {
+  record: OperationalDispatchRecord;
+  artifactRef?: string;
+  receiptRef?: string;
+  status?: string;
+  validationSummary?: string;
+}): HostedReceiptMetadataProjection {
+  const status = options.status
+    ? assertHostedReceiptStatus(options.status)
+    : defaultHostedStatus(options.record.decision);
+  const payload: HostedReceiptMetadataProjection['hosted_payload'] = {
+    task_id: sanitizeOpaqueRef(options.record.task_ref, 'hosted_payload.task_id', 128),
+    seat_id: sanitizeOpaqueRef(options.record.seat, 'hosted_payload.seat_id', 64),
+    status,
+    receipt_ref: sanitizeRepoRelative(options.receiptRef ?? options.record.receipt_ref, 'hosted_payload.receipt_ref'),
+    validation_summary: sanitizeSummary(options.validationSummary ?? defaultValidationSummary(options.record)),
+  };
+  const artifactRef = options.artifactRef
+    ? sanitizeArtifactRef(options.artifactRef, 'hosted_payload.artifact_ref')
+    : undefined;
+  if (artifactRef) {
+    payload.artifact_ref = artifactRef;
+  }
+  return {
+    schema: 'hosted-receipt-metadata-projection.v0',
+    projection_id: projectionId(payload, options.record.record_id),
+    source_schema: 'operational-dispatch-record.v0',
+    source_record_id: options.record.record_id,
+    hosted_payload: payload,
+    authority_boundary: {
+      hosted_plane_can_execute: false,
+      hosted_plane_can_authorize: false,
+      hosted_plane_can_attach_grant: false,
+      hosted_plane_can_change_local_ledger: false,
+    },
+    projection_boundary: {
+      metadata_only: true,
+      raw_receipt_body_included: false,
+      source_decision_included: false,
+      local_paths_included: false,
+    },
+  };
+}

package/packages/control/src/dispatch/record.ts

@@ -0,0 +1,153 @@
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { sanitize } from '../fs';
+import { formatLedgerEntryLine, type LedgerEntryV0 } from '../ledger/entry';
+import type { OperationalDispatchDecision } from './decision';
+
+export interface OperationalDispatchRecord {
+  schema: 'operational-dispatch-record.v0';
+  record_id: string;
+  recorded_at: string;
+  recorded_by: string;
+  task_ref: string;
+  seat: string;
+  decision: OperationalDispatchDecision['decision'];
+  reasons: string[];
+  warnings: string[];
+  profile_hint: OperationalDispatchDecision['profile_hint'];
+  receipt_ref: string;
+  ledger_ref: string;
+  authority_boundary: OperationalDispatchDecision['authority_boundary'];
+  source_decision: OperationalDispatchDecision;
+}
+
+export interface RecordedDispatch {
+  record: OperationalDispatchRecord;
+  receiptPath: string;
+  ledgerPath: string;
+}
+
+function assertIsoTimestamp(value: string): void {
+  if (!Number.isFinite(Date.parse(value))) {
+    throw new Error('--at must be an ISO-8601 timestamp');
+  }
+}
+
+function isoNow(at?: string): string {
+  const value = at ?? new Date().toISOString();
+  assertIsoTimestamp(value);
+  return new Date(value).toISOString();
+}
+
+function assertOpaqueId(value: string, name: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) {
+    throw new Error(`${name} must be an opaque id using letters, numbers, hyphen, or underscore`);
+  }
+}
+
+function projectRelative(projectRoot: string, path: string): string {
+  const resolvedRoot = resolve(projectRoot);
+  const resolvedPath = resolve(path);
+  const rel = relative(resolvedRoot, resolvedPath);
+  if (rel.length === 0 || rel.startsWith('..') || rel.includes('\\')) {
+    throw new Error(`path must stay inside project root: ${path}`);
+  }
+  return rel;
+}
+
+function hashDecision(decision: OperationalDispatchDecision, recordedAt: string): string {
+  return createHash('sha256')
+    .update(JSON.stringify({ decision, recordedAt }))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+function taskSlug(taskRef: string): string {
+  return sanitize(taskRef).slice(0, 48) || 'task';
+}
+
+async function ensureLedger(ledgerPath: string): Promise<void> {
+  await mkdir(dirname(ledgerPath), { recursive: true });
+  try {
+    await readFile(ledgerPath, 'utf-8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    await writeFile(ledgerPath, '# Local Ledger\n\n');
+  }
+}
+
+function ledgerLine(record: OperationalDispatchRecord): string {
+  const reasons = record.reasons.join(',') || 'none';
+  const entry: LedgerEntryV0 = {
+    schema: 'ledger-entry.v0',
+    entry_id: `ledger-entry:${record.record_id}`,
+    created_at: record.recorded_at,
+    entry_type: 'decision',
+    spine_eligible: true,
+    authority: {
+      class: 'advisory',
+      grants_execution: false,
+    },
+    refs: {
+      receipts: [record.receipt_ref],
+    },
+    export_class: 'workspace_shared',
+    summary: `dispatch ${record.decision} for ${record.task_ref}`,
+  };
+
+  return formatLedgerEntryLine(entry, {
+    task: record.task_ref,
+    seat: record.seat,
+    decision: record.decision,
+    reasons,
+    receipt: record.receipt_ref,
+    authority: 'advisory-only',
+  });
+}
+
+export async function recordOperationalDispatch(options: {
+  projectRoot: string;
+  decision: OperationalDispatchDecision;
+  recordedBy?: string;
+  at?: string;
+}): Promise<RecordedDispatch> {
+  const projectRoot = resolve(options.projectRoot);
+  const recordedAt = isoNow(options.at);
+  const recordedBy = options.recordedBy ?? options.decision.seat;
+  assertOpaqueId(recordedBy, '--recorded-by');
+
+  const slug = taskSlug(options.decision.task_ref);
+  const hash = hashDecision(options.decision, recordedAt);
+  const recordId = `dispatch-record:${slug}:${hash}`;
+  const stamp = recordedAt.replace(/[:.]/g, '-');
+  const receiptPath = join(projectRoot, 'docs', 'work', 'receipts', `${stamp}-${slug}-${hash}.yaml`);
+  const ledgerPath = join(projectRoot, 'docs', 'work', 'ledger', 'LEDGER.md');
+  const receiptRef = projectRelative(projectRoot, receiptPath);
+  const ledgerRef = projectRelative(projectRoot, ledgerPath);
+
+  const record: OperationalDispatchRecord = {
+    schema: 'operational-dispatch-record.v0',
+    record_id: recordId,
+    recorded_at: recordedAt,
+    recorded_by: recordedBy,
+    task_ref: options.decision.task_ref,
+    seat: options.decision.seat,
+    decision: options.decision.decision,
+    reasons: options.decision.reasons,
+    warnings: options.decision.warnings,
+    profile_hint: options.decision.profile_hint,
+    receipt_ref: receiptRef,
+    ledger_ref: ledgerRef,
+    authority_boundary: options.decision.authority_boundary,
+    source_decision: options.decision,
+  };
+
+  await mkdir(dirname(receiptPath), { recursive: true });
+  await writeFile(receiptPath, stringifyYaml(record));
+  await ensureLedger(ledgerPath);
+  await appendFile(ledgerPath, `${ledgerLine(record)}\n`);
+
+  return { record, receiptPath, ledgerPath };
+}

package/packages/control/src/engagement/project.ts

@@ -0,0 +1,170 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export const PROJECT_BINDING_SCHEMA = 'project-binding.v0';
+
+export interface ProjectBinding {
+  schema: typeof PROJECT_BINDING_SCHEMA;
+  project_id: string;
+  project_name: string;
+  project_ref: '.';
+  created_at: string;
+  authority_boundary: {
+    project_binding_authorizes_work: false;
+    can_merge: false;
+    can_close: false;
+    can_grant: false;
+    can_write_global_ledger: false;
+  };
+}
+
+const PROJECT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$/;
+
+export function projectBindingPath(projectRoot: string): string {
+  return join(resolve(projectRoot), '.etiquette', 'project.yaml');
+}
+
+function safeProjectName(root: string): string {
+  return basename(resolve(root)).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'project';
+}
+
+function assertProjectId(value: string, label = 'project_id'): void {
+  if (!PROJECT_ID_RE.test(value)) {
+    throw new Error(`${label} must be an opaque id using letters, numbers, hyphen, or underscore`);
+  }
+}
+
+function assertIsoTimestamp(value: string, label: string): void {
+  if (!Number.isFinite(Date.parse(value))) throw new Error(`${label} must be an ISO-8601 timestamp`);
+}
+
+function renderProjectBinding(binding: ProjectBinding): string {
+  return [
+    `schema: ${binding.schema}`,
+    `project_id: ${binding.project_id}`,
+    `project_name: ${binding.project_name}`,
+    'project_ref: .',
+    `created_at: ${binding.created_at}`,
+    'authority_boundary:',
+    '  project_binding_authorizes_work: false',
+    '  can_merge: false',
+    '  can_close: false',
+    '  can_grant: false',
+    '  can_write_global_ledger: false',
+    '',
+  ].join('\n');
+}
+
+export function validateProjectBinding(value: unknown): ProjectBinding {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error('project binding must be an object');
+  }
+  const record = value as Record<string, unknown>;
+  if (record.schema !== PROJECT_BINDING_SCHEMA) {
+    throw new Error(`project binding schema must be ${PROJECT_BINDING_SCHEMA}`);
+  }
+  if (typeof record.project_id !== 'string') throw new Error('project_id is required');
+  if (typeof record.project_name !== 'string' || record.project_name.trim().length === 0) {
+    throw new Error('project_name is required');
+  }
+  if (record.project_ref !== '.') throw new Error('project_ref must be .');
+  if (typeof record.created_at !== 'string') throw new Error('created_at is required');
+  assertProjectId(record.project_id);
+  assertIsoTimestamp(record.created_at, 'created_at');
+  const boundary = record.authority_boundary;
+  if (typeof boundary !== 'object' || boundary === null || Array.isArray(boundary)) {
+    throw new Error('authority_boundary is required');
+  }
+  for (const key of [
+    'project_binding_authorizes_work',
+    'can_merge',
+    'can_close',
+    'can_grant',
+    'can_write_global_ledger',
+  ]) {
+    if ((boundary as Record<string, unknown>)[key] !== false) {
+      throw new Error(`authority_boundary.${key} must be false`);
+    }
+  }
+  return {
+    schema: PROJECT_BINDING_SCHEMA,
+    project_id: record.project_id,
+    project_name: record.project_name.trim(),
+    project_ref: '.',
+    created_at: new Date(record.created_at).toISOString(),
+    authority_boundary: {
+      project_binding_authorizes_work: false,
+      can_merge: false,
+      can_close: false,
+      can_grant: false,
+      can_write_global_ledger: false,
+    },
+  };
+}
+
+export async function readProjectBinding(projectRoot: string): Promise<ProjectBinding | null> {
+  const path = projectBindingPath(projectRoot);
+  if (!existsSync(path)) return null;
+  return validateProjectBinding(parseYaml(await readFile(path, 'utf-8')));
+}
+
+export async function ensureProjectBinding(projectRoot: string, at?: string): Promise<ProjectBinding> {
+  const existing = await readProjectBinding(projectRoot);
+  if (existing) return existing;
+  const root = resolve(projectRoot);
+  const createdAt = at ? new Date(at).toISOString() : new Date().toISOString();
+  assertIsoTimestamp(createdAt, 'created_at');
+  const projectName = safeProjectName(root);
+  const binding: ProjectBinding = {
+    schema: PROJECT_BINDING_SCHEMA,
+    project_id: `${projectName}-${randomUUID().slice(0, 8)}`,
+    project_name: projectName,
+    project_ref: '.',
+    created_at: createdAt,
+    authority_boundary: {
+      project_binding_authorizes_work: false,
+      can_merge: false,
+      can_close: false,
+      can_grant: false,
+      can_write_global_ledger: false,
+    },
+  };
+  await mkdir(dirname(projectBindingPath(root)), { recursive: true });
+  await writeFile(projectBindingPath(root), renderProjectBinding(binding));
+  return binding;
+}
+
+export function assertEngagementProject(
+  actualProjectId: string | null | undefined,
+  expectedProjectId: string | null | undefined,
+  context: string,
+): void {
+  if (!expectedProjectId) return;
+  assertProjectId(expectedProjectId, '--expect-project-id');
+  if (!actualProjectId) {
+    throw new Error(`engagement mismatch: ${context} has no project_id; expected ${expectedProjectId}`);
+  }
+  if (actualProjectId !== expectedProjectId) {
+    throw new Error(
+      `ERROR: different engagement - ${context} project_id=${actualProjectId} does not match expected project_id=${expectedProjectId}`,
+    );
+  }
+}
+
+export function assertSessionProject(
+  sessionProjectId: string | null | undefined,
+  currentProjectId: string,
+  context: string,
+): void {
+  if (!sessionProjectId) {
+    throw new Error(`engagement mismatch: ${context} has no project_id; recreate the session under the current project`);
+  }
+  if (sessionProjectId !== currentProjectId) {
+    throw new Error(
+      `ERROR: different engagement - ${context} project_id=${sessionProjectId} does not match current project_id=${currentProjectId}`,
+    );
+  }
+}

package/packages/control/src/fs.ts

@@ -0,0 +1,19 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export function now(): string {
+  return new Date().toISOString();
+}
+
+export function sanitize(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+export async function readJson<T>(path: string): Promise<T> {
+  return JSON.parse(await readFile(path, 'utf-8')) as T;
+}
+
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}