@cassiomc1/forgeloop 0.1.0

package/src/core/inspect.js

@@ -0,0 +1,115 @@
+import { fileExists, ensureWithin, readBytes } from "./filesystem.js";
+import { AGENT_SUPPORT } from "./agent-support.js";
+import { readManifest } from "./manifest.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { inspectSchemaHealth } from "./schema-validation.js";
+import { readAndClassifyWorkState, WORK_STATE_PATH } from "./work-state.js";
+import { createEvidence } from "./evidence.js";
+import { runDoctor } from "../commands/doctor.js";
+
+const PROFILE_PATH = "PROJECT_PROFILE.md";
+function profileMetadata(bytes) {
+  const text = bytes.toString("utf8");
+  return {
+    mode: text.match(/^profile-mode:\s*([^\s]+)\s*$/m)?.[1] ?? null,
+    status: text.match(/^profile-status:\s*([^\s]+)\s*$/m)?.[1] ?? null,
+  };
+}
+
+export async function inspectTarget({ target, packageRoot, contractFile = null }) {
+  let manifest = null;
+  let manifestError = null;
+  try {
+    manifest = await readManifest(target);
+  } catch (error) {
+    manifestError = error.message;
+  }
+
+  const profilePath = ensureWithin(target, PROFILE_PATH);
+  const profile = (await fileExists(profilePath))
+    ? profileMetadata(await readBytes(profilePath))
+    : { mode: null, status: null };
+  const statePath = ensureWithin(target, WORK_STATE_PATH);
+  const statePresent = await fileExists(statePath);
+  const state = await readAndClassifyWorkState({ target, packageRoot, contractFile });
+  const schemaHealth = await inspectSchemaHealth(target);
+  const doctor = await runDoctor({ target, packageRoot });
+  const agents = await Promise.all(AGENT_SUPPORT.map(async (record) => ({
+    id: record.id,
+    name: record.name,
+    support: record.support,
+    instructionFiles: record.instructionFiles,
+    available: (await Promise.all(
+      record.instructionFiles.map(async (relativePath) => fileExists(ensureWithin(target, relativePath))),
+    )).some(Boolean),
+  })));
+
+  const findings = [...doctor.findings];
+  for (const schema of schemaHealth.schemas) {
+    if (schema.status !== "valid") {
+      findings.push({
+        code: `schema-${schema.status}`,
+        severity: "error",
+        path: `schemas/${schema.name}.schema.json`,
+        message: schema.error ?? `Schema is ${schema.status}.`,
+        remediation: "Restore the shipped schema and rerun inspect.",
+        evidence: createEvidence({
+          kind: schema.status === "missing" ? "NOT_VERIFIED" : "OBSERVED",
+          source: `schemas/${schema.name}.schema.json`,
+          result: schema.status,
+        }),
+      });
+    }
+  }
+  if (state.status === "INVALID") {
+    findings.push({
+      code: "state-invalid",
+      severity: "error",
+      path: WORK_STATE_PATH,
+      message: state.error ?? "Work state is invalid.",
+      remediation: "Repair or clear the checkpoint after reviewing the parse error.",
+      evidence: createEvidence({ kind: "BLOCKED", source: WORK_STATE_PATH, result: "invalid" }),
+    });
+  }
+
+  const protocolEvidence = schemaHealth.evidence ?? [createEvidence({
+    kind: schemaHealth.status === "valid" ? "OBSERVED" : "NOT_VERIFIED",
+    source: "ForgeLoop schema health",
+    result: schemaHealth.status,
+  })];
+  const evidence = [
+    ...(doctor.evidence ?? []),
+    ...(state.evidence ?? []),
+    ...protocolEvidence,
+  ];
+  return {
+    target: { path: target },
+    manifest: {
+      present: manifest !== null,
+      status: manifestError ? "invalid" : manifest ? "ready" : "missing",
+      packageVersion: manifest?.packageVersion ?? null,
+      error: manifestError,
+    },
+    profile,
+    adapters: {
+      detected: agents.filter((agent) => agent.available).map((agent) => agent.id),
+      agents,
+    },
+    protocol: {
+      version: PROTOCOL_VERSION,
+      schemaStatus: schemaHealth.status,
+      schemas: schemaHealth.schemas,
+      evidence: protocolEvidence,
+    },
+    state: { ...state, path: WORK_STATE_PATH, present: statePresent },
+    compatibility: {
+      agents: AGENT_SUPPORT.map((record) => record.id),
+    },
+    findings,
+    evidence,
+    ok: doctor.ok
+      && !manifestError
+      && schemaHealth.status === "valid"
+      && !["INVALID", "REVALIDATION_REQUIRED"].includes(state.status),
+  };
+}

