dsh-desktop-kit 2.0.0 → 2.1.0

package/plugins/dsh-project-memory/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-project-memory",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "private": true,
-  "description": "Local per-project long-term memory for DSH: auto-injected digest, project_memory tool, automatic session journal.",
+  "description": "Local per-project long-term memory for DSH: auto-detection, bounded local recon, auto-injected digest with recall, project_memory tool, automatic session journal.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -12,6 +12,7 @@
   },
   "files": [
     "index.js",
+    "scan.js",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",

package/plugins/dsh-project-memory/scan.js

@@ -0,0 +1,607 @@
+/**
+ * dsh-project-memory — local project reconnaissance.
+ *
+ * Pure, bounded, dependency-free scanning used to bootstrap a dossier without
+ * an LLM call. The scanner only reads an allowlist of manifest/doc files; it
+ * never opens secrets (`.env`, keys, credentials), dumps, vendored code or
+ * binary assets, and every string it returns passes through `redactText`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const SCAN_VERSION = 1;
+const MAX_DEPTH = 3;
+const MAX_FILES = 1500;
+const MAX_FILE_BYTES = 96 * 1024;
+const MAX_BLOCK_CHARS = 3200;
+
+const SKIP_DIRS = new Set([
+  "node_modules", "vendor", ".git", ".hg", ".svn", ".idea", ".vscode", "dist", "build",
+  "coverage", ".next", ".nuxt", "target", "bin", "obj", "storage", "cache", "tmp",
+  "temp", ".cache", "venv", ".venv", "env", "__pycache__", ".pnpm-store", "pods",
+]);
+
+const SECRET_FILE = /^(?:\.env(?:\..*)?|.*\.(?:pem|key|p12|pfx|keystore)|id_(?:rsa|ed25519|ecdsa)(?:\.pub)?|credentials?(?:\..*)?|secrets?(?:\..*)?|auth\.json|service-account.*\.json|wp-config\.php)$/iu;
+const ENV_TEMPLATE = /^\.env\.(?:example|sample|dist|template|defaults)$/iu;
+const DOC_FILES = ["README.md", "README.rst", "README.txt", "AGENTS.md", "CONTRIBUTING.md"];
+const MANIFEST_FILES = [
+  "package.json", "composer.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml",
+  "Gemfile", "pom.xml", "build.gradle", "build.gradle.kts", "mix.exs", "pubspec.yaml",
+];
+const STRONG_MARKERS = [
+  ".git", "composer.json", "package.json", "pyproject.toml", "go.mod", "Cargo.toml",
+  "Gemfile", "pom.xml", "artisan", "wp-config.php", "manage.py", "mix.exs", "pubspec.yaml",
+  "bitrix", "docker-compose.yml", "docker-compose.yaml",
+];
+const WEAK_MARKERS = ["AGENTS.md", "Makefile", "Dockerfile", "README.md"];
+const ENTRY_CANDIDATES = [
+  "artisan", "public/index.php", "index.php", "src/main.ts", "src/main.js", "src/index.ts",
+  "src/index.js", "main.py", "app.py", "manage.py", "server.js", "app.js", "main.go",
+  "cmd/server/main.go", "Program.cs", "bin/console", "config/app.php", "next.config.js",
+  "next.config.mjs", "vite.config.ts", "vite.config.js",
+];
+const KEY_DIRS = [
+  "src", "app", "routes", "config", "database/migrations", "migrations", "tests", "test",
+  "public", "resources", "storage", "components", "packages", "apps", "plugins", "skills",
+  "tools", "server", "api", "cmd", "internal", "lib", "docs", "scripts", "deploy", "docker",
+  ".github/workflows", "assets",
+];
+
+/* ------------------------------------------------------------------ */
+/* redaction                                                          */
+/* ------------------------------------------------------------------ */
+
+/** Strip secrets and personal data before anything reaches the dossier. */
+export function redactText(input) {
+  let text = String(input ?? "");
+  const rules = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu, "[REDACTED:PRIVATE_KEY]"],
+    [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu, "[REDACTED:JWT]"],
+    [/\b(?:sk|rk)-[A-Za-z0-9_-]{16,}\b/gu, "[REDACTED:KEY]"],
+    [/\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{16,}\b/gu, "[REDACTED:GITHUB_TOKEN]"],
+    [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/gu, "[REDACTED:SLACK_TOKEN]"],
+    [/\bAKIA[0-9A-Z]{16}\b/gu, "[REDACTED:AWS_KEY]"],
+    [/\bAIza[0-9A-Za-z_-]{30,}\b/gu, "[REDACTED:GOOGLE_KEY]"],
+    [/\bsk_live_[0-9A-Za-z]{16,}\b/gu, "[REDACTED:STRIPE_KEY]"],
+    [/\bAuthorization:\s*(?:Bearer|Basic)\s+[^\s]+/giu, "Authorization: [REDACTED]"],
+    [/\b(\w+:\/\/)[^:@/\s]+:[^@/\s]+@/gu, "$1[REDACTED]@"],
+    [/\b([A-Z][A-Z0-9_]*(?:PASSWORD|PASSWD|PWD|SECRET|TOKEN|API[_-]?KEY|PRIVATE[_-]?KEY|DSN|DATABASE_URL|REDIS_URL|ACCESS[_-]?KEY)[A-Z0-9_]*)\s*[:=]\s*["']?[^\s"',;]+/giu, "$1=[REDACTED]"],
+    [/(^|\n)([A-Z0-9_]*(?:PASSWORD|PASSWD|PWD|SECRET|TOKEN|API[_-]?KEY|PRIVATE[_-]?KEY|DSN|DATABASE_URL|REDIS_URL|ACCESS[_-]?KEY)[A-Z0-9_]*)\s*[:=]\s*[^\n]*/giu, "$1$2=[REDACTED]"],
+    [/(^|\n)(\s*(?:password|passwd|pwd|secret|token|api[_-]?key|authorization)\s*[:=]\s*)[^\n]*/giu, "$1$2[REDACTED]"],
+    [/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/giu, "[email]"],
+    [/(?:\+7|8)[\s(-]*\d{3}[\s)-]*\d{3}[\s-]*\d{2}[\s-]*\d{2}\b/gu, "[phone]"],
+  ];
+  for (const [pattern, replacement] of rules) text = text.replace(pattern, replacement);
+  return text;
+}
+
+/* ------------------------------------------------------------------ */
+/* bounded filesystem access                                          */
+/* ------------------------------------------------------------------ */
+
+function readSafe(filePath) {
+  try {
+    const name = path.basename(filePath);
+    if (SECRET_FILE.test(name) && !ENV_TEMPLATE.test(name)) return "";
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return "";
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function exists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function listDir(directory) {
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function firstLine(text) {
+  return String(text ?? "").split(/\r?\n/u).find((line) => line.trim().length > 0)?.trim() ?? "";
+}
+
+function clampText(text, max) {
+  const value = String(text ?? "").replace(/\s+/gu, " ").trim();
+  return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+
+/* ------------------------------------------------------------------ */
+/* detection                                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Find the nearest project root above `cwd`, without ever crossing the user's
+ * home directory or a filesystem root. Returns `{root, markers, confidence}`.
+ */
+export function detectProject(cwd) {
+  if (typeof cwd !== "string" || cwd.trim().length === 0) return undefined;
+  let current;
+  try {
+    current = path.resolve(cwd);
+  } catch {
+    return undefined;
+  }
+  const stop = path.parse(current).root;
+  const home = path.resolve(process.env.USERPROFILE || process.env.HOME || "");
+  const normalize = (value) => path.resolve(value).replaceAll("\\", "/").replace(/\/+$/u, "").toLowerCase();
+  for (let depth = 0; depth < 14; depth += 1) {
+    if (current === stop) break;
+    if (home && normalize(current) === normalize(home)) break;
+    const strong = STRONG_MARKERS.filter((marker) => exists(path.join(current, marker)));
+    const weak = WEAK_MARKERS.filter((marker) => exists(path.join(current, marker)));
+    /* A bare README/Makefile is not enough at the user's home or drive root. */
+    if (strong.length > 0) return { root: current, markers: [...strong, ...weak], confidence: strong.includes(".git") ? "high" : "medium" };
+    if (weak.length >= 2 && depth <= 3) return { root: current, markers: [...strong, ...weak], confidence: "low" };
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return undefined;
+}
+
+/** Direct child directories that look like separate projects. */
+export function detectChildProjects(cwd, limit = 6) {
+  const root = path.resolve(cwd);
+  const found = [];
+  for (const entry of listDir(root)) {
+    if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+    const child = path.join(root, entry.name);
+    if (STRONG_MARKERS.some((marker) => exists(path.join(child, marker)))) found.push(child);
+    if (found.length >= limit) break;
+  }
+  return found;
+}
+
+/* ------------------------------------------------------------------ */
+/* git                                                                */
+/* ------------------------------------------------------------------ */
+
+export function gitInfo(root) {
+  try {
+    const dotGit = path.join(root, ".git");
+    if (!exists(dotGit)) return undefined;
+    let gitDir = dotGit;
+    try {
+      if (fs.statSync(dotGit).isFile()) {
+        const content = readSafe(dotGit);
+        const match = content.match(/gitdir:\s*(.+)/u);
+        if (match) gitDir = path.resolve(root, match[1].trim());
+      }
+    } catch {
+      /* keep dotGit */
+    }
+    const headRaw = readSafe(path.join(gitDir, "HEAD")).trim();
+    let branch = "detached";
+    let head = headRaw.slice(0, 12) || "unknown";
+    if (headRaw.startsWith("ref: ")) {
+      const ref = headRaw.slice(5).trim();
+      branch = ref.replace(/^refs\/heads\//u, "");
+      head = readSafe(path.join(gitDir, ...ref.split("/"))).trim().slice(0, 12) || "unknown";
+    }
+    const config = readSafe(path.join(gitDir, "config"));
+    const remoteMatch = config.match(/url\s*=\s*(.+)/u);
+    const remote = remoteMatch ? redactText(remoteMatch[1].trim().replace(/\/\/[^@/]+@/u, "//[REDACTED]@")) : "";
+    return { branch, head, remote: remote.slice(0, 200) };
+  } catch {
+    return undefined;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* scan                                                               */
+/* ------------------------------------------------------------------ */
+
+function collectFiles(root) {
+  const stats = { files: 0, languages: new Map(), bytes: 0, truncated: false };
+  const walk = (directory, depth) => {
+    if (depth > MAX_DEPTH || stats.files >= MAX_FILES) {
+      if (stats.files >= MAX_FILES) stats.truncated = true;
+      return;
+    }
+    for (const entry of listDir(directory)) {
+      if (stats.files >= MAX_FILES) { stats.truncated = true; return; }
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".") && entry.name !== ".github") continue;
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) { walk(full, depth + 1); continue; }
+      if (!entry.isFile()) continue;
+      stats.files += 1;
+      const ext = path.extname(entry.name).toLowerCase();
+      if ([".php", ".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".rs", ".rb", ".java", ".cs", ".vue", ".svelte", ".sql", ".sh", ".ps1", ".css", ".scss"].includes(ext)) {
+        stats.languages.set(ext, (stats.languages.get(ext) ?? 0) + 1);
+      }
+      try { stats.bytes += fs.statSync(full).size; } catch { /* skip */ }
+    }
+  };
+  walk(root, 0);
+  return stats;
+}
+
+function unique(list, limit) {
+  return [...new Set(list.filter((item) => typeof item === "string" && item.trim().length > 0))].slice(0, limit);
+}
+
+function parseEnvKeys(root) {
+  const candidates = [".env.example", ".env.sample", ".env.dist", ".env.template", ".env.defaults"];
+  const keys = [];
+  for (const name of candidates) {
+    const text = readSafe(path.join(root, name));
+    if (text.length === 0) continue;
+    for (const line of text.split(/\r?\n/u)) {
+      const match = line.match(/^\s*([A-Z][A-Z0-9_]{2,})\s*=/u);
+      if (match) keys.push(match[1]);
+    }
+    if (keys.length > 0) break;
+  }
+  return unique(keys, 60);
+}
+
+function detectStack({ packageInfo, composer, manifests, root, files }) {
+  const deps = new Set([
+    ...Object.keys(packageInfo?.dependencies ?? {}),
+    ...Object.keys(packageInfo?.devDependencies ?? {}),
+    ...Object.keys(composer?.require ?? {}),
+    ...Object.keys(composer?.["require-dev"] ?? {}),
+  ]);
+  const labels = [];
+  const frameworks = [];
+  const databases = [];
+  const add = (list, value) => { if (value && !list.includes(value)) list.push(value); };
+
+  if (deps.has("laravel/framework") || exists(path.join(root, "artisan"))) { add(frameworks, "Laravel"); add(labels, "PHP · Laravel"); }
+  else if (deps.has("symfony/framework-bundle")) { add(frameworks, "Symfony"); add(labels, "PHP · Symfony"); }
+  else if (manifests.composer) { add(frameworks, "PHP"); add(labels, "PHP"); }
+  if (exists(path.join(root, "wp-config.php")) || exists(path.join(root, "wp-content"))) { add(frameworks, "WordPress"); add(labels, "WordPress"); }
+  if (exists(path.join(root, "bitrix")) || manifests.bitrix) { add(frameworks, "1C-Bitrix"); add(labels, "1C-Bitrix"); }
+  if (deps.has("next")) { add(frameworks, "Next.js"); add(labels, "Next.js"); }
+  if (deps.has("nuxt")) { add(frameworks, "Nuxt"); add(labels, "Nuxt"); }
+  if (deps.has("react")) { add(frameworks, "React"); add(labels, "React"); }
+  if (deps.has("vue")) { add(frameworks, "Vue"); add(labels, "Vue"); }
+  if (deps.has("svelte")) { add(frameworks, "Svelte"); add(labels, "Svelte"); }
+  if (deps.has("@angular/core")) { add(frameworks, "Angular"); add(labels, "Angular"); }
+  if (deps.has("vite")) { add(frameworks, "Vite"); add(labels, "Vite"); }
+  if (deps.has("typescript")) add(labels, "TypeScript");
+  if (deps.has("tailwindcss")) add(labels, "Tailwind");
+  if (deps.has("express")) { add(frameworks, "Express"); add(labels, "Node · Express"); }
+  if (deps.has("@nestjs/core")) { add(frameworks, "NestJS"); add(labels, "NestJS"); }
+  if (deps.has("django") || exists(path.join(root, "manage.py"))) { add(frameworks, "Django"); add(labels, "Python · Django"); }
+  if (deps.has("flask")) { add(frameworks, "Flask"); add(labels, "Python · Flask"); }
+  if (deps.has("fastapi")) { add(frameworks, "FastAPI"); add(labels, "Python · FastAPI"); }
+  if (deps.has("rails") || manifests.gemfile) { add(frameworks, "Rails"); add(labels, "Ruby · Rails"); }
+  if (manifests.go) { add(frameworks, "Go"); add(labels, "Go"); }
+  if (manifests.cargo) { add(frameworks, "Rust"); add(labels, "Rust"); }
+  if (manifests.pom || manifests.gradle) { add(frameworks, "Java"); add(labels, "Java"); }
+  if (manifests.dotnet) { add(frameworks, ".NET"); add(labels, ".NET"); }
+  if (manifests.pyproject || manifests.requirements) add(labels, "Python");
+  if (files.languages.get(".ts") || files.languages.get(".tsx")) add(labels, "TypeScript");
+
+  const dbMap = {
+    pg: "PostgreSQL", postgres: "PostgreSQL", mysql2: "MySQL", mysql: "MySQL", sqlite3: "SQLite",
+    mongodb: "MongoDB", mongoose: "MongoDB", redis: "Redis", prisma: "Prisma", sequelize: "Sequelize",
+    typeorm: "TypeORM", "drizzle-orm": "Drizzle", knex: "Knex",
+  };
+  for (const [dependency, label] of Object.entries(dbMap)) if (deps.has(dependency)) add(databases, label);
+  if (manifests.composer && (composer?.require?.["doctrine/dbal"] || composer?.require?.["laravel/framework"])) add(databases, "SQL (Eloquent)");
+  if (exists(path.join(root, "docker-compose.yml")) || exists(path.join(root, "docker-compose.yaml"))) add(labels, "Docker");
+  return { labels: unique(labels, 12), frameworks: unique(frameworks, 10), databases: unique(databases, 6) };
+}
+
+function detectCommands({ packageInfo, composer, root, manifests }) {
+  const commands = [];
+  const add = (label, command) => {
+    if (!command || commands.some((item) => item.command === command)) return;
+    commands.push({ label, command: clampText(redactText(command), 140) });
+  };
+  const scripts = packageInfo?.scripts ?? {};
+  for (const key of ["dev", "start", "build", "test", "lint", "typecheck", "check", "format"]) {
+    if (typeof scripts[key] === "string") add(`npm ${key}`, `npm run ${key}`);
+  }
+  if (packageInfo?.packageManager?.startsWith("pnpm")) {
+    for (const key of ["dev", "build", "test", "lint"]) if (typeof scripts[key] === "string") add(`pnpm ${key}`, `pnpm ${key}`);
+  }
+  if (composer?.scripts) {
+    for (const key of ["test", "lint", "serve", "dev"]) if (composer.scripts[key]) add(`composer ${key}`, `composer ${key}`);
+  }
+  if (exists(path.join(root, "artisan"))) {
+    add("serve", "php artisan serve");
+    add("test", "php artisan test");
+    add("migrate", "php artisan migrate");
+  }
+  if (exists(path.join(root, "manage.py"))) {
+    add("runserver", "python manage.py runserver");
+    add("test", "python manage.py test");
+  }
+  if (manifests.pyproject || manifests.requirements) {
+    if (exists(path.join(root, "pytest.ini")) || exists(path.join(root, "pyproject.toml"))) add("pytest", "pytest -q");
+  }
+  if (manifests.go) { add("test", "go test ./..."); add("run", "go run ."); }
+  if (manifests.cargo) { add("test", "cargo test"); add("run", "cargo run"); }
+  if (exists(path.join(root, "docker-compose.yml")) || exists(path.join(root, "docker-compose.yaml"))) add("docker", "docker compose up -d");
+  const makefile = readSafe(path.join(root, "Makefile"));
+  if (makefile) {
+    const targets = [...makefile.matchAll(/^([a-zA-Z0-9_.-]+):(?:\s|$)/gmu)].map((match) => match[1]).filter((name) => !name.startsWith(".")).slice(0, 8);
+    for (const target of targets) if (["test", "lint", "build", "dev", "run", "up", "install"].includes(target)) add(`make ${target}`, `make ${target}`);
+  }
+  return commands.slice(0, 16);
+}
+
+function detectTests(root, packageInfo) {
+  const frameworks = [];
+  if (exists(path.join(root, "phpunit.xml")) || exists(path.join(root, "phpunit.xml.dist"))) frameworks.push("PHPUnit");
+  if (exists(path.join(root, "pest.php"))) frameworks.push("Pest");
+  if (exists(path.join(root, "playwright.config.ts")) || exists(path.join(root, "playwright.config.js"))) frameworks.push("Playwright");
+  if (exists(path.join(root, "vitest.config.ts")) || exists(path.join(root, "vitest.config.js"))) frameworks.push("Vitest");
+  if (exists(path.join(root, "jest.config.js")) || exists(path.join(root, "jest.config.ts"))) frameworks.push("Jest");
+  if (exists(path.join(root, "pytest.ini")) || exists(path.join(root, "conftest.py"))) frameworks.push("pytest");
+  const deps = { ...(packageInfo?.dependencies ?? {}), ...(packageInfo?.devDependencies ?? {}) };
+  if (deps.vitest && !frameworks.includes("Vitest")) frameworks.push("Vitest");
+  if (deps.jest && !frameworks.includes("Jest")) frameworks.push("Jest");
+  if (deps["@playwright/test"] && !frameworks.includes("Playwright")) frameworks.push("Playwright");
+  const dirs = ["tests", "test", "spec", "__tests__", "cypress", "e2e"].filter((name) => exists(path.join(root, name)));
+  if (packageInfo?.scripts?.test) frameworks.push("npm test");
+  return { frameworks: unique(frameworks, 6), dirs };
+}
+
+function detectDocker(root) {
+  const file = ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"].find((name) => exists(path.join(root, name)));
+  if (!file) return { file: "", services: [] };
+  const text = readSafe(path.join(root, file));
+  const services = [];
+  for (const line of text.split(/\r?\n/u)) {
+    const match = line.match(/^\s{2}([a-zA-Z0-9_.-]+):\s*$/u);
+    if (match && match[1] !== "services" && match[1] !== "volumes" && match[1] !== "networks") services.push(match[1]);
+  }
+  return { file, services: unique(services, 10) };
+}
+
+function detectCi(root) {
+  const directory = path.join(root, ".github", "workflows");
+  return listDir(directory).filter((entry) => entry.isFile() && /\.ya?ml$/iu.test(entry.name)).map((entry) => entry.name).slice(0, 10);
+}
+
+function detectDocs(root) {
+  for (const name of DOC_FILES) {
+    const text = readSafe(path.join(root, name));
+    if (text.length === 0) continue;
+    const heading = firstLine(text).replace(/^#+\s*/u, "");
+    const body = text.replace(/^#.*$/gmu, "").split(/\r?\n\s*\r?\n/u).map((part) => part.trim()).find((part) => part.length > 20 && !part.startsWith("```") && !part.startsWith("<"));
+    return { file: name, heading: clampText(heading, 120), summary: clampText(redactText(body ?? ""), 320), agents: name === "AGENTS.md" || exists(path.join(root, "AGENTS.md")) };
+  }
+  return { file: "", heading: "", summary: "", agents: exists(path.join(root, "AGENTS.md")) };
+}
+
+function detectManifests(root) {
+  const manifests = {
+    package: exists(path.join(root, "package.json")),
+    composer: exists(path.join(root, "composer.json")),
+    pyproject: exists(path.join(root, "pyproject.toml")),
+    requirements: exists(path.join(root, "requirements.txt")),
+    go: exists(path.join(root, "go.mod")),
+    cargo: exists(path.join(root, "Cargo.toml")),
+    gemfile: exists(path.join(root, "Gemfile")),
+    pom: exists(path.join(root, "pom.xml")),
+    gradle: exists(path.join(root, "build.gradle")) || exists(path.join(root, "build.gradle.kts")),
+    dotnet: listDir(root).some((entry) => entry.isFile() && entry.name.endsWith(".sln")),
+    bitrix: exists(path.join(root, "bitrix")),
+  };
+  return manifests;
+}
+
+function detectPackageManager(root, packageInfo) {
+  if (packageInfo?.packageManager) return packageInfo.packageManager.split("@")[0];
+  if (exists(path.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (exists(path.join(root, "yarn.lock"))) return "yarn";
+  if (exists(path.join(root, "bun.lockb")) || exists(path.join(root, "bun.lock"))) return "bun";
+  if (exists(path.join(root, "package-lock.json"))) return "npm";
+  if (exists(path.join(root, "composer.lock"))) return "composer";
+  return "";
+}
+
+function detectFrameworksFromManifests(root, manifests) {
+  const values = {};
+  if (manifests.package) values.packageInfo = parseJson(readSafe(path.join(root, "package.json")));
+  if (manifests.composer) values.composer = parseJson(readSafe(path.join(root, "composer.json")));
+  if (manifests.pyproject) {
+    const text = readSafe(path.join(root, "pyproject.toml"));
+    const name = text.match(/^name\s*=\s*"([^"]+)"/mu);
+    const poetry = /\[tool\.poetry\.dependencies\]/u.test(text);
+    values.pyproject = { name: name?.[1] ?? "", poetry };
+  }
+  if (manifests.cargo) values.cargo = { name: (readSafe(path.join(root, "Cargo.toml")).match(/^name\s*=\s*"([^"]+)"/mu) ?? [])[1] ?? "" };
+  if (manifests.go) values.go = { module: (readSafe(path.join(root, "go.mod")).match(/^module\s+(\S+)/mu) ?? [])[1] ?? "" };
+  if (manifests.gemfile) {
+    const text = readSafe(path.join(root, "Gemfile"));
+    values.gemfile = [...text.matchAll(/^\s*gem\s+["']([^"']+)["']/gmu)].map((match) => match[1]);
+  }
+  if (manifests.pom) values.pom = { artifact: (readSafe(path.join(root, "pom.xml")).match(/<artifactId>([^<]+)<\/artifactId>/u) ?? [])[1] ?? "" };
+  return values;
+}
+
+/**
+ * Bounded local scan of one project root. Never throws; returns a JSON-safe
+ * fact sheet capped at a few kilobytes.
+ */
+export function scanProject(root, options = {}) {
+  const fact = {
+    version: SCAN_VERSION,
+    scannedAt: new Date().toISOString(),
+    root: path.resolve(root),
+    name: path.basename(path.resolve(root)),
+    git: undefined,
+    stack: { labels: [], frameworks: [], databases: [], languages: [] },
+    commands: [],
+    entryPoints: [],
+    keyDirs: [],
+    tests: { frameworks: [], dirs: [] },
+    ci: [],
+    docs: { file: "", heading: "", summary: "", agents: false },
+    env: { exampleKeys: [], hasEnv: false },
+    docker: { file: "", services: [] },
+    warnings: [],
+    stats: { files: 0, bytes: 0, truncated: false },
+  };
+  try {
+    const resolved = path.resolve(root);
+    if (!exists(resolved)) return fact;
+    const manifests = detectManifests(resolved);
+    const { packageInfo, composer } = detectFrameworksFromManifests(resolved, manifests);
+    const files = collectFiles(resolved);
+    const stack = detectStack({ packageInfo, composer, manifests, root: resolved, files });
+    fact.git = gitInfo(resolved);
+    fact.stack = {
+      ...stack,
+      languages: [...files.languages.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([ext, count]) => ({ ext, count })),
+    };
+    fact.commands = detectCommands({ packageInfo, composer, root: resolved, manifests });
+    fact.entryPoints = ENTRY_CANDIDATES.filter((name) => exists(path.join(resolved, name))).slice(0, 12);
+    fact.keyDirs = KEY_DIRS.filter((name) => exists(path.join(resolved, name))).slice(0, 16);
+    fact.tests = detectTests(resolved, packageInfo);
+    fact.ci = detectCi(resolved);
+    fact.docs = detectDocs(resolved);
+    fact.env = { exampleKeys: parseEnvKeys(resolved), hasEnv: exists(path.join(resolved, ".env")) };
+    fact.docker = detectDocker(resolved);
+    fact.package = packageInfo
+      ? { name: clampText(packageInfo.name ?? "", 80), version: clampText(packageInfo.version ?? "", 40), description: clampText(redactText(packageInfo.description ?? ""), 200), manager: detectPackageManager(resolved, packageInfo), engines: packageInfo.engines ?? undefined }
+      : undefined;
+    if (composer) fact.package = { ...(fact.package ?? {}), name: clampText(composer.name ?? fact.package?.name ?? "", 80), description: clampText(redactText(composer.description ?? fact.package?.description ?? ""), 200) };
+    fact.stats = { files: files.files, bytes: files.bytes, truncated: files.truncated };
+    if (!fact.docs.file) fact.warnings.push("нет README — назначение проекта неизвестно");
+    if (fact.tests.frameworks.length === 0 && fact.tests.dirs.length === 0) fact.warnings.push("тесты не обнаружены");
+    if (fact.env.hasEnv) fact.warnings.push("есть .env (не читался, значения не сохранены)");
+    if (fact.env.exampleKeys.length === 0 && (manifests.composer || manifests.package)) fact.warnings.push("нет .env.example — состав переменных неизвестен");
+    if (files.truncated) fact.warnings.push(`скан ограничен ${MAX_FILES} файлами`);
+    if (options.includeChildren !== false) {
+      const children = detectChildProjects(resolved, 4);
+      if (children.length > 1) fact.warnings.push(`рядом несколько проектов: ${children.map((child) => path.basename(child)).join(", ")} — уточни корень`);
+    }
+  } catch (error) {
+    fact.warnings.push(`скан не удался: ${clampText(String(error), 160)}`);
+  }
+  return fact;
+}
+
+/* ------------------------------------------------------------------ */
+/* rendering                                                          */
+/* ------------------------------------------------------------------ */
+
+function fmtCommands(commands) {
+  return commands.map((item) => `${item.label}: \`${item.command}\``).join(" · ");
+}
+
+function fmtLanguages(languages) {
+  return languages.map((item) => `${item.ext}×${item.count}`).join(", ");
+}
+
+/** Human-readable banner used by the digest and `brief`. */
+export function scanSummary(facts) {
+  if (!facts) return [];
+  const lines = [];
+  if (facts.stack?.labels?.length) lines.push(`Стек: ${facts.stack.labels.join(" · ")}`);
+  if (facts.package?.name) lines.push(`Пакет: ${facts.package.name}${facts.package.version ? ` ${facts.package.version}` : ""}${facts.package.manager ? ` · ${facts.package.manager}` : ""}`);
+  if (facts.commands?.length) lines.push(`Команды: ${fmtCommands(facts.commands.slice(0, 6))}`);
+  if (facts.entryPoints?.length) lines.push(`Точки входа: ${facts.entryPoints.join(", ")}`);
+  if (facts.keyDirs?.length) lines.push(`Каталоги: ${facts.keyDirs.slice(0, 8).join(", ")}`);
+  if (facts.tests?.frameworks?.length || facts.tests?.dirs?.length) lines.push(`Тесты: ${[...(facts.tests.frameworks ?? []), ...(facts.tests.dirs ?? [])].join(", ")}`);
+  if (facts.stack?.databases?.length) lines.push(`Данные: ${facts.stack.databases.join(", ")}`);
+  if (facts.docs?.heading) lines.push(`README: ${facts.docs.heading}${facts.docs.summary ? ` — ${clampText(facts.docs.summary, 180)}` : ""}`);
+  if (facts.docs?.agents) lines.push("Есть AGENTS.md с правилами проекта.");
+  if (facts.env?.exampleKeys?.length) lines.push(`Переменные (.env.example, только имена): ${facts.env.exampleKeys.slice(0, 12).join(", ")}`);
+  if (facts.warnings?.length) lines.push(`Предупреждения: ${facts.warnings.join("; ")}`);
+  return lines;
+}
+
+/** Auto blocks appended to dossier sections (marked, so rescans replace them). */
+export function renderAutoSections(facts) {
+  if (!facts) return {};
+  const stamp = facts.scannedAt?.slice(0, 16).replace("T", " ") ?? "—";
+  const stack = facts.stack?.labels?.join(" · ") || "не определён";
+  const git = facts.git ? `${facts.git.branch}@${facts.git.head}${facts.git.remote ? ` · ${facts.git.remote}` : ""}` : "не git или неизвестно";
+  const commands = facts.commands ?? [];
+  const entry = facts.entryPoints ?? [];
+  const dirs = facts.keyDirs ?? [];
+  const tests = facts.tests ?? {};
+  const warnings = facts.warnings ?? [];
+  const block = (body) => `<!-- AUTO-SCAN:START v${facts.version} -->\n${body}\n<!-- AUTO-SCAN:END -->`;
+
+  const project = block([
+    `## Автоскан (${stamp})`,
+    `- Стек: ${stack}`,
+    `- Git: ${git}`,
+    facts.package?.name ? `- Пакет: ${facts.package.name}${facts.package.version ? ` ${facts.package.version}` : ""}` : "",
+    commands.length ? `- Команды: ${fmtCommands(commands.slice(0, 6))}` : "",
+    facts.docs?.heading ? `- README: ${facts.docs.heading}` : "",
+    facts.stats ? `- Файлов в скане: ${facts.stats.files}${facts.stats.truncated ? " (ограничено)" : ""}; языки: ${fmtLanguages(facts.stack?.languages ?? [])}` : "",
+    warnings.length ? `- Предупреждения: ${warnings.join("; ")}` : "",
+  ].filter(Boolean).join("\n"));
+
+  const architecture = block([
+    "## Автоскан структуры",
+    dirs.length ? `- Ключевые каталоги: ${dirs.join(", ")}` : "- Ключевые каталоги: не найдены",
+    entry.length ? `- Точки входа: ${entry.join(", ")}` : "",
+    facts.stack?.databases?.length ? `- Данные: ${facts.stack.databases.join(", ")}` : "",
+    facts.docker?.services?.length ? `- Docker: ${facts.docker.services.join(", ")}` : "",
+    facts.ci?.length ? `- CI: ${facts.ci.join(", ")}` : "",
+  ].filter(Boolean).join("\n"));
+
+  const codeMap = block([
+    "## Автоскан карты кода",
+    entry.length ? `- Точки входа: ${entry.join(", ")}` : "- Точки входа: не найдены",
+    dirs.length ? `- Каталоги: ${dirs.join(", ")}` : "",
+    `- Тесты: ${[...(tests.frameworks ?? []), ...(tests.dirs ?? [])].join(", ") || "не обнаружены"}`,
+  ].filter(Boolean).join("\n"));
+
+  const runbook = block([
+    "## Автоскан команд",
+    commands.length ? commands.map((item) => `- ${item.label}: \`${item.command}\``).join("\n") : "- Команды не обнаружены",
+    facts.env?.exampleKeys?.length ? `- Переменные окружения (только имена): ${facts.env.exampleKeys.slice(0, 20).join(", ")}` : "",
+    facts.docker?.file ? `- Compose: \`${facts.docker.file}\`` : "",
+  ].filter(Boolean).join("\n"));
+
+  return {
+    PROJECT: project.slice(0, MAX_BLOCK_CHARS),
+    ARCHITECTURE: architecture.slice(0, MAX_BLOCK_CHARS),
+    "CODE-MAP": codeMap.slice(0, MAX_BLOCK_CHARS),
+    RUNBOOK: runbook.slice(0, MAX_BLOCK_CHARS),
+  };
+}
+
+/** Replace an existing AUTO-SCAN block or append one without touching user text. */
+export function mergeAutoBlock(existing, block) {
+  const text = String(existing ?? "");
+  if (!block) return text;
+  const pattern = /<!-- AUTO-SCAN:START[\s\S]*?AUTO-SCAN:END -->/gu;
+  if (pattern.test(text)) return text.replace(pattern, block);
+  return `${text.trimEnd()}\n\n${block}\n`;
+}
+
+/** Compact one-screen project card for `brief`. */
+export function renderBrief(facts, project, extras = {}) {
+  const lines = [`Проект: «${project.name}» (${project.slug})`, `Корень: ${project.roots?.[0] ?? "?"}`];
+  lines.push(...scanSummary(facts));
+  if (extras.invariants?.length) lines.push(`Инварианты: ${extras.invariants.join(" · ")}`);
+  if (extras.gotchas?.length) lines.push(`Грабли: ${extras.gotchas.join(" · ")}`);
+  if (extras.journal) lines.push(`Последний журнал: ${clampText(extras.journal, 300)}`);
+  lines.push(`Досье: ${extras.dossier ?? ""}`);
+  lines.push("Детали: project_memory action=read file=... или action=search query=...");
+  return lines.join("\n").slice(0, 2400);
+}
+
+export const SCAN_LIMITS = { MAX_DEPTH, MAX_FILES, MAX_FILE_BYTES };