qfai 2.1.1 → 2.2.0

package/dist/graph/cli.mjs

@@ -0,0 +1,1541 @@
+// src/core/graph/codePreparation.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { mkdir as mkdir4, rm as rm4 } from "fs/promises";
+import path7 from "path";
+
+// src/shared/assets.ts
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function initAssetsCandidates(baseDir) {
+  return [
+    path.resolve(baseDir, "../assets/init"),
+    path.resolve(baseDir, "../../assets/init"),
+    path.resolve(baseDir, "../../../assets/init")
+  ];
+}
+var INIT_ASSETS_SENTINELS = [
+  path.join(".qfai", "assistant"),
+  path.join("root", "qfai.config.yaml")
+];
+function isInitAssetsDir(candidate) {
+  return INIT_ASSETS_SENTINELS.every((sentinel) => existsSync(path.join(candidate, sentinel)));
+}
+function getInitAssetsDir() {
+  const base = import.meta.url;
+  const basePath = base.startsWith("file:") ? fileURLToPath(base) : base;
+  const baseDir = path.dirname(basePath);
+  const candidates = initAssetsCandidates(baseDir);
+  for (const candidate of candidates) {
+    if (isInitAssetsDir(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    [
+      "Template assets for init were not found.",
+      "Checked paths:",
+      ...candidates.map((candidate) => `- ${candidate}`)
+    ].join("\n")
+  );
+}
+
+// src/core/graph/process.ts
+import { execFile } from "child_process";
+import { access, lstat as lstat2, realpath } from "fs/promises";
+import path4 from "path";
+import { promisify } from "util";
+
+// src/core/graph/layout.ts
+import path2 from "path";
+var GRAPH_VERSIONS = { codegraph: "1.6.2", graphify: "0.9.86" };
+function graphExecutionEnvironment() {
+  return { platform: process.platform, architecture: process.arch };
+}
+function graphEnvironmentKey(environment = graphExecutionEnvironment()) {
+  if (!/^[a-z0-9]+$/i.test(environment.platform) || !/^[a-z0-9]+$/i.test(environment.architecture))
+    throw new Error("Unsupported graph execution environment.");
+  return `${environment.platform}-${environment.architecture}`;
+}
+function graphRuntimePaths(root, environment = graphExecutionEnvironment()) {
+  const directory = path2.join(root, ".qfai", "tools", "runtimes", graphEnvironmentKey(environment));
+  return {
+    directory,
+    codegraph: path2.join(
+      directory,
+      "codegraph",
+      "node_modules",
+      "@colbymchenry",
+      "codegraph",
+      "npm-shim.js"
+    ),
+    codegraphSdk: path2.join(
+      directory,
+      "codegraph",
+      "node_modules",
+      "@colbymchenry",
+      "codegraph",
+      "npm-sdk.js"
+    ),
+    codegraphNode: path2.join(
+      directory,
+      "codegraph",
+      "node_modules",
+      "@colbymchenry",
+      `codegraph-${environment.platform}-${environment.architecture}`,
+      environment.platform === "win32" ? "node.exe" : "node"
+    ),
+    python: environment.platform === "win32" ? path2.join(directory, "graphify", "Scripts", "python.exe") : path2.join(directory, "graphify", "bin", "python")
+  };
+}
+function graphAnalysisRoot(root, engine, environment = graphExecutionEnvironment()) {
+  return path2.join(root, ".qfai", "tools", "analysis", graphEnvironmentKey(environment), engine);
+}
+
+// src/core/graph/storage.ts
+import { randomUUID } from "crypto";
+import { lstat, mkdir, readdir, rename, rm } from "fs/promises";
+import path3 from "path";
+
+// src/core/fs/errno.ts
+function isEnoent(err) {
+  return hasErrnoCode(err) && err.code === "ENOENT";
+}
+function hasErrnoCode(err) {
+  return err !== null && typeof err === "object" && "code" in err && typeof err.code === "string";
+}
+
+// src/core/graph/storage.ts
+async function assertGraphStoragePath(root, directory) {
+  const relative = path3.relative(root, directory);
+  const parts = relative.split(path3.sep);
+  if (path3.isAbsolute(relative) || parts[0] !== ".qfai" || parts[1] !== "tools" || parts.includes("..")) {
+    throw new Error("Graph storage must stay inside project-local .qfai/tools.");
+  }
+  for (let depth = 1; depth <= parts.length; depth += 1) {
+    try {
+      const stats = await lstat(path3.join(root, ...parts.slice(0, depth)));
+      if (stats.isSymbolicLink() || !stats.isDirectory())
+        throw new Error(
+          "Graph storage has an unsafe path component; retain it and repair the project configuration."
+        );
+    } catch (cause) {
+      if (isEnoent(cause)) return;
+      throw cause;
+    }
+  }
+}
+async function assertIndependentAnalysis(directory) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const child = path3.join(directory, entry.name);
+    const stats = await lstat(child);
+    if (stats.isSymbolicLink() || stats.isFile() && stats.nlink > 1) {
+      throw new Error(
+        "Graph analysis contains a shared file or unsafe link; retain it and prepare an independent copy."
+      );
+    }
+    if (stats.isDirectory()) await assertIndependentAnalysis(child);
+  }
+}
+async function replaceGraphDirectory(staged, current, root) {
+  await assertGraphStoragePath(root, staged);
+  await assertGraphStoragePath(root, current);
+  const parent = path3.dirname(current);
+  await mkdir(parent, { recursive: true });
+  const previous = path3.join(parent, `.previous-${randomUUID()}`);
+  let retained = false;
+  try {
+    await rename(current, previous);
+    retained = true;
+  } catch (cause) {
+    if (!isEnoent(cause)) throw cause;
+  }
+  try {
+    await rename(staged, current);
+  } catch (cause) {
+    if (retained) await rename(previous, current);
+    throw cause;
+  }
+  if (retained) await rm(previous, { recursive: true, force: true });
+}
+
+// src/core/graph/process.ts
+var execute = promisify(execFile);
+var GRAPH_PYTHON_FLAGS = ["-I", "-X", "utf8"];
+function privateEngineEnvironment(root, engine, execution) {
+  const environment = {};
+  const allowed = {
+    path: "PATH",
+    systemroot: "SystemRoot",
+    windir: "WINDIR",
+    comspec: "ComSpec",
+    pathext: "PATHEXT",
+    tmp: "TMP",
+    temp: "TEMP",
+    lang: "LANG",
+    lc_all: "LC_ALL"
+  };
+  for (const [name, value] of Object.entries(process.env)) {
+    const canonical = allowed[name.toLowerCase()];
+    if (canonical) environment[canonical] = value;
+  }
+  const home = path4.join(root, ".qfai", "tools", "home", graphEnvironmentKey(execution), engine);
+  return {
+    ...environment,
+    HOME: home,
+    USERPROFILE: home,
+    APPDATA: path4.join(home, "AppData", "Roaming"),
+    LOCALAPPDATA: path4.join(home, "AppData", "Local"),
+    XDG_CONFIG_HOME: path4.join(home, ".config"),
+    XDG_CACHE_HOME: path4.join(home, ".cache"),
+    XDG_DATA_HOME: path4.join(home, ".local", "share"),
+    XDG_STATE_HOME: path4.join(home, ".local", "state")
+  };
+}
+function graphifyEnvironment(root, environment = graphExecutionEnvironment()) {
+  return {
+    ...privateEngineEnvironment(root, "graphify", environment),
+    PYTHONUTF8: "1",
+    PYTHONIOENCODING: "utf-8",
+    GRAPHIFY_QUERY_LOG_DISABLE: "1",
+    GRAPHIFY_OUT: "graphify-out",
+    GRAPHIFY_ALLOW_LOCAL_PROVIDERS: "0",
+    GRAPHIFY_NO_AUTO_REFRESH: "1"
+  };
+}
+function codegraphEnvironment(root, environment = graphExecutionEnvironment()) {
+  const privateEnvironment = privateEngineEnvironment(root, "codegraph", environment);
+  const home = privateEnvironment.HOME ?? "";
+  return {
+    ...privateEnvironment,
+    CODEGRAPH_INSTALL_DIR: path4.join(home, ".codegraph"),
+    CODEGRAPH_NO_DOWNLOAD: "1",
+    CODEGRAPH_NO_UPDATE_CHECK: "1",
+    CODEGRAPH_TELEMETRY: "0",
+    CODEGRAPH_DIR: ".codegraph"
+  };
+}
+function graphifyCorpusEnvironment(root, analysis) {
+  return {
+    ...graphifyEnvironment(root),
+    GRAPHIFY_OUT: path4.toNamespacedPath(path4.join(analysis, "graphify-out"))
+  };
+}
+async function graphifyConfigurationSafe(root) {
+  const home = graphifyEnvironment(root).HOME;
+  if (!home) return false;
+  try {
+    const configuration = path4.join(home, ".graphify");
+    await assertGraphStoragePath(root, configuration);
+    await lstat2(path4.join(configuration, "providers.json"));
+    return false;
+  } catch (cause) {
+    return isEnoent(cause);
+  }
+}
+var runGraphProcess = async (command, args, options) => {
+  try {
+    const result = await execute(command, [...args], {
+      cwd: options.cwd,
+      ...options.env ? { env: options.env } : {},
+      windowsHide: true,
+      timeout: options.timeoutMs ?? 12e4,
+      maxBuffer: options.maxBufferBytes ?? 4 * 1024 * 1024
+    });
+    return { exitCode: 0, stdout: result.stdout };
+  } catch (cause) {
+    if (!(cause instanceof Error) || !("code" in cause)) throw cause;
+    return { exitCode: typeof cause.code === "number" ? cause.code : 1, stdout: "" };
+  }
+};
+
+// src/core/graph/reuse.ts
+import os from "os";
+import path6 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  cp,
+  lstat as lstat4,
+  mkdir as mkdir3,
+  readFile,
+  readdir as readdir3,
+  realpath as realpath2,
+  rename as rename2,
+  rm as rm3,
+  writeFile
+} from "fs/promises";
+
+// src/core/graph/analysis.ts
+import path5 from "path";
+import { copyFile, lstat as lstat3, mkdir as mkdir2, readdir as readdir2, rm as rm2 } from "fs/promises";
+async function inspectCodeCoverage(root, run) {
+  const unknown = { complete: false, unsupported: [], unreadable: [], unparsed: [] };
+  const runtime = graphRuntimePaths(root);
+  const analysis = graphAnalysisRoot(root, "codegraph");
+  const result = await run(
+    runtime.codegraphNode,
+    [
+      "--liftoff-only",
+      path5.resolve(getInitAssetsDir(), "..", "graph", "codegraph-native.mjs"),
+      runtime.codegraphSdk,
+      analysis,
+      "coverage"
+    ],
+    { cwd: analysis, env: codegraphEnvironment(root) }
+  );
+  if (result.exitCode !== 0) return unknown;
+  let value;
+  try {
+    value = JSON.parse(result.stdout);
+  } catch {
+    return unknown;
+  }
+  if (!object(value) || Object.keys(value).length !== 4 || typeof value.complete !== "boolean" || !stringArray(value.unsupported) || !stringArray(value.unreadable) || !stringArray(value.unparsed))
+    return unknown;
+  return {
+    complete: value.complete && value.unsupported.length === 0 && value.unreadable.length === 0 && value.unparsed.length === 0,
+    unsupported: value.unsupported,
+    unreadable: value.unreadable,
+    unparsed: value.unparsed
+  };
+}
+function stringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+async function inspectCurrentCodeAnalysis(root, run) {
+  const analysis = graphAnalysisRoot(root, "codegraph");
+  return inspectCodeAnalysisAt(root, analysis, run);
+}
+async function inspectCodeAnalysisAt(root, analysis, run) {
+  await assertGraphStoragePath(root, analysis);
+  try {
+    if (!(await lstat3(path5.join(analysis, ".codegraph", "codegraph.db"))).isFile()) return false;
+  } catch (cause) {
+    if (isEnoent(cause)) return false;
+    throw cause;
+  }
+  await mirrorGraphCorpus(root, analysis);
+  return nativeCodeAnalysisCurrent(root, analysis, run);
+}
+async function nativeCodeAnalysisCurrent(root, analysis, run) {
+  const result = await run(
+    process.execPath,
+    [graphRuntimePaths(root).codegraph, "status", analysis, "--json"],
+    { cwd: root, env: codegraphEnvironment(root) }
+  );
+  if (result.exitCode !== 0) return false;
+  let value;
+  try {
+    value = JSON.parse(result.stdout);
+  } catch (cause) {
+    if (!(cause instanceof SyntaxError)) throw cause;
+    return false;
+  }
+  if (!object(value) || !object(value.index) || !object(value.pendingChanges)) return false;
+  const changes = value.pendingChanges;
+  return value.initialized === true && value.version === GRAPH_VERSIONS.codegraph && value.projectPath === analysis && value.worktreeMismatch === null && value.index.state === "complete" && value.index.pendingRefs === 0 && value.index.reindexRecommended === false && value.index.builtWithVersion === GRAPH_VERSIONS.codegraph && value.index.builtWithExtractionVersion !== void 0 && value.index.builtWithExtractionVersion === value.index.currentExtractionVersion && ["added", "modified", "removed"].every((key) => changes[key] === 0);
+}
+var excludedDirectories = /* @__PURE__ */ new Set([
+  ".git",
+  ".codegraph",
+  ".codegraph-wsl",
+  ".graphify",
+  "graphify-out",
+  "node_modules",
+  "dist",
+  "tmp",
+  ".claude",
+  ".codex",
+  ".vscode",
+  ".ssh",
+  ".aws",
+  ".azure"
+]);
+function excludedGraphInput(relative) {
+  const parts = relative.split("/");
+  const name = parts.at(-1) ?? "";
+  return parts.some((part) => excludedDirectories.has(part.toLowerCase())) || /^\.qfai\/(?:tools|report|evidence|review|discussion)(?:\/|$)/i.test(relative) || relative.toLowerCase() === ".qfai/graph-processing.json" || /^(?:\.npmrc|\.pypirc|\.netrc|\.git-credentials)$/i.test(name) || /^\.env(?:\.|$)/i.test(name) || /\.(?:pem|key|p12|pfx|keystore)$/i.test(name) || /^(?:id_(?:rsa|dsa|ecdsa|ed25519)|credentials?(?:\.|$)|secrets?(?:\.|$)|\.mcp\.json$)/i.test(
+    name
+  );
+}
+async function mirrorGraphCorpus(root, destination, scope) {
+  await assertGraphStoragePath(root, destination);
+  await assertIndependentAnalysis(destination);
+  const files = /* @__PURE__ */ new Set();
+  await visit("");
+  await removeAbsent("");
+  async function visit(relative) {
+    for (const entry of await readdir2(path5.join(root, ...relative.split("/")), {
+      withFileTypes: true
+    })) {
+      const next = relative ? `${relative}/${entry.name}` : entry.name;
+      if (excludedGraphInput(next) || entry.isSymbolicLink()) continue;
+      if (scope && !scope.some(
+        (item) => item === next || next.startsWith(`${item}/`) || item.startsWith(`${next}/`)
+      ))
+        continue;
+      if (entry.isDirectory()) {
+        await visit(next);
+      } else if (entry.isFile()) {
+        const source = path5.join(root, ...next.split("/"));
+        const stats = await lstat3(source);
+        if (!stats.isFile() || stats.nlink > 1) continue;
+        const target = path5.join(destination, ...next.split("/"));
+        await mkdir2(path5.dirname(target), { recursive: true });
+        await copyFile(source, target);
+        files.add(next);
+      }
+    }
+  }
+  async function removeAbsent(relative) {
+    for (const entry of await readdir2(path5.join(destination, ...relative.split("/")), {
+      withFileTypes: true
+    })) {
+      const next = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.name === ".codegraph" || entry.name === ".git" || entry.name === "graphify-out")
+        continue;
+      const target = path5.join(destination, ...next.split("/"));
+      if (entry.isDirectory()) await removeAbsent(next);
+      else if (!files.has(next)) await rm2(target);
+    }
+  }
+}
+function object(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/core/graph/reuse.ts
+function verifiedNativeRelease(output) {
+  const release = /^v(\d+\.\d+\.\d+)$/.exec(output.trim());
+  return release?.[1] === "24.16.0";
+}
+function graphReuseEnvironment() {
+  return { platform: process.platform, architecture: process.arch, machine: os.hostname() };
+}
+async function restoreCompletedCodeAnalysis(root, run, environment = graphReuseEnvironment()) {
+  if (environment.platform !== "win32" || environment.architecture !== "x64") return "cold";
+  const nativeRuntime = await run(graphRuntimePaths(root).codegraphNode, ["--version"], {
+    cwd: root,
+    env: codegraphEnvironment(root)
+  });
+  if (nativeRuntime.exitCode !== 0 || !verifiedNativeRelease(nativeRuntime.stdout)) return "cold";
+  const location = await completedAnalysisCache(root, "codegraph", run, environment);
+  if (!location) return "cold";
+  let candidates;
+  try {
+    candidates = await readdir3(location.directory, { withFileTypes: true });
+  } catch (cause) {
+    if (isEnoent(cause)) return "cold";
+    throw cause;
+  }
+  for (const entry of candidates) {
+    if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name.startsWith(".")) continue;
+    const candidate = path6.join(location.directory, entry.name);
+    if (!await cacheDirectorySafe(location.repository, candidate)) continue;
+    const metadata = await readSnapshotMetadata(candidate);
+    if (!metadata || Object.keys(metadata).some(
+      (key) => !["layout", "corpusPolicy", "repository", "engineVersion", "environment"].includes(key)
+    ) || metadata.layout !== 1 || metadata.corpusPolicy !== 1 || metadata.repository !== location.repository || metadata.engineVersion !== GRAPH_VERSIONS.codegraph || !sameEnvironment(metadata.environment, environment))
+      continue;
+    if (!await safeCompletedCorpus(path6.join(candidate, "analysis"))) continue;
+    if (!await safeCodegraphInputs(root, path6.join(candidate, "analysis"), run)) continue;
+    const current = graphAnalysisRoot(root, "codegraph");
+    const staged = path6.join(path6.dirname(current), `.restoring-codegraph-${randomUUID2()}`);
+    await assertGraphStoragePath(root, staged);
+    try {
+      const cached = path6.join(candidate, "analysis");
+      await assertIndependentAnalysis(cached);
+      await mkdir3(path6.dirname(staged), { recursive: true });
+      await cp(cached, staged, { recursive: true, dereference: false });
+      await assertIndependentAnalysis(staged);
+      if (!await inspectCodeAnalysisAt(root, staged, run)) continue;
+      await replaceGraphDirectory(staged, current, root);
+      return "restored";
+    } finally {
+      await rm3(staged, { recursive: true, force: true });
+    }
+  }
+  return "cold";
+}
+async function completedAnalysisCache(root, engine, run, environment = graphReuseEnvironment()) {
+  const git = await run("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+    cwd: root
+  });
+  if (git.exitCode !== 0 || !path6.isAbsolute(git.stdout.trim())) return void 0;
+  const repository = await realpath2(git.stdout.trim());
+  return {
+    repository,
+    directory: path6.join(repository, "qfai-graph-cache", graphEnvironmentKey(environment), engine)
+  };
+}
+async function publishCompletedCodeAnalysis(root, run, environment = graphReuseEnvironment()) {
+  let staged;
+  try {
+    if (environment.platform !== "win32" || environment.architecture !== "x64")
+      return "unavailable";
+    const native = await run(graphRuntimePaths(root).codegraphNode, ["--version"], {
+      cwd: root,
+      env: codegraphEnvironment(root)
+    });
+    if (native.exitCode !== 0 || !verifiedNativeRelease(native.stdout)) return "unavailable";
+    const cache = await completedAnalysisCache(root, "codegraph", run, environment);
+    if (!cache) return "unavailable";
+    await ensureCacheDirectory(cache.repository, cache.directory);
+    const analysis = graphAnalysisRoot(root, "codegraph");
+    if (!await safeCompletedCorpus(analysis) || !await safeCodegraphInputs(root, analysis, run))
+      return "unavailable";
+    const identity = randomUUID2();
+    staged = path6.join(cache.directory, `.publishing-${identity}`);
+    await mkdir3(staged);
+    await cp(analysis, path6.join(staged, "analysis"), { recursive: true, dereference: false });
+    await assertIndependentAnalysis(path6.join(staged, "analysis"));
+    if (!await safeCompletedCorpus(path6.join(staged, "analysis")) || !await safeCodegraphInputs(root, path6.join(staged, "analysis"), run))
+      return "unavailable";
+    if (!await nativeCodeAnalysisCurrent(root, path6.join(staged, "analysis"), run))
+      return "unavailable";
+    await writeFile(
+      path6.join(staged, "completed.json"),
+      JSON.stringify({
+        layout: 1,
+        corpusPolicy: 1,
+        repository: cache.repository,
+        engineVersion: GRAPH_VERSIONS.codegraph,
+        environment
+      }) + "\n"
+    );
+    await rename2(staged, path6.join(cache.directory, identity));
+    return "published";
+  } catch {
+    return "unavailable";
+  } finally {
+    if (staged) await rm3(staged, { recursive: true, force: true });
+  }
+}
+async function ensureCacheDirectory(repository, directory) {
+  const relative = path6.relative(repository, directory);
+  const parts = relative.split(path6.sep);
+  if (path6.isAbsolute(relative) || parts.includes("..") || parts[0] !== "qfai-graph-cache")
+    throw new Error("Unsafe completed analysis path.");
+  for (let depth = 1; depth <= parts.length; depth += 1) {
+    const component = path6.join(repository, ...parts.slice(0, depth));
+    let stats;
+    try {
+      stats = await lstat4(component);
+    } catch (cause) {
+      if (!isEnoent(cause)) throw cause;
+      await mkdir3(component);
+      stats = await lstat4(component);
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory())
+      throw new Error("Unsafe completed analysis path.");
+  }
+}
+async function cacheDirectorySafe(repository, candidate) {
+  const relative = path6.relative(repository, candidate);
+  const parts = relative.split(path6.sep);
+  if (path6.isAbsolute(relative) || parts.includes("..") || parts[0] !== "qfai-graph-cache")
+    return false;
+  for (let depth = 1; depth <= parts.length; depth += 1) {
+    const stats = await lstat4(path6.join(repository, ...parts.slice(0, depth)));
+    if (stats.isSymbolicLink() || !stats.isDirectory()) return false;
+  }
+  return true;
+}
+async function readSnapshotMetadata(candidate) {
+  try {
+    const stats = await lstat4(path6.join(candidate, "completed.json"));
+    if (!stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) return void 0;
+    const metadata = JSON.parse(
+      await readFile(path6.join(candidate, "completed.json"), "utf8")
+    );
+    return object2(metadata) ? metadata : void 0;
+  } catch (cause) {
+    if (isEnoent(cause) || cause instanceof SyntaxError) return void 0;
+    throw cause;
+  }
+}
+function sameEnvironment(value, environment) {
+  return object2(value) && Object.keys(value).length === 3 && value.platform === environment.platform && value.architecture === environment.architecture && value.machine === environment.machine;
+}
+async function safeCompletedCorpus(directory, relative = "", engineDirectory = ".codegraph") {
+  try {
+    for (const entry of await readdir3(path6.join(directory, ...relative.split("/")), {
+      withFileTypes: true
+    })) {
+      const next = relative ? `${relative}/${entry.name}` : entry.name;
+      const input = next.startsWith(`${engineDirectory}/`) ? next.slice(engineDirectory.length + 1) : next;
+      if (next !== engineDirectory && excludedGraphInput(input) || /\.(?:pid|lock)$/i.test(entry.name))
+        return false;
+      const stats = await lstat4(path6.join(directory, ...next.split("/")));
+      if (stats.isSymbolicLink() || stats.isFile() && stats.nlink !== 1) return false;
+      if (stats.isDirectory() && !await safeCompletedCorpus(directory, next, engineDirectory))
+        return false;
+      if (!stats.isDirectory() && !stats.isFile()) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function object2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function safeCodegraphInputs(root, analysis, run) {
+  const runtime = graphRuntimePaths(root);
+  const result = await run(
+    runtime.codegraphNode,
+    [
+      "--liftoff-only",
+      path6.resolve(getInitAssetsDir(), "..", "graph", "codegraph-native.mjs"),
+      runtime.codegraphSdk,
+      analysis,
+      "inventory"
+    ],
+    { cwd: analysis, env: codegraphEnvironment(root) }
+  );
+  if (result.exitCode !== 0) return false;
+  try {
+    const inventory = JSON.parse(result.stdout);
+    if (!object2(inventory) || !Array.isArray(inventory.files)) return false;
+    for (const file of inventory.files) {
+      if (typeof file !== "string" || !file || path6.posix.isAbsolute(file) || path6.win32.isAbsolute(file))
+        return false;
+      const normalized = file.replaceAll("\\", "/");
+      const parts = normalized.split("/");
+      if (parts.some((part) => !part || part === "." || part === "..") || excludedGraphInput(normalized))
+        return false;
+      const stats = await lstat4(path6.join(analysis, ...parts));
+      if (!stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/core/graph/codePreparation.ts
+async function prepareCodeAnalysis(root, run, environment) {
+  const current = graphAnalysisRoot(root, "codegraph");
+  const staged = path7.join(path7.dirname(current), `.preparing-codegraph-${randomUUID3()}`);
+  let created = false;
+  try {
+    if (await inspectCurrentCodeAnalysis(root, run))
+      return { status: "prepared", source: "current" };
+    if (await restoreCompletedCodeAnalysis(root, run, environment) === "restored")
+      return { status: "prepared", source: "restored" };
+    await assertGraphStoragePath(root, staged);
+    await mkdir4(staged, { recursive: true });
+    created = true;
+    await mirrorGraphCorpus(root, staged);
+    const runtime = graphRuntimePaths(root);
+    const result = await run(
+      runtime.codegraphNode,
+      [
+        "--liftoff-only",
+        path7.resolve(getInitAssetsDir(), "..", "graph", "codegraph-native.mjs"),
+        runtime.codegraphSdk,
+        staged
+      ],
+      { cwd: staged, env: codegraphEnvironment(root) }
+    );
+    if (result.exitCode !== 0 || !await inspectCodeAnalysisAt(root, staged, run)) return failed();
+    await assertIndependentAnalysis(staged);
+    await replaceGraphDirectory(staged, current, root);
+    return {
+      status: "prepared",
+      source: "generated",
+      reuse: await publishCompletedCodeAnalysis(root, run, environment)
+    };
+  } catch {
+    return failed();
+  } finally {
+    if (created) await rm4(staged, { recursive: true, force: true });
+  }
+}
+function failed() {
+  return {
+    status: "failed",
+    recovery: "Repair the local CodeGraph runtime and prepare independent analysis."
+  };
+}
+
+// src/core/graph/documents.ts
+import { mkdir as mkdir7, readFile as readFile3, rm as rm6, writeFile as writeFile3 } from "fs/promises";
+import { randomUUID as randomUUID6 } from "crypto";
+
+// src/core/graph/documentReuse.ts
+import { randomUUID as randomUUID4 } from "crypto";
+import { cp as cp2, lstat as lstat5, mkdir as mkdir5, readdir as readdir4, rename as rename3, rm as rm5, writeFile as writeFile2 } from "fs/promises";
+import path8 from "path";
+async function restoreCompletedDocumentAnalysis(root, run, inspect, environment = graphReuseEnvironment()) {
+  let staged;
+  try {
+    if (!await compatible(root, run, environment)) return "cold";
+    const cache = await completedAnalysisCache(root, "graphify", run, environment);
+    if (!cache) return "cold";
+    for (const entry of await readdir4(cache.directory, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name.startsWith(".")) continue;
+      const candidate = path8.join(cache.directory, entry.name);
+      if (!await cacheDirectorySafe(cache.repository, candidate)) continue;
+      const metadata = await readSnapshotMetadata(candidate);
+      if (!metadata || Object.keys(metadata).length !== 5 || metadata.layout !== 1 || metadata.corpusPolicy !== 1 || metadata.repository !== cache.repository || metadata.engineVersion !== GRAPH_VERSIONS.graphify || !sameEnvironment(metadata.environment, environment))
+        continue;
+      const analysis = path8.join(candidate, "analysis");
+      if (!await safeDocumentCopy(root, analysis, run)) continue;
+      const current = graphAnalysisRoot(root, "graphify");
+      staged = path8.join(path8.dirname(current), `.restoring-graphify-${randomUUID4()}`);
+      await assertGraphStoragePath(root, staged);
+      await mkdir5(path8.dirname(staged), { recursive: true });
+      await cp2(analysis, staged, { recursive: true, dereference: false });
+      await assertIndependentAnalysis(staged);
+      if (await inspect(staged, true)) {
+        await replaceGraphDirectory(staged, current, root);
+        return "restored";
+      }
+      await rm5(staged, { recursive: true, force: true });
+      staged = void 0;
+    }
+  } catch {
+    return "cold";
+  } finally {
+    if (staged) await discard(staged);
+  }
+  return "cold";
+}
+async function publishCompletedDocumentAnalysis(root, run, inspect, environment = graphReuseEnvironment()) {
+  let staged;
+  try {
+    if (!await compatible(root, run, environment)) return "unavailable";
+    const cache = await completedAnalysisCache(root, "graphify", run, environment);
+    if (!cache) return "unavailable";
+    await ensureCacheDirectory(cache.repository, cache.directory);
+    const analysis = graphAnalysisRoot(root, "graphify");
+    if (!await safeDocumentCopy(root, analysis, run)) return "unavailable";
+    const identity = randomUUID4();
+    staged = path8.join(cache.directory, `.publishing-${identity}`);
+    await mkdir5(staged);
+    const copy = path8.join(staged, "analysis");
+    await cp2(analysis, copy, { recursive: true, dereference: false });
+    await assertIndependentAnalysis(copy);
+    if (!await safeDocumentCopy(root, copy, run) || !await inspect(copy, false))
+      return "unavailable";
+    await writeFile2(
+      path8.join(staged, "completed.json"),
+      JSON.stringify({
+        layout: 1,
+        corpusPolicy: 1,
+        repository: cache.repository,
+        engineVersion: GRAPH_VERSIONS.graphify,
+        environment
+      }) + "\n"
+    );
+    await rename3(staged, path8.join(cache.directory, identity));
+    return "published";
+  } catch {
+    return "unavailable";
+  } finally {
+    if (staged) await discard(staged);
+  }
+}
+async function compatible(root, run, environment) {
+  if (environment.platform !== "win32" || environment.architecture !== "x64") return false;
+  const result = await run(
+    graphRuntimePaths(root).python,
+    [...GRAPH_PYTHON_FLAGS, "-c", "import sys; print(sys.version.split()[0])"],
+    { cwd: root, env: graphifyEnvironment(root) }
+  );
+  return result.exitCode === 0 && result.stdout.trim() === "3.12.13";
+}
+async function safeDocumentCopy(root, analysis, run) {
+  if (!await safeCompletedCorpus(analysis, "", "graphify-out")) return false;
+  const result = await run(
+    graphRuntimePaths(root).python,
+    [
+      ...GRAPH_PYTHON_FLAGS,
+      path8.resolve(getInitAssetsDir(), "..", "graph", "graphify-native.py"),
+      path8.toNamespacedPath(analysis),
+      "inventory"
+    ],
+    { cwd: analysis, env: graphifyCorpusEnvironment(root, analysis) }
+  );
+  if (result.exitCode !== 0) return false;
+  try {
+    const inventory = JSON.parse(result.stdout);
+    if (typeof inventory !== "object" || inventory === null || Object.keys(inventory).length !== 1 || !("files" in inventory) || !Array.isArray(inventory.files))
+      return false;
+    for (const file of inventory.files) {
+      if (typeof file !== "string" || path8.posix.isAbsolute(file) || path8.win32.isAbsolute(file))
+        return false;
+      const parts = file.replaceAll("\\", "/").split("/");
+      if (parts.some((part) => !part || part === "." || part === "..") || excludedGraphInput(parts.join("/")))
+        return false;
+      const stats = await lstat5(path8.join(analysis, ...parts));
+      if (!stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function discard(directory) {
+  try {
+    await rm5(directory, { recursive: true, force: true });
+  } catch {
+  }
+}
+
+// src/core/graph/locks.ts
+import { randomUUID as randomUUID5 } from "crypto";
+import { unlink } from "fs/promises";
+import path11 from "path";
+
+// src/core/graph/localFiles.ts
+import { lstat as lstat7, mkdir as mkdir6, open as open2 } from "fs/promises";
+import path10 from "path";
+
+// src/core/init/fsGuards.ts
+import { constants } from "fs";
+import { access as access2, lstat as lstat6, open, readFile as readFile2, stat } from "fs/promises";
+import path9 from "path";
+async function readPinnedRegularFileBytes(filePath, maxBytes) {
+  let handle;
+  try {
+    handle = await open(filePath, OPEN_READ_FLAGS);
+    const pinned = await handle.stat();
+    if (!pinned.isFile() || pinned.size > maxBytes) return null;
+    const buffer = Buffer.alloc(maxBytes + 1);
+    let filled = 0;
+    while (filled < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, filled);
+      if (bytesRead === 0) break;
+      filled += bytesRead;
+    }
+    if (filled > maxBytes) return null;
+    return {
+      content: Buffer.from(buffer.subarray(0, filled)),
+      mode: pinned.mode & 4095,
+      uid: pinned.uid,
+      gid: pinned.gid,
+      dev: pinned.dev,
+      ino: pinned.ino
+    };
+  } catch (error) {
+    const code = error?.code;
+    if (code === "ENXIO" || code === "EISDIR") return null;
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+var OPEN_READ_FLAGS = typeof constants.O_NONBLOCK === "number" ? constants.O_RDONLY | constants.O_NONBLOCK : constants.O_RDONLY;
+
+// src/core/graph/localFiles.ts
+var GRAPH_STATE_BYTES = 32768;
+var GRAPH_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+var GraphLocalStateError = class extends Error {
+  constructor(message, recovery, options) {
+    super(message, options);
+    this.recovery = recovery;
+  }
+};
+async function graphStateDirectory(root) {
+  const directory = path10.join(root, ".qfai", "tools", "state", graphEnvironmentKey());
+  await assertGraphStoragePath(root, directory);
+  await mkdir6(directory, { recursive: true });
+  await assertGraphStoragePath(root, directory);
+  return directory;
+}
+function invalidGraphState() {
+  return new GraphLocalStateError(
+    "Project graph permission state is invalid.",
+    "Retain the local state and repair .qfai/tools/state before retrying the graph CLI or hook."
+  );
+}
+function graphStateText(value, maximum) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maximum && !value.includes("\0");
+}
+async function readGraphLocalFile(file) {
+  try {
+    const before = await lstat7(file);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)
+      throw invalidGraphState();
+    const pinned = await readPinnedRegularFileBytes(file, GRAPH_STATE_BYTES);
+    const after = await lstat7(file);
+    if (!pinned || before.dev !== pinned.dev || before.ino !== pinned.ino || after.dev !== pinned.dev || after.ino !== pinned.ino || !after.isFile() || after.isSymbolicLink() || after.nlink !== 1)
+      throw invalidGraphState();
+    return pinned.content.toString("utf8");
+  } catch (cause) {
+    if (isEnoent(cause)) return void 0;
+    throw cause;
+  }
+}
+async function writeGraphLocalFile(file, value) {
+  const text = JSON.stringify(value);
+  if (Buffer.byteLength(text) > GRAPH_STATE_BYTES) throw invalidGraphState();
+  const handle = await open2(file, "wx", 384);
+  try {
+    await handle.writeFile(text, "utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/core/graph/locks.ts
+async function withGraphLock(root, kind, action) {
+  const directory = await graphStateDirectory(root);
+  const file = path11.join(directory, `${kind}.lock`);
+  const owner = {
+    kind: "graph-lock",
+    pid: process.pid,
+    createdAt: Date.now(),
+    token: randomUUID5()
+  };
+  try {
+    await writeGraphLocalFile(file, owner);
+  } catch (cause) {
+    if (!hasErrnoCode(cause) || cause.code !== "EEXIST") throw cause;
+    const text = await readGraphLocalFile(file);
+    let active = false;
+    try {
+      const existing = text === void 0 ? void 0 : JSON.parse(text);
+      if (typeof existing !== "object" || existing === null || Array.isArray(existing))
+        throw new Error("Invalid graph lock metadata.", { cause });
+      const value = existing;
+      if (Object.keys(value).length !== 4 || value.kind !== "graph-lock" || typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0 || typeof value.createdAt !== "number" || !Number.isSafeInteger(value.createdAt) || value.createdAt < 0 || typeof value.token !== "string" || !GRAPH_UUID.test(value.token))
+        throw new Error("Invalid graph lock metadata.", { cause });
+      try {
+        process.kill(value.pid, 0);
+        active = true;
+      } catch (liveness) {
+        if (!hasErrnoCode(liveness) || liveness.code !== "ESRCH") active = true;
+      }
+    } catch {
+    }
+    throw new GraphLocalStateError(
+      `Project graph ${kind} lock ${active ? "is contended" : "requires manual recovery"}.`,
+      active ? `Retry after the active worktree ${kind} operation finishes; retain its lock.` : `Retain and inspect .qfai/tools/state/${graphEnvironmentKey()}/${kind}.lock; remove only a confirmed abandoned worktree lock before retrying.`,
+      { cause }
+    );
+  }
+  try {
+    return await action();
+  } finally {
+    await releaseGraphLock(file, JSON.stringify(owner));
+  }
+}
+async function releaseGraphLock(file, owner) {
+  const text = await readGraphLocalFile(file);
+  if (text !== owner)
+    throw new GraphLocalStateError(
+      "Project graph lock ownership changed.",
+      "Retain the lock and repair the worktree graph state before retrying."
+    );
+  await unlink(file);
+}
+
+// src/core/graph/documents.ts
+import path12 from "path";
+function notCurrent() {
+  return { current: false, unsupported: [], unreadable: [] };
+}
+var DOCUMENT_PROCESSING_SETUP = 'Configure a selected local backend and model in .qfai/graph-processing.json using .agents/rules/graph-exploration.md, then run node .qfai/tools/graph-cli.mjs documents "<question>".';
+async function prepareDocumentAnalysisLocked(root, run = runGraphProcess, approveExternal = () => Promise.resolve(false), environment) {
+  if (!await graphifyConfigurationSafe(root)) return providerConflict();
+  if (await inspectDocumentAnalysis(root, run)) return { status: "prepared", source: "current" };
+  const processing = await readGraphProcessing(root);
+  if (!processing) {
+    return {
+      status: "not-ready",
+      recovery: DOCUMENT_PROCESSING_SETUP
+    };
+  }
+  const inspect = async (analysis, refresh) => (await inspectDocumentScopeAt(root, analysis, run, refresh)).current;
+  if (await restoreCompletedDocumentAnalysis(root, run, inspect, environment) === "restored")
+    return { status: "prepared", source: "restored" };
+  const endpoint = processing.endpoint ?? "http://127.0.0.1:11434/v1";
+  const selected = new URL(endpoint);
+  const backend = processing.backend;
+  const credential = typeof processing.credentialEnv === "string" ? process.env[processing.credentialEnv] : void 0;
+  if (processing.credentialEnv !== void 0 && !credential) {
+    return {
+      status: "not-ready",
+      recovery: "Set the explicitly selected credential environment variable before document processing."
+    };
+  }
+  const local = ["127.0.0.1", "localhost", "[::1]"].includes(selected.hostname);
+  let scope;
+  if (processing.scope !== void 0) {
+    if (!validDocumentScope(processing.scope))
+      return { status: "not-ready", recovery: "Select the exact document scope for processing." };
+    scope = Object.freeze(processing.scope.map((item) => item.replaceAll("\\", "/")));
+  }
+  if (!local) {
+    if (!scope) {
+      return {
+        status: "not-ready",
+        recovery: "Select the exact document scope for external processing."
+      };
+    }
+    const approval = await approveExternal(
+      Object.freeze({
+        destination: endpoint,
+        scope,
+        backend,
+        model: processing.model,
+        worktree: root
+      })
+    );
+    if (approval !== true) {
+      return {
+        status: "not-ready",
+        recovery: "External document processing requires explicit human authorization of its destination and scope."
+      };
+    }
+  }
+  const current = graphAnalysisRoot(root, "graphify");
+  const staged = path12.join(path12.dirname(current), `.preparing-graphify-${randomUUID6()}`);
+  await assertGraphStoragePath(root, staged);
+  await mkdir7(staged, { recursive: true });
+  try {
+    await mirrorGraphCorpus(root, staged, scope);
+    const result = await run(
+      graphRuntimePaths(root).python,
+      [
+        ...GRAPH_PYTHON_FLAGS,
+        "-m",
+        "graphify",
+        "extract",
+        path12.toNamespacedPath(staged),
+        "--backend",
+        backend,
+        "--model",
+        processing.model,
+        "--no-cluster",
+        "--no-dedup",
+        "--max-workers",
+        "1",
+        "--max-concurrency",
+        "1"
+      ],
+      {
+        cwd: staged,
+        env: {
+          ...graphifyCorpusEnvironment(root, staged),
+          [backend === "ollama" ? "OLLAMA_BASE_URL" : "OPENAI_BASE_URL"]: endpoint,
+          ...credential ? { [backend === "ollama" ? "OLLAMA_API_KEY" : "OPENAI_API_KEY"]: credential } : {}
+        }
+      }
+    );
+    if (result.exitCode !== 0 || !await currentGraphifyCorpus(root, staged, graphRuntimePaths(root).python, run)) {
+      return {
+        status: "failed",
+        recovery: "Check the selected local model and repair Graphify document analysis."
+      };
+    }
+    await writeFile3(
+      path12.join(staged, "graphify-out", "managed.json"),
+      JSON.stringify({ engineVersion: GRAPH_VERSIONS.graphify, scope: "documents", processing })
+    );
+    await assertIndependentAnalysis(staged);
+    await replaceGraphDirectory(staged, current, root);
+    return {
+      status: "prepared",
+      source: "generated",
+      reuse: await publishCompletedDocumentAnalysis(root, run, inspect, environment)
+    };
+  } finally {
+    await rm6(staged, { recursive: true, force: true });
+  }
+}
+async function readGraphProcessing(root) {
+  const processing = await readOptionalJson(path12.join(root, ".qfai", "graph-processing.json"));
+  return validGraphProcessing(processing) ? processing : void 0;
+}
+function validGraphProcessing(processing) {
+  const allowed = /* @__PURE__ */ new Set(["backend", "model", "endpoint", "scope", "credentialEnv"]);
+  if (!object3(processing) || Object.keys(processing).some((key) => !allowed.has(key)) || processing.backend !== "ollama" && processing.backend !== "openai" || typeof processing.model !== "string" || !processing.model.trim() || processing.scope !== void 0 && !validDocumentScope(processing.scope) || processing.credentialEnv !== void 0 && (typeof processing.credentialEnv !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(processing.credentialEnv)))
+    return false;
+  if (processing.endpoint !== void 0) {
+    if (typeof processing.endpoint !== "string" || !processing.endpoint.trim()) return false;
+    try {
+      const endpoint = new URL(processing.endpoint);
+      if (!["http:", "https:"].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash)
+        return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+async function inspectDocumentAnalysis(root, run) {
+  return (await inspectDocumentScope(root, run)).current;
+}
+async function inspectDocumentScope(root, run) {
+  const analysis = graphAnalysisRoot(root, "graphify");
+  await assertGraphStoragePath(root, analysis);
+  return inspectDocumentScopeAt(root, analysis, run);
+}
+async function inspectDocumentScopeAt(root, analysis, run, refresh = true) {
+  const managed = await readOptionalJson(path12.join(analysis, "graphify-out", "managed.json"));
+  const selected = await readGraphProcessing(root);
+  const processing = await processingForCompletedQuery(
+    root,
+    selected,
+    object3(managed) ? managed.processing : void 0
+  );
+  if (!object3(managed) || Object.keys(managed).length !== 3 || managed.engineVersion !== GRAPH_VERSIONS.graphify || managed.scope !== "documents" || !sameProcessing(managed.processing, processing))
+    return notCurrent();
+  if (!await safeDocumentCopy(root, analysis, run)) return notCurrent();
+  const scope = object3(processing) && validDocumentScope(processing.scope) ? processing.scope : void 0;
+  if (refresh) await mirrorGraphCorpus(root, analysis, scope);
+  return nativeGraphifyScope(root, analysis, graphRuntimePaths(root).python, run);
+}
+async function processingForCompletedQuery(root, selected, recorded) {
+  if (selected !== void 0) return selected;
+  try {
+    await readFile3(path12.join(root, ".qfai", "graph-processing.json"));
+    return void 0;
+  } catch (cause) {
+    if (!isEnoent(cause)) throw cause;
+  }
+  if (!validGraphProcessing(recorded)) return void 0;
+  return recorded;
+}
+async function currentGraphifyCorpus(root, analysis, python, run, kind = "semantic") {
+  return (await nativeGraphifyScope(root, analysis, python, run, kind)).current;
+}
+async function nativeGraphifyScope(root, analysis, python, run, kind = "semantic") {
+  if (!await graphifyConfigurationSafe(root)) return notCurrent();
+  const result = await run(
+    python,
+    [
+      ...GRAPH_PYTHON_FLAGS,
+      path12.resolve(getInitAssetsDir(), "..", "graph", "graphify-native.py"),
+      path12.toNamespacedPath(analysis),
+      kind
+    ],
+    {
+      cwd: analysis,
+      env: graphifyCorpusEnvironment(root, analysis)
+    }
+  );
+  if (result.exitCode !== 0) return notCurrent();
+  let state;
+  try {
+    state = JSON.parse(result.stdout);
+  } catch (cause) {
+    if (!(cause instanceof SyntaxError)) throw cause;
+    return notCurrent();
+  }
+  if (!object3(state) || typeof state.current !== "boolean" || !stringArray2(state.unsupported) || !stringArray2(state.unreadable))
+    return notCurrent();
+  const sourcePath = (file) => path12.isAbsolute(file) ? path12.relative(path12.toNamespacedPath(analysis), path12.toNamespacedPath(file)).split(path12.sep).join("/") : file;
+  return {
+    current: state.current,
+    unsupported: state.unsupported.map(sourcePath),
+    unreadable: state.unreadable.map(sourcePath)
+  };
+}
+async function readOptionalJson(file) {
+  try {
+    return JSON.parse(await readFile3(file, "utf8"));
+  } catch (cause) {
+    if (isEnoent(cause) || cause instanceof SyntaxError) return void 0;
+    throw cause;
+  }
+}
+function object3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sameProcessing(left, right) {
+  if (!object3(left) || !object3(right)) return false;
+  const fields = ["backend", "model", "endpoint", "credentialEnv", "scope"];
+  if (Object.keys(left).some((key) => !fields.includes(key))) return false;
+  return fields.every((key) => JSON.stringify(left[key]) === JSON.stringify(right[key]));
+}
+function stringArray2(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function validDocumentScope(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(
+    (item) => typeof item === "string" && item !== "" && !path12.isAbsolute(item) && !item.split(/[\\/]/).some((part) => part === ".." || part === "." || part === "")
+  );
+}
+function providerConflict() {
+  return {
+    status: "not-ready",
+    recovery: "Review private Graphify provider settings and unsafe home paths before processing; existing settings were retained."
+  };
+}
+
+// src/core/graph/query.ts
+import { readFile as readFile4 } from "fs/promises";
+import path13 from "path";
+async function exploreGraph(root, request, run = runGraphProcess) {
+  const requestedScope = Object.freeze({ ...request });
+  try {
+    return { ...await exploreGraphScope(root, request, run), requestedScope };
+  } catch {
+    const engine = request.domain === "code" ? "codegraph" : "graphify";
+    return {
+      requestedScope,
+      engine,
+      status: "failed",
+      failure: `${engine === "codegraph" ? "CodeGraph" : "Graphify"} operation failed.`,
+      recovery: `Repair ${engine === "codegraph" ? "CodeGraph" : "Graphify"} analysis and retry the graph query.`
+    };
+  }
+}
+async function exploreGraphScope(root, request, run) {
+  const documentScope = request.domain === "documents" ? await inspectDocumentScope(root, run) : void 0;
+  if (documentScope?.current) {
+    const result = await run(
+      graphRuntimePaths(root).python,
+      [
+        ...GRAPH_PYTHON_FLAGS,
+        "-m",
+        "graphify",
+        "query",
+        request.question,
+        "--graph",
+        path13.toNamespacedPath(
+          path13.join(graphAnalysisRoot(root, "graphify"), "graphify-out", "graph.json")
+        )
+      ],
+      {
+        cwd: graphAnalysisRoot(root, "graphify"),
+        env: graphifyCorpusEnvironment(root, graphAnalysisRoot(root, "graphify"))
+      }
+    );
+    if (result.exitCode !== 0 && result.exitCode !== 4) {
+      return {
+        engine: "graphify",
+        status: "failed",
+        failure: "Graphify query failed.",
+        recovery: "Repair Graphify analysis and retry the graph query."
+      };
+    }
+    const coverage = {
+      unsupported: documentScope.unsupported,
+      unreadable: documentScope.unreadable
+    };
+    const inference = result.stdout.includes("[INFERRED]") ? {
+      inferenceNotice: "Inferred relationships need source confirmation; they do not establish semantic correctness or complete coverage."
+    } : {};
+    if (coverage.unsupported.length > 0 || coverage.unreadable.length > 0) {
+      return {
+        engine: "graphify",
+        status: "incomplete",
+        answer: result.stdout,
+        coverage,
+        ...inference,
+        recovery: "Review unsupported and unreadable scope; this result does not establish absence."
+      };
+    }
+    return {
+      engine: "graphify",
+      status: result.exitCode === 4 ? "no-match" : "answered",
+      answer: result.stdout,
+      coverage,
+      ...inference
+    };
+  }
+  if (request.domain === "code" && await inspectCurrentCodeAnalysis(root, run)) {
+    const result = await run(
+      process.execPath,
+      [
+        graphRuntimePaths(root).codegraph,
+        "context",
+        request.question,
+        "--path",
+        graphAnalysisRoot(root, "codegraph"),
+        "--format",
+        "json",
+        "--no-code"
+      ],
+      {
+        cwd: root,
+        env: codegraphEnvironment(root)
+      }
+    );
+    const context = nativeCodeContext(result.stdout, request.question);
+    if (result.exitCode !== 0 || !context)
+      return {
+        engine: "codegraph",
+        status: "failed",
+        failure: "CodeGraph query failed or returned unusable data.",
+        recovery: "Repair CodeGraph analysis and retry the graph query."
+      };
+    const coverage = await inspectCodeCoverage(root, run);
+    if (!coverage.complete)
+      return {
+        engine: "codegraph",
+        status: "incomplete",
+        answer: result.stdout,
+        coverage,
+        recovery: "Review unknown, unsupported, unreadable and unparsed code scope; this result does not establish absence."
+      };
+    return {
+      engine: "codegraph",
+      status: context.empty ? "no-match" : "answered",
+      answer: result.stdout,
+      coverage,
+      ...context.empty ? {
+        inferenceNotice: "No match in this context search over the confirmed native code scope; this does not establish global absence."
+      } : {}
+    };
+  }
+  return {
+    engine: request.domain === "code" ? "codegraph" : "graphify",
+    status: "not-ready",
+    recovery: request.domain === "documents" && await readGraphProcessing(root) === void 0 ? "Select document processing in .qfai/graph-processing.json before preparing document analysis." : "Prepare the requested graph analysis before querying it."
+  };
+}
+function nativeCodeContext(stdout, question) {
+  let value;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    return void 0;
+  }
+  if (!object4(value) || value.query !== question || typeof value.summary !== "string")
+    return void 0;
+  const arrays = ["entryPoints", "nodes", "edges", "codeBlocks", "relatedFiles"];
+  if (arrays.some((key) => !Array.isArray(value[key])) || !object4(value.stats)) return void 0;
+  const stats = value.stats;
+  const counts = ["nodeCount", "edgeCount", "fileCount", "codeBlockCount", "totalCodeSize"];
+  if (counts.some((key) => !Number.isSafeInteger(stats[key]) || Number(stats[key]) < 0))
+    return void 0;
+  for (const [count, entries] of [
+    ["nodeCount", "nodes"],
+    ["edgeCount", "edges"],
+    ["fileCount", "relatedFiles"],
+    ["codeBlockCount", "codeBlocks"]
+  ]) {
+    const list = value[entries];
+    if (!Array.isArray(list) || stats[count] !== list.length) return void 0;
+  }
+  const empty = stats.nodeCount === 0;
+  if (empty && (arrays.some((key) => Array.isArray(value[key]) && value[key].length !== 0) || counts.some((key) => stats[key] !== 0)))
+    return void 0;
+  return { empty };
+}
+function object4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/core/graph/runner.ts
+async function queryPreparedGraph(root, request, run = runGraphProcess) {
+  return withGraphLock(root, "analysis", async () => {
+    const initial = await exploreGraph(root, request, run);
+    if (initial.status !== "not-ready") return initial;
+    const preparation = request.domain === "code" ? await prepareCodeAnalysis(root, run) : await prepareDocumentAnalysisLocked(root, run);
+    if (preparation.status !== "prepared")
+      return {
+        ...initial,
+        status: preparation.status === "failed" ? "failed" : "not-ready",
+        ...preparation.status === "failed" ? {
+          failure: `${initial.engine === "codegraph" ? "CodeGraph" : "Graphify"} analysis preparation failed.`
+        } : {},
+        ...preparation.recovery ? { recovery: preparation.recovery } : {}
+      };
+    return exploreGraph(root, request, run);
+  });
+}
+
+// src/core/graph/fallbackState.ts
+import { randomUUID as randomUUID7 } from "crypto";
+import { rename as rename4, unlink as unlink3 } from "fs/promises";
+import path15 from "path";
+
+// src/core/graph/permissionRecords.ts
+import { opendir, unlink as unlink2 } from "fs/promises";
+import path14 from "path";
+async function readGraphSearchRecords(root, directory) {
+  const records = [];
+  const entries = await opendir(directory);
+  for await (const entry of entries) {
+    if (entry.name === "state.lock" || entry.name === "analysis.lock") continue;
+    if (records.length >= 128) throw fullGraphState();
+    const match = /^(.+)\.(pending|grant|draft)\.json$/.exec(entry.name);
+    if (!match || !GRAPH_UUID.test(match[1] ?? "")) throw invalidGraphState();
+    const file = path14.join(directory, entry.name);
+    const text = await readGraphLocalFile(file);
+    if (text === void 0) throw invalidGraphState();
+    let input;
+    try {
+      input = JSON.parse(text);
+    } catch {
+      throw invalidGraphState();
+    }
+    const record = parseGraphSearchRecord(input, root);
+    if (!record || record.id !== match[1] || (match[2] === "pending" ? record.kind !== "pending" : record.kind !== "grant"))
+      throw invalidGraphState();
+    records.push({ file, record, draft: match[2] === "draft" });
+  }
+  const current = [];
+  for (const item of records) {
+    if (Date.now() >= item.record.expiresAt) await unlink2(item.file);
+    else current.push(item);
+  }
+  return current;
+}
+function fullGraphState() {
+  return new GraphLocalStateError(
+    "Project graph permission state is full.",
+    "Retry after pending attempts or search grants expire; retain valid worktree state."
+  );
+}
+function parseGraphSearchRecord(input, root) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return void 0;
+  const value = input;
+  const fields = [
+    "id",
+    "kind",
+    "domain",
+    "target",
+    "operation",
+    "worktree",
+    "session",
+    "createdAt",
+    "expiresAt"
+  ];
+  if (value.kind === "grant") fields.push("reason");
+  if (Object.keys(value).length !== fields.length || fields.some((field) => !Object.hasOwn(value, field)) || typeof value.id !== "string" || !GRAPH_UUID.test(value.id) || value.kind !== "pending" && value.kind !== "grant" || value.domain !== "code" && value.domain !== "documents" || !graphStateText(value.target, 4096) || !graphStateText(value.operation, 128) || !graphStateText(value.worktree, 4096) || value.worktree !== path14.resolve(root) || !graphStateText(value.session, 4096) || typeof value.createdAt !== "number" || typeof value.expiresAt !== "number" || !Number.isSafeInteger(value.createdAt) || value.createdAt < 0 || value.createdAt > Date.now() || !Number.isSafeInteger(value.expiresAt) || value.expiresAt !== value.createdAt + (value.kind === "pending" ? 6e5 : 6e4))
+    return void 0;
+  const scope = {
+    id: value.id,
+    domain: value.domain,
+    target: value.target,
+    operation: value.operation,
+    worktree: value.worktree,
+    session: value.session,
+    createdAt: value.createdAt,
+    expiresAt: value.expiresAt
+  };
+  if (value.kind === "pending") return { ...scope, kind: "pending" };
+  return graphStateText(value.reason, 2048) ? { ...scope, kind: "grant", reason: value.reason } : void 0;
+}
+
+// src/core/graph/fallbackState.ts
+async function requestStoredGraphFallback(root, attemptId, question, reason, run = runGraphProcess) {
+  const observed = await withGraphLock(root, "state", async () => {
+    const directory = await graphStateDirectory(root);
+    const records = await readGraphSearchRecords(root, directory);
+    const pending = records.find(
+      (item) => item.record.kind === "pending" && item.record.id === attemptId
+    );
+    if (!pending || pending.record.kind !== "pending") throw invalidGraphState();
+    return pending.record;
+  });
+  const graph = await queryPreparedGraph(root, { domain: observed.domain, question }, run);
+  const publication = await withGraphLock(root, "state", async () => {
+    const directory = await graphStateDirectory(root);
+    const records = await readGraphSearchRecords(root, directory);
+    const pending = records.find(
+      (item) => item.record.kind === "pending" && item.record.id === attemptId
+    );
+    if (!pending || JSON.stringify(pending.record) !== JSON.stringify(observed))
+      throw invalidGraphState();
+    if (records.length >= 128) throw fullGraphState();
+    const createdAt = Date.now();
+    const grant = {
+      ...observed,
+      kind: "grant",
+      reason,
+      createdAt,
+      expiresAt: createdAt + 6e4
+    };
+    const draft = path15.join(directory, `${grant.id}.draft.json`);
+    await writeGraphLocalFile(draft, grant);
+    await unlink3(pending.file);
+    return { directory, draft, grant };
+  });
+  await assertGraphStoragePath(root, publication.directory);
+  if (Date.now() >= publication.grant.expiresAt) throw invalidGraphState();
+  await rename4(
+    publication.draft,
+    path15.join(publication.directory, `${publication.grant.id}.grant.json`)
+  );
+  const { target, operation, worktree, session, expiresAt } = publication.grant;
+  return {
+    status: "ready",
+    permitted: true,
+    domain: observed.domain,
+    scope: { target, operation, worktree, session, reason, expiresAt },
+    graph
+  };
+}
+
+// src/cli/graphCli.ts
+var QUERY_USAGE = 'Run node .qfai/tools/graph-cli.mjs code "<question>" or documents "<question>". For a denied search, run node .qfai/tools/graph-cli.mjs fallback --attempt-id <observed-UUID> --question "<unresolved question>" --reason "<graph limitation>". Supply only the listed arguments.';
+async function runInstalledGraphCli(root, args, io = {
+  output: (text) => {
+    process.stdout.write(text);
+  },
+  fail: () => {
+    process.exitCode = 2;
+  }
+}, run = runGraphProcess) {
+  const request = args[0] === "fallback" ? readFallback(args) : readQuestion(args);
+  if (!request) {
+    io.output(
+      JSON.stringify({
+        status: "failed",
+        ...args[0] === "fallback" ? { permitted: false } : {},
+        failure: "Invalid graph command arguments.",
+        recovery: QUERY_USAGE
+      }) + "\n"
+    );
+    io.fail();
+    return;
+  }
+  let answer;
+  try {
+    answer = "attemptId" in request ? await requestStoredGraphFallback(
+      root,
+      request.attemptId,
+      request.question,
+      request.reason,
+      run
+    ) : await queryPreparedGraph(root, request, run);
+  } catch (cause) {
+    const fallback = "attemptId" in request;
+    answer = {
+      status: "failed",
+      permitted: false,
+      failure: cause instanceof GraphLocalStateError ? cause.message : fallback ? "Search fallback failed." : "Graph operation failed.",
+      recovery: cause instanceof GraphLocalStateError ? cause.recovery : fallback ? "Retain .qfai/tools/state and local analysis, repair project-local graph preparation, then retry the same fallback CLI command." : "Repair project-local graph preparation and retry the same CLI command."
+    };
+  }
+  io.output(JSON.stringify(answer) + "\n");
+  if (answer.status === "failed" || answer.status === "not-ready") io.fail();
+}
+function readFallback(args) {
+  if (args.length !== 7) return void 0;
+  const values = /* @__PURE__ */ new Map();
+  for (let index = 1; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1]?.trim();
+    if (!flag || !["--attempt-id", "--question", "--reason"].includes(flag) || values.has(flag) || !value || value.startsWith("--"))
+      return void 0;
+    values.set(flag, value);
+  }
+  const attemptId = values.get("--attempt-id");
+  const question = values.get("--question");
+  const reason = values.get("--reason");
+  if (!attemptId || !GRAPH_UUID.test(attemptId) || !graphStateText(question, 16384) || !graphStateText(reason, 2048))
+    return void 0;
+  return { attemptId, question, reason };
+}
+function readQuestion(args) {
+  const domain = args[0];
+  const question = args[1]?.trim();
+  if (domain !== "code" && domain !== "documents" || args.length !== 2 || !question || question.length > 16384 || question.includes("\0") || question.startsWith("--"))
+    return void 0;
+  return { domain, question };
+}
+export {
+  runInstalledGraphCli
+};
+//# sourceMappingURL=cli.mjs.map