@abelxiaoxing/cadence 1.8.4 → 2.0.0

package/src/candidate-context.ts

@@ -1,289 +0,0 @@
-import { isAgentsPath, isValidRelativePath } from "./contracts.ts";
-import type { BeginCandidateInput, TaskLedger } from "./task-ledger.ts";
-export type CandidateContextRequestCode =
-  | "approved-context-needed"
-  | "task-split-needed"
-  | "boundary-review-needed";
-
-export type CandidateContextRef =
-  | { kind: "requested-path"; path: string; access: "read" | "write" }
-  | { kind: "source-citation"; path: string; line: number }
-  | { kind: "contract-diagnostic"; ref: string };
-
-export type CandidateContextRefInput = string | CandidateContextRef;
-
-export type CandidateArtifactSubmissionResult =
-  | {
-      kind: "sealed-candidate";
-      candidateId: string;
-      state: "sealed";
-      artifactHash: string;
-      bytes: number;
-      paths: string[];
-      replayed?: true;
-    }
-  | {
-      kind: "context-request";
-      candidateId: string;
-      code: CandidateContextRequestCode;
-      refs: CandidateContextRef[];
-    };
-
-export type CandidateContextRequest = Extract<
-  CandidateArtifactSubmissionResult,
-  { kind: "context-request" }
->;
-
-export interface CandidateContextBoundary {
-  phase: "red" | "green" | "refactor";
-  readPaths: readonly string[];
-  writePaths: readonly string[];
-  deletePaths?: readonly string[];
-  taskPaths: readonly string[];
-  contextReadRoots?: readonly string[];
-  redWritePaths: readonly string[];
-  agents: {
-    impact: "none" | "update-existing" | "create-index" | "remove-index";
-    target?: string;
-  };
-}
-
-export interface ClassifiedCandidateContextRequest {
-  kind: "paused" | "retryable" | "approval-needed";
-  code:
-    | "approved-context-needed"
-    | "task-split-needed"
-    | "boundary-review-needed"
-    | "red-artifact-constraint"
-    | "agents-context-needed"
-    | "agents-write-parent-owned"
-    | "agents-contract-insufficient";
-  contextRequest: {
-    code: CandidateContextRequestCode;
-    refs: CandidateContextRef[];
-  };
-}
-
-const LEGACY_CITATION = /^(.*):(\d+)$/u;
-const LEGACY_DIAGNOSTIC =
-  /^(?:phase-contract|task-contract|sealed-contract|workflow-contract)\.[a-z0-9._-]+$/iu;
-
-function validDiagnosticRef(value: unknown): value is string {
-  return (
-    typeof value === "string" &&
-    value.length > 0 &&
-    value.length <= 512 &&
-    value.trim() === value &&
-    !/[\r\n\0]/u.test(value)
-  );
-}
-
-function normalizeCandidateContextRef(
-  input: CandidateContextRefInput,
-): CandidateContextRef {
-  if (typeof input === "string") {
-    const citation = LEGACY_CITATION.exec(input);
-    if (citation && isValidRelativePath(citation[1])) {
-      const line = Number(citation[2]);
-      if (Number.isSafeInteger(line) && line >= 1) {
-        return { kind: "source-citation", path: citation[1], line };
-      }
-    }
-    if (LEGACY_DIAGNOSTIC.test(input)) {
-      return { kind: "contract-diagnostic", ref: input };
-    }
-    if (!isValidRelativePath(input)) {
-      throw new Error("context request refs are invalid");
-    }
-    return { kind: "requested-path", path: input, access: "read" };
-  }
-  if (!input || typeof input !== "object" || Array.isArray(input)) {
-    throw new Error("context request refs are invalid");
-  }
-  if (
-    input.kind === "requested-path" &&
-    Object.keys(input).length === 3 &&
-    isValidRelativePath(input.path) &&
-    (input.access === "read" || input.access === "write")
-  ) {
-    return { ...input };
-  }
-  if (
-    input.kind === "source-citation" &&
-    Object.keys(input).length === 3 &&
-    isValidRelativePath(input.path) &&
-    Number.isSafeInteger(input.line) &&
-    input.line >= 1
-  ) {
-    return { ...input };
-  }
-  if (
-    input.kind === "contract-diagnostic" &&
-    Object.keys(input).length === 2 &&
-    validDiagnosticRef(input.ref)
-  ) {
-    return { ...input };
-  }
-  throw new Error("context request refs are invalid");
-}
-
-export function normalizeCandidateContextRefs(
-  value: unknown,
-): CandidateContextRef[] {
-  if (!Array.isArray(value) || value.length === 0 || value.length > 32) {
-    throw new Error("context request refs are invalid");
-  }
-  const refs = value.map((entry) =>
-    normalizeCandidateContextRef(entry as CandidateContextRefInput),
-  );
-  const identities = refs.map((ref) => JSON.stringify(ref));
-  if (new Set(identities).size !== refs.length) {
-    throw new Error("context request refs are invalid");
-  }
-  return refs;
-}
-
-function contextRefWithinBoundary(relative: string, approved: string): boolean {
-  return (
-    approved === "." ||
-    relative === approved ||
-    relative.startsWith(`${approved}/`)
-  );
-}
-
-function normalizedBoundary(
-  boundary: readonly string[] | CandidateContextBoundary,
-): CandidateContextBoundary {
-  if (!Array.isArray(boundary)) return boundary as CandidateContextBoundary;
-  return {
-    phase: "green",
-    readPaths: boundary,
-    writePaths: [],
-    deletePaths: [],
-    taskPaths: boundary,
-    redWritePaths: [],
-    agents: { impact: "none" },
-  };
-}
-
-function pathWithinAny(relative: string, approved: readonly string[]): boolean {
-  return approved.some((path) => contextRefWithinBoundary(relative, path));
-}
-
-export function permitsContextRead(
-  relative: string,
-  roots: readonly string[],
-): boolean {
-  // Dynamic discovery never grants hidden credentials or a directory tree.
-  return (
-    isValidRelativePath(relative) &&
-    relative.split("/").every((part) => !part.startsWith(".")) &&
-    !/\.(?:pem|key|p12|pfx)$/iu.test(relative) &&
-    pathWithinAny(relative, roots)
-  );
-}
-
-export function classifyCandidateContextRequest(
-  request: {
-    kind: "context-request";
-    candidateId: string;
-    code: CandidateContextRequestCode;
-    refs: readonly CandidateContextRefInput[];
-  },
-  inputBoundary: readonly string[] | CandidateContextBoundary,
-): ClassifiedCandidateContextRequest {
-  const refs = normalizeCandidateContextRefs(request.refs);
-  const boundary = normalizedBoundary(inputBoundary);
-  const phasePaths = [
-    ...boundary.readPaths,
-    ...boundary.writePaths,
-    ...(boundary.deletePaths ?? []),
-  ];
-  const requested = refs.filter(
-    (ref): ref is Extract<CandidateContextRef, { kind: "requested-path" }> =>
-      ref.kind === "requested-path",
-  );
-  const ordinaryRequested = requested.filter((ref) => !isAgentsPath(ref.path));
-  const outsideOrdinary = ordinaryRequested.filter(
-    (ref) =>
-      !(
-        ref.access === "read" &&
-        permitsContextRead(ref.path, boundary.contextReadRoots ?? [])
-      ) &&
-      !pathWithinAny(
-        ref.path,
-        ref.access === "write"
-          ? [...boundary.writePaths, ...(boundary.deletePaths ?? [])]
-          : [...phasePaths, ...boundary.taskPaths],
-      ),
-  );
-  const agentsRequested = requested.filter((ref) => isAgentsPath(ref.path));
-  const agentsWrites = agentsRequested.filter((ref) => ref.access === "write");
-  const citedRedArtifacts = refs.filter(
-    (ref): ref is Extract<CandidateContextRef, { kind: "source-citation" }> =>
-      ref.kind === "source-citation" &&
-      pathWithinAny(ref.path, boundary.redWritePaths) &&
-      !pathWithinAny(ref.path, [
-        ...boundary.writePaths,
-        ...(boundary.deletePaths ?? []),
-      ]),
-  );
-  const requestedRedArtifacts = outsideOrdinary.filter(
-    (ref) =>
-      pathWithinAny(ref.path, boundary.redWritePaths) &&
-      pathWithinAny(ref.path, boundary.taskPaths),
-  );
-  const redArtifactConstraint =
-    boundary.phase === "green" &&
-    (citedRedArtifacts.length > 0 || requestedRedArtifacts.length > 0) &&
-    outsideOrdinary.every((ref) => requestedRedArtifacts.includes(ref)) &&
-    agentsRequested.every((ref) => ref.access === "read");
-
-  let classification: Pick<ClassifiedCandidateContextRequest, "kind" | "code">;
-  if (outsideOrdinary.length > 0 && !redArtifactConstraint) {
-    classification = {
-      kind: "approval-needed",
-      code: "boundary-review-needed",
-    };
-  } else if (agentsWrites.length > 0) {
-    const targetMismatch = agentsWrites.some(
-      (ref) =>
-        boundary.agents.impact === "none" ||
-        boundary.agents.target === undefined ||
-        ref.path !== boundary.agents.target,
-    );
-    classification = targetMismatch
-      ? { kind: "approval-needed", code: "agents-contract-insufficient" }
-      : { kind: "paused", code: "agents-write-parent-owned" };
-  } else if (redArtifactConstraint) {
-    classification = { kind: "retryable", code: "red-artifact-constraint" };
-  } else if (agentsRequested.length > 0) {
-    classification = { kind: "paused", code: "agents-context-needed" };
-  } else {
-    classification = {
-      kind: "retryable",
-      code:
-        request.code === "task-split-needed"
-          ? "task-split-needed"
-          : "approved-context-needed",
-    };
-  }
-  return {
-    ...classification,
-    contextRequest: {
-      code: request.code,
-      refs,
-    },
-  };
-}
-
-export interface CandidateArtifactSubmission {
-  ledger: Pick<
-    TaskLedger,
-    "beginCandidate" | "appendCandidateSegment" | "sealCandidate"
-  >;
-  identity: BeginCandidateInput;
-  workspaceRoot: string;
-  writePaths: readonly string[];
-  deletePaths: readonly string[];
-}

