skill-family-engineering-kit 0.1.0

package/src/errors.mjs

@@ -0,0 +1,144 @@
+import { ContractsError, isRegisteredErrorCode } from "skill-family-contracts";
+
+/**
+ * Engineering kit error policy.
+ *
+ * The kit never invents error codes: every rejection carries a code from the
+ * frozen contracts registry (skill-family-contracts owns the registry; adding
+ * a code there would be a contracts change outside this package's write set).
+ *
+ * Mapping onto the frozen SFC codes:
+ * - SFC2002 (UNKNOWN_OPERATION)  — intake rejected a name outside the frozen
+ *                                  four-command vocabulary.
+ * - SFC2003 (INVALID_PARAMS)     — intake rejected option/parameter values
+ *                                  (unknown flags, malformed ids, requests
+ *                                  for mutation modes the kit does not have).
+ * - SFC2004 (EXECUTION_FAILED)   — a well-formed command failed while
+ *                                  executing; details.kind carries one stable
+ *                                  KIT_ERROR_KINDS value (same pairing the
+ *                                  harness uses for mechanism evidence).
+ * - SFC1001 (SCHEMA_VALIDATION_FAILED) — a contract document discovered in a
+ *                                  target failed its registered schema (the
+ *                                  check command reports these).
+ *
+ * HarnessError instances thrown by skill-family-harness-node are already
+ * coded (SFC2004 + their own stable kinds) and propagate unchanged; the kit
+ * never re-wraps or masks them.
+ */
+
+/**
+ * Stable kit-level failure kinds. Each value appears as `details.kind` on a
+ * KitError or as the `kind` of a plan/check finding. The set is frozen for
+ * the v1 kit; values are strings so they serialize unchanged.
+ */
+export const KIT_ERROR_KINDS = Object.freeze({
+  // scaffold
+  TARGET_NOT_DIRECTORY: "target-not-directory",
+  TARGET_NOT_EMPTY: "target-not-empty",
+  INVALID_ROOT: "invalid-root",
+  // projection
+  INVALID_MANIFEST: "invalid-manifest",
+  UNAUTHORIZED_PATH: "unauthorized-path",
+  HANDWRITTEN_OVERWRITE: "handwritten-overwrite",
+  SELF_PROJECTION: "self-projection",
+  CONFLICT_DRIFT: "conflict-drift",
+  TYPE_CONFLICT: "type-conflict",
+  SYMLINK_ON_PLANNED_PATH: "symlink-on-planned-path",
+  PROJECTION_WRITE_FAILED: "projection-write-failed",
+  // check / shared
+  CONTRACTS_MISSING: "contracts-missing",
+  CONTRACT_PARSE_FAILED: "contract-parse-failed",
+  MANAGED_FILE_MISSING: "managed-file-missing",
+  MANAGED_FILE_DRIFT: "managed-file-drift",
+  SYMLINK_AT_MANAGED_PATH: "symlink-at-managed-path",
+  CLOSURE_INPUT_MISSING: "closure-input-missing",
+  CONTRACTS_VERSION_MISMATCH: "contracts-version-mismatch",
+  README_MISSING: "readme-missing",
+  IDENTITY_MISMATCH: "identity-mismatch",
+  IDENTITY_RECORD_MISSING: "identity-record-missing",
+  GIT_NO_COMMITS: "git-no-commits",
+  GIT_DIRTY: "git-dirty",
+  MUTATION_MODE_REQUESTED: "mutation-mode-requested",
+});
+
+/** Error carrying one frozen SFC code plus a stable kit kind in details. */
+export class KitError extends ContractsError {
+  constructor(code, message, details) {
+    if (!isRegisteredErrorCode(code)) {
+      throw new TypeError(
+        `KitError refuses unregistered error code: ${String(code)}`,
+      );
+    }
+    super(code, message, details);
+    this.name = "KitError";
+  }
+}
+
+/**
+ * Builds the canonical kit execution-failure error: SFC2004 with a stable
+ * details.kind. Extra structured evidence may be merged into details but can
+ * never override the kind.
+ */
+export function kitError(kind, message, extraDetails) {
+  const values = Object.values(KIT_ERROR_KINDS);
+  if (!values.includes(kind)) {
+    throw new TypeError(`kitError: unknown kit error kind: ${String(kind)}`);
+  }
+  const details = { ...(extraDetails ?? {}), kind };
+  return new KitError("SFC2004", message, details);
+}
+
+/**
+ * Aggregate refusal error for projection refusals. The first refusal's kind
+ * becomes details.kind; it may be a kit kind OR a stable harness kind
+ * (path-traversal, symlink-escape, ...) that propagated unchanged — both
+ * sets are frozen and stable, and the SFC code stays registered.
+ */
+export function refusalError(refusals, message, extraDetails) {
+  if (!Array.isArray(refusals) || refusals.length === 0) {
+    throw new TypeError("refusalError: refusals must be a non-empty array");
+  }
+  const first = refusals[0];
+  const kind = first && typeof first.kind === "string" && first.kind.length > 0 ? first.kind : "refused";
+  return new KitError("SFC2004", message, { ...(extraDetails ?? {}), kind, refusals });
+}
+
+/** Intake rejection: a name outside the frozen four-command vocabulary. */
+export function unknownCommandError(name) {
+  return new KitError(
+    "SFC2002",
+    `unknown command: ${String(name)} (the kit has exactly four top-level commands)`,
+    { kind: "unknown-command", command: String(name) },
+  );
+}
+
+/** Intake rejection: option/parameter values violate the command contract. */
+export function invalidParamsError(message, extraDetails) {
+  return new KitError("SFC2003", message, {
+    ...(extraDetails ?? {}),
+    kind: "invalid-params",
+  });
+}
+
+/**
+ * Flags that request a mutation mode the kit structurally does not have.
+ * They are refused at intake (never silently ignored) so a caller cannot
+ * believe an auto-fix or an adopt-in-place happened.
+ */
+export const REFUSED_MUTATION_FLAGS = Object.freeze([
+  "--fix",
+  "--apply",
+  "--adopt",
+  "--write",
+  "--repair",
+  "--force",
+  "--overwrite",
+]);
+
+export function mutationModeError(flag, command) {
+  return new KitError(
+    "SFC2003",
+    `refused: '${flag}' requests a mutation mode the '${command}' command does not have (the kit never auto-fixes)`,
+    { kind: KIT_ERROR_KINDS.MUTATION_MODE_REQUESTED, flag },
+  );
+}

