@cassiomc1/forgeloop 0.1.0 → 0.1.2

package/src/core/artifacts.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+
+import { assertSafePath, ensureWithin, fileExists, readBytes, writeFileAtomic } from "./filesystem.js";
+import { assertSecretFree } from "./receipt.js";
+import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { getPackageRoot } from "./templates.js";
+
+export const ARTIFACT_PATHS = Object.freeze({
+  contract: ".forgeloop/current-contract.json",
+  route: ".forgeloop/routing-result.json",
+  preflight: ".forgeloop/preflight.json",
+  sources: ".forgeloop/sources.json",
+  events: ".forgeloop/events.ndjson",
+  session: ".forgeloop/session.json",
+  config: ".forgeloop/config.json",
+  gates: ".forgeloop/gates",
+  state: ".forgeloop/work-state.json",
+  receipt: ".forgeloop/execution-receipt.json",
+});
+
+export class ArtifactError extends Error {
+  constructor(code, message, artifacts = []) {
+    super(message);
+    this.name = "ArtifactError";
+    this.code = code;
+    this.artifacts = artifacts;
+  }
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
+    );
+  }
+  return value;
+}
+
+export function canonicalFingerprint(value) {
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalize(value)))
+    .digest("hex");
+}
+
+function artifactError(code, relativePath, error) {
+  if (error instanceof ArtifactError) return error;
+  return new ArtifactError(
+    code,
+    `${relativePath}: ${error.message}`,
+    [relativePath],
+  );
+}
+
+export async function readJsonArtifact(
+  target,
+  relativePath,
+  schemaName,
+  packageRoot = getPackageRoot(),
+) {
+  try {
+    await assertSafePath(target, relativePath);
+  } catch (error) {
+    throw artifactError("ARTIFACT_PATH_INVALID", relativePath, error);
+  }
+
+  const artifactPath = ensureWithin(target, relativePath);
+  if (!(await fileExists(artifactPath))) {
+    throw new ArtifactError(
+      "ARTIFACT_MISSING",
+      `Artifact is missing: ${relativePath}`,
+      [relativePath],
+    );
+  }
+
+  let value;
+  try {
+    const bytes = await readBytes(artifactPath);
+    assertJsonBytes(bytes, relativePath);
+    value = JSON.parse(bytes.toString("utf8"));
+    assertJsonLimits(value, relativePath);
+    const schema = await readSchema(schemaName, packageRoot);
+    assertSchema(value, schema, relativePath);
+  } catch (error) {
+    throw artifactError(
+      ["JSON_LIMIT_EXCEEDED", "ARTIFACT_PATH_INVALID"].includes(error.code)
+        ? error.code
+        : "ARTIFACT_INVALID",
+      relativePath,
+      error,
+    );
+  }
+
+  return {
+    value,
+    path: relativePath,
+    fingerprint: canonicalFingerprint(value),
+  };
+}
+
+export async function writeJsonArtifact(
+  target,
+  relativePath,
+  value,
+  schemaName,
+  packageRoot = getPackageRoot(),
+  { dryRun = false } = {},
+) {
+  try {
+    await assertSafePath(target, relativePath);
+  } catch (error) {
+    throw artifactError("ARTIFACT_PATH_INVALID", relativePath, error);
+  }
+  try {
+    const artifactPath = ensureWithin(target, relativePath);
+    assertSecretFree(value);
+    const schema = await readSchema(schemaName, packageRoot);
+    assertSchema(value, schema, relativePath);
+    assertJsonLimits(value, relativePath);
+    const serialized = `${JSON.stringify(value, null, 2)}\n`;
+    assertJsonBytes(serialized, relativePath);
+    await writeFileAtomic(artifactPath, serialized, { dryRun });
+    return { path: relativePath, fingerprint: canonicalFingerprint(value), value };
+  } catch (error) {
+    throw artifactError(
+      error.code === "JSON_LIMIT_EXCEEDED" ? error.code : "ARTIFACT_INVALID",
+      relativePath,
+      error,
+    );
+  }
+}

package/src/core/audit.js

