@cassiomc1/forgeloop 0.1.15 → 1.0.0

package/src/core/command-tokenizer.js

@@ -0,0 +1,122 @@
+export function tokenizeCommand(commandString) {
+  const tokens = [];
+  let current = "";
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+
+  for (let i = 0; i < commandString.length; i++) {
+    const char = commandString[i];
+
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+    } else if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+    } else if (/\s/.test(char) && !inSingleQuote && !inDoubleQuote) {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = "";
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.length > 0) tokens.push(current);
+  return tokens;
+}
+
+export function splitCommandPipeline(commandString) {
+  const parts = [];
+  let current = "";
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+
+  for (let i = 0; i < commandString.length; i++) {
+    const char = commandString[i];
+    const next = commandString[i + 1];
+
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      current += char;
+    } else if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      current += char;
+    } else if (!inSingleQuote && !inDoubleQuote) {
+      if ((char === "&" && next === "&") || (char === "|" && next === "|")) {
+        if (current.trim().length > 0) parts.push(current.trim());
+        current = "";
+        i++;
+      } else if (char === ";" || char === "|") {
+        if (current.trim().length > 0) parts.push(current.trim());
+        current = "";
+      } else {
+        current += char;
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.trim().length > 0) parts.push(current.trim());
+  return parts.length > 0 ? parts : [commandString];
+}
+
+export function extractToolFromArgs(args) {
+  if (!Array.isArray(args) || args.length === 0) return null;
+  for (let idx = 0; idx < args.length; idx++) {
+    const arg = args[idx];
+    if (arg === "-p" || arg === "--package") {
+      if (args[idx + 1] && !args[idx + 1].startsWith("-")) return args[idx + 1];
+    }
+    if (arg.startsWith("--package=")) return arg.split("=")[1];
+    if (!arg.startsWith("-")) return arg;
+  }
+  return null;
+}
+
+export function extractNpmExecTool(args) {
+  if (!Array.isArray(args) || args.length === 0) return null;
+  for (let idx = 0; idx < args.length; idx++) {
+    const arg = args[idx];
+    if (arg === "-p" || arg === "--package") {
+      if (args[idx + 1] && !args[idx + 1].startsWith("-")) return args[idx + 1];
+    }
+    if (arg.startsWith("--package=")) return arg.slice("--package=".length);
+  }
+  let afterDoubleDash = false;
+  for (let idx = 0; idx < args.length; idx++) {
+    const arg = args[idx];
+    if (arg === "--") {
+      afterDoubleDash = true;
+      if (args[idx + 1] && !args[idx + 1].startsWith("-")) return args[idx + 1];
+      continue;
+    }
+    if (!afterDoubleDash && !arg.startsWith("-")) return arg;
+  }
+  return null;
+}
+
+export function normalizeExecutableName(binaryToken) {
+  const base = binaryToken.split(/[\\/]/u).pop() ?? binaryToken;
+  return base.toLowerCase().replace(/\.(?:cmd|bat|exe)$/u, "");
+}
+
+export function unwrapCommandArgv(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return null;
+  let i = 0;
+  while (i < argv.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(argv[i])) i++;
+  if (i >= argv.length) return null;
+  const binary = normalizeExecutableName(argv[i]);
+  if (["sh", "bash", "zsh", "dash", "ksh"].includes(binary)) {
+    const shellFlagIndex = argv.findIndex((item, index) => index > i && /^-.*c/.test(item));
+    const shellCommand = shellFlagIndex >= 0 ? argv[shellFlagIndex + 1] : null;
+    if (shellCommand) return tokenizeCommand(shellCommand);
+  }
+  if (binary === "cmd") {
+    const shellFlagIndex = argv.findIndex((item, index) => index > i && /^\/c$/iu.test(item));
+    const shellCommand = shellFlagIndex >= 0 ? argv.slice(shellFlagIndex + 1).join(" ") : null;
+    if (shellCommand) return tokenizeCommand(shellCommand);
+  }
+  if (binary === "call") return argv.slice(i + 1);
+  return argv.slice(i);
+}