package/src/core/json-safety.js

@@ -0,0 +1,54 @@
+export const JSON_LIMITS = Object.freeze({
+  maxBytes: 2 * 1024 * 1024,
+  maxDepth: 32,
+  maxArrayLength: 10_000,
+  maxObjectKeys: 10_000,
+  maxStringLength: 100_000,
+});
+
+export class JsonLimitError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "JsonLimitError";
+    this.code = "JSON_LIMIT_EXCEEDED";
+  }
+}
+
+export function assertJsonBytes(bytes, label = "JSON artifact", limits = JSON_LIMITS) {
+  const size = typeof bytes === "string" ? Buffer.byteLength(bytes, "utf8") : bytes.byteLength;
+  if (size > limits.maxBytes) {
+    throw new JsonLimitError(`${label} exceeds the ${limits.maxBytes}-byte limit`);
+  }
+  return bytes;
+}
+
+export function assertJsonLimits(value, label = "JSON artifact", limits = JSON_LIMITS) {
+  const visited = new WeakSet();
+
+  function visit(current, depth, location) {
+    if (typeof current === "string") {
+      if (current.length > limits.maxStringLength) {
+        throw new JsonLimitError(`${location} exceeds the string length limit`);
+      }
+      return;
+    }
+    if (!current || typeof current !== "object") return;
+    if (visited.has(current)) throw new JsonLimitError(`${location} contains a circular reference`);
+    visited.add(current);
+    if (depth > limits.maxDepth) throw new JsonLimitError(`${location} exceeds the JSON depth limit`);
+    if (Array.isArray(current)) {
+      if (current.length > limits.maxArrayLength) throw new JsonLimitError(`${location} exceeds the array length limit`);
+      current.forEach((item, index) => visit(item, depth + 1, `${location}[${index}]`));
+    } else {
+      const keys = Object.keys(current);
+      if (keys.length > limits.maxObjectKeys) throw new JsonLimitError(`${location} exceeds the object key limit`);
+      for (const key of keys) {
+        if (key.length > limits.maxStringLength) throw new JsonLimitError(`${location} contains an oversized key`);
+        visit(current[key], depth + 1, `${location}.${key}`);
+      }
+    }
+  }
+
+  visit(value, 0, label);
+  return value;
+}

package/src/core/manifest.js

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { assertSafePath, ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
+import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
+
+export const MANIFEST_SCHEMA_VERSION = 1;
+export const MANIFEST_PATH = ".forgeloop/manifest.json";
+export const PACKAGE_NAME = "@cassiomc1/forgeloop";
+
+export function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function createManifest(packageVersion) {
+  return {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    packageName: PACKAGE_NAME,
+    packageVersion,
+    files: {},
+  };
+}
+
+function validateManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error("Manifest must contain a JSON object");
+  }
+  if (manifest.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+    throw new Error(`Unsupported manifest schema: ${manifest.schemaVersion}`);
+  }
+  if (typeof manifest.packageVersion !== "string" || !manifest.packageVersion) {
+    throw new Error("Manifest packageVersion is required");
+  }
+  if (!manifest.files || typeof manifest.files !== "object" || Array.isArray(manifest.files)) {
+    throw new Error("Manifest files must be an object");
+  }
+
+  for (const [relativePath, record] of Object.entries(manifest.files)) {
+    ensureWithin("/manifest-root", relativePath);
+    if (!record || typeof record.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(record.sha256)) {
+      throw new Error(`Invalid manifest hash for ${relativePath}`);
+    }
+    if (typeof record.preserve !== "boolean") {
+      throw new Error(`Invalid manifest preserve flag for ${relativePath}`);
+    }
+  }
+  return manifest;
+}
+
+export async function readManifest(target) {
+  await assertSafePath(target, MANIFEST_PATH);
+  const manifestPath = ensureWithin(target, MANIFEST_PATH);
+  if (!(await fileExists(manifestPath))) return null;
+  let raw;
+  try {
+    const bytes = await readFile(manifestPath);
+    assertJsonBytes(bytes, MANIFEST_PATH);
+    raw = JSON.parse(bytes.toString("utf8"));
+    assertJsonLimits(raw, MANIFEST_PATH);
+  } catch (error) {
+    throw new Error(`Unable to parse ${MANIFEST_PATH}: ${error.message}`);
+  }
+  return validateManifest(raw);
+}
+
+export async function writeManifest(target, manifest, { dryRun = false } = {}) {
+  validateManifest(manifest);
+  await assertSafePath(target, MANIFEST_PATH);
+  const manifestPath = ensureWithin(target, MANIFEST_PATH);
+  await writeFileAtomic(
+    manifestPath,
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    { dryRun },
+  );
+}