@@ -0,0 +1,88 @@
+import { ARTIFACT_PATHS } from "./artifacts.js";
+import { evaluateCompletion } from "./completion.js";
+import { readManifest } from "./manifest.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { readJsonArtifact } from "./artifacts.js";
+import { currentChangedPaths } from "./repository.js";
+
+function sortErrors(errors) {
+  return [...errors].sort((left, right) => left.code.localeCompare(right.code)
+    || left.message.localeCompare(right.message));
+}
+
+async function compareChangedPaths(target, packageRoot) {
+  let receipt;
+  try {
+    receipt = (await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot)).value;
+  } catch {
+    return { status: "NOT_VERIFIED", expected: [], observed: [], missing: [], unexpected: [] };
+  }
+  const observed = await currentChangedPaths(target);
+  if (observed === null) {
+    return { status: "NOT_VERIFIED", expected: receipt.changedPaths ?? [], observed: [], missing: [], unexpected: [] };
+  }
+  const expected = [...new Set(receipt.changedPaths ?? [])].sort();
+  const missing = expected.filter((relativePath) => !observed.includes(relativePath));
+  const unexpected = observed.filter((relativePath) => !expected.includes(relativePath));
+  return {
+    status: missing.length === 0 && unexpected.length === 0 ? "MATCH" : "MISMATCH",
+    expected,
+    observed,
+    missing,
+    unexpected,
+  };
+}
+
+export async function evaluateAudit({ target, packageRoot, strict = false } = {}) {
+  const completion = await evaluateCompletion({ target, packageRoot, strict });
+  let manifest = null;
+  let manifestError = null;
+  try {
+    manifest = await readManifest(target);
+  } catch (error) {
+    manifestError = error.message;
+  }
+  const errors = sortErrors(completion.errors);
+  const changedPaths = await compareChangedPaths(target, packageRoot);
+  if (changedPaths.status === "MISMATCH") {
+    errors.push({
+      code: "E_RECEIPT_PATH_MISMATCH",
+      message: "Receipt changedPaths do not match observed repository paths",
+      artifacts: [ARTIFACT_PATHS.receipt],
+      missing: changedPaths.missing,
+      unexpected: changedPaths.unexpected,
+      next: "Run forgeloop prepare-completion to refresh changed paths, then rerun audit.",
+    });
+  }
+  const stale = errors.some((error) => error.code.includes("STALE") || error.code === "E_PHASE_ARTIFACT_STALE");
+  const blocked = errors.some((error) => ["E_GATE_UNVERIFIED", "E_GATE_STALE", "E_EVIDENCE_COVERAGE_PARTIAL", "E_PHASE_PREREQUISITE_MISSING"].includes(error.code));
+  const status = errors.length === 0 && completion.status === "VALID"
+    ? "VALID"
+    : stale
+      ? "STALE"
+      : blocked
+        ? "INCOMPLETE"
+        : "INVALID";
+  return {
+    schemaVersion: 1,
+    protocolVersion: PROTOCOL_VERSION,
+    status,
+    strict,
+    errors,
+    warnings: [...completion.warnings, ...(manifestError ? [{ code: "E_INSTALLATION_INVALID", message: manifestError }] : [])],
+    installation: {
+      status: manifest ? "ready" : manifestError ? "invalid" : "missing",
+      manifest: Boolean(manifest),
+    },
+    completion,
+    changedPaths,
+    publicationStatus: completion.publicationStatus,
+    productionReadiness: completion.productionReadiness,
+    artifacts: {
+      contract: ARTIFACT_PATHS.contract,
+      route: ARTIFACT_PATHS.route,
+      state: ARTIFACT_PATHS.state,
+      receipt: ARTIFACT_PATHS.receipt,
+    },
+  };
+}

package/src/core/bundles.js

