@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/context-inspection.js

@@ -0,0 +1,204 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { basename, isAbsolute, join } from "node:path";
+import { git, repoRoot, resolveCommit } from "./git.js";
+import { normalizeRepoPath } from "./repo-tree.js";
+import { childEnv } from "./env.js";
+import { redactText } from "./privacy.js";
+import { validateContextBudget } from "./context-budget.js";
+import { validateContextBudget as validateContextBudget2 } from "./context-budget.js";
+const CONTEXT_INSPECTION_LIMITS = { selections: 50, files: 200, scanned: 5e3, fileBytes: 512 * 1024, totalBytes: 8 * 1024 * 1024, previewCharacters: 3e3 };
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+class ContextInspectionError extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.status = status;
+  }
+}
+function sensitiveContextPath(path) {
+  const parts = path.replace(/\\/g, "/").toLowerCase().split("/");
+  return parts.some((part) => [".git", ".ssh", ".aws", ".gnupg", ".azure", ".kube"].includes(part)) || /^(?:\.env(?:\..*)?|\.npmrc|\.netrc|\.pypirc|credentials(?:\.json)?|secrets?(?:\.json|\.ya?ml)?|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|.*\.(?:pem|key|p12|pfx|kdbx))$/.test(parts.at(-1) ?? "");
+}
+function assertContextPathAllowed(raw) {
+  if (typeof raw !== "string" || isAbsolute(raw) || /^[a-z]:/i.test(raw) || /[\x00-\x1f]/.test(raw) || raw.length > 1e3) throw new ContextInspectionError("Context paths must stay inside the repository.");
+  const path = normalizeRepoPath(raw);
+  if (!path) throw new ContextInspectionError("Select a repository file or folder.");
+  if (sensitiveContextPath(path)) throw new ContextInspectionError(`Potential credential or Git-internal path is not allowed as explicit context: ${path}`);
+  return path;
+}
+async function assertNoContextSymlinks(repo, path, baseRef) {
+  const root = await realpath(repo);
+  let current = root;
+  for (const part of path.split("/")) {
+    current = join(current, part);
+    const info = await lstat(current).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (!info) break;
+    if (info.isSymbolicLink()) throw new ContextInspectionError(`Symbolic context paths are refused: ${path}`);
+  }
+  if (baseRef) {
+    const mode = await git(["--literal-pathspecs", "ls-tree", "--format=%(objectmode)", baseRef, "--", path], root, { timeoutMs: 1e4 });
+    if (mode.code !== 0) throw new ContextInspectionError("Cannot validate the selected base context path.");
+    if (/^(?:120000|160000)$/m.test(mode.stdout.trim())) throw new ContextInspectionError(`Symbolic links and submodules are refused as explicit context: ${path}`);
+  }
+}
+const treeObjects = (text) => text.split("\0").filter(Boolean).map((record) => {
+  const tab = record.indexOf("	");
+  const [mode, type, object, size] = record.slice(0, tab).split(/\s+/);
+  return { path: record.slice(tab + 1), mode, type, object, bytes: Number(size) };
+});
+function gitBlob(repo, object, signal) {
+  if (!/^[a-f0-9]{40,64}$/.test(object)) return Promise.reject(new ContextInspectionError("Invalid context object."));
+  return new Promise((resolve, reject) => execFile("git", ["cat-file", "blob", object], { cwd: repo, env: childEnv({ GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0" }), timeout: 1e4, maxBuffer: CONTEXT_INSPECTION_LIMITS.fileBytes + 1, encoding: "buffer", signal }, (error, stdout) => error ? reject(error) : resolve(stdout)));
+}
+async function workingFile(repo, path) {
+  await assertNoContextSymlinks(repo, path);
+  const handle = await open(join(repo, path), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch((error) => {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  });
+  if (!handle) return void 0;
+  try {
+    const before = await handle.stat();
+    if (!before.isFile()) throw new ContextInspectionError("Not a regular text file.");
+    if (before.size > CONTEXT_INSPECTION_LIMITS.fileBytes) throw new ContextInspectionError("File exceeds the 512 KiB inspection limit.");
+    const buffer = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const read = await handle.read(buffer, offset, buffer.length - offset, offset);
+      if (!read.bytesRead) break;
+      offset += read.bytesRead;
+    }
+    const after = await handle.stat();
+    if (offset !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw new ContextInspectionError("File changed while being inspected. Inspect again.", 409);
+    return buffer;
+  } finally {
+    await handle.close();
+  }
+}
+async function inspectContext(input) {
+  if (!Array.isArray(input.paths) || input.paths.length > CONTEXT_INSPECTION_LIMITS.selections || input.paths.some((path) => typeof path !== "string")) throw new ContextInspectionError("Choose at most 50 repository context selections.");
+  const repo = await realpath(await repoRoot(input.repo));
+  const baseRef = await resolveCommit(repo, input.baseRef || "HEAD");
+  const files = [];
+  const seen = /* @__PURE__ */ new Set();
+  let fileBytes = 0;
+  let scanned = 0;
+  let truncated = false;
+  const add = async (path, selectedBy, source, object) => {
+    if (seen.has(path)) return;
+    seen.add(path);
+    scanned++;
+    if (files.length >= CONTEXT_INSPECTION_LIMITS.files || scanned > CONTEXT_INSPECTION_LIMITS.scanned) {
+      truncated = true;
+      return;
+    }
+    const result = { path, selectedBy, source };
+    if (sensitiveContextPath(path)) {
+      files.push({ ...result, sensitive: true, omitted: "Potential credential or Git-internal file; not included in the preview." });
+      return;
+    }
+    try {
+      assertContextPathAllowed(path);
+      await assertNoContextSymlinks(repo, path);
+      if (object && Number.isFinite(object.bytes) && object.bytes >= 0) result.bytes = object.bytes;
+      if (source === "working-copy") {
+        const info = await lstat(join(repo, path)).catch(() => void 0);
+        if (info?.isFile()) result.bytes = info.size;
+      }
+      if (object && (object.type !== "blob" || object.mode === "120000")) throw new ContextInspectionError("Symbolic links and submodules are not inspected.");
+      if (object && object.bytes > CONTEXT_INSPECTION_LIMITS.fileBytes) throw new ContextInspectionError("File exceeds the 512 KiB inspection limit.");
+      const local = source === "working-copy" ? await workingFile(repo, path) : void 0;
+      const buffer = local ?? (object ? await gitBlob(repo, object.object, input.signal) : void 0);
+      if (!local && object) result.source = "base-ref";
+      if (!buffer) throw new ContextInspectionError("File was not found in the working copy or selected base.");
+      if (fileBytes + buffer.length > CONTEXT_INSPECTION_LIMITS.totalBytes) {
+        truncated = true;
+        throw new ContextInspectionError("Aggregate file inspection exceeds 8 MiB.");
+      }
+      const text = new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+      if (text.includes("\0")) throw new ContextInspectionError("Binary file; token and text previews are unavailable.");
+      if (text.startsWith("version https://git-lfs.github.com/spec/v1")) throw new ContextInspectionError("Git LFS pointer; materialized file contents are not included in this estimate.");
+      const preview = redactText(text.slice(0, CONTEXT_INSPECTION_LIMITS.previewCharacters));
+      fileBytes += buffer.length;
+      files.push({ ...result, bytes: buffer.length, approximateTokens: Math.ceil(buffer.length / 4), hash: hash(buffer), preview, redacted: preview !== text.slice(0, CONTEXT_INSPECTION_LIMITS.previewCharacters), truncated: text.length > CONTEXT_INSPECTION_LIMITS.previewCharacters });
+    } catch (error) {
+      files.push({ ...result, omitted: error instanceof TypeError ? "Binary or invalid UTF-8 file; no text preview." : error.message });
+    }
+  };
+  for (const raw of input.paths) {
+    if (input.signal?.aborted) throw new ContextInspectionError("Context inspection cancelled.", 409);
+    let path;
+    try {
+      path = assertContextPathAllowed(raw);
+      await assertNoContextSymlinks(repo, path);
+    } catch (error) {
+      if (files.length < CONTEXT_INSPECTION_LIMITS.files) files.push({ path: raw, selectedBy: raw, source: "working-copy", sensitive: sensitiveContextPath(raw), omitted: error.message });
+      continue;
+    }
+    const exact = await git(["--literal-pathspecs", "ls-tree", "-l", "-z", baseRef, "--", path], repo, { timeoutMs: 1e4, signal: input.signal });
+    if (exact.code !== 0) throw new ContextInspectionError("Cannot inspect the selected base tree.");
+    const entry = treeObjects(exact.stdout).find((entry2) => entry2.path === path);
+    if (entry?.type === "tree") {
+      const listing = await git(["--literal-pathspecs", "ls-tree", "-r", "-l", "-z", baseRef, "--", path], repo, { timeoutMs: 1e4, signal: input.signal });
+      if (listing.code !== 0) throw new ContextInspectionError("Cannot expand the selected context directory.");
+      const entries = treeObjects(listing.stdout);
+      for (const file of entries.slice(0, CONTEXT_INSPECTION_LIMITS.scanned)) {
+        if (files.length >= CONTEXT_INSPECTION_LIMITS.files) {
+          truncated = true;
+          break;
+        }
+        await add(file.path, path, "base-ref", file);
+      }
+      if (entries.length > CONTEXT_INSPECTION_LIMITS.scanned) truncated = true;
+    } else await add(path, path, "working-copy", entry);
+  }
+  const rawAttachments = input.attachments ?? [];
+  if (!Array.isArray(rawAttachments) || rawAttachments.length > 20 || rawAttachments.some((entry) => !entry || typeof entry.name !== "string" || entry.name.length > 500 || /[\x00-\x1f]/.test(entry.name) || !Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > 10 * 1024 * 1024)) throw new ContextInspectionError("Attachment metadata must describe at most 20 files of up to 10 MiB each.");
+  const attachments = rawAttachments.map((entry) => ({ name: entry.name, bytes: entry.size, ...sensitiveContextPath(basename(entry.name)) ? { omitted: "Potential credential attachment; actual dispatch rejects this selection." } : /\.(?:txt|md|json|csv|ya?ml|[cm]?[jt]sx?|py|go|rs|html|css|xml|toml)$/i.test(entry.name) ? { approximateTokens: Math.ceil(entry.size / 4) } : {} }));
+  const attachmentBytes = attachments.reduce((sum, entry) => sum + entry.bytes, 0);
+  if (attachmentBytes > 25 * 1024 * 1024) throw new ContextInspectionError("Attachment metadata exceeds the 25 MiB context limit.");
+  const omittedBytes = files.reduce((sum, file) => sum + (file.omitted ? file.bytes ?? 0 : 0), 0);
+  return { inspectedAt: Date.now(), baseRef, files, attachments, fileBytes, omittedBytes, attachmentBytes, bytes: fileBytes + omittedBytes + attachmentBytes, approximateTokens: files.reduce((sum, file) => sum + (file.approximateTokens ?? 0), 0) + attachments.reduce((sum, entry) => sum + (entry.approximateTokens ?? 0), 0), unknownTokenAttachments: attachments.filter((entry) => entry.approximateTokens === void 0).length, truncated, scanned, note: "Folders expand committed base files only. Explicit files show current copies; local files missing from the base need individual selection. Reference contents are not pasted into prompts. Byte totals include known omitted-file sizes; unscanned files remain unknown. Token estimates cover known text only; hidden CLI history/system prompts, later file reads and image tokens are excluded." };
+}
+class ContextBudgetError extends Error {
+  constructor(evidence) {
+    super(`Explicit invocation context exceeds its configured budget: ${evidence.violations.map((entry) => `${entry.limit} ${entry.actual.toLocaleString()} > ${entry.ceiling.toLocaleString()}`).join("; ")}. Hidden provider context is not included in this measurement.`);
+    this.evidence = evidence;
+    this.name = "ContextBudgetError";
+  }
+}
+function measurePromptContext(input, rawBudget) {
+  if (typeof input.prompt !== "string") throw new ContextInspectionError("Measure the assembled invocation prompt text.");
+  const budget = validateContextBudget(rawBudget);
+  const schema = input.jsonSchema === void 0 ? "" : JSON.stringify(input.jsonSchema);
+  const promptBytes = Buffer.byteLength(input.prompt);
+  const schemaBytes = Buffer.byteLength(schema);
+  const bytes = promptBytes + schemaBytes;
+  const approximateTokens = Math.ceil(bytes / 4);
+  const violations = [];
+  if (budget?.maxPromptBytes !== void 0 && bytes > budget.maxPromptBytes) violations.push({ limit: "maxPromptBytes", actual: bytes, ceiling: budget.maxPromptBytes });
+  if (budget?.maxApproximateTokens !== void 0 && approximateTokens > budget.maxApproximateTokens) violations.push({ limit: "maxApproximateTokens", actual: approximateTokens, ceiling: budget.maxApproximateTokens });
+  return { scope: "assembled-invocation-input", measuredAt: Date.now(), promptBytes, schemaBytes, bytes, approximateTokens, hash: hash(JSON.stringify([input.prompt, schema])), resumed: !!input.resumeSessionId, excluded: ["CLI system instructions", "Earlier conversation history", "Tool output and later file reads", "Image/audio tokenization", "Provider transport wrappers"], ...budget ? { policy: budget.policy } : {}, exceeded: !!violations.length, violations };
+}
+function enforceContextBudget(input, budget) {
+  const evidence = measurePromptContext(input, budget);
+  if (evidence.exceeded && evidence.policy === "block") throw new ContextBudgetError(evidence);
+  return evidence;
+}
+export {
+  CONTEXT_INSPECTION_LIMITS,
+  ContextBudgetError,
+  ContextInspectionError,
+  assertContextPathAllowed,
+  assertNoContextSymlinks,
+  enforceContextBudget,
+  inspectContext,
+  measurePromptContext,
+  sensitiveContextPath,
+  validateContextBudget2 as validateContextBudget
+};

package/src/context.js

@@ -0,0 +1,154 @@
+import { copyFile, mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import { CONTEXT_DIR, objectTypeAt, workingCopyDiffers } from "./git.js";
+import { copyFileInside } from "./repo-config.js";
+import { normalizeRepoPath, resolveInsideRepo } from "./repo-tree.js";
+import { assertContextPathAllowed, assertNoContextSymlinks, sensitiveContextPath } from "./context-inspection.js";
+const LIMITS = {
+  paths: 50,
+  attachments: 20,
+  fileBytes: 10 * 1024 * 1024,
+  totalBytes: 25 * 1024 * 1024
+};
+const EMPTY_CONTEXT = { paths: [], attachments: [] };
+function hasStagedFiles(ctx) {
+  return ctx.attachments.length > 0 || ctx.paths.some((p) => p.workingCopy);
+}
+async function prepareContext(repo, baseRef, input, stageDir) {
+  const ctx = { paths: [], attachments: [] };
+  const rawPaths = input?.paths ?? [];
+  const rawAttachments = input?.attachments ?? [];
+  if (rawPaths.length > LIMITS.paths) throw new Error(`Too many context paths (max ${LIMITS.paths})`);
+  if (rawAttachments.length > LIMITS.attachments) throw new Error(`Too many attached files (max ${LIMITS.attachments})`);
+  let total = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const { path: raw } of rawPaths) {
+    const path = normalizeRepoPath(String(raw ?? ""));
+    if (!path || seen.has(path)) continue;
+    assertContextPathAllowed(String(raw));
+    await assertNoContextSymlinks(repo, path, baseRef);
+    seen.add(path);
+    const inBase = await objectTypeAt(repo, baseRef, path);
+    const local = await resolveInsideRepo(repo, path).then((abs) => stat(abs).then((s) => ({ abs, s }))).catch((err) => {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    });
+    if (!inBase && !local) throw new Error(`"${path}" was not found in the repository`);
+    if (inBase === "tree" || local?.s.isDirectory()) {
+      if (!inBase) throw new Error(`Folder "${path}" isn't in the base branch; commit it, or drop the individual files you need`);
+      ctx.paths.push({ path, type: "dir" });
+      continue;
+    }
+    if (!local || inBase && !await workingCopyDiffers(repo, baseRef, path)) {
+      ctx.paths.push({ path, type: "file" });
+      continue;
+    }
+    if (local.s.size > LIMITS.fileBytes) throw new Error(`"${path}" is larger than ${mb(LIMITS.fileBytes)}`);
+    total += local.s.size;
+    if (total > LIMITS.totalBytes) throw new Error(`Context files exceed ${mb(LIMITS.totalBytes)} in total`);
+    const staged = join(stageDir, "repo", ...path.split("/"));
+    await mkdir(dirname(staged), { recursive: true });
+    await copyFile(local.abs, staged);
+    ctx.paths.push({ path, type: "file", workingCopy: `${CONTEXT_DIR}/repo/${path}`, note: inBase ? "modified" : "uncommitted" });
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const att of rawAttachments) {
+    if (sensitiveContextPath(String(att.name ?? "file").replace(/\\/g, "/").split("/").at(-1))) throw new Error("Potential credential attachments are not allowed as explicit context");
+    const data = Buffer.from(String(att.data ?? ""), "base64");
+    if (data.length > LIMITS.fileBytes) throw new Error(`"${att.name}" is larger than ${mb(LIMITS.fileBytes)}`);
+    total += data.length;
+    if (total > LIMITS.totalBytes) throw new Error(`Context files exceed ${mb(LIMITS.totalBytes)} in total`);
+    const name = uniqueName(safeFileName(String(att.name ?? "file")), names);
+    await mkdir(join(stageDir, "attachments"), { recursive: true });
+    await writeFile(join(stageDir, "attachments", name), data);
+    ctx.attachments.push({ name, size: data.length, file: `${CONTEXT_DIR}/attachments/${name}` });
+  }
+  return ctx;
+}
+async function stageMessageFiles(stageDir, prefix, files) {
+  if (files.length > LIMITS.attachments) throw new Error(`Too many attached files (max ${LIMITS.attachments})`);
+  const names = /* @__PURE__ */ new Set();
+  const paths = [];
+  let total = 0;
+  for (const f of files) {
+    if (sensitiveContextPath(String(f.name ?? "file").replace(/\\/g, "/").split("/").at(-1))) throw new Error("Potential credential attachments are not allowed as message context");
+    const data = Buffer.from(String(f.data ?? ""), "base64");
+    if (data.length > LIMITS.fileBytes) throw new Error(`"${f.name}" is larger than ${mb(LIMITS.fileBytes)}`);
+    total += data.length;
+    if (total > LIMITS.totalBytes) throw new Error(`Attached files exceed ${mb(LIMITS.totalBytes)} in total`);
+    const name = uniqueName(`${prefix}-${safeFileName(String(f.name ?? "file"))}`, names);
+    const dir = join(stageDir, "messages");
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, name), data);
+    paths.push(`${CONTEXT_DIR}/messages/${name}`);
+  }
+  return paths;
+}
+async function copyMessageFiles(stageDir, worktree, files) {
+  for (const file of files) {
+    const rel = `${CONTEXT_DIR}/messages/${basename(file)}`;
+    const done = await copyFileInside(worktree, rel, join(stageDir, "messages", basename(file)));
+    if (!done.copied) throw new Error(`Couldn't put ${basename(file)} in the worktree: ${done.why ?? "it's in the way"}`);
+  }
+}
+async function copyStagedContext(stageDir, worktree) {
+  const refused = [];
+  const walk = async (rel) => {
+    for (const entry of await readdir(join(stageDir, rel), { withFileTypes: true })) {
+      const path = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile()) {
+        const done = await copyFileInside(worktree, `${CONTEXT_DIR}/${path}`, join(stageDir, path));
+        if (!done.copied) refused.push({ path: `${CONTEXT_DIR}/${path}`, why: done.why ?? "it's in the way" });
+      }
+    }
+  };
+  await walk("");
+  return refused;
+}
+function contextPrompt(ctx) {
+  if (!ctx.paths.length && !ctx.attachments.length) return "";
+  const lines = ["", "## Context from the user"];
+  if (ctx.paths.length) {
+    lines.push("The user pointed you to these. Read them before you start (paths are relative to the repository root):");
+    for (const p of ctx.paths) {
+      if (p.type === "dir") lines.push(`- \`${p.path}/\` (folder)`);
+      else if (p.note === "uncommitted") lines.push(`- \`${p.path}\` \u2014 not committed yet; the user's copy is at \`${p.workingCopy}\``);
+      else if (p.note === "modified") lines.push(`- \`${p.path}\` \u2014 the user has local changes; their version is at \`${p.workingCopy}\``);
+      else lines.push(`- \`${p.path}\``);
+    }
+  }
+  if (ctx.attachments.length) {
+    lines.push("Files the user attached:");
+    for (const a of ctx.attachments) lines.push(`- \`${a.file}\` (${kb(a.size)})`);
+  }
+  if (hasStagedFiles(ctx)) {
+    lines.push(`\`${CONTEXT_DIR}/\` is reference material: read it, but don't edit it or copy it into the codebase unless the task asks for that.`);
+  }
+  return lines.join("\n") + "\n";
+}
+function safeFileName(raw) {
+  const base = raw.split(/[\\/]/).pop() || "file";
+  const cleaned = base.replace(/[^\w.\- ()]+/g, "_").replace(/^\.+/, "_").slice(0, 120);
+  return cleaned || "file";
+}
+function uniqueName(name, taken) {
+  const ext = extname(name);
+  const stem = name.slice(0, name.length - ext.length);
+  let candidate = name;
+  for (let i = 2; taken.has(candidate.toLowerCase()); i++) candidate = `${stem} (${i})${ext}`;
+  taken.add(candidate.toLowerCase());
+  return candidate;
+}
+const kb = (bytes) => bytes < 1024 ? `${bytes} B` : `${Math.round(bytes / 1024)} KB`;
+const mb = (bytes) => `${Math.round(bytes / 1024 / 1024)} MB`;
+export {
+  EMPTY_CONTEXT,
+  LIMITS,
+  contextPrompt,
+  copyMessageFiles,
+  copyStagedContext,
+  hasStagedFiles,
+  prepareContext,
+  stageMessageFiles
+};

package/src/conventions.js

@@ -0,0 +1,283 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rename, rm, rmdir } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { CODEFLOW_HOME } from "./config.js";
+import { git, repoRoot, resolveCommit, withRepoLock } from "./git.js";
+const CONVENTIONS_PATH = ".codeflow/conventions.md";
+const MAX_CONVENTION_BYTES = 64 * 1024;
+const MAX_CONVENTION_REVISIONS = 32;
+const MAX_DOCUMENT_BYTES = MAX_CONVENTION_BYTES * MAX_CONVENTION_REVISIONS * 6 + 128 * 1024;
+const digest = (text) => createHash("sha256").update(text).digest("hex");
+const validRevision = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+const validHash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+class ConventionsError extends Error {
+  constructor(message, status = 400, current) {
+    super(message);
+    this.status = status;
+    this.current = current;
+    this.name = "ConventionsError";
+  }
+}
+const queues = /* @__PURE__ */ new Map();
+function serialized(key, fn) {
+  const next = (queues.get(key) ?? Promise.resolve()).catch(() => void 0).then(fn);
+  const tail = next.catch(() => void 0);
+  queues.set(key, tail);
+  void tail.then(() => {
+    if (queues.get(key) === tail) queues.delete(key);
+  });
+  return next;
+}
+function projectKey(id) {
+  if (typeof id !== "string" || !id.trim() || id.length > 200 || /[\x00-\x1f]/.test(id)) throw new ConventionsError("Choose an existing project for conventions.");
+  return createHash("sha256").update(id).digest("hex");
+}
+function normalizedText(value) {
+  if (typeof value !== "string" || value.includes("\0") || Buffer.from(value).toString("utf8") !== value) throw new ConventionsError("Conventions must be valid UTF-8 plain text without binary NUL characters.");
+  const text = value.replace(/\r\n/g, "\n");
+  const normalized = text && !text.endsWith("\n") ? `${text}
+` : text;
+  if (Buffer.byteLength(normalized) > MAX_CONVENTION_BYTES) throw new ConventionsError("Conventions are limited to 64 KiB including the final newline.");
+  return normalized;
+}
+function projection(document) {
+  const current = document.revisions.at(-1);
+  return { projectId: document.projectId, revision: current?.revision ?? 0, text: current?.text ?? "", hash: current?.hash ?? digest(""), updatedAt: current?.at ?? 0, history: document.revisions.slice().reverse().map(({ text: _text, ...version }) => ({ ...version })) };
+}
+async function syncDirectory(path) {
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+class ConventionsStore {
+  directory;
+  constructor(home = CODEFLOW_HOME) {
+    this.directory = join(resolve(home), "conventions");
+  }
+  file(projectId) {
+    return join(this.directory, `${projectKey(projectId)}.json`);
+  }
+  async safeDirectory(create = false) {
+    if (create) await mkdir(this.directory, { recursive: true, mode: 448 });
+    const info = await lstat(this.directory).catch((error) => {
+      if (!create && error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (info && (!info.isDirectory() || info.isSymbolicLink())) throw new ConventionsError("Conventions storage must be a regular private directory.");
+    return !!info;
+  }
+  async read(projectId) {
+    const file = this.file(projectId);
+    if (!await this.safeDirectory()) return { version: 1, projectId, revisions: [] };
+    const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch((error) => {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    });
+    if (!handle) return { version: 1, projectId, revisions: [] };
+    try {
+      const stat = await handle.stat();
+      if (!stat.isFile() || stat.size > MAX_DOCUMENT_BYTES) throw new ConventionsError("Conventions history is not a bounded regular file.");
+      const document = JSON.parse(await handle.readFile("utf8"));
+      if (!document || document.version !== 1 || document.projectId !== projectId || !Array.isArray(document.revisions) || document.revisions.length < 1 || document.revisions.length > MAX_CONVENTION_REVISIONS) throw new ConventionsError("Conventions history is invalid; it has been left untouched.");
+      let previous = 0;
+      for (const version of document.revisions) {
+        if (!version || !validRevision(version.revision) || version.revision <= previous || !Number.isSafeInteger(version.at) || version.at < 0 || typeof version.note !== "string" || version.note.length > 500 || typeof version.text !== "string" || normalizedText(version.text) !== version.text || !validHash(version.hash) || digest(version.text) !== version.hash || version.restoredFrom !== void 0 && (!validRevision(version.restoredFrom) || version.restoredFrom < 1 || version.restoredFrom >= version.revision)) throw new ConventionsError("Conventions history is invalid; it has been left untouched.");
+        previous = version.revision;
+      }
+      return document;
+    } finally {
+      await handle.close();
+    }
+  }
+  async write(document) {
+    await this.safeDirectory(true);
+    const file = this.file(document.projectId);
+    const temporary = `${file}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+      const handle = await open(temporary, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify(document));
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await this.safeDirectory();
+      await rename(temporary, file);
+      await syncDirectory(this.directory);
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+  expect(document, revision) {
+    if (!validRevision(revision)) throw new ConventionsError("Send the exact current conventions revision.");
+    const current = projection(document);
+    if (current.revision !== revision) throw new ConventionsError(`Conventions changed to revision ${current.revision}. Your draft was not saved.`, 409, current);
+    if (revision >= Number.MAX_SAFE_INTEGER) throw new ConventionsError("Conventions revision limit reached.");
+  }
+  async append(document, text, note, restoredFrom) {
+    const version = { revision: (document.revisions.at(-1)?.revision ?? 0) + 1, text, hash: digest(text), at: Date.now(), note, ...restoredFrom ? { restoredFrom } : {} };
+    const next = { ...document, revisions: [...document.revisions, version].slice(-MAX_CONVENTION_REVISIONS) };
+    await this.write(next);
+    return projection(next);
+  }
+  get(projectId) {
+    return serialized(this.file(projectId), async () => projection(await this.read(projectId)));
+  }
+  save(projectId, input) {
+    return serialized(this.file(projectId), async () => {
+      const text = normalizedText(input.text);
+      const note = input.note ?? "";
+      if (typeof note !== "string" || note.length > 500 || note.includes("\0")) throw new ConventionsError("Revision notes are limited to 500 characters.");
+      const document = await this.read(projectId);
+      this.expect(document, input.revision);
+      return this.append(document, text, note.trim());
+    });
+  }
+  previewRestore(projectId, version) {
+    return serialized(this.file(projectId), async () => {
+      const document = await this.read(projectId);
+      const found = document.revisions.find((entry) => entry.revision === version);
+      if (!validRevision(version) || version < 1 || !found) throw new ConventionsError("That conventions revision is no longer retained.", 404);
+      return { revision: projection(document).revision, version, hash: found.hash, text: found.text };
+    });
+  }
+  restore(projectId, input) {
+    return serialized(this.file(projectId), async () => {
+      const document = await this.read(projectId);
+      this.expect(document, input.revision);
+      const found = document.revisions.find((entry) => entry.revision === input.version);
+      if (!found || !validHash(input.hash) || found.hash !== input.hash) throw new ConventionsError("Preview the retained revision again before restoring it.", 409);
+      return this.append(document, found.text, `Restored revision ${found.revision}`, found.revision);
+    });
+  }
+  async inspectRepository(repo) {
+    const root = await regularRepository(repo);
+    return withRepoLock(root, () => inspectAt(root));
+  }
+  publish(projectId, input, guard) {
+    return serialized(this.file(projectId), async () => {
+      if (!guard || guard.actor !== "user" || !Array.isArray(guard.repos) || typeof guard.isIdle !== "function") throw new ConventionsError("Only an explicit user action can publish project guidance.", 403);
+      const document = await this.read(projectId);
+      this.expect(document, input.revision);
+      const current = projection(document);
+      if (!current.revision) throw new ConventionsError("Save a conventions revision before publishing it.");
+      if (input.sourceHash !== null && !validHash(input.sourceHash) || typeof input.head !== "string" || !/^[a-f0-9]{40,64}$/.test(input.head)) throw new ConventionsError("Inspect the repository file before publishing.");
+      const root = await regularRepository(input.repo);
+      const owned = await Promise.all(guard.repos.map((repo) => realpath(repo).catch(() => "")));
+      if (!owned.includes(root)) throw new ConventionsError("Publish only to a repository owned by this project.", 403);
+      return withRepoLock(root, async () => {
+        if (!await guard.isIdle()) throw new ConventionsError("Wait for repository activity to finish before publishing conventions.", 409);
+        const before = await inspectAt(root);
+        if (!before.clean) throw new ConventionsError("Commit or save existing repository changes before publishing conventions.", 409);
+        if (before.sourceHash !== input.sourceHash || before.head !== input.head) throw new ConventionsError("The repository guidance or HEAD changed. Inspect it again before publishing.", 409);
+        const directory = join(root, ".codeflow");
+        const existed = !!await lstat(directory).catch(() => void 0);
+        await mkdir(directory, { recursive: false }).catch((error) => {
+          if (error.code !== "EEXIST") throw error;
+        });
+        const temporary = join(directory, `.conventions-${randomBytes(8).toString("hex")}.tmp`);
+        let wrote = false;
+        let staged = false;
+        try {
+          await safeTarget(root);
+          const handle = await open(temporary, "wx", 420);
+          try {
+            await handle.writeFile(current.text);
+            await handle.sync();
+          } finally {
+            await handle.close();
+          }
+          const latest = await inspectAt(root);
+          const status = await git(["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ".", `:(exclude).codeflow/${basename(temporary)}`], root);
+          if (status.code !== 0 || status.stdout || latest.sourceHash !== before.sourceHash || latest.head !== before.head || !await guard.isIdle()) throw new ConventionsError("Repository activity changed during publication. Inspect and retry.", 409);
+          await safeTarget(root);
+          await rename(temporary, join(root, CONVENTIONS_PATH));
+          wrote = true;
+          await syncDirectory(directory);
+          if (!await guard.isIdle() || await resolveCommit(root) !== before.head) throw new ConventionsError("Repository activity changed during publication.", 409);
+          const add = await git(["add", "-f", "--", CONVENTIONS_PATH], root);
+          if (add.code !== 0) throw new ConventionsError("Could not stage conventions. Resolve the Git index error and retry.", 409);
+          staged = true;
+          const index = await git(["show", `:${CONVENTIONS_PATH}`], root);
+          if (index.code !== 0 || index.stdout !== current.text) throw new ConventionsError("A Git filter changed the guidance while staging. Review the repository filters before publishing.", 409);
+          return { repo: root, path: CONVENTIONS_PATH, revision: current.revision, hash: current.hash, staged: true, head: before.head, requiresCommit: true };
+        } catch (error) {
+          if (wrote) {
+            const latest = await inspectAt(root).catch(() => void 0);
+            if (latest?.head === before.head && latest.sourceHash === current.hash) {
+              const reset = staged ? await git(["reset", "-q", before.head, "--", CONVENTIONS_PATH], root) : { code: 0 };
+              if (reset.code === 0) {
+                if (before.exists) {
+                  const rollback = await open(temporary, "wx", 420);
+                  try {
+                    await rollback.writeFile(before.text);
+                    await rollback.sync();
+                  } finally {
+                    await rollback.close();
+                  }
+                  await rename(temporary, join(root, CONVENTIONS_PATH));
+                } else await rm(join(root, CONVENTIONS_PATH));
+                await syncDirectory(directory);
+                wrote = false;
+              } else throw new ConventionsError(`${error.message} The staged file needs manual review.`, 409);
+            } else throw new ConventionsError(`${error.message} Concurrent changes were preserved; review the repository file before retrying.`, 409);
+          }
+          throw error;
+        } finally {
+          await rm(temporary, { force: true });
+          if (!existed && !wrote) await rmdir(directory).catch(() => void 0);
+        }
+      });
+    });
+  }
+}
+async function regularRepository(repo) {
+  if (typeof repo !== "string" || !(await lstat(repo)).isDirectory()) throw new ConventionsError("Choose a regular project repository directory.");
+  const root = await realpath(await repoRoot(repo));
+  if ((await lstat(join(root, ".git"))).isSymbolicLink()) throw new ConventionsError("Publishing through a symbolic .git marker is refused.");
+  return root;
+}
+async function safeTarget(root) {
+  const directory = join(root, ".codeflow");
+  const target = join(root, CONVENTIONS_PATH);
+  const dir = await lstat(directory).catch((error) => {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  });
+  if (dir && (!dir.isDirectory() || dir.isSymbolicLink() || await realpath(directory) !== directory)) throw new ConventionsError("Publishing refuses symbolic links or non-directory .codeflow paths.");
+  const info = dir ? await lstat(target).catch((error) => {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }) : void 0;
+  if (info && (!info.isFile() || info.isSymbolicLink() || info.size > MAX_CONVENTION_BYTES)) throw new ConventionsError("Publish only to a regular conventions file under 64 KiB.");
+  return info;
+}
+async function inspectAt(root) {
+  const info = await safeTarget(root);
+  let text = "";
+  if (info) {
+    const handle = await open(join(root, CONVENTIONS_PATH), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const stat = await handle.stat();
+      if (!stat.isFile() || stat.size > MAX_CONVENTION_BYTES) throw new ConventionsError("The conventions file changed during inspection.", 409);
+      text = new TextDecoder("utf-8", { fatal: true }).decode(await handle.readFile());
+      if (text.includes("\0")) throw new ConventionsError("The repository conventions file is binary.");
+    } finally {
+      await handle.close();
+    }
+  }
+  const [head, branch, status, tracked] = await Promise.all([resolveCommit(root), git(["symbolic-ref", "--quiet", "--short", "HEAD"], root), git(["status", "--porcelain=v1", "-z", "--untracked-files=all"], root), git(["ls-files", "--error-unmatch", "--", CONVENTIONS_PATH], root)]);
+  if (status.code !== 0) throw new ConventionsError("Cannot inspect repository status.");
+  return { repo: root, path: CONVENTIONS_PATH, exists: !!info, tracked: tracked.code === 0, sourceHash: info ? digest(text) : null, text, head, branch: branch.code === 0 ? branch.stdout.trim() : null, clean: !status.stdout };
+}
+export {
+  CONVENTIONS_PATH,
+  ConventionsError,
+  ConventionsStore,
+  MAX_CONVENTION_BYTES,
+  MAX_CONVENTION_REVISIONS
+};