package/src/core/protocol.js

@@ -0,0 +1,81 @@
+export const PROTOCOL_VERSION = 1;
+
+export const FAILURE_CLASSES = Object.freeze([
+  "CONTRACT_FAILURE",
+  "DISCOVERY_FAILURE",
+  "ROUTING_FAILURE",
+  "IMPLEMENTATION_FAILURE",
+  "VERIFICATION_FAILURE",
+  "REGRESSION_FAILURE",
+  "REVIEW_FAILURE",
+  "CAPABILITY_FAILURE",
+  "AUTHORITY_FAILURE",
+  "ENVIRONMENT_FAILURE",
+  "EXTERNAL_SERVICE_FAILURE",
+  "STALE_STATE_FAILURE",
+]);
+
+export const WORK_PHASES = Object.freeze([
+  "RECEIVED",
+  "DISCOVERING",
+  "CONTRACT_READY",
+  "ROUTED",
+  "DESIGNING",
+  "PLANNED",
+  "EXECUTING",
+  "VERIFYING",
+  "DIAGNOSING",
+  "CORRECTING",
+  "REVIEWING",
+  "COMPLETE",
+  "BLOCKED",
+]);
+
+export const GUIDE_IDS = Object.freeze([
+  "premium",
+  "clean",
+  "test",
+  "security",
+  "design",
+  "performance",
+  "accessibility",
+  "games",
+]);
+
+export const GUIDE_ORDER = GUIDE_IDS;
+
+export const WORK_TRANSITIONS = Object.freeze({
+  RECEIVED: ["DISCOVERING"],
+  DISCOVERING: ["CONTRACT_READY"],
+  CONTRACT_READY: ["ROUTED"],
+  ROUTED: ["DESIGNING", "PLANNED"],
+  DESIGNING: ["PLANNED"],
+  PLANNED: ["EXECUTING"],
+  EXECUTING: ["VERIFYING"],
+  VERIFYING: ["DIAGNOSING", "REVIEWING"],
+  DIAGNOSING: ["CORRECTING"],
+  CORRECTING: ["VERIFYING"],
+  REVIEWING: ["COMPLETE", "CORRECTING"],
+  COMPLETE: [],
+  BLOCKED: [],
+});
+
+export function isValidTransition(from, to) {
+  if (!WORK_PHASES.includes(from) || !WORK_PHASES.includes(to)) return false;
+  if (to === "BLOCKED" && from !== "COMPLETE" && from !== "BLOCKED") return true;
+  return WORK_TRANSITIONS[from].includes(to);
+}
+
+export function assertFailureClass(value) {
+  if (!FAILURE_CLASSES.includes(value)) {
+    throw new Error(`Unknown failure class: ${value}`);
+  }
+  return value;
+}
+
+export function assertWorkPhase(value) {
+  if (!WORK_PHASES.includes(value)) {
+    throw new Error(`Unknown work phase: ${value}`);
+  }
+  return value;
+}

package/src/core/receipt.js