package/src/gitprobe.mjs

@@ -0,0 +1,230 @@
+import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Read-only Git pre-state diagnosis.
+ *
+ * The kit never performs Git writes. Diagnosis uses two layers:
+ *
+ * 1. Filesystem facts (no process is spawned at all): does `.git` exist,
+ *    and does HEAD resolve to a commit? This layer works without the git
+ *    binary and can never have a side effect.
+ *
+ * 2. One optional read-only `git status` query, strictly confined to the
+ *    frozen argument vector GIT_STATUS_ARGS. GIT_OPTIONAL_LOCKS=0 and
+ *    --no-optional-locks keep git from refreshing the index, and
+ *    core.fsmonitor is disabled so no fsmonitor state is written. The
+ *    spawn is best-effort: any failure (no binary, timeout, unreadable
+ *    repository) degrades to filesystem facts with cleanState "unknown".
+ *
+ * The result is data for plans and check reports; it is never used to
+ * decide whether a write happens (writes are bounded by manifests and
+ * containment alone).
+ */
+
+/** The single frozen read-only argument vector the kit may spawn. */
+export const GIT_STATUS_ARGS = Object.freeze([
+  "--no-optional-locks",
+  "-c",
+  "core.fsmonitor=false",
+  "status",
+  "--porcelain=2",
+]);
+
+/** Frozen read-only vector listing the index (tracked) paths. */
+export const GIT_LS_FILES_ARGS = Object.freeze([
+  "--no-optional-locks",
+  "-c",
+  "core.fsmonitor=false",
+  "ls-files",
+  "-z",
+]);
+
+/**
+ * Frozen read-only vector asking git's own ignore machinery which of the
+ * NUL-separated stdin paths are ignored. Real ignore semantics:
+ * globs, directory rules, negations and nested .gitignore files are all
+ * decided by git itself, never by a lexical reimplementation.
+ *
+ * --no-index evaluates the ignore rules purely: without it git skips
+ * index-tracked paths entirely, which would hide the tracked-but-ignored
+ * hazard. Rule files (.gitignore at every level, $GIT_DIR/info/exclude,
+ * core.excludesFile) stay authoritative; only the index filter is removed.
+ */
+export const GIT_CHECK_IGNORE_ARGS = Object.freeze([
+  "--no-optional-locks",
+  "-c",
+  "core.fsmonitor=false",
+  "check-ignore",
+  "-z",
+  "--no-index",
+  "--stdin",
+]);
+
+/** Every git invocation the kit is allowed to make (read-only verbs only). */
+export const GIT_READ_ONLY_ALLOWLIST = Object.freeze([
+  GIT_STATUS_ARGS,
+  GIT_LS_FILES_ARGS,
+  GIT_CHECK_IGNORE_ARGS,
+]);
+
+const PROBE_TIMEOUT_MS = 10_000;
+
+function gitSpawnEnv() {
+  return {
+    ...process.env,
+    GIT_OPTIONAL_LOCKS: "0",
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_CONFIG_NOSYSTEM: "1",
+  };
+}
+
+async function readGitFile(root, relPath) {
+  try {
+    return await readFile(path.join(root, ".git", relPath), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolves whether HEAD points at an existing commit, using only files
+ * under `.git`. Returns true/false/null (undecidable).
+ */
+async function headHasCommitFs(root) {
+  const head = await readGitFile(root, "HEAD");
+  if (head === null) return null;
+  const trimmed = head.trim();
+  if (/^[0-9a-f]{40}$/.test(trimmed)) return true; // detached HEAD at a commit
+  const match = /^ref:\s*(.+)$/.exec(trimmed);
+  if (!match) return null;
+  const ref = match[1].trim();
+  const loose = await readGitFile(root, ref);
+  if (loose !== null && loose.trim().length > 0) return true;
+  const packed = await readGitFile(root, "packed-refs");
+  if (packed !== null) {
+    for (const line of packed.split("\n")) {
+      if (line.startsWith("#") || line.startsWith("^")) continue;
+      const parts = line.trim().split(/\s+/);
+      if (parts.length >= 2 && parts[1] === ref) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Probes the Git pre-state of root. Never writes anywhere; the only
+ * possible process spawn is the frozen read-only status query.
+ *
+ * Returns:
+ * {
+ *   repository: boolean,            // `.git` is present
+ *   headCommit: true|false|null,    // does HEAD resolve to a commit
+ *   cleanState: true|false|null,    // null when undecidable (no spawn/fs only)
+ *   probe: "git-status"|"fs-only",  // which layer produced cleanState
+ *   spawn: "ok"|"skipped"|"failed", // whether the read-only spawn happened
+ * }
+ */
+export async function probeGitState(root, { allowSpawn = true } = {}) {
+  const result = {
+    repository: false,
+    headCommit: null,
+    cleanState: null,
+    probe: "fs-only",
+    spawn: "skipped",
+  };
+
+  const head = await readGitFile(root, "HEAD");
+  if (head === null) return result; // no .git/HEAD => not a usable repository
+  result.repository = true;
+  result.headCommit = await headHasCommitFs(root);
+
+  if (!allowSpawn) return result;
+
+  const child = spawnSync("git", [...GIT_STATUS_ARGS], {
+    cwd: root,
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+    env: gitSpawnEnv(),
+  });
+  if (child.error || child.status !== 0) {
+    result.spawn = "failed";
+    return result;
+  }
+  result.spawn = "ok";
+  result.probe = "git-status";
+  result.cleanState = child.stdout.trim().length === 0;
+  return result;
+}
+
+function splitNulList(buffer) {
+  return buffer
+    .toString("utf8")
+    .split("\0")
+    .filter((entry) => entry.length > 0);
+}
+
+/**
+ * Proves or refuses the tracked/ignore facts for candidate paths.
+ *
+ * "tracked" comes exclusively from the read-only git index (ls-files) and
+ * "ignored" exclusively from git's own ignore machinery (check-ignore):
+ * declarations from project manifests or managed locks are passed in as
+ * candidate paths only and can never impersonate tracked state.
+ *
+ * Never fabricates true/false: when spawning is not allowed, the target is
+ * not a repository, the git binary is unusable, or any frozen vector fails,
+ * the outcome is { status: "not-proven", reason } — callers must report
+ * unknown, not guess.
+ *
+ * Returns either:
+ *   { status: "not-proven", reason: "spawn-not-allowed"|"no-repository"|
+ *                                  "no-candidates"|"git-unavailable" }
+ *   { status: "proven", tracked, ignored, trackedButIgnored, ignoredNotTracked }
+ * trackedButIgnored / ignoredNotTracked are sorted arrays of candidate paths.
+ */
+export async function probeGitFacts(root, candidatePaths, { allowSpawn = true } = {}) {
+  const notProven = (reason) => ({ status: "not-proven", reason });
+  const candidates = [
+    ...new Set(
+      (candidatePaths ?? [])
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.replaceAll("\\", "/").replace(/\/+/g, "/").replace(/^\.\//, ""))
+        .filter((entry) => entry.length > 0 && !entry.startsWith(".git/")),
+    ),
+  ].sort();
+  if (!allowSpawn) return notProven("spawn-not-allowed");
+  const head = await readGitFile(root, "HEAD");
+  if (head === null) return notProven("no-repository");
+  if (candidates.length === 0) return notProven("no-candidates");
+
+  const ls = spawnSync("git", [...GIT_LS_FILES_ARGS], {
+    cwd: root,
+    encoding: "buffer",
+    timeout: PROBE_TIMEOUT_MS,
+    env: gitSpawnEnv(),
+  });
+  if (ls.error || ls.status !== 0) return notProven("git-unavailable");
+  const tracked = new Set(splitNulList(ls.stdout));
+
+  const check = spawnSync("git", [...GIT_CHECK_IGNORE_ARGS], {
+    cwd: root,
+    input: Buffer.from(candidates.join("\0") + "\0", "utf8"),
+    encoding: "buffer",
+    timeout: PROBE_TIMEOUT_MS,
+    env: gitSpawnEnv(),
+  });
+  // check-ignore exits 0 when at least one path is ignored, 1 when none is;
+  // anything else (128 = not a repository, binary failure) is never a fact.
+  if (check.error || check.status === null || check.status > 1) return notProven("git-unavailable");
+  const ignored = new Set(splitNulList(check.stdout));
+
+  return {
+    status: "proven",
+    tracked,
+    ignored,
+    trackedButIgnored: candidates.filter((entry) => tracked.has(entry) && ignored.has(entry)),
+    ignoredNotTracked: candidates.filter((entry) => !tracked.has(entry) && ignored.has(entry)),
+  };
+}