@@ -0,0 +1,120 @@
+import { readdir } from "node:fs/promises";
+
+import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { readContract, validateContract } from "./contract.js";
+import { assertSafePath, ensureWithin, fileExists, readBytes, writeFileAtomic } from "./filesystem.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+
+export const BUNDLE_SCHEMA_VERSION = 1;
+const BUNDLE_ROOT = ".forgeloop/tasks";
+
+function safeTaskId(taskId) {
+  if (typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(taskId)) {
+    const error = new Error(`Invalid task ID for bundle: ${taskId}`);
+    error.code = "E_BUNDLE_PATH_INVALID";
+    throw error;
+  }
+  return taskId;
+}
+
+function bundleDirectory(taskId) {
+  return `${BUNDLE_ROOT}/${safeTaskId(taskId)}`;
+}
+
+async function copyJson(target, sourcePath, destinationPath, schemaName, packageRoot, artifacts, relativeName) {
+  try {
+    const value = await readJsonArtifact(target, sourcePath, schemaName, packageRoot);
+    await writeJsonArtifact(target, destinationPath, value.value, schemaName, packageRoot);
+    artifacts.push(relativeName);
+    return value;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return null;
+    throw error;
+  }
+}
+
+export async function exportTaskBundle(target, taskId, packageRoot) {
+  safeTaskId(taskId);
+  const directory = bundleDirectory(taskId);
+  const artifacts = [];
+  const required = [
+    [ARTIFACT_PATHS.contract, "contract.json", "current-contract"],
+    [ARTIFACT_PATHS.route, "route.json", "routing-result"],
+    [ARTIFACT_PATHS.state, "state.json", "work-state"],
+  ];
+  for (const [sourcePath, destinationName, schemaName] of required) {
+    const source = schemaName === "current-contract"
+      ? await readContract(target, packageRoot)
+      : await readJsonArtifact(target, sourcePath, schemaName, packageRoot);
+    if (source.value.taskId !== undefined && source.value.taskId !== taskId) {
+      const error = new Error(`${sourcePath} belongs to ${source.value.taskId}, not ${taskId}`);
+      error.code = "E_BUNDLE_TASK_MISMATCH";
+      throw error;
+    }
+    await writeJsonArtifact(target, `${directory}/${destinationName}`, source.value, schemaName, packageRoot);
+    artifacts.push(destinationName);
+  }
+  const optional = [
+    [ARTIFACT_PATHS.preflight, "preflight.json", "preflight"],
+    [ARTIFACT_PATHS.receipt, "receipt.json", "execution-receipt"],
+    [ARTIFACT_PATHS.sources, "sources.json", "source-registry"],
+    [ARTIFACT_PATHS.config, "config.json", "config"],
+  ];
+  for (const [sourcePath, destinationName, schemaName] of optional) {
+    const copied = await copyJson(target, sourcePath, `${directory}/${destinationName}`, schemaName, packageRoot, artifacts, destinationName);
+    if (copied && !artifacts.includes(destinationName)) artifacts.push(destinationName);
+  }
+  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+  if (await fileExists(eventsPath)) {
+    await assertSafePath(target, `${directory}/events.ndjson`);
+    await writeFileAtomic(ensureWithin(target, `${directory}/events.ndjson`), await readBytes(eventsPath));
+    artifacts.push("events.ndjson");
+  }
+  const gateDirectory = ensureWithin(target, ARTIFACT_PATHS.gates);
+  if (await fileExists(gateDirectory)) {
+    const entries = await readdir(gateDirectory, { withFileTypes: true });
+    for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith(".json")).sort((left, right) => left.name.localeCompare(right.name))) {
+      const gateName = entry.name.slice(0, -5);
+      const sourcePath = `${ARTIFACT_PATHS.gates}/${entry.name}`;
+      const destinationPath = `${directory}/gates/${entry.name}`;
+      const gate = await readJsonArtifact(target, sourcePath, "gate", packageRoot);
+      if (gate.value.taskId !== taskId) continue;
+      await writeJsonArtifact(target, destinationPath, gate.value, "gate", packageRoot);
+      artifacts.push(`gates/${gateName}.json`);
+    }
+  }
+  artifacts.sort();
+  const manifest = {
+    schemaVersion: BUNDLE_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId,
+    artifacts,
+  };
+  await writeJsonArtifact(target, `${directory}/bundle.json`, manifest, "task-bundle", packageRoot);
+  return { ...manifest, path: `${directory}/bundle.json` };
+}
+
+export async function readTaskBundle(target, taskId, packageRoot) {
+  const directory = bundleDirectory(taskId);
+  const manifest = await readJsonArtifact(target, `${directory}/bundle.json`, "task-bundle", packageRoot);
+  const loaded = {};
+  const mappings = {
+    "contract.json": ["contract", "current-contract"],
+    "route.json": ["route", "routing-result"],
+    "state.json": ["state", "work-state"],
+    "preflight.json": ["preflight", "preflight"],
+    "receipt.json": ["receipt", "execution-receipt"],
+    "sources.json": ["sources", "source-registry"],
+    "config.json": ["config", "config"],
+  };
+  for (const artifact of manifest.value.artifacts) {
+    const mapping = mappings[artifact];
+    if (!mapping) continue;
+    const loadedArtifact = await readJsonArtifact(target, `${directory}/${artifact}`, mapping[1], packageRoot);
+    if (mapping[1] === "current-contract") {
+      await validateContract(loadedArtifact.value, packageRoot);
+    }
+    loaded[mapping[0]] = loadedArtifact.value;
+  }
+  return { manifest: manifest.value, artifacts: loaded };
+}

package/src/core/checks.js

