@openprd/cli 0.1.19 → 0.1.22

package/src/kernel/atomic-store.js

@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+class AtomicStoreConflictError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'AtomicStoreConflictError';
+    this.code = 'OPENPRD_ATOMIC_STORE_CONFLICT';
+    Object.assign(this, details);
+  }
+}
+
+class AtomicStoreLockTimeoutError extends Error {
+  constructor(lockPath, timeoutMs) {
+    super(`Timed out after ${timeoutMs}ms waiting for lock ${lockPath}`);
+    this.name = 'AtomicStoreLockTimeoutError';
+    this.code = 'OPENPRD_LOCK_TIMEOUT';
+    this.lockPath = lockPath;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+class JsonlCorruptionError extends Error {
+  constructor(filePath, line, cause) {
+    super(`JSONL corruption in ${filePath} at line ${line}: ${cause.message}`);
+    this.name = 'JsonlCorruptionError';
+    this.code = 'OPENPRD_JSONL_CORRUPTION';
+    this.filePath = filePath;
+    this.line = line;
+    this.cause = cause;
+  }
+}
+
+function timeValue(clock = () => new Date()) {
+  const value = clock();
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? new Date() : date;
+}
+
+async function fileExists(filePath) {
+  return fs.access(filePath).then(() => true, () => false);
+}
+
+async function syncDirectory(directory) {
+  let handle;
+  try {
+    handle = await fs.open(directory, 'r');
+    await handle.sync();
+  } catch {
+    // Directory fsync is not available on every supported filesystem.
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+async function atomicWriteText(filePath, text, options = {}) {
+  const directory = path.dirname(filePath);
+  await fs.mkdir(directory, { recursive: true });
+  const temporaryPath = path.join(
+    directory,
+    `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  let handle;
+  try {
+    handle = await fs.open(temporaryPath, 'wx', options.mode ?? 0o600);
+    await handle.writeFile(text, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await fs.rename(temporaryPath, filePath);
+    await syncDirectory(directory);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await fs.rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function atomicWriteJson(filePath, value, options = {}) {
+  const serialized = JSON.stringify(value, null, options.indent ?? 2);
+  if (serialized === undefined) throw new TypeError('atomicWriteJson value must be JSON-serializable');
+  await atomicWriteText(filePath, `${serialized}\n`, options);
+  return value;
+}
+
+async function readJsonIfExists(filePath, fallback = null) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    throw error;
+  }
+}
+
+async function isStaleLock(lockPath, staleLockMs, now) {
+  try {
+    const [stat, raw] = await Promise.all([
+      fs.stat(lockPath),
+      fs.readFile(lockPath, 'utf8').catch(() => ''),
+    ]);
+    let recordedAt = Number.NaN;
+    try {
+      recordedAt = Date.parse(JSON.parse(raw).createdAt);
+    } catch {
+      // A truncated lock is judged by its filesystem timestamp.
+    }
+    const newestTimestamp = Math.max(stat.mtimeMs, Number.isNaN(recordedAt) ? 0 : recordedAt);
+    return now.getTime() - newestTimestamp > staleLockMs;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function releaseOwnedLock(lockPath, token) {
+  let lock;
+  try {
+    lock = JSON.parse(await fs.readFile(lockPath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    return;
+  }
+  if (lock.token === token) await fs.rm(lockPath, { force: true });
+}
+
+async function withFileLock(lockPath, operation, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const staleLockMs = options.staleLockMs ?? 30_000;
+  const retryDelayMs = options.retryDelayMs ?? 10;
+  const clock = options.clock ?? (() => new Date());
+  const token = options.token ?? `${process.pid}:${randomUUID()}`;
+  const startedAt = Date.now();
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+
+  while (true) {
+    let handle;
+    let created = false;
+    try {
+      handle = await fs.open(lockPath, 'wx', 0o600);
+      created = true;
+      await handle.writeFile(`${JSON.stringify({
+        token,
+        pid: process.pid,
+        createdAt: timeValue(clock).toISOString(),
+      })}\n`, 'utf8');
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      break;
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      if (created) await fs.rm(lockPath, { force: true }).catch(() => {});
+      if (error.code !== 'EEXIST') throw error;
+      const now = timeValue(clock);
+      if (await isStaleLock(lockPath, staleLockMs, now)) {
+        await fs.rm(lockPath, { force: true }).catch(() => {});
+        continue;
+      }
+      if (Date.now() - startedAt >= timeoutMs) throw new AtomicStoreLockTimeoutError(lockPath, timeoutMs);
+      await delay(retryDelayMs);
+    }
+  }
+
+  try {
+    return await operation({ token, lockPath });
+  } finally {
+    await releaseOwnedLock(lockPath, token);
+  }
+}
+
+async function compareAndSwapJson(filePath, options = {}) {
+  const revisionField = options.revisionField ?? 'revision';
+  const expectedRevision = options.expectedRevision ?? 0;
+  const lockPath = options.lockPath ?? `${filePath}.lock`;
+  return withFileLock(lockPath, async () => {
+    const currentValue = await readJsonIfExists(filePath, null);
+    const actualRevision = currentValue === null ? 0 : currentValue?.[revisionField];
+    if (!Number.isSafeInteger(actualRevision) || actualRevision < 0) {
+      throw new AtomicStoreConflictError(`Stored revision at ${filePath} is invalid`, {
+        filePath,
+        expectedRevision,
+        actualRevision,
+      });
+    }
+    if (actualRevision !== expectedRevision) {
+      throw new AtomicStoreConflictError(
+        `Revision conflict at ${filePath}: expected ${expectedRevision}, found ${actualRevision}`,
+        { filePath, expectedRevision, actualRevision, currentValue },
+      );
+    }
+    const nextValue = typeof options.nextValue === 'function'
+      ? await options.nextValue(currentValue)
+      : options.nextValue;
+    if (nextValue === undefined) throw new TypeError('compareAndSwapJson requires nextValue');
+    await atomicWriteJson(filePath, nextValue, options);
+    return { previousValue: currentValue, value: nextValue };
+  }, options);
+}
+
+function parseJsonl(filePath, text) {
+  const records = [];
+  const endsWithNewline = text.endsWith('\n');
+  const lines = text.split('\n');
+  let characterOffset = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const physicalLine = lines[index];
+    const line = physicalLine.endsWith('\r') ? physicalLine.slice(0, -1) : physicalLine;
+    const lineCharacterLength = physicalLine.length + (index < lines.length - 1 ? 1 : 0);
+    if (line.trim()) {
+      try {
+        records.push(JSON.parse(line));
+      } catch (error) {
+        const isIncompleteTail = !endsWithNewline && index === lines.length - 1;
+        if (!isIncompleteTail) throw new JsonlCorruptionError(filePath, index + 1, error);
+        return {
+          records,
+          cleanText: text.slice(0, characterOffset),
+          recovered: true,
+          recoveredBytes: Buffer.byteLength(text.slice(characterOffset), 'utf8'),
+          missingFinalNewline: false,
+        };
+      }
+    }
+    characterOffset += lineCharacterLength;
+  }
+  return {
+    records,
+    cleanText: text,
+    recovered: Boolean(text) && !endsWithNewline,
+    recoveredBytes: 0,
+    missingFinalNewline: Boolean(text) && !endsWithNewline,
+  };
+}
+
+async function readJsonlRecovered(filePath, options = {}) {
+  let text;
+  try {
+    text = await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { records: [], recovered: false, recoveredBytes: 0, repaired: false };
+    }
+    throw error;
+  }
+  const result = parseJsonl(filePath, text);
+  let repaired = false;
+  if (options.repair && result.recovered) {
+    const repairedText = result.cleanText
+      ? `${result.cleanText.replace(/\n?$/, '\n')}`
+      : '';
+    await atomicWriteText(filePath, repairedText, options);
+    repaired = true;
+  }
+  return {
+    records: result.records,
+    recovered: result.recovered,
+    recoveredBytes: result.recoveredBytes,
+    repaired,
+  };
+}
+
+async function recoverJsonlTail(filePath, options = {}) {
+  return readJsonlRecovered(filePath, { ...options, repair: true });
+}
+
+async function appendJsonlAtomic(filePath, value, options = {}) {
+  const lockPath = options.lockPath ?? `${filePath}.lock`;
+  return withFileLock(lockPath, async () => {
+    await recoverJsonlTail(filePath, options);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) throw new TypeError('appendJsonlAtomic value must be JSON-serializable');
+    const handle = await fs.open(filePath, 'a', options.mode ?? 0o600);
+    try {
+      await handle.writeFile(`${serialized}\n`, 'utf8');
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    return value;
+  }, options);
+}
+
+export {
+  AtomicStoreConflictError,
+  AtomicStoreLockTimeoutError,
+  JsonlCorruptionError,
+  appendJsonlAtomic,
+  atomicWriteJson,
+  atomicWriteText,
+  compareAndSwapJson,
+  fileExists,
+  readJsonIfExists,
+  readJsonlRecovered,
+  recoverJsonlTail,
+  withFileLock,
+};

package/src/kernel/event-envelope.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+
+const EVENT_ENVELOPE_SCHEMA = 'openprd.event';
+const EVENT_ENVELOPE_VERSION = 1;
+
+class EventEnvelopeValidationError extends Error {
+  constructor(errors) {
+    super(`Invalid OpenPrd event envelope: ${errors.map((item) => `${item.path} ${item.message}`).join('; ')}`);
+    this.name = 'EventEnvelopeValidationError';
+    this.code = 'OPENPRD_INVALID_EVENT_ENVELOPE';
+    this.errors = errors;
+  }
+}
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function inspectJsonValue(value, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return null;
+  if (typeof value === 'number') return Number.isFinite(value) ? null : 'must not contain non-finite numbers';
+  if (typeof value !== 'object') return `must not contain ${typeof value} values`;
+  if (seen.has(value)) return 'must not contain circular references';
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const error = inspectJsonValue(item, seen);
+      if (error) return error;
+    }
+    seen.delete(value);
+    return null;
+  }
+  if (!isPlainObject(value)) return 'must contain only plain JSON objects';
+  for (const item of Object.values(value)) {
+    const error = inspectJsonValue(item, seen);
+    if (error) return error;
+  }
+  seen.delete(value);
+  return null;
+}
+
+function canonicalize(value) {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((item) => canonicalize(item));
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .filter((key) => value[key] !== undefined)
+      .map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+function canonicalJson(value) {
+  const error = inspectJsonValue(value);
+  if (error) throw new TypeError(`Value is not canonical JSON: ${error}`);
+  return JSON.stringify(canonicalize(value));
+}
+
+function normalizeTimestamp(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? String(value ?? '') : date.toISOString();
+}
+
+function eventIdentitySeed(value) {
+  const { eventId: _eventId, ...seed } = value ?? {};
+  return seed;
+}
+
+function createStableEventId(value) {
+  const digest = createHash('sha256')
+    .update(canonicalJson(eventIdentitySeed(value)))
+    .digest('hex');
+  return `evt_${digest.slice(0, 32)}`;
+}
+
+function validateEventEnvelope(envelope) {
+  const errors = [];
+  const add = (path, message) => errors.push({ path, message });
+  if (!isPlainObject(envelope)) {
+    add('$', 'must be a plain object');
+    return { ok: false, errors };
+  }
+  if (envelope.schema !== EVENT_ENVELOPE_SCHEMA) add('schema', `must equal ${EVENT_ENVELOPE_SCHEMA}`);
+  if (envelope.version !== EVENT_ENVELOPE_VERSION) add('version', `must equal ${EVENT_ENVELOPE_VERSION}`);
+  if (typeof envelope.eventId !== 'string' || !envelope.eventId.trim()) add('eventId', 'must be a non-empty string');
+  if (typeof envelope.eventType !== 'string' || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/i.test(envelope.eventType)) {
+    add('eventType', 'must be a dotted, underscored, or dashed event name');
+  }
+  if (typeof envelope.projectId !== 'string' || !envelope.projectId.trim()) add('projectId', 'must be a non-empty string');
+  if (
+    typeof envelope.streamId !== 'string'
+    || !envelope.streamId.trim()
+    || envelope.streamId.includes('..')
+    || /[\0\r\n]/.test(envelope.streamId)
+  ) {
+    add('streamId', 'must be a safe non-empty logical stream ID');
+  }
+  if (!Number.isSafeInteger(envelope.revision) || envelope.revision < 1) add('revision', 'must be a positive safe integer');
+  if (typeof envelope.occurredAt !== 'string' || Number.isNaN(Date.parse(envelope.occurredAt))) {
+    add('occurredAt', 'must be an ISO-compatible timestamp');
+  }
+  if (!isPlainObject(envelope.actor) || typeof envelope.actor.type !== 'string' || !envelope.actor.type.trim()) {
+    add('actor', 'must be an object with a non-empty type');
+  } else if (envelope.actor.id !== undefined && (typeof envelope.actor.id !== 'string' || !envelope.actor.id.trim())) {
+    add('actor.id', 'must be a non-empty string when present');
+  } else {
+    const actorError = inspectJsonValue(envelope.actor);
+    if (actorError) add('actor', actorError);
+  }
+  const payloadError = inspectJsonValue(envelope.payload);
+  if (!isPlainObject(envelope.payload) || payloadError) add('payload', payloadError ?? 'must be a plain object');
+  const metadataError = inspectJsonValue(envelope.metadata);
+  if (!isPlainObject(envelope.metadata) || metadataError) add('metadata', metadataError ?? 'must be a plain object');
+  for (const field of ['causationId', 'correlationId']) {
+    if (envelope[field] !== null && envelope[field] !== undefined && (typeof envelope[field] !== 'string' || !envelope[field].trim())) {
+      add(field, 'must be a non-empty string or null');
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function assertEventEnvelope(envelope) {
+  const validation = validateEventEnvelope(envelope);
+  if (!validation.ok) throw new EventEnvelopeValidationError(validation.errors);
+  return envelope;
+}
+
+function createEventEnvelope(input, options = {}) {
+  const clock = options.clock ?? (() => new Date());
+  const occurredAt = normalizeTimestamp(input?.occurredAt ?? clock());
+  const envelopeWithoutId = {
+    schema: EVENT_ENVELOPE_SCHEMA,
+    version: EVENT_ENVELOPE_VERSION,
+    eventType: input?.eventType,
+    projectId: input?.projectId,
+    streamId: input?.streamId,
+    revision: input?.revision,
+    occurredAt,
+    actor: input?.actor ?? { type: 'system' },
+    causationId: input?.causationId ?? null,
+    correlationId: input?.correlationId ?? null,
+    payload: input?.payload ?? {},
+    metadata: input?.metadata ?? {},
+  };
+  const idFactory = options.idFactory ?? createStableEventId;
+  assertEventEnvelope({ ...envelopeWithoutId, eventId: input?.eventId ?? 'evt_pending' });
+  const envelope = {
+    ...envelopeWithoutId,
+    eventId: input?.eventId ?? idFactory(envelopeWithoutId),
+  };
+  return assertEventEnvelope(envelope);
+}
+
+export {
+  EVENT_ENVELOPE_SCHEMA,
+  EVENT_ENVELOPE_VERSION,
+  EventEnvelopeValidationError,
+  assertEventEnvelope,
+  canonicalJson,
+  createEventEnvelope,
+  createStableEventId,
+  validateEventEnvelope,
+};

package/src/kernel/index.js

@@ -0,0 +1,4 @@
+export * from './atomic-store.js';
+export * from './event-envelope.js';
+export * from './project-ledger.js';
+export * from './project-manifest.js';