package/src/candidate-patch.ts

@@ -1,271 +0,0 @@
-import { lstatSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
-import { compareCanonicalStrings } from "./canonical.ts";
-
-import { isValidRelativePath } from "./contracts.ts";
-import { observeSafePath } from "./safe-path.ts";
-
-export type CandidatePatchOperation =
-  | {
-      kind: "replace";
-      path: string;
-      oldText: string;
-      newText: string;
-    }
-  | { kind: "rewrite"; path: string; content: string }
-  | {
-      kind: "create";
-      path: string;
-      content: string;
-      mode: "regular" | "executable";
-    }
-  | { kind: "delete"; path: string };
-
-interface CandidateFileState {
-  path: string;
-  base: string | null;
-  current: string | null;
-  mode: "100644" | "100755";
-}
-
-function exactKeys(value: object, expected: readonly string[]): boolean {
-  const actual = Object.keys(value).sort();
-  return (
-    actual.length === expected.length &&
-    [...expected].sort().every((key, index) => actual[index] === key)
-  );
-}
-
-function safeText(value: unknown, maxBytes: number): value is string {
-  if (typeof value !== "string" || value.includes("\0")) return false;
-  const encoded = Buffer.from(value, "utf8");
-  return encoded.byteLength <= maxBytes && encoded.toString("utf8") === value;
-}
-
-function renderFileDiff(state: CandidateFileState): string {
-  if (state.base === state.current) return "";
-  if (state.base === null && state.current === "") {
-    throw new Error("candidate-empty-file-create-unsupported");
-  }
-  if (state.current === null && state.base === "") {
-    throw new Error("candidate-empty-file-delete-unsupported");
-  }
-  const output: string[] = [`diff --git a/${state.path} b/${state.path}`];
-  if (state.base === null) output.push(`new file mode ${state.mode}`);
-  if (state.current === null) output.push(`deleted file mode ${state.mode}`);
-  const generated = generateUnifiedPatch(
-    state.path,
-    state.base ?? "",
-    state.current ?? "",
-    3,
-  );
-  const generatedHeaders = `--- ${state.path}\n+++ ${state.path}\n`;
-  if (!generated.startsWith(generatedHeaders)) {
-    throw new Error("candidate-patch-diff-invalid");
-  }
-  output.push(state.base === null ? "--- /dev/null" : `--- a/${state.path}`);
-  output.push(state.current === null ? "+++ /dev/null" : `+++ b/${state.path}`);
-  return `${output.join("\n")}\n${generated.slice(generatedHeaders.length)}`;
-}
-
-function occurrenceCount(value: string, search: string): number {
-  let count = 0;
-  let offset = 0;
-  for (;;) {
-    const found = value.indexOf(search, offset);
-    if (found < 0) return count;
-    count += 1;
-    if (count > 1) return count;
-    offset = found + 1;
-  }
-}
-
-export function compileCandidatePatch(input: {
-  root: string;
-  writePaths: readonly string[];
-  deletePaths: readonly string[];
-  operations: readonly CandidatePatchOperation[];
-  maxBytes: number;
-}): string {
-  if (
-    !path.isAbsolute(input.root) ||
-    !Number.isSafeInteger(input.maxBytes) ||
-    input.maxBytes < 1 ||
-    !Array.isArray(input.operations) ||
-    input.operations.length < 1 ||
-    input.operations.length > 128
-  ) {
-    throw new Error("candidate-patch-invalid");
-  }
-  const writePaths = new Set(input.writePaths);
-  const deletePaths = new Set(input.deletePaths);
-  const states = new Map<string, CandidateFileState>();
-
-  const requirePath = (relative: unknown): string => {
-    if (
-      !isValidRelativePath(relative) ||
-      relative === "." ||
-      relative.trim() !== relative ||
-      /[\r\n\t]/u.test(relative)
-    ) {
-      throw new Error("candidate-patch-path-invalid");
-    }
-    return relative;
-  };
-  const load = (relative: string): CandidateFileState => {
-    const existing = states.get(relative);
-    if (existing) return existing;
-    const observation = observeSafePath(input.root, relative);
-    if (observation.kind === "directory" || observation.kind === "unsafe") {
-      throw new Error("candidate-patch-path-unsafe");
-    }
-    let base: string | null = null;
-    let mode: CandidateFileState["mode"] = "100644";
-    if (observation.kind === "file") {
-      const target = path.join(input.root, relative);
-      const stat = lstatSync(target);
-      if (stat.size > input.maxBytes) {
-        throw new Error("candidate-patch-source-too-large");
-      }
-      const bytes = readFileSync(target);
-      try {
-        base = new TextDecoder("utf-8", {
-          fatal: true,
-          ignoreBOM: true,
-        }).decode(bytes);
-      } catch {
-        throw new Error("candidate-patch-source-invalid");
-      }
-      if (base.includes("\0")) {
-        throw new Error("candidate-patch-source-invalid");
-      }
-      mode = stat.mode & 0o111 ? "100755" : "100644";
-    }
-    const state = { path: relative, base, current: base, mode };
-    states.set(relative, state);
-    return state;
-  };
-
-  for (const [operationIndex, operation] of input.operations.entries()) {
-    if (
-      !operation ||
-      typeof operation !== "object" ||
-      Array.isArray(operation)
-    ) {
-      throw new Error("candidate-patch-operation-invalid");
-    }
-    switch (operation.kind) {
-      case "replace": {
-        if (
-          !exactKeys(operation, ["kind", "path", "oldText", "newText"]) ||
-          !safeText(operation.oldText, input.maxBytes) ||
-          operation.oldText.length === 0 ||
-          !safeText(operation.newText, input.maxBytes)
-        ) {
-          throw new Error("candidate-patch-replace-invalid");
-        }
-        const relative = requirePath(operation.path);
-        const reject = (reason: string, hint: string): never => {
-          throw new Error(
-            JSON.stringify({
-              code: "candidate-patch-replace-invalid",
-              operationIndex,
-              ...(relative.length <= 512 && !/[\p{Cc}\p{Cf}]/u.test(relative)
-                ? { path: relative }
-                : {}),
-              reason,
-              hint,
-            }),
-          );
-        };
-        if (!writePaths.has(relative)) {
-          reject(
-            "path-not-authorized",
-            "Use only approved write paths; request context instead of widening authority.",
-          );
-        }
-        const state = load(relative);
-        const current =
-          state.current ??
-          reject(
-            "file-not-found",
-            "Use create for a new approved file, or correct the path.",
-          );
-        const occurrences = occurrenceCount(current, operation.oldText);
-        if (occurrences !== 1) {
-          reject(
-            occurrences === 0 ? "old-text-not-found" : "old-text-ambiguous",
-            "Read the approved file and supply exact unique oldText, including enough surrounding context. Operations are applied in order.",
-          );
-        }
-        state.current = current.replace(operation.oldText, operation.newText);
-        break;
-      }
-      case "rewrite": {
-        if (
-          !exactKeys(operation, ["kind", "path", "content"]) ||
-          !safeText(operation.content, input.maxBytes)
-        ) {
-          throw new Error("candidate-patch-rewrite-invalid");
-        }
-        const relative = requirePath(operation.path);
-        if (!writePaths.has(relative)) {
-          throw new Error("candidate-patch-rewrite-invalid");
-        }
-        const state = load(relative);
-        if (state.current === null) {
-          throw new Error("candidate-patch-rewrite-invalid");
-        }
-        state.current = operation.content;
-        break;
-      }
-      case "create": {
-        if (
-          !exactKeys(operation, ["kind", "path", "content", "mode"]) ||
-          !safeText(operation.content, input.maxBytes) ||
-          operation.content.length === 0 ||
-          (operation.mode !== "regular" && operation.mode !== "executable")
-        ) {
-          throw new Error("candidate-patch-create-invalid");
-        }
-        const relative = requirePath(operation.path);
-        if (!writePaths.has(relative)) {
-          throw new Error("candidate-patch-create-invalid");
-        }
-        const state = load(relative);
-        if (state.base !== null || state.current !== null) {
-          throw new Error("candidate-patch-create-invalid");
-        }
-        state.current = operation.content;
-        state.mode = operation.mode === "executable" ? "100755" : "100644";
-        break;
-      }
-      case "delete": {
-        if (!exactKeys(operation, ["kind", "path"])) {
-          throw new Error("candidate-patch-delete-invalid");
-        }
-        const relative = requirePath(operation.path);
-        if (!deletePaths.has(relative)) {
-          throw new Error("candidate-patch-delete-invalid");
-        }
-        const state = load(relative);
-        if (state.base === null || state.current === null) {
-          throw new Error("candidate-patch-delete-invalid");
-        }
-        state.current = null;
-        break;
-      }
-      default:
-        throw new Error("candidate-patch-operation-invalid");
-    }
-  }
-
-  const diff = [...states.values()]
-    .filter((state) => state.base !== state.current)
-    .sort((left, right) => compareCanonicalStrings(left.path, right.path))
-    .map(renderFileDiff)
-    .join("");
-  if (diff.length === 0) throw new Error("candidate-patch-empty");
-  return diff;
-}

package/src/candidate-workspace.ts

@@ -1,80 +0,0 @@
-import { spawn } from "node:child_process";
-import { lstatSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { observeSafePath } from "./safe-path.ts";
-
-export function runGitApply(
-  root: string,
-  diff: Uint8Array,
-  checkOnly: boolean,
-  signal: AbortSignal,
-): Promise<"ok" | "failed" | "cancelled"> {
-  if (signal.aborted) return Promise.resolve("cancelled");
-  return new Promise((resolve) => {
-    let settled = false;
-    const settle = (value: "ok" | "failed" | "cancelled") => {
-      if (settled) return;
-      settled = true;
-      signal.removeEventListener("abort", abort);
-      resolve(value);
-    };
-    const child = spawn(
-      "git",
-      [
-        // Candidate patches bind exact bytes, independent of host checkout
-        // preferences. Git's Windows autocrlf default must not rewrite them.
-        "-c",
-        "core.autocrlf=false",
-        "-c",
-        "core.eol=lf",
-        "apply",
-        ...(checkOnly ? ["--check"] : []),
-        "--recount",
-        "--whitespace=nowarn",
-        "-",
-      ],
-      { cwd: root, shell: false, stdio: ["pipe", "ignore", "ignore"] },
-    );
-    const abort = () => {
-      child.kill("SIGTERM");
-      settle("cancelled");
-    };
-    signal.addEventListener("abort", abort, { once: true });
-    child.once("error", () => settle(signal.aborted ? "cancelled" : "failed"));
-    child.once("close", (code) =>
-      settle(signal.aborted ? "cancelled" : code === 0 ? "ok" : "failed"),
-    );
-    child.stdin.on("error", () => undefined);
-    child.stdin.end(Buffer.from(diff));
-  });
-}
-export function revisionChanges(
-  root: string,
-  paths: readonly string[],
-): Record<
-  string,
-  { kind: "absent" } | { kind: "file"; bytes: Uint8Array; mode: number }
-> {
-  const changes: Record<
-    string,
-    { kind: "absent" } | { kind: "file"; bytes: Uint8Array; mode: number }
-  > = {};
-  for (const relative of [...new Set(paths)].sort()) {
-    const observation = observeSafePath(root, relative);
-    if (observation.kind === "absent") {
-      changes[relative] = { kind: "absent" };
-      continue;
-    }
-    if (observation.kind !== "file") {
-      throw new Error("workflow-candidate-path-unsafe");
-    }
-    const target = path.join(root, ...relative.split("/"));
-    const stat = lstatSync(target);
-    changes[relative] = {
-      kind: "file",
-      bytes: readFileSync(target),
-      mode: stat.mode & 0o777,
-    };
-  }
-  return changes;
-}

package/src/canonical.ts

@@ -1,16 +0,0 @@
-/** Canonical identity ordering is UTF-16 code-unit order, never host collation. */
-export function compareCanonicalStrings(left: string, right: string): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}
-
-export function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.entries(value as Record<string, unknown>)
-      .filter(([, entry]) => entry !== undefined)
-      .sort(([left], [right]) => compareCanonicalStrings(left, right))
-      .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
-      .join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
-}