@@ -0,0 +1,115 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+
+export const CHECK_SCHEMA_VERSION = 1;
+export const CHECK_STATUSES = Object.freeze(["passed", "failed", "blocked", "not-run"]);
+export const CHECK_EVIDENCE_KINDS = Object.freeze(["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED"]);
+
+function checkError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function string(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw checkError("E_CHECK_INVALID", `${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function optionalString(value, label) {
+  if (value !== undefined) string(value, label);
+}
+
+function contradiction(message) {
+  return checkError("E_CHECK_STATUS_CONTRADICTION", message);
+}
+
+export function createCheck(input = {}) {
+  const check = {
+    schemaVersion: CHECK_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    id: input.id,
+    kind: input.kind,
+    requirement: input.requirement,
+    status: input.status ?? "not-run",
+    evidenceKind: input.evidenceKind ?? "NOT_VERIFIED",
+    source: input.source,
+    ...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+    ...(input.timestamp !== undefined ? { timestamp: input.timestamp } : {}),
+    ...(input.repositoryFingerprint !== undefined ? { repositoryFingerprint: input.repositoryFingerprint } : {}),
+    ...(input.viewport !== undefined ? { viewport: structuredClone(input.viewport) } : {}),
+    ...(input.details !== undefined ? { details: structuredClone(input.details) } : {}),
+  };
+  return assertCheck(check);
+}
+
+export function assertCheck(value, label = "check") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw checkError("E_CHECK_INVALID", `${label} must be an object`);
+  }
+  if (value.schemaVersion !== CHECK_SCHEMA_VERSION || value.protocolVersion !== PROTOCOL_VERSION) {
+    throw checkError("E_CHECK_INVALID", `${label} has an unsupported protocol version`);
+  }
+  string(value.id, `${label}.id`);
+  string(value.kind, `${label}.kind`);
+  string(value.requirement, `${label}.requirement`);
+  string(value.source, `${label}.source`);
+  if (!CHECK_STATUSES.includes(value.status)) {
+    throw checkError("E_CHECK_INVALID", `${label}.status must be one of ${CHECK_STATUSES.join(", ")}`);
+  }
+  if (!CHECK_EVIDENCE_KINDS.includes(value.evidenceKind)) {
+    throw checkError("E_EVIDENCE_KIND_INVALID", `${label}.evidenceKind must be one of ${CHECK_EVIDENCE_KINDS.join(", ")}`);
+  }
+  if (value.exitCode !== undefined && (!Number.isInteger(value.exitCode) || value.exitCode < 0)) {
+    throw checkError("E_CHECK_INVALID", `${label}.exitCode must be a non-negative integer`);
+  }
+  optionalString(value.timestamp, `${label}.timestamp`);
+  if (value.status === "passed" && ["NOT_VERIFIED", "BLOCKED"].includes(value.evidenceKind)) {
+    throw contradiction(`${label} passed cannot use ${value.evidenceKind} evidence`);
+  }
+  if (value.status === "passed" && value.exitCode !== undefined && value.exitCode !== 0) {
+    throw contradiction(`${label} passed requires exitCode 0 when exitCode is recorded`);
+  }
+  if (value.status === "blocked" && value.evidenceKind !== "BLOCKED") {
+    throw contradiction(`${label} blocked must use BLOCKED evidence`);
+  }
+  if (value.status === "not-run" && value.evidenceKind !== "NOT_VERIFIED") {
+    throw contradiction(`${label} not-run must use NOT_VERIFIED evidence`);
+  }
+  return value;
+}
+
+export function assertCheckList(value, label = "checks") {
+  if (!Array.isArray(value)) throw checkError("E_CHECK_INVALID", `${label} must be an array`);
+  const ids = new Set();
+  value.forEach((item, index) => {
+    assertCheck(item, `${label}[${index}]`);
+    if (ids.has(item.id)) throw checkError("E_CHECK_INVALID", `${label} contains duplicate id ${item.id}`);
+    ids.add(item.id);
+  });
+  return value;
+}
+
+export function requiredChecksSatisfied(checks, requiredIds, { allowInferred = false } = {}) {
+  assertCheckList(checks);
+  if (!Array.isArray(requiredIds)) throw checkError("E_CHECK_INVALID", "requiredIds must be an array");
+  const byId = new Map(checks.map((check) => [check.id, check]));
+  const errors = [];
+  for (const id of requiredIds) {
+    const check = byId.get(id);
+    if (!check) {
+      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is missing: ${id}`, [id]));
+      continue;
+    }
+    if (check.status !== "passed") {
+      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is not passed: ${id}`, [id]));
+      continue;
+    }
+    if (!allowInferred && check.evidenceKind !== "OBSERVED") {
+      errors.push(checkError("E_EVIDENCE_KIND_INVALID", `Required check must be observed: ${id}`, [id]));
+    }
+  }
+  return errors;
+}