wowbagger 0.1.0-alpha.1

package/src/namespace.js

@@ -0,0 +1,35 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const NAMESPACE = /^wbns_[a-f0-9]{32}$/;
+
+function namespaceFile(ledgerDirectory) {
+  return path.join(path.resolve(ledgerDirectory), '.wowbagger', 'namespace');
+}
+
+export async function readNamespace(ledgerDirectory) {
+  try {
+    const text = await readFile(namespaceFile(ledgerDirectory), 'utf8');
+    const value = text.trim();
+    return NAMESPACE.test(value) ? value : null;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function provisionNamespace(ledgerDirectory) {
+  const existing = await readNamespace(ledgerDirectory);
+  if (existing) return { namespace: existing, created: false };
+  await mkdir(path.dirname(namespaceFile(ledgerDirectory)), { recursive: true });
+  const namespace = `wbns_${randomBytes(16).toString('hex')}`;
+  const handle = await open(namespaceFile(ledgerDirectory), 'wx');
+  try {
+    await handle.writeFile(`${namespace}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return { namespace, created: true };
+}

package/src/ready.js

@@ -0,0 +1,85 @@
+import { isDependencySatisfied } from './dependencies.js';
+
+export function selectReady(items, asOf) {
+  const byId = new Map(items.map((item) => [item.data.id, item]));
+  const ancestorsBacklogById = new Map();
+
+  return items
+    .filter((item) => isReady(item, byId, ancestorsBacklogById, asOf))
+    .sort((left, right) => comparePriority(left.data, right.data)
+      || compareText(left.data.created, right.data.created)
+      || compareText(left.data.id, right.data.id))
+    .map((item) => item.data.id);
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// Items carrying a priority sort before items without one, then by ascending
+// priority. The core reports the supplied priority; it never invents or
+// recalculates one.
+function comparePriority(left, right) {
+  const hasLeft = typeof left.priority === 'number';
+  const hasRight = typeof right.priority === 'number';
+
+  if (hasLeft !== hasRight) {
+    return hasLeft ? -1 : 1;
+  }
+  if (!hasLeft) {
+    return 0;
+  }
+  return left.priority - right.priority;
+}
+
+function isReady(item, byId, ancestorsBacklogById, asOf) {
+  const { data } = item;
+
+  return data.kind === 'task'
+    && data.status === 'backlog'
+    && (!data.snoozed_until || data.snoozed_until <= asOf)
+    && Array.isArray(data.depends_on)
+    && dependenciesAreSatisfied(data, byId)
+    && ancestorsAreBacklog(data, byId, ancestorsBacklogById);
+}
+
+function dependenciesAreSatisfied(data, byId) {
+  if (data.schema_version === 1) {
+    return data.depends_on.length === 0;
+  }
+  return data.depends_on.every((id) => isDependencySatisfied(byId.get(id)?.data.status));
+}
+
+function ancestorsAreBacklog(data, byId, ancestorsBacklogById) {
+  let parentId = data.parent;
+  const visited = new Set();
+  const path = [];
+  let result = true;
+
+  while (parentId) {
+    if (ancestorsBacklogById.has(parentId)) {
+      result = ancestorsBacklogById.get(parentId);
+      break;
+    }
+
+    if (visited.has(parentId)) {
+      result = false;
+      break;
+    }
+    visited.add(parentId);
+    path.push(parentId);
+
+    const parent = byId.get(parentId);
+    if (!parent || parent.data.status !== 'backlog') {
+      result = false;
+      break;
+    }
+    parentId = parent.data.parent;
+  }
+
+  for (const id of path) {
+    ancestorsBacklogById.set(id, result);
+  }
+
+  return result;
+}

package/src/request.js

@@ -0,0 +1,246 @@
+import { TextDecoder } from 'node:util';
+
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+
+export function parseJsonRequest(bytes) {
+  let source;
+  try {
+    source = UTF8.decode(bytes);
+  } catch {
+    return invalidJson('invalid-utf8');
+  }
+
+  try {
+    const parser = new JsonParser(source);
+    const value = parser.parse();
+    return { value, issues: parser.issues };
+  } catch {
+    return invalidJson();
+  }
+}
+
+export function pointer(parts) {
+  return parts.length === 0 ? '' : `/${parts.map(escapePointerPart).join('/')}`;
+}
+
+export function sortIssues(issues) {
+  return [...issues].sort((left, right) => compareText(left.path, right.path)
+    || compareText(left.code, right.code)
+    || compareText(left.message, right.message));
+}
+
+export class JsonNumber {
+  constructor(source) {
+    this.source = source;
+  }
+}
+
+// `parseJsonRequest` boxes every JSON number as a JsonNumber and builds every
+// object with a null prototype, but every consumer downstream of it compares
+// against plain JS values. This rebuilds the parsed tree into ordinary
+// objects and arrays with the numbers unwrapped.
+//
+// The rebuild MUST use `Object.fromEntries` (or another define-not-assign
+// path). A `normalized[key] = …` loop invokes Object.prototype's `__proto__`
+// setter for the key `__proto__`, which installs the value as the new
+// object's prototype and erases it as an own key — so a caller-supplied
+// `__proto__` member disappears from `Object.keys` and slips past every
+// exact-member schema check downstream.
+export function normalizeJsonValue(value) {
+  if (value instanceof JsonNumber) {
+    return Number(value.source);
+  }
+  if (Array.isArray(value)) {
+    return value.map(normalizeJsonValue);
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, normalizeJsonValue(entry)]));
+  }
+  return value;
+}
+
+function invalidJson(inputDiagnostic = null) {
+  return {
+    value: null,
+    inputDiagnostic,
+    issues: [{
+      path: '',
+      code: 'invalid-json',
+      message: 'Request input must be valid JSON.',
+    }],
+  };
+}
+
+class JsonParser {
+  constructor(source) {
+    this.source = source;
+    this.index = 0;
+    this.issues = [];
+  }
+
+  parse() {
+    this.skipWhitespace();
+    const value = this.value([]);
+    this.skipWhitespace();
+    if (this.index !== this.source.length) {
+      throw new Error('trailing JSON input');
+    }
+    return value;
+  }
+
+  value(location) {
+    this.skipWhitespace();
+    const character = this.source[this.index];
+    if (character === '{') {
+      return this.object(location);
+    }
+    if (character === '[') {
+      return this.array(location);
+    }
+    if (character === '"') {
+      return this.string();
+    }
+    if (this.source.startsWith('true', this.index)) {
+      this.index += 4;
+      return true;
+    }
+    if (this.source.startsWith('false', this.index)) {
+      this.index += 5;
+      return false;
+    }
+    if (this.source.startsWith('null', this.index)) {
+      this.index += 4;
+      return null;
+    }
+    return this.number();
+  }
+
+  object(location) {
+    this.expect('{');
+    this.skipWhitespace();
+    const object = Object.create(null);
+    const seen = new Set();
+    if (this.consume('}')) {
+      return object;
+    }
+
+    while (true) {
+      this.skipWhitespace();
+      if (this.source[this.index] !== '"') {
+        throw new Error('object key is not a string');
+      }
+      const key = this.string();
+      this.skipWhitespace();
+      this.expect(':');
+      const childLocation = [...location, key];
+      const value = this.value(childLocation);
+      if (seen.has(key)) {
+        this.issues.push({
+          path: pointer(childLocation),
+          code: 'duplicate-key',
+          message: `JSON member ${key} must not be repeated.`,
+        });
+      } else {
+        seen.add(key);
+        object[key] = value;
+      }
+      this.skipWhitespace();
+      if (this.consume('}')) {
+        return object;
+      }
+      this.expect(',');
+    }
+  }
+
+  array(location) {
+    this.expect('[');
+    this.skipWhitespace();
+    const values = [];
+    if (this.consume(']')) {
+      return values;
+    }
+    while (true) {
+      values.push(this.value([...location, String(values.length)]));
+      this.skipWhitespace();
+      if (this.consume(']')) {
+        return values;
+      }
+      this.expect(',');
+    }
+  }
+
+  string() {
+    const start = this.index;
+    this.expect('"');
+    let escaped = false;
+    while (this.index < this.source.length) {
+      const character = this.source[this.index];
+      this.index += 1;
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (character === '\\') {
+        escaped = true;
+        continue;
+      }
+      if (character === '"') {
+        return JSON.parse(this.source.slice(start, this.index));
+      }
+      if (character.charCodeAt(0) < 0x20) {
+        throw new Error('unescaped control character');
+      }
+    }
+    throw new Error('unterminated JSON string');
+  }
+
+  number() {
+    const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(this.source.slice(this.index));
+    if (!match) {
+      throw new Error('invalid JSON value');
+    }
+    this.index += match[0].length;
+    return new JsonNumber(match[0]);
+  }
+
+  skipWhitespace() {
+    while (this.index < this.source.length && /[\u0009\u000a\u000d\u0020]/.test(this.source[this.index])) {
+      this.index += 1;
+    }
+  }
+
+  consume(character) {
+    if (this.source[this.index] !== character) {
+      return false;
+    }
+    this.index += 1;
+    return true;
+  }
+
+  expect(character) {
+    if (!this.consume(character)) {
+      throw new Error(`expected ${character}`);
+    }
+  }
+}
+
+function escapePointerPart(part) {
+  return part.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function compareText(left, right) {
+  const leftIterator = left[Symbol.iterator]();
+  const rightIterator = right[Symbol.iterator]();
+  while (true) {
+    const leftValue = leftIterator.next();
+    const rightValue = rightIterator.next();
+    if (leftValue.done || rightValue.done) {
+      return leftValue.done === rightValue.done ? 0 : leftValue.done ? -1 : 1;
+    }
+    const leftPoint = leftValue.value.codePointAt(0);
+    const rightPoint = rightValue.value.codePointAt(0);
+    if (leftPoint !== rightPoint) {
+      return leftPoint < rightPoint ? -1 : 1;
+    }
+  }
+}

package/src/schema-migration.js

@@ -0,0 +1,300 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, readdir, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+
+import { loadLedger, parseLedgerItemSource } from './ledger.js';
+import { validateLedger } from './validate.js';
+
+const MAINTENANCE_NOTICE = 'NOTICE: This is a quiesced-window maintenance operation. Take a backup before --apply; recovery uses that backup and Git, not the mutation contract.';
+const HISTORY_NOTICE = 'NOTICE: Schema 1 cleanup history is unrecoverable. Prerequisites previously moved from depends_on to related stay there; no dependency is inferred.';
+const UTF8_BYTE_ORDER_MARK = Buffer.from([0xef, 0xbb, 0xbf]);
+
+export async function runSchema2MigrationCli(argumentsList, streams = {}) {
+  const stdout = streams.stdout ?? process.stdout;
+  const options = parseArguments(argumentsList);
+
+  stdout.write(`${MAINTENANCE_NOTICE}\n`);
+  stdout.write(`${HISTORY_NOTICE}\n`);
+  const result = await migrateSchema2(options.ledger, {
+    apply: options.apply,
+    onItem: async (change) => {
+      stdout.write(`CHANGED ${change.path} (${change.id}): schema_version 1 -> 2\n`);
+    },
+  });
+
+  if (options.apply) {
+    stdout.write(`Summary: ${result.changes.length} ${itemWord(result.changes.length)} changed.\n`);
+    stdout.write('Validation: schema version 2 passed.\n');
+  } else {
+    for (const change of result.changes) {
+      stdout.write(`WOULD CHANGE ${change.path} (${change.id}): schema_version 1 -> 2\n`);
+    }
+    stdout.write(`Summary: ${result.changes.length} ${itemWord(result.changes.length)} would change; 0 files written (dry run).\n`);
+  }
+}
+
+function itemWord(count) {
+  return count === 1 ? 'item' : 'items';
+}
+
+export async function migrateSchema2(ledgerDirectory, { apply = false, onItem = async () => {} } = {}) {
+  const ledger = await loadLedger(ledgerDirectory);
+  const inputValidation = validateLedger(ledger);
+  const schemaVersions = new Set(ledger.items.map((item) => item.data.schema_version));
+  if (schemaVersions.has(1) && schemaVersions.has(2)) {
+    throw new SchemaMigrationError(
+      'mixed-schema-versions',
+      'The ledger contains schema versions 1 and 2. This is a partial migration state. Restore the complete ledger from the pre-migration backup or Git, validate schema version 1, then rerun the dry run.',
+    );
+  }
+  if (inputValidation.valid && ledger.items.length === 0) {
+    throw new SchemaMigrationError(
+      'empty-ledger',
+      'An empty ledger has no schema_version stamp to migrate and still defaults to schema version 1. No files were changed.',
+    );
+  }
+  if (ledger.items.length > 0 && schemaVersions.size === 1 && schemaVersions.has(2)) {
+    if (!inputValidation.valid) {
+      throw new SchemaMigrationError(
+        'invalid-schema-2',
+        'Every item is schema version 2, but the complete ledger is invalid. Repair the schema version 2 ledger or restore the pre-migration backup or Git. No files were changed.',
+        inputValidation.errors,
+      );
+    }
+    throw new SchemaMigrationError(
+      'already-schema-2',
+      'Every item is already schema version 2. This tool will not run again. Validate the ledger as schema version 2; if validation fails, restore the pre-migration backup or Git.',
+    );
+  }
+  if (!inputValidation.valid) {
+    throw new SchemaMigrationError(
+      'invalid-schema-1',
+      'The ledger must validate completely as schema version 1 before migration. No files were changed.',
+      inputValidation.errors,
+    );
+  }
+  const heldLocks = await heldItemLocks(ledgerDirectory);
+  if (heldLocks.length > 0) {
+    throw new SchemaMigrationError(
+      'lock-held',
+      `Item locks are held under the ledger: ${heldLocks.join(', ')}. The migration requires a quiesced window. Stop all writers and resolve the locks through audited manual recovery before rerunning the dry run. No files were changed.`,
+    );
+  }
+  const changes = ledger.items.map((item) => {
+    const source = schema2Source(item.source);
+    return {
+      id: item.data.id,
+      path: item.path,
+      file: item.file,
+      before: item.bytes,
+      after: migratedBytes(item.bytes, source),
+      source,
+    };
+  });
+
+  const candidate = {
+    errors: [...ledger.errors],
+    items: changes.map((change, index) => candidateItem(ledger.items[index], change)),
+  };
+  const validation = validateLedger(candidate);
+  if (!validation.valid || candidate.items.some((item) => item.data.schema_version !== 2)) {
+    throw new Error('The planned schema version 2 ledger does not validate.');
+  }
+
+  let completed = 0;
+  if (apply) {
+    for (const change of changes) {
+      try {
+        await atomicRewrite(change);
+      } catch {
+        const state = completed === 0
+          ? 'No item write completed.'
+          : 'The ledger now contains mixed schema versions.';
+        throw new SchemaMigrationError(
+          'partial-write-failed',
+          `Migration stopped at ${change.path} after ${completed} of ${changes.length} item writes. ${state} Restore the complete ledger from the pre-migration backup or Git before rerunning.`,
+        );
+      }
+      completed += 1;
+      await onItem(change);
+    }
+
+    const migratedLedger = await loadLedger(ledgerDirectory);
+    const postValidation = validateLedger(migratedLedger);
+    const uniformSchema2 = migratedLedger.items.length > 0
+      && migratedLedger.items.every((item) => item.data.schema_version === 2);
+    if (!postValidation.valid || !uniformSchema2) {
+      throw new SchemaMigrationError(
+        'post-validation-failed',
+        `The post-migration ledger did not validate as schema version 2 after ${completed} of ${changes.length} item writes. Restore the pre-migration backup or Git before any rerun.`,
+        postValidation.errors,
+      );
+    }
+  }
+
+  return { apply, changes, completed };
+}
+
+async function heldItemLocks(ledgerDirectory) {
+  const lockDirectory = path.join(path.resolve(ledgerDirectory), '.wowbagger-locks');
+  let entries;
+  try {
+    entries = await readdir(lockDirectory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return [];
+    }
+    throw new SchemaMigrationError(
+      'lock-state-unknown',
+      'The item-lock directory could not be inspected. Quiescence is not established. No files were changed.',
+    );
+  }
+  return entries
+    .filter((entry) => entry.name.endsWith('.lock'))
+    .map((entry) => `.wowbagger-locks/${entry.name}`)
+    .sort();
+}
+
+export function formatSchemaMigrationError(error) {
+  if (!(error instanceof SchemaMigrationError)) {
+    return `ERROR: ${error.message}\n`;
+  }
+  const diagnostics = error.diagnostics
+    .map((entry) => `${entry.path} ${entry.field} [${entry.code}]: ${entry.message}`)
+    .join('\n');
+  return `ERROR [${error.code}]: ${error.message}\n${diagnostics ? `${diagnostics}\n` : ''}`;
+}
+
+class SchemaMigrationError extends Error {
+  constructor(code, message, diagnostics = []) {
+    super(message);
+    this.code = code;
+    this.diagnostics = diagnostics;
+  }
+}
+
+async function atomicRewrite(change) {
+  const sourceHandle = await open(change.file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let sourceStat;
+  let current;
+  try {
+    sourceStat = await sourceHandle.stat();
+    current = await sourceHandle.readFile();
+  } finally {
+    await sourceHandle.close();
+  }
+  if (!sourceStat.isFile() || !current.equals(change.before)) {
+    throw new Error(`Item changed after migration preflight: ${change.path}.`);
+  }
+
+  const temporary = path.join(
+    path.dirname(change.file),
+    `.wowbagger-schema-2-${process.pid}-${randomUUID()}.tmp`,
+  );
+  let temporaryHandle;
+  try {
+    temporaryHandle = await open(temporary, 'wx', sourceStat.mode & 0o777);
+    await temporaryHandle.writeFile(change.after);
+    await temporaryHandle.chmod(sourceStat.mode & 0o777);
+    await temporaryHandle.sync();
+    await temporaryHandle.close();
+    temporaryHandle = undefined;
+    await rename(temporary, change.file);
+  } finally {
+    await temporaryHandle?.close().catch(() => {});
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+function candidateItem(item, change) {
+  const parsed = parseLedgerItemSource(change.source);
+  if (parsed.error) {
+    return { ...item, data: {}, source: change.source, bytes: change.after };
+  }
+  return {
+    ...item,
+    data: parsed.data,
+    body: parsed.body,
+    source: change.source,
+    bytes: change.after,
+  };
+}
+
+function schema2Source(source) {
+  const bounds = frontmatterBounds(source);
+  const document = parseDocument(source.slice(bounds.start, bounds.end), {
+    prettyErrors: false,
+    schema: 'core',
+    uniqueKeys: true,
+  });
+  const schemaVersion = document.get('schema_version', true);
+  if (!schemaVersion?.range) {
+    throw new Error('The schema_version scalar could not be located.');
+  }
+  const start = bounds.start + schemaVersion.range[0];
+  const end = bounds.start + schemaVersion.range[1];
+  return `${source.slice(0, start)}2${source.slice(end)}`;
+}
+
+function migratedBytes(before, source) {
+  const bytes = Buffer.from(source, 'utf8');
+  return before.subarray(0, UTF8_BYTE_ORDER_MARK.length).equals(UTF8_BYTE_ORDER_MARK)
+    ? Buffer.concat([UTF8_BYTE_ORDER_MARK, bytes])
+    : bytes;
+}
+
+function frontmatterBounds(source) {
+  const opening = nextLine(source, 0);
+  if (opening.content !== '---' || opening.next === null) {
+    throw new Error('The item frontmatter could not be located.');
+  }
+  const start = opening.next;
+  let cursor = start;
+  while (cursor < source.length) {
+    const line = nextLine(source, cursor);
+    if (line.content === '---') {
+      return { start, end: cursor };
+    }
+    if (line.next === null) {
+      break;
+    }
+    cursor = line.next;
+  }
+  throw new Error('The item frontmatter could not be located.');
+}
+
+function nextLine(source, start) {
+  const lf = source.indexOf('\n', start);
+  if (lf === -1) {
+    return { content: source.slice(start), next: null };
+  }
+  const carriageReturn = lf > start && source[lf - 1] === '\r';
+  return {
+    content: source.slice(start, carriageReturn ? lf - 1 : lf),
+    next: lf + 1,
+  };
+}
+
+function parseArguments(argumentsList) {
+  let ledger;
+  let apply = false;
+
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === '--ledger' && ledger === undefined && index + 1 < argumentsList.length) {
+      ledger = argumentsList[index + 1];
+      index += 1;
+    } else if (argument === '--apply' && !apply) {
+      apply = true;
+    } else {
+      throw new Error('Usage: node scripts/migrate-schema-2.js --ledger <dir> [--apply]');
+    }
+  }
+
+  if (ledger === undefined) {
+    throw new Error('Usage: node scripts/migrate-schema-2.js --ledger <dir> [--apply]');
+  }
+  return { ledger, apply };
+}