package/src/core/conformance.js

@@ -1,6 +1,7 @@
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { createEvidence } from "./evidence.js";
 import { canonicalFingerprint } from "./artifacts.js";
+import { evaluateContinuityConformance } from "./continuity-conformance.js";
 
 function error(code, message, artifacts = []) {
   return { code, message, artifacts };
@@ -49,9 +50,13 @@ export function validateTaskArtifactSet({
   taskBriefs = [],
   delegatedResults = [],
   events = [],
+  continuity = null,
+  continuityContext = {},
 } = {}) {
   const errors = [];
   const incomplete = [];
+  const continuityResult = evaluateContinuityConformance({ continuity, state, ...continuityContext });
+  errors.push(...continuityResult.errors);
 
   addVersionErrors(route, "route", errors);
   addVersionErrors(state, "state", errors);
@@ -122,11 +127,11 @@ export function validateTaskArtifactSet({
 
   const sortedErrors = sortErrors(errors);
   let status = "VALID";
-  if (sortedErrors.some((item) => item.code === "UNSUPPORTED_PROTOCOL_VERSION")) {
+  if (sortedErrors.some((item) => item.code === "UNSUPPORTED_PROTOCOL_VERSION") || continuityResult.status === "INVALID") {
     status = "INVALID";
   } else if (sortedErrors.length > 0) {
     status = "INCONSISTENT";
-  } else if (stateClassification?.status === "REVALIDATION_REQUIRED") {
+  } else if (stateClassification?.status === "REVALIDATION_REQUIRED" || continuityResult.status === "STALE") {
     status = "STALE";
   } else if (incomplete.length > 0) {
     status = "INCOMPLETE";
@@ -173,6 +178,7 @@ export function validateTaskArtifactSet({
     incomplete: [...new Set(incomplete)].sort(),
     stale,
     delegation,
+    continuity: continuityResult,
     evidence: [createEvidence({
       kind: evidenceKind,
       source: "ForgeLoop protocol conformance",

package/src/core/continuity-cli-options.js

@@ -0,0 +1,58 @@
+const OPTION_FIELDS = Object.freeze({
+  "--focus-id": ["continuityFocusId", false],
+  "--focus-summary": ["continuityFocusSummary", false],
+  "--remaining": ["continuityRemaining", true],
+  "--known-issue": ["continuityKnownIssues", true],
+  "--changed-area": ["continuityChangedAreas", true],
+  "--inspect-first": ["continuityInspectFirst", true],
+  "--resume-note": ["continuityResumeNote", false],
+});
+
+export function continuityOptionDefaults() {
+  return {
+    continuityFocusId: null,
+    continuityFocusSummary: null,
+    continuityRemaining: [],
+    continuityKnownIssues: [],
+    continuityChangedAreas: [],
+    continuityInspectFirst: [],
+    continuityResumeNote: null,
+  };
+}
+
+export function consumeContinuityOption({ argument, argv, index, options }) {
+  const definition = OPTION_FIELDS[argument];
+  if (!definition) return { handled: false, index };
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) throw new Error(`${argument} requires a value`);
+  const [field, repeatable] = definition;
+  if (repeatable) options[field].push(value);
+  else options[field] = value;
+  return { handled: true, index: index + 1 };
+}
+
+export function hasContinuityOptions(options = {}) {
+  return Boolean(
+    options.continuityFocusId
+    || options.continuityFocusSummary
+    || options.continuityResumeNote
+    || options.continuityRemaining?.length
+    || options.continuityKnownIssues?.length
+    || options.continuityChangedAreas?.length
+    || options.continuityInspectFirst?.length
+  );
+}
+
+export function validateContinuityOptions(command, options = {}) {
+  if (command !== "record-continuity" && hasContinuityOptions(options)) {
+    throw new Error(`Continuity recording options are not valid for ${command}`);
+  }
+  if (command === "record-continuity") {
+    const hasFocusId = Boolean(options.continuityFocusId);
+    const hasFocusSummary = Boolean(options.continuityFocusSummary);
+    if (hasFocusId !== hasFocusSummary) {
+      throw new Error("record-continuity requires --focus-id and --focus-summary together");
+    }
+  }
+  return options;
+}

package/src/core/continuity-conformance.js

@@ -0,0 +1,46 @@
+import { classifyContinuity } from "./continuity-reconciliation.js";
+
+function error(code, message) {
+  return { code, message, artifacts: ["continuity", "state"] };
+}
+
+export function evaluateContinuityConformance(input = {}) {
+  if (!input.continuity) {
+    return {
+      required: false,
+      status: "NOT_APPLICABLE",
+      classification: "ABSENT",
+      errors: [],
+      reasonCodes: [],
+      reasons: ["CONTINUITY_ABSENT"],
+      authority: "OPERATIONAL_CONTEXT_ONLY",
+      evidenceAuthority: "NONE",
+    };
+  }
+
+  const classification = classifyContinuity(input);
+  const result = {
+    required: false,
+    status: classification.classification === "FRESH"
+      ? "VALID"
+      : classification.classification === "RECONCILIATION_REQUIRED"
+        ? "STALE"
+        : classification.classification === "NOT_APPLICABLE"
+          ? "NOT_APPLICABLE"
+          : classification.classification,
+    classification: classification.classification,
+    errors: [],
+    reasonCodes: [...classification.reasonCodes],
+    reasons: [...classification.reasons],
+    authority: "OPERATIONAL_CONTEXT_ONLY",
+    evidenceAuthority: "NONE",
+  };
+
+  if (["INVALID", "INCONSISTENT"].includes(classification.classification)) {
+    result.errors = classification.reasonCodes.map((code, index) => error(
+      code,
+      classification.reasons[index] ?? `Continuity is ${classification.classification.toLowerCase()}`,
+    ));
+  }
+  return result;
+}

package/src/core/continuity-observability.js

@@ -0,0 +1,20 @@
+const HEALTHY = new Set(["ABSENT", "FRESH", "NOT_APPLICABLE"]);
+
+export function continuityIsHealthy(result) {
+  return HEALTHY.has(result?.classification ?? "ABSENT");
+}
+
+export function continuityFinding(result) {
+  if (continuityIsHealthy(result)) return null;
+  const classification = result?.classification ?? "INVALID";
+  const severity = classification === "RECONCILIATION_REQUIRED" ? "warning" : "error";
+  return {
+    code: `continuity-${classification.toLowerCase().replaceAll("_", "-")}`,
+    severity,
+    path: result?.path ?? ".forgeloop/continuity.json",
+    message: result?.reasons?.join(", ") || `Continuity is ${classification}`,
+    remediation: classification === "RECONCILIATION_REQUIRED"
+      ? "Run forgeloop reconcile-continuity, inspect the current checkout, then record corrected continuity before advancing verification."
+      : "Repair or clear continuity after reviewing the current work state and checkout.",
+  };
+}

package/src/core/continuity-reconciliation.js

@@ -0,0 +1,224 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { assertContinuitySemantics, readContinuity } from "./continuity.js";
+import { WORK_TRANSITIONS } from "./protocol.js";
+
+const RECONCILIATION_CODE = "E_CONTINUITY_RECONCILIATION_REQUIRED";
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function pathCoveredByHint(changedPath, hint) {
+  const normalizedPath = String(changedPath).replaceAll("\\", "/").replace(/^\.\//, "");
+  const normalizedHint = String(hint).replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+  return normalizedPath === normalizedHint || normalizedPath.startsWith(`${normalizedHint}/`);
+}
+
+function compareChangedPaths(changedPaths, hints) {
+  if (!Array.isArray(changedPaths)) return "NOT_VERIFIED";
+  if (!Array.isArray(hints) || hints.length === 0) return changedPaths.length === 0 ? "MATCH" : "MISMATCH";
+  const matched = hints.filter((hint) => changedPaths.some((changedPath) => pathCoveredByHint(changedPath, hint))).length;
+  if (matched === hints.length) return "MATCH";
+  if (matched > 0) return "PARTIAL";
+  return "MISMATCH";
+}
+
+function compareRepository(saved, current) {
+  const savedUnavailable = !saved || (saved.branch === null && saved.head === null);
+  const currentUnavailable = !current || (current.branch === null && current.head === null);
+  if (savedUnavailable && currentUnavailable) return "NOT_VERIFIED";
+  if (!saved || !current) return "NOT_VERIFIED";
+  return saved.branch === current.branch && saved.head === current.head ? "MATCH" : "MISMATCH";
+}
+
+function phaseReachable(from, to) {
+  if (from === to) return true;
+  if (to === "BLOCKED" && from !== "COMPLETE") return true;
+  if (from === "BLOCKED") return false;
+  const queue = [from];
+  const visited = new Set(queue);
+  while (queue.length > 0) {
+    const phase = queue.shift();
+    for (const next of WORK_TRANSITIONS[phase] ?? []) {
+      if (next === to) return true;
+      if (!visited.has(next)) {
+        visited.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  return false;
+}
+
+function baseResult(classification, overrides = {}) {
+  return {
+    classification,
+    taskMatches: overrides.taskMatches ?? null,
+    workStateMatches: overrides.workStateMatches ?? null,
+    contractMatches: overrides.contractMatches ?? null,
+    phaseMatches: overrides.phaseMatches ?? null,
+    repositoryComparison: overrides.repositoryComparison ?? "NOT_VERIFIED",
+    changedPathComparison: overrides.changedPathComparison ?? "NOT_VERIFIED",
+    reasonCodes: uniqueSorted(overrides.reasonCodes ?? []),
+    reasons: uniqueSorted(overrides.reasons ?? []),
+    authority: "OPERATIONAL_CONTEXT_ONLY",
+    evidenceAuthority: "NONE",
+  };
+}
+
+export function classifyContinuity({
+  continuity,
+  state,
+  contractFingerprint,
+  repositoryFingerprint,
+  changedPaths,
+} = {}) {
+  if (!continuity) {
+    return baseResult("ABSENT", { reasons: ["CONTINUITY_ABSENT"] });
+  }
+
+  let value;
+  try {
+    value = assertContinuitySemantics(continuity);
+  } catch (error) {
+    return baseResult("INVALID", {
+      reasonCodes: [error.code ?? "E_CONTINUITY_INVALID"],
+      reasons: [error.message],
+    });
+  }
+
+  if (!state || typeof state !== "object") {
+    return baseResult("INCONSISTENT", {
+      reasonCodes: ["E_CONTINUITY_STATE_MISSING"],
+      reasons: ["CONTINUITY_STATE_MISSING"],
+    });
+  }
+
+  if (state.phase === "COMPLETE") {
+    return baseResult("NOT_APPLICABLE", {
+      taskMatches: value.taskId === state.taskId,
+      phaseMatches: value.phase === state.phase,
+      reasons: ["CONTINUITY_NOT_APPLICABLE_AFTER_COMPLETE"],
+    });
+  }
+
+  const taskMatches = value.taskId === state.taskId;
+  const workStateMatches = value.workStateFingerprint === canonicalFingerprint(state);
+  const expectedContract = contractFingerprint ?? state.contractFingerprint ?? null;
+  const contractMatches = value.contractFingerprint === state.contractFingerprint
+    && (expectedContract === null || value.contractFingerprint === expectedContract);
+  const phaseMatches = value.phase === state.phase;
+  const repositoryComparison = compareRepository(value.repositoryFingerprint, repositoryFingerprint);
+  const changedPathComparison = compareChangedPaths(changedPaths, value.changedAreas);
+
+  const inconsistentCodes = [];
+  const inconsistentReasons = [];
+  if (!taskMatches) {
+    inconsistentCodes.push("E_CONTINUITY_TASK_MISMATCH");
+    inconsistentReasons.push("CONTINUITY_TASK_MISMATCH");
+  }
+  if (!contractMatches) {
+    inconsistentCodes.push("E_CONTINUITY_CONTRACT_MISMATCH");
+    inconsistentReasons.push("CONTINUITY_CONTRACT_MISMATCH");
+  }
+  if (!phaseMatches && !phaseReachable(value.phase, state.phase)) {
+    inconsistentCodes.push("E_CONTINUITY_PHASE_MISMATCH");
+    inconsistentReasons.push("CONTINUITY_PHASE_MISMATCH");
+  }
+  if (inconsistentCodes.length > 0) {
+    return baseResult("INCONSISTENT", {
+      taskMatches,
+      workStateMatches,
+      contractMatches,
+      phaseMatches,
+      repositoryComparison,
+      changedPathComparison,
+      reasonCodes: inconsistentCodes,
+      reasons: inconsistentReasons,
+    });
+  }
+
+  const reconciliationReasons = [];
+  if (!workStateMatches) reconciliationReasons.push("CONTINUITY_WORK_STATE_CHANGED");
+  if (!phaseMatches) reconciliationReasons.push("CONTINUITY_PHASE_CHANGED");
+  if (repositoryComparison === "MISMATCH") reconciliationReasons.push("CONTINUITY_REPOSITORY_CHANGED");
+  if (["PARTIAL", "MISMATCH"].includes(changedPathComparison)) {
+    reconciliationReasons.push("CONTINUITY_CHANGED_PATHS_DIFFER");
+  }
+
+  if (reconciliationReasons.length > 0) {
+    return baseResult("RECONCILIATION_REQUIRED", {
+      taskMatches,
+      workStateMatches,
+      contractMatches,
+      phaseMatches,
+      repositoryComparison,
+      changedPathComparison,
+      reasonCodes: [RECONCILIATION_CODE],
+      reasons: reconciliationReasons,
+    });
+  }
+
+  return baseResult("FRESH", {
+    taskMatches,
+    workStateMatches,
+    contractMatches,
+    phaseMatches,
+    repositoryComparison,
+    changedPathComparison,
+  });
+}
+
+export async function reconcileContinuity({ target, packageRoot } = {}) {
+  const [{ readWorkState }, { readContract }, repository] = await Promise.all([
+    import("./work-state.js"),
+    import("./contract.js"),
+    import("./repository.js"),
+  ]);
+
+  const state = await readWorkState(target, packageRoot);
+  let continuityArtifact;
+  try {
+    continuityArtifact = await readContinuity(target, packageRoot);
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      return { ...classifyContinuity({ continuity: null, state }), path: ".forgeloop/continuity.json", present: false };
+    }
+    return {
+      ...baseResult("INVALID", {
+        reasonCodes: [error.code ?? "E_CONTINUITY_INVALID"],
+        reasons: [error.message],
+      }),
+      path: ".forgeloop/continuity.json",
+      present: true,
+      error: error.message,
+    };
+  }
+
+  let contractFingerprint = null;
+  try {
+    const contract = await readContract(target, packageRoot);
+    contractFingerprint = contract.fingerprint;
+  } catch {
+    contractFingerprint = null;
+  }
+
+  const [repositoryFingerprint, changedPaths] = await Promise.all([
+    repository.currentRepositoryFingerprint(target),
+    repository.currentChangedPaths(target),
+  ]);
+
+  return {
+    ...classifyContinuity({
+      continuity: continuityArtifact.value,
+      state,
+      contractFingerprint,
+      repositoryFingerprint,
+      changedPaths,
+    }),
+    path: continuityArtifact.path,
+    present: true,
+    fingerprint: continuityArtifact.fingerprint,
+    continuity: continuityArtifact.value,
+  };
+}