killeros 2.0.2 → 2.0.4

package/killeros/init-evidence.ts

@@ -0,0 +1,240 @@
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export const INIT_READ_TOOL = "killeros_init_read";
+export const INIT_LIST_TOOL = "killeros_init_list";
+
+const SNAPSHOT_LIMIT = 40 * 1024;
+const AUTOMATIC_FILE_LIMIT = 8 * 1024;
+const READ_LIMIT = 32 * 1024;
+const PATH_LIMIT = 400;
+const DIRECTORY_LIMIT = 120;
+const DEPTH_LIMIT = 4;
+const EXCLUDED_DIRS = new Set([
+  ".agents", ".claude", ".git", ".next", ".pi", ".pytest_cache", ".turbo", ".venv", "__pycache__", "archive", "build", "coverage", "data", "dist", "logs", "node_modules", "target", "test-results", "vendor",
+]);
+const EXCLUDED_GUIDANCE = new Set([
+  ".cursorrules", "agents.md", "agents.local.md", "claude.md", "claude.local.md", "copilot-instructions.md", "gemini.md", "memory.md", "skill.md",
+]);
+const ROOT_EVIDENCE = [
+  "README.md", "README.rst", "README.txt", "CONTRIBUTING.md", "package.json", "pyproject.toml", "requirements.txt", "Cargo.toml", "go.mod", "Makefile", "Dockerfile", "compose.yaml", "compose.yml", "config.yaml", "config.yml", "tsconfig.json", "vite.config.ts", "vite.config.js", "eslint.config.js", "eslint.config.mjs",
+] as const;
+const NESTED_EVIDENCE = new Set(["package.json", "pyproject.toml", "requirements.txt", "Cargo.toml", "go.mod"]);
+
+export interface InitEvidenceIndex {
+  projectRoot: string;
+  canonicalPaths: ReadonlyMap<string, string>;
+  snapshot: string;
+}
+
+export interface InitEvidenceBuildResult {
+  index: InitEvidenceIndex;
+}
+
+function evidenceKey(relativePath: string): string {
+  const normalized = relativePath.replaceAll("\\", "/");
+  return process.platform === "win32" ? normalized.toLocaleLowerCase() : normalized;
+}
+
+function sensitiveEvidencePath(relativePath: string): boolean {
+  const normalized = relativePath.replaceAll("\\", "/").toLocaleLowerCase();
+  const name = path.posix.basename(normalized);
+  return /^\.env(?:\.|$)/u.test(name)
+    || [".npmrc", ".pypirc", ".netrc", "id_rsa", "id_ed25519", "credentials.json"].includes(name)
+    || /^service-account.*\.json$/u.test(name)
+    || /\.(?:pem|key|p12|pfx|jks|keystore)$/u.test(name);
+}
+
+function excludedPath(relativePath: string): boolean {
+  const segments = relativePath.replaceAll("\\", "/").split("/");
+  return segments.some((segment, index) =>
+    (index < segments.length - 1 && EXCLUDED_DIRS.has(segment.toLocaleLowerCase()))
+    || EXCLUDED_GUIDANCE.has(segment.toLocaleLowerCase()))
+    || sensitiveEvidencePath(relativePath);
+}
+
+async function collectCandidates(projectRoot: string): Promise<string[]> {
+  const files: string[] = [];
+  const queue: Array<{ relativePath: string; depth: number }> = [{ relativePath: "", depth: 0 }];
+  let directoriesRead = 0;
+  while (queue.length && files.length < PATH_LIMIT && directoriesRead < DIRECTORY_LIMIT) {
+    const current = queue.shift()!;
+    directoriesRead += 1;
+    let entries;
+    try {
+      entries = await fs.readdir(path.join(projectRoot, current.relativePath), { withFileTypes: true });
+    } catch (error) {
+      if (!current.relativePath) throw error;
+      continue;
+    }
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (files.length >= PATH_LIMIT) break;
+      const relativePath = path.posix.join(current.relativePath.replaceAll("\\", "/"), entry.name);
+      if (entry.isDirectory()) {
+        if (current.depth < DEPTH_LIMIT && !EXCLUDED_DIRS.has(entry.name.toLocaleLowerCase())) {
+          queue.push({ relativePath, depth: current.depth + 1 });
+        }
+      } else if (entry.isFile() && !excludedPath(relativePath)) {
+        try {
+          const stat = await fs.lstat(path.join(projectRoot, relativePath));
+          if (stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1) files.push(relativePath);
+        } catch {
+          // Files may disappear while the bounded map is collected.
+        }
+      }
+    }
+  }
+  return files;
+}
+
+async function gitIgnoredPaths(projectRoot: string, candidates: readonly string[]): Promise<ReadonlySet<string>> {
+  if (!candidates.length) return new Set();
+  return new Promise((resolve) => {
+    let settled = false;
+    let stdout = Buffer.alloc(0);
+    const child = spawn("git", ["-C", projectRoot, "check-ignore", "--stdin", "-z"], {
+      shell: false,
+      stdio: ["pipe", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    const finish = (value: ReadonlySet<string>): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish(new Set());
+    }, 2_000);
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (stdout.length <= 256 * 1024) stdout = Buffer.concat([stdout, chunk]);
+    });
+    child.once("error", () => finish(new Set()));
+    child.once("close", (code) => {
+      if (code === 1) return finish(new Set());
+      if (code !== 0 || stdout.length > 256 * 1024 || stdout.at(-1) !== 0) return finish(new Set());
+      const candidateSet = new Set(candidates.map(evidenceKey));
+      const values = stdout.subarray(0, -1).toString("utf8").split("\0");
+      if (values.some((value) => !value || !candidateSet.has(evidenceKey(value)))) return finish(new Set());
+      finish(new Set(values.map(evidenceKey)));
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(`${candidates.join("\0")}\0`);
+  });
+}
+
+function appendWithinLimit(current: string, section: string, limit: number): string {
+  const remaining = limit - Buffer.byteLength(current, "utf8");
+  if (remaining <= 0) return current;
+  const bytes = Buffer.from(section, "utf8");
+  return current + bytes.subarray(0, remaining).toString("utf8");
+}
+
+async function validateAndRead(projectRoot: string, absolutePath: string, limit: number): Promise<{ content: string; truncated: boolean }> {
+  const relative = path.relative(projectRoot, absolutePath);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error("path is not available to /init");
+  }
+  let current = projectRoot;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    const stat = await fs.lstat(current);
+    if (stat.isSymbolicLink()) throw new Error("/init rejects symbolic-link and junction paths");
+  }
+  const pathStat = await fs.lstat(absolutePath);
+  if (!pathStat.isFile() || pathStat.nlink !== 1) throw new Error("/init rejects linked and non-regular files");
+  const handle = await fs.open(absolutePath, "r");
+  try {
+    const openedStat = await handle.stat();
+    if (!openedStat.isFile() || openedStat.nlink !== 1
+      || openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino) {
+      throw new Error("/init file changed while it was being opened");
+    }
+    const buffer = Buffer.alloc(limit + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const data = buffer.subarray(0, Math.min(bytesRead, limit));
+    if (data.includes(0)) throw new Error("/init rejects binary files");
+    return { content: data.toString("utf8"), truncated: bytesRead > limit };
+  } finally {
+    await handle.close();
+  }
+}
+
+function normalizeRequestedPath(requestedPath: string): string {
+  if (!requestedPath || requestedPath.trim() !== requestedPath || requestedPath.startsWith("~")
+    || /^file:/iu.test(requestedPath) || path.isAbsolute(requestedPath)) {
+    throw new Error("path is not available to /init");
+  }
+  const normalized = requestedPath.replaceAll("\\", "/");
+  if (!normalized || normalized.split("/").some((segment) => segment === ".." || segment === "")) {
+    throw new Error("path is not available to /init");
+  }
+  return normalized.replace(/^\.\//u, "");
+}
+
+export async function buildInitEvidence(projectRoot: string): Promise<InitEvidenceBuildResult> {
+  const candidates = await collectCandidates(projectRoot);
+  const ignored = await gitIgnoredPaths(projectRoot, candidates);
+  const canonicalPaths = new Map<string, string>();
+  for (const relativePath of candidates) {
+    if (!ignored.has(evidenceKey(relativePath))) canonicalPaths.set(evidenceKey(relativePath), relativePath);
+  }
+
+  let snapshot = [
+    "# KillerOS repository snapshot",
+    "Root AGENTS.md is protected policy and is intentionally not part of this untrusted evidence.",
+    "",
+    "## Project files",
+    [...canonicalPaths.values()].join("\n"),
+  ].join("\n");
+  snapshot = appendWithinLimit("", snapshot, SNAPSHOT_LIMIT);
+  const automatic = new Set<string>(ROOT_EVIDENCE);
+  for (const relativePath of canonicalPaths.values()) {
+    const name = path.posix.basename(relativePath);
+    if (NESTED_EVIDENCE.has(name) || /^\.github\/workflows\/[^/]+\.ya?ml$/iu.test(relativePath)) automatic.add(relativePath);
+  }
+  for (const requested of automatic) {
+    const relativePath = canonicalPaths.get(evidenceKey(requested));
+    if (!relativePath || Buffer.byteLength(snapshot, "utf8") >= SNAPSHOT_LIMIT) continue;
+    try {
+      const result = await validateAndRead(projectRoot, path.join(projectRoot, relativePath), AUTOMATIC_FILE_LIMIT);
+      const suffix = result.truncated ? "\n[truncated by /init]" : "";
+      snapshot = appendWithinLimit(snapshot, `\n\n## ${relativePath}\n${result.content}${suffix}`, SNAPSHOT_LIMIT);
+    } catch {
+      // A mapped file may become unsafe or disappear before snapshot creation.
+    }
+  }
+  return { index: { projectRoot, canonicalPaths, snapshot } };
+}
+
+export async function readInitEvidence(index: InitEvidenceIndex, requestedPath: string): Promise<string> {
+  const normalized = normalizeRequestedPath(requestedPath);
+  const relativePath = index.canonicalPaths.get(evidenceKey(normalized));
+  if (!relativePath) throw new Error(`${requestedPath} is not available to /init`);
+  const result = await validateAndRead(index.projectRoot, path.join(index.projectRoot, relativePath), READ_LIMIT);
+  return result.truncated ? `${result.content}\n[truncated by /init at ${READ_LIMIT} bytes]` : result.content;
+}
+
+export async function readGeneratedInitTarget(projectRoot: string, targetPath: string): Promise<string> {
+  const result = await validateAndRead(projectRoot, targetPath, READ_LIMIT);
+  return result.truncated ? `${result.content}\n[truncated by /init at ${READ_LIMIT} bytes]` : result.content;
+}
+
+export function listInitEvidence(index: InitEvidenceIndex, requestedPath = "."): string[] {
+  const prefix = requestedPath === "." ? "" : normalizeRequestedPath(requestedPath).replace(/\/$/u, "");
+  const prefixWithSlash = prefix ? `${prefix}/` : "";
+  const children = new Set<string>();
+  let found = !prefix;
+  for (const relativePath of index.canonicalPaths.values()) {
+    if (!relativePath.startsWith(prefixWithSlash)) continue;
+    const remainder = relativePath.slice(prefixWithSlash.length);
+    if (!remainder) continue;
+    found = true;
+    children.add(remainder.split("/")[0]!);
+  }
+  if (!found) throw new Error(`${requestedPath} is not available to /init`);
+  return [...children].sort((left, right) => left.localeCompare(right)).slice(0, PATH_LIMIT);
+}

package/killeros/init-target.ts

@@ -0,0 +1,289 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+const TARGET_LIMIT = 128 * 1024;
+const REQUIRED_GUIDANCE_HEADINGS = [
+  "# AGENTS.md",
+  "## 1. Think Before Coding",
+  "## 2. Simplicity First",
+  "## 3. Surgical Changes",
+  "## 4. Goal-Driven Execution",
+] as const;
+
+export interface InitTargetBaseline {
+  exists: boolean;
+  content?: string;
+  digest?: string;
+  dev?: number;
+  ino?: number;
+  mode?: number;
+  nlink?: number;
+}
+
+export interface InitInstallOperations {
+  renameFile?: typeof fs.rename;
+  linkFile?: typeof fs.link;
+  unlinkFile?: typeof fs.unlink;
+}
+
+function digest(content: Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function captureExistingTarget(targetPath: string): Promise<InitTargetBaseline> {
+  const pathStat = await fs.lstat(targetPath);
+  if (pathStat.isSymbolicLink() || !pathStat.isFile() || pathStat.nlink !== 1) {
+    throw new Error("/init requires root AGENTS.md to be absent or a regular, non-linked file");
+  }
+  if (pathStat.size > TARGET_LIMIT) throw new Error(`/init root AGENTS.md exceeds ${TARGET_LIMIT} bytes`);
+  const handle = await fs.open(targetPath, constants.O_RDONLY);
+  try {
+    const openedStat = await handle.stat();
+    if (!openedStat.isFile() || openedStat.nlink !== 1
+      || openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino) {
+      throw new Error("/init target changed while /init was inspecting it");
+    }
+    if (openedStat.size > TARGET_LIMIT) throw new Error(`/init root AGENTS.md exceeds ${TARGET_LIMIT} bytes`);
+    const bytes = await handle.readFile();
+    if (bytes.length > TARGET_LIMIT) throw new Error(`/init root AGENTS.md exceeds ${TARGET_LIMIT} bytes`);
+    return {
+      exists: true,
+      content: bytes.toString("utf8"),
+      digest: digest(bytes),
+      dev: openedStat.dev,
+      ino: openedStat.ino,
+      mode: openedStat.mode,
+      nlink: openedStat.nlink,
+    };
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function captureInitTargetBaseline(targetPath: string): Promise<InitTargetBaseline> {
+  try {
+    return await captureExistingTarget(targetPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { exists: false };
+    throw error;
+  }
+}
+
+function sameBaseline(left: InitTargetBaseline, right: InitTargetBaseline): boolean {
+  if (left.exists !== right.exists) return false;
+  if (!left.exists) return true;
+  return left.digest === right.digest
+    && left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.nlink === right.nlink;
+}
+
+async function installedCandidateMatches(targetPath: string, candidate: InitTargetBaseline): Promise<boolean> {
+  try {
+    const pathStat = await fs.lstat(targetPath);
+    if (pathStat.isSymbolicLink() || !pathStat.isFile() || pathStat.nlink !== 2) return false;
+    const handle = await fs.open(targetPath, constants.O_RDONLY);
+    try {
+      const openedStat = await handle.stat();
+      if (!openedStat.isFile() || openedStat.nlink !== 2
+        || openedStat.dev !== pathStat.dev || openedStat.ino !== pathStat.ino
+        || openedStat.size > TARGET_LIMIT) return false;
+      const bytes = await handle.readFile();
+      return bytes.length <= TARGET_LIMIT
+        && openedStat.dev === candidate.dev
+        && openedStat.ino === candidate.ino
+        && openedStat.mode === candidate.mode
+        && digest(bytes) === candidate.digest;
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function removeCandidateName(candidatePath: string, unlinkFile: typeof fs.unlink): Promise<void> {
+  try {
+    await unlinkFile(candidatePath);
+  } catch {
+    // The target is already committed through an exclusive hard link. Temporary-name
+    // cleanup is best effort and must not turn that successful commit into a false failure.
+  }
+}
+
+export function validateGeneratedGuidance(content: string): string | undefined {
+  const size = Buffer.byteLength(content, "utf8");
+  if (size < 1 || size > TARGET_LIMIT) return `/init output must be between 1 and ${TARGET_LIMIT} UTF-8 bytes`;
+  if (content.split("\n", 1)[0] !== "# AGENTS.md") return "generated guidance must start with the exact # AGENTS.md heading";
+  let previous = -1;
+  for (const heading of REQUIRED_GUIDANCE_HEADINGS) {
+    const matches = [...content.matchAll(new RegExp(`^${heading.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}$`, "gmu"))];
+    if (matches.length !== 1) return `generated guidance must contain ${heading} exactly once`;
+    const index = matches[0]!.index;
+    if (index <= previous) return "generated guidance headings must occur in the required order";
+    previous = index;
+  }
+  if (/\[(?:FILL IN|exact|confirmed)/iu.test(content)) return "generated guidance contains an unresolved template marker";
+  return undefined;
+}
+
+function recoveryPath(targetPath: string): string {
+  return path.join(path.dirname(targetPath), `.killeros-init-recovery-${randomUUID()}.md`);
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.lstat(filePath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function installInitAgentsFile(
+  targetPath: string,
+  content: string,
+  baseline: InitTargetBaseline,
+  operations: InitInstallOperations = {},
+): Promise<void> {
+  const validationError = validateGeneratedGuidance(content);
+  if (validationError) throw new Error(validationError);
+  const renameFile = operations.renameFile ?? fs.rename;
+  const linkFile = operations.linkFile ?? fs.link;
+  const unlinkFile = operations.unlinkFile ?? fs.unlink;
+
+  return withFileMutationQueue(targetPath, async () => {
+    const current = await captureInitTargetBaseline(targetPath);
+    if (!sameBaseline(current, baseline)) {
+      throw new Error("/init target changed while /init was generating; the newer AGENTS.md was preserved");
+    }
+
+    const tempDirectory = await fs.mkdtemp(path.join(path.dirname(targetPath), ".killeros-init-"));
+    const candidatePath = path.join(tempDirectory, "candidate.md");
+    const heldPath = path.join(tempDirectory, "held.md");
+    let held = false;
+    let installed = false;
+    let candidate: InitTargetBaseline | undefined;
+    let retainedRecovery: string | undefined;
+    try {
+      const handle = await fs.open(candidatePath, "wx", 0o600);
+      try {
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+
+      candidate = await captureExistingTarget(candidatePath);
+      if (!baseline.exists) {
+        try {
+          await linkFile(candidatePath, targetPath);
+          installed = true;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+            throw new Error("/init target changed while /init was generating; the newer AGENTS.md was preserved");
+          }
+          throw error;
+        }
+        if (!await installedCandidateMatches(targetPath, candidate)) {
+          throw new Error("/init target changed while /init was generating; the newer AGENTS.md was preserved");
+        }
+        await removeCandidateName(candidatePath, unlinkFile);
+        installed = false;
+        return;
+      }
+
+      // Node cannot lock arbitrary external writers. The exclusive links, held-target
+      // boundary, final held-file hash, and Pi mutation queue make installation fail closed.
+      await renameFile(targetPath, heldPath);
+      held = true;
+      const moved = await captureExistingTarget(heldPath);
+      if (!sameBaseline(moved, baseline)) {
+        if (!await pathExists(targetPath)) {
+          await renameFile(heldPath, targetPath);
+          held = false;
+          throw new Error("/init target changed while /init was generating; the newer AGENTS.md was preserved");
+        }
+        retainedRecovery = recoveryPath(targetPath);
+        await renameFile(heldPath, retainedRecovery);
+        held = false;
+        throw new Error(`/init target changed while /init was generating; both versions were preserved; recovery file: ${retainedRecovery}`);
+      }
+
+      try {
+        await linkFile(candidatePath, targetPath);
+        installed = true;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+          retainedRecovery = recoveryPath(targetPath);
+          await renameFile(heldPath, retainedRecovery);
+          held = false;
+          throw new Error(`/init target changed while /init was generating; the newer AGENTS.md was preserved; recovery file: ${retainedRecovery}`);
+        }
+        throw error;
+      }
+
+      const finalHeld = await captureExistingTarget(heldPath);
+      if (!sameBaseline(finalHeld, baseline) || !await installedCandidateMatches(targetPath, candidate)) {
+        throw new Error("/init target changed while /init was generating; the newer AGENTS.md was preserved");
+      }
+      await unlinkFile(heldPath);
+      held = false;
+      await removeCandidateName(candidatePath, unlinkFile);
+      installed = false;
+    } catch (error) {
+      if (held) {
+        if (installed && candidate && await installedCandidateMatches(targetPath, candidate)) {
+          try {
+            await unlinkFile(targetPath);
+            installed = false;
+          } catch {
+            // A different writer may have replaced the linked candidate.
+          }
+        }
+        if (!await pathExists(targetPath)) {
+          try {
+            await renameFile(heldPath, targetPath);
+            held = false;
+          } catch {
+            // The original error remains primary; cleanup below retains bytes if needed.
+          }
+        }
+        if (held) {
+          retainedRecovery = recoveryPath(targetPath);
+          try {
+            await renameFile(heldPath, retainedRecovery);
+            held = false;
+          } catch {
+            // Leave the non-empty temporary directory rather than deleting held bytes.
+          }
+        }
+      }
+      if (retainedRecovery && error instanceof Error && !error.message.includes(retainedRecovery)) {
+        throw new Error(`${error.message}; recovery file: ${retainedRecovery}`, { cause: error });
+      }
+      throw error;
+    } finally {
+      try {
+        await fs.rm(tempDirectory, { recursive: !held, force: !held });
+      } catch {
+        // A retained held file is safer than deleting ambiguous user bytes.
+      }
+    }
+  });
+}
+
+export async function writeInitAgentsFile(
+  targetPath: string,
+  content: string,
+  renameFile: typeof fs.rename = fs.rename,
+): Promise<void> {
+  const baseline = await captureInitTargetBaseline(targetPath);
+  return installInitAgentsFile(targetPath, content, baseline, { renameFile });
+}