@@ -0,0 +1,129 @@
+import { GUIDE_IDS, PROTOCOL_VERSION } from "./protocol.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { assertEvidenceList, evidenceMatches } from "./evidence.js";
+import { assertJsonLimits } from "./json-safety.js";
+
+const RECEIPT_SCHEMA_VERSION = 1;
+const SECRET_WORDS = new Set(["token", "password", "secret", "credential"]);
+const SECRET_VALUE_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
+  /(?:^|\s)(?:sk|ghp|glpat|xox[baprs])-[-_a-z0-9]{8,}/i,
+  /(?:AKIA|ASIA)[A-Z0-9]{12,}/,
+];
+
+function findSecretLikeValues(value, location, violations) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => findSecretLikeValues(item, `${location}[${index}]`, violations));
+    return;
+  }
+  if (!value || typeof value !== "object") {
+    if (typeof value === "string" && SECRET_VALUE_PATTERNS.some((pattern) => pattern.test(value))) {
+      violations.push(`${location}: secret-like value is not allowed`);
+    }
+    return;
+  }
+
+  for (const [key, child] of Object.entries(value)) {
+    const childLocation = `${location}.${key}`;
+    const pathLikeDocumentation = /\.(?:md|txt|json)$/i.test(key);
+    const words = key.split(/(?=[A-Z])|[_\-\s]+/).filter(Boolean).map((word) => word.toLowerCase());
+    const compact = key.replaceAll(/[^a-z0-9]/gi, "").toLowerCase();
+    const containsSensitiveWord = !pathLikeDocumentation && (
+      words.some((word) => SECRET_WORDS.has(word))
+      || ["apikey", "privatekey", "accesskey", "secretkey"].some((term) => compact.includes(term))
+      || words.some((word, index) => ["api", "private", "access", "secret"].includes(word)
+        && ["key", "token"].includes(words[index + 1]))
+    );
+    if (containsSensitiveWord) {
+      violations.push(`${childLocation}: secret-like field is not allowed`);
+    }
+    findSecretLikeValues(child, childLocation, violations);
+  }
+}
+
+export function assertSecretFree(value) {
+  assertJsonLimits(value, "secret-free artifact");
+  const violations = [];
+  findSecretLikeValues(value, "$", violations);
+  if (violations.length > 0) throw new Error(violations.join("; "));
+}
+
+function assertKnownGuides(guides) {
+  const unknown = guides.filter((guide) => !GUIDE_IDS.includes(guide));
+  if (unknown.length > 0) throw new Error(`Receipt contains unknown guide: ${unknown[0]}`);
+  if (new Set(guides).size !== guides.length) throw new Error("Receipt selectedGuides must not contain duplicates");
+}
+
+export function assertReceiptSemantics(receipt) {
+  const evidence = receipt.evidence ?? [];
+  assertEvidenceList(evidence, "receipt.evidence");
+
+  for (const [index, check] of receipt.checks.entries()) {
+    if (check?.status === "passed") {
+      const hasCommandOrResult = [check.command, check.result, check.name]
+        .some((value) => typeof value === "string" && value.trim().length > 0);
+      if (!hasCommandOrResult) {
+        throw new Error(`receipt.checks[${index}] passed check requires a command or result`);
+      }
+    }
+  }
+
+  if (receipt.status === "complete") {
+    const verificationEvidence = evidence.filter((item) => ["OBSERVED", "INFERRED"].includes(item.kind));
+    if (verificationEvidence.length === 0) {
+      throw new Error("COMPLETE receipt requires verification evidence");
+    }
+  }
+
+  const publicationEvidence = [
+    [receipt.publication.committed, ["commit", "committed"], "committed", "commit"],
+    [receipt.publication.pushed, ["git push", "pushed"], "pushed", "push"],
+    [receipt.publication.deployed, ["deploy", "deployed", "deployment"], "deployed", "deployment"],
+  ];
+  for (const [claimed, terms, field, label] of publicationEvidence) {
+    if (claimed && !evidenceMatches(evidence, terms)) {
+      throw new Error(`publication.${field} requires ${label} evidence`);
+    }
+  }
+
+  if (receipt.review.independent === true) {
+    const implementer = receipt.review.implementerId;
+    const reviewer = receipt.review.reviewerId;
+    if (typeof implementer !== "string" || typeof reviewer !== "string" || implementer === reviewer) {
+      throw new Error("independent review requires distinct implementer and reviewer identities");
+    }
+  }
+  return receipt;
+}
+
+export async function validateReceipt(receipt, packageRoot) {
+  assertSecretFree(receipt);
+  const schema = await readSchema("execution-receipt", packageRoot);
+  assertSchema(receipt, schema, "execution receipt");
+  assertKnownGuides(receipt.selectedGuides);
+  return assertReceiptSemantics(receipt);
+}
+
+export async function createReceipt(input, packageRoot) {
+  assertSecretFree(input);
+  const receipt = {
+    schemaVersion: RECEIPT_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: input.taskId,
+    contractFingerprint: input.contractFingerprint,
+    status: input.status ?? "in-progress",
+    selectedGuides: [...(input.selectedGuides ?? [])],
+    changedPaths: [...(input.changedPaths ?? [])],
+    checks: [...(input.checks ?? [])],
+    evidence: [...(input.evidence ?? [])],
+    review: input.review ?? { status: "not-run", independent: false },
+    limitations: [...(input.limitations ?? [])],
+    publication: input.publication ?? {
+      committed: false,
+      pushed: false,
+      pullRequest: null,
+      deployed: false,
+    },
+  };
+  return validateReceipt(receipt, packageRoot);
+}

package/src/core/repository.js

@@ -0,0 +1,19 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function currentRepositoryFingerprint(target) {
+  try {
+    const [{ stdout: branchOutput }, { stdout: headOutput }] = await Promise.all([
+      execFileAsync("git", ["-C", target, "branch", "--show-current"], { windowsHide: true }),
+      execFileAsync("git", ["-C", target, "rev-parse", "HEAD"], { windowsHide: true }),
+    ]);
+    return {
+      branch: branchOutput.trim() || null,
+      head: headOutput.trim() || null,
+    };
+  } catch {
+    return { branch: null, head: null };
+  }
+}