ccdesk 0.2.2 → 0.2.3

package/dist/{server → core}/scan/context.js

@@ -1,7 +1,8 @@
 import { basename, join } from "node:path";
 import {} from "../../shared/types.js";
 import {} from "./env.js";
-import { isWithin, parseFrontmatter, readTextFile, resolvedPath } from "./files.js";
+import { isWithin, readTextFile, resolvedPath } from "./files.js";
+import { parseFrontmatter } from "./data.js";
 /**
  * Imports can name any file, so a cloned repo's CLAUDE.md could point at private files.
  * ccdesk shows an import's text only from the project, your Claude folders and ~/.agents.
@@ -59,20 +60,39 @@ export async function buildContext(input) {
             note: "Part of every session; their size depends on your Claude Code version and model",
         }, null),
     ];
-    const style = effective.find((s) => s.key === "outputStyle")?.value;
-    if (typeof style === "string" && !BUILT_IN_STYLES.includes(style.toLowerCase())) {
-        const custom = inventory.outputStyles.find((s) => s.name === style);
-        blocks.push(custom
-            ? block({ kind: "output-style", path: custom.path, scope: custom.scope }, parseFrontmatter(custom.text).body)
-            : block({
-                kind: "not-counted",
-                path: `Output style "${style}"`,
-                scope: "user",
-                note: "ccdesk could not find this style's file",
-            }, null));
+    const style = outputStyleBlock(effective, inventory);
+    if (style)
+        blocks.push(style);
+    blocks.push(...(await instructionBlocks(env, projectRoot, instructions)));
+    const index = memory?.index;
+    if (memory?.loaded && index) {
+        blocks.push(block({ kind: "memory-index", path: index.path, scope: "memory" }, index.text.split("\n").slice(0, index.loadedLines).join("\n")));
     }
-    // A file both imported and loaded on its own (a rule, an AGENTS.md) is counted once, as itself,
-    // also when it is loaded through a link, to it or to its folder, and imported by its real path.
+    blocks.push(...listingBlocks(inventory));
+    return blocks;
+}
+/** The output style's text, when outputStyle names one that is not built in. */
+function outputStyleBlock(effective, inventory) {
+    const style = effective.find((s) => s.key === "outputStyle")?.value;
+    if (typeof style !== "string" || BUILT_IN_STYLES.includes(style.toLowerCase()))
+        return null;
+    const custom = inventory.outputStyles.find((s) => s.name === style);
+    if (custom)
+        return block({ kind: "output-style", path: custom.path, scope: custom.scope }, parseFrontmatter(custom.text).body);
+    return block({
+        kind: "not-counted",
+        path: `Output style "${style}"`,
+        scope: "user",
+        note: "ccdesk could not find this style's file",
+    }, null);
+}
+/**
+ * The loaded instruction files, each after the files it imports. A file both imported and loaded
+ * on its own (a rule, an AGENTS.md) is counted once, as itself, also when it is loaded through a
+ * link, to it or to its folder, and imported by its real path.
+ */
+async function instructionBlocks(env, projectRoot, instructions) {
+    const blocks = [];
     const loaded = new Set((await Promise.all(instructions
         .filter((i) => i.status === "loaded")
         .map(async (i) => [i.path, i.realPath ?? (await resolvedPath(i.path))]))).flat());
@@ -85,20 +105,7 @@ export async function buildContext(input) {
                 continue;
             added.add(ref.resolved);
             await importsOf(file, ref.resolved);
-            const fields = { kind: "import", path: ref.resolved, scope: file.scope, via };
-            if (ref.pending)
-                blocks.push(block({ ...fields, note: "Not loaded until you approve imports from outside this project" }, null));
-            else if (ref.tooLarge)
-                blocks.push(block({ ...fields, note: "Over 4 MiB, so Claude Code does not load it" }, null));
-            else if (!showable(env, projectRoot, ref.resolved))
-                blocks.push(block({
-                    ...fields,
-                    note: "Outside this project and your Claude folders, so ccdesk does not show or count it. Claude Code loads it.",
-                }, null));
-            else {
-                const text = await readTextFile(env, ref.resolved);
-                blocks.push(block(fields, text ? injectedText(text.text) : null));
-            }
+            blocks.push(await importBlock(env, projectRoot, file, ref, via));
         }
     };
     for (const file of instructions) {
@@ -107,10 +114,26 @@ export async function buildContext(input) {
         await importsOf(file, file.path);
         blocks.push(block({ kind: "instruction", path: file.path, scope: file.scope }, injectedText(file.text)));
     }
-    const index = memory?.index;
-    if (memory?.loaded && index) {
-        blocks.push(block({ kind: "memory-index", path: index.path, scope: "memory" }, index.text.split("\n").slice(0, index.loadedLines).join("\n")));
-    }
+    return blocks;
+}
+/** One imported file: its text, or why ccdesk does not count it. */
+async function importBlock(env, projectRoot, file, ref, via) {
+    const fields = { kind: "import", path: ref.resolved, scope: file.scope, via };
+    if (ref.pending)
+        return block({ ...fields, note: "Not loaded until you approve imports from outside this project" }, null);
+    if (ref.tooLarge)
+        return block({ ...fields, note: "Over 4 MiB, so Claude Code does not load it" }, null);
+    if (!showable(env, projectRoot, ref.resolved))
+        return block({
+            ...fields,
+            note: "Outside this project and your Claude folders, so ccdesk does not show or count it. Claude Code loads it.",
+        }, null);
+    const text = await readTextFile(env, ref.resolved);
+    return block(fields, text ? injectedText(text.text) : null);
+}
+/** The skill listing, the subagent descriptions and the MCP tool names Claude sees. */
+function listingBlocks(inventory) {
+    const blocks = [];
     const listed = [...inventory.skills, ...inventory.commands].filter((s) => s.listed !== false && !s.shadowedBy);
     const listing = skillListing(listed);
     if (listing)

package/dist/core/scan/data.d.ts

@@ -0,0 +1,8 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+interface Frontmatter {
+    data: Record<string, unknown>;
+    body: string;
+}
+export declare const FRONTMATTER: RegExp;
+export declare function parseFrontmatter(text: string): Frontmatter;
+export {};

package/dist/core/scan/data.js

@@ -0,0 +1,18 @@
+import { parse as parseYaml } from "yaml";
+// Checks on parsed data shared by file reading and redaction, kept apart so neither imports the other.
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export function parseFrontmatter(text) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return { data: {}, body: text };
+    try {
+        const data = parseYaml(match[1] ?? "");
+        return { data: isRecord(data) ? data : {}, body: text.slice(match[0].length) };
+    }
+    catch {
+        return { data: {}, body: text.slice(match[0].length) };
+    }
+}

package/dist/core/scan/env.d.ts

@@ -0,0 +1,26 @@
+/** Every location ccdesk reads, resolved once so tests can point it at a sandbox. */
+export interface ScanEnv {
+    home: string;
+    /** `~/.claude`, or `--config-dir` or `CLAUDE_CONFIG_DIR` when set. */
+    claudeDir: string;
+    /** CLAUDE_CONFIG_DIR for the claude commands ccdesk runs: `--config-dir` or the shell's; unset for ~/.claude. */
+    configDir?: string | undefined;
+    /** Claude Code's own state file: OAuth, trust decisions, user MCP servers. Read-only for ccdesk. */
+    claudeJson: string;
+    /** System directory for organisation-managed CLAUDE.md and managed-settings.json. */
+    managedDir: string;
+    platform: NodeJS.Platform;
+    /**
+     * The environment ccdesk runs in: where it finds an editor and `claude` (PATH, VISUAL, EDITOR,
+     * CCDESK_EDITOR), and what the programs it starts inherit.
+     */
+    processEnv: NodeJS.ProcessEnv;
+    /** CLAUDE_CODE_DISABLE_AUTO_MEMORY from the shell ccdesk runs in; it outranks autoMemoryEnabled. */
+    disableAutoMemory?: string | undefined;
+    /** CLAUDE_CODE_PROJECT_DIR_NAME, read only beside CLAUDE_CONFIG_DIR: one memory store for every project. */
+    projectDirName?: string | undefined;
+}
+/** `configDirFlag`, from `--config-dir`, stands in for CLAUDE_CONFIG_DIR and wins over it. */
+export declare function scanEnvFromProcess(configDirFlag?: string): ScanEnv;
+/** Your configuration home: your home directory, or the folder whose .claude is CLAUDE_CONFIG_DIR. */
+export declare function isConfigHome(env: ScanEnv, path: string): boolean;

package/dist/{server → core}/scan/env.js

@@ -3,8 +3,11 @@ import { join, resolve } from "node:path";
 /** `configDirFlag`, from `--config-dir`, stands in for CLAUDE_CONFIG_DIR and wins over it. */
 export function scanEnvFromProcess(configDirFlag) {
     const home = homedir();
+    // Kept as the object itself: on Windows it reads PATH and Path alike, which a copy would not.
+    // biome-ignore lint/style/noProcessEnv: building a ScanEnv from the real process is this function's job.
+    const processEnv = process.env;
     // Made absolute here, from the folder ccdesk started in, because claude runs elsewhere.
-    const chosen = configDirFlag ?? (process.env.CLAUDE_CONFIG_DIR || undefined);
+    const chosen = configDirFlag ?? (processEnv.CLAUDE_CONFIG_DIR || undefined);
     const configDir = chosen === undefined ? undefined : resolve(chosen);
     return {
         home,
@@ -14,8 +17,9 @@ export function scanEnvFromProcess(configDirFlag) {
         claudeJson: configDir ? join(configDir, ".claude.json") : join(home, ".claude.json"),
         managedDir: managedDirFor(process.platform),
         platform: process.platform,
-        disableAutoMemory: process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY,
-        projectDirName: configDir ? process.env.CLAUDE_CODE_PROJECT_DIR_NAME || undefined : undefined,
+        processEnv,
+        disableAutoMemory: processEnv.CLAUDE_CODE_DISABLE_AUTO_MEMORY,
+        projectDirName: configDir ? processEnv.CLAUDE_CODE_PROJECT_DIR_NAME || undefined : undefined,
     };
 }
 /** Your configuration home: your home directory, or the folder whose .claude is CLAUDE_CONFIG_DIR. */

package/dist/core/scan/files.d.ts

@@ -0,0 +1,68 @@
+import { type FileHandle } from "node:fs/promises";
+import { type Problem, type TextFile } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+/** Claude Code skips a CLAUDE.md larger than this (docs: memory#auto-memory), so ccdesk reads no more. */
+export declare const MAX_TEXT_BYTES: number;
+/** ccdesk never reads Claude Code's credentials, whatever name or link leads to them. */
+export declare function isSecretPath(path: string): boolean;
+/**
+ * Whether a path is Claude Code's credentials file: by name, through any link on the way, or by
+ * being the same file as `<config>/.credentials.json`, so a copy kept under another name or a hard
+ * link to it counts too.
+ */
+export declare function isCredentials(env: ScanEnv, path: string): Promise<boolean>;
+/**
+ * Opens a file to read, or null for the credentials file. The open file is checked again, so a
+ * file swapped in after the first check is not read either.
+ */
+export declare function openUnlessCredentials(env: ScanEnv, path: string): Promise<FileHandle | null>;
+/**
+ * A UNC share or a path under /net or /Network. Claude Code does not follow a link there, because
+ * looking it up can contact the host it names (docs: memory#share-rules-across-projects-with-symlinks).
+ */
+export declare function isNetworkPath(path: string): boolean;
+/** A pattern where `*` matches anything, matched against the whole string. */
+export declare function wildcard(pattern: string, flags?: string): RegExp;
+export declare function isWithin(parent: string, child: string): boolean;
+export declare function isDir(path: string): Promise<boolean>;
+export declare function isFile(path: string): Promise<boolean>;
+export declare function listDir(path: string): Promise<string[]>;
+/**
+ * A text file, or null when there is none to read: nothing at the path, a folder, a link to a
+ * network location, or the credentials file. A file that is there but cannot be read, such as one
+ * without read permission or a link loop, also goes into `problems`.
+ */
+export declare function readTextFile(env: ScanEnv, path: string, problems?: Problem[]): Promise<TextFile | null>;
+export declare function resolvedPath(path: string): Promise<string>;
+type JsonResult = {
+    ok: true;
+    data: Record<string, unknown>;
+}
+/** `unparsed`: the file was read, but is not a JSON object. */
+ | {
+    ok: false;
+    missing: boolean;
+    unparsed?: boolean;
+    error: string;
+};
+/** A JSON object file; `emptyIsObject` reads an empty file as `{}`. */
+export declare function readJsonObject(env: ScanEnv, path: string, { emptyIsObject }?: {
+    emptyIsObject?: boolean | undefined;
+}): Promise<JsonResult>;
+/** The object in a JSON file, or null; a file that is there but does not read or parse goes into `problems`. */
+export declare function readJsonOrReport(env: ScanEnv, path: string, problems: Problem[]): Promise<Record<string, unknown> | null>;
+/** The strings in a JSON list; anything else counts as no strings. */
+export declare function stringsIn(value: unknown): string[];
+/** A frontmatter list given as a YAML list or a comma-separated string, such as `paths`. */
+export declare function toStringList(value: unknown): string[];
+export declare function stringField(data: Record<string, unknown>, key: string): string;
+/** Fingerprint of a file's text, so a change can require the file to be as it was reviewed. */
+export declare function revisionOf(text: string | null): string;
+export declare function shortHash(text: string): string;
+/**
+ * Markdown files under `dir`. A symlinked folder is entered once, so a link loop ends, and a link
+ * to a network location is not followed. Depth and count are bounded by ccdesk, since a link can
+ * lead anywhere; Claude Code's own limits are not documented.
+ */
+export declare function walkMarkdown(dir: string): Promise<string[]>;
+export {};

package/dist/core/scan/files.js

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+import {} from "node:fs";
+import { lstat, open, readdir, readlink, realpath, stat } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import {} from "../../shared/types.js";
+import { jsonSyntaxError, shownJsonFile, shownText } from "../secrets.js";
+import { isRecord } from "./data.js";
+import {} from "./env.js";
+/** Claude Code skips a CLAUDE.md larger than this (docs: memory#auto-memory), so ccdesk reads no more. */
+export const MAX_TEXT_BYTES = 4 * 1024 * 1024;
+/** ccdesk never reads Claude Code's credentials, whatever name or link leads to them. */
+export function isSecretPath(path) {
+    return basename(path) === ".credentials.json";
+}
+/**
+ * Whether a path, any link on the way, or the file it finally leads to is the credentials file, so
+ * a credentials file that is itself a link is caught too. Checked before opening.
+ */
+async function leadsToSecret(path) {
+    let current = path;
+    for (let hop = 0; hop < 40; hop++) {
+        if (isSecretPath(current))
+            return true;
+        const info = await lstat(current).catch(() => null);
+        if (!info?.isSymbolicLink())
+            break;
+        current = resolve(dirname(current), await readlink(current));
+    }
+    return isSecretPath(await realpath(path).catch(() => path));
+}
+/** The identity of `<config>/.credentials.json`, or null when there is none. */
+function credentialsIdentity(env) {
+    return stat(join(env.claudeDir, ".credentials.json"), { bigint: true }).catch(() => null);
+}
+function sameFile(a, b) {
+    return b !== null && a.dev === b.dev && a.ino === b.ino;
+}
+/**
+ * Whether a path is Claude Code's credentials file: by name, through any link on the way, or by
+ * being the same file as `<config>/.credentials.json`, so a copy kept under another name or a hard
+ * link to it counts too.
+ */
+export async function isCredentials(env, path) {
+    if (await leadsToSecret(path))
+        return true;
+    const info = await stat(path, { bigint: true }).catch(() => null);
+    return info !== null && sameFile(info, await credentialsIdentity(env));
+}
+/**
+ * Opens a file to read, or null for the credentials file. The open file is checked again, so a
+ * file swapped in after the first check is not read either.
+ */
+export async function openUnlessCredentials(env, path) {
+    if (await isCredentials(env, path))
+        return null;
+    const handle = await open(path, "r");
+    if (sameFile(await handle.stat({ bigint: true }), await credentialsIdentity(env))) {
+        await handle.close();
+        return null;
+    }
+    return handle;
+}
+/**
+ * A UNC share or a path under /net or /Network. Claude Code does not follow a link there, because
+ * looking it up can contact the host it names (docs: memory#share-rules-across-projects-with-symlinks).
+ */
+export function isNetworkPath(path) {
+    if (/^[\\/]{2}wsl(\$|\.localhost)[\\/]/i.test(path))
+        return false;
+    return /^[\\/]{2}[^\\/]/.test(path) || /^\/(net|Network)(\/|$)/.test(path);
+}
+/** Where a symlink points, read without following it; null for anything else. */
+async function linkTarget(path) {
+    try {
+        if (!(await lstat(path)).isSymbolicLink())
+            return null;
+        return resolve(dirname(path), await readlink(path));
+    }
+    catch {
+        return null;
+    }
+}
+/** A link to a network location, which ccdesk, like Claude Code, does not follow. */
+async function linksToNetwork(path) {
+    const target = await linkTarget(path);
+    return target !== null && isNetworkPath(target);
+}
+/** A pattern where `*` matches anything, matched against the whole string. */
+export function wildcard(pattern, flags = "") {
+    const body = pattern
+        .split("*")
+        .map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${body}$`, flags);
+}
+export function isWithin(parent, child) {
+    const rel = relative(parent, child);
+    // Only the parent segment leads out; a name such as ..cache is inside.
+    const up = rel === ".." || rel.startsWith(`..${sep}`);
+    return rel === "" || (!up && !rel.startsWith(sep) && !/^[a-zA-Z]:/.test(rel));
+}
+export async function isDir(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function listDir(path) {
+    try {
+        return (await readdir(path)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * A text file, or null when there is none to read: nothing at the path, a folder, a link to a
+ * network location, or the credentials file. A file that is there but cannot be read, such as one
+ * without read permission or a link loop, also goes into `problems`.
+ */
+export async function readTextFile(env, path, problems) {
+    try {
+        if (await linksToNetwork(path))
+            return null;
+        const real = await realpath(path);
+        const info = await stat(path);
+        if (!info.isFile())
+            return null;
+        const handle = await openUnlessCredentials(env, path);
+        if (!handle)
+            return null;
+        let text;
+        try {
+            const buffer = Buffer.alloc(Math.min(info.size, MAX_TEXT_BYTES));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            text = buffer.subarray(0, bytesRead).toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+        text = real.endsWith(".json") ? shownJsonFile(text) : (shownText(text) ?? "");
+        const ref = {
+            path,
+            mtime: info.mtime.toISOString(),
+            bytes: info.size,
+            lines: text === "" ? 0 : text.split("\n").length,
+            text,
+        };
+        if ((await lstat(path)).isSymbolicLink())
+            ref.realPath = real;
+        return ref;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT" && code !== "ENOTDIR")
+            problems?.push({ path, error: `cannot be read (${code ?? String(error)})` });
+        return null;
+    }
+}
+export async function resolvedPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return path;
+    }
+}
+/** A JSON object file; `emptyIsObject` reads an empty file as `{}`. */
+export async function readJsonObject(env, path, { emptyIsObject = false } = {}) {
+    let raw;
+    try {
+        const handle = await openUnlessCredentials(env, path);
+        if (!handle)
+            return { ok: false, missing: false, error: "ccdesk does not read credentials" };
+        try {
+            raw = await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        const missing = error.code === "ENOENT";
+        return { ok: false, missing, error: String(error) };
+    }
+    if (emptyIsObject && raw.trim() === "")
+        return { ok: true, data: {} };
+    try {
+        const data = JSON.parse(raw);
+        if (!isRecord(data))
+            return { ok: false, missing: false, unparsed: true, error: "not a JSON object" };
+        return { ok: true, data };
+    }
+    catch (error) {
+        return { ok: false, missing: false, unparsed: true, error: jsonSyntaxError(error) };
+    }
+}
+/** The object in a JSON file, or null; a file that is there but does not read or parse goes into `problems`. */
+export async function readJsonOrReport(env, path, problems) {
+    const result = await readJsonObject(env, path);
+    if (result.ok)
+        return result.data;
+    if (!result.missing)
+        problems.push({ path, error: result.error });
+    return null;
+}
+/** The strings in a JSON list; anything else counts as no strings. */
+export function stringsIn(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/** A frontmatter list given as a YAML list or a comma-separated string, such as `paths`. */
+export function toStringList(value) {
+    if (typeof value === "string")
+        return value
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    return stringsIn(value);
+}
+export function stringField(data, key) {
+    const value = data[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+/** Fingerprint of a file's text, so a change can require the file to be as it was reviewed. */
+export function revisionOf(text) {
+    return text === null ? "missing" : createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+export function shortHash(text) {
+    return createHash("sha1").update(text).digest("hex").slice(0, 10);
+}
+/**
+ * Markdown files under `dir`. A symlinked folder is entered once, so a link loop ends, and a link
+ * to a network location is not followed. Depth and count are bounded by ccdesk, since a link can
+ * lead anywhere; Claude Code's own limits are not documented.
+ */
+export async function walkMarkdown(dir) {
+    const out = [];
+    const seen = new Set();
+    const walk = async (folder, depth) => {
+        const real = await resolvedPath(folder);
+        if (seen.has(real) || depth > MAX_WALK_DEPTH)
+            return;
+        seen.add(real);
+        for (const name of await listDir(folder)) {
+            if (out.length >= MAX_WALK_FILES)
+                return;
+            const path = join(folder, name);
+            if (await linksToNetwork(path))
+                continue;
+            if (await isDir(path))
+                await walk(path, depth + 1);
+            else if (name.endsWith(".md"))
+                out.push(path);
+        }
+    };
+    await walk(dir, 0);
+    return out;
+}
+const MAX_WALK_DEPTH = 8;
+const MAX_WALK_FILES = 1000;

package/dist/core/scan/git.d.ts

@@ -0,0 +1,14 @@
+import { type Visibility } from "../../shared/types.ts";
+export declare function gitRoot(dir: string): Promise<string | null>;
+/** Every checkout of the repository `dir` is in, the main one first; empty outside git. */
+export declare function worktrees(dir: string): Promise<string[]>;
+/** Main worktree root: worktrees of one repository share Claude Code's auto memory. */
+export declare function mainWorktreeRoot(dir: string): Promise<string | null>;
+/**
+ * The key ~/.claude.json keeps a folder's trust answers and local MCP servers under: the main
+ * checkout's root, else the repository root, else the folder itself outside git. The scan reads
+ * under it and `claude mcp add --scope local` writes under it, so both take it from here.
+ */
+export declare function trustKey(dir: string, mainRoot: string | null, root: string | null): string;
+/** Git visibility of each path, batched into two git calls per repository. */
+export declare function visibilityOf(root: string | null, paths: string[]): Promise<Map<string, Visibility>>;

package/dist/core/scan/git.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { dirname, normalize, relative } from "node:path";
+import { promisify } from "node:util";
+import {} from "../../shared/types.js";
+import { isWithin } from "./files.js";
+const run = promisify(execFile);
+export async function gitRoot(dir) {
+    try {
+        const { stdout } = await run("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+            timeout: 5000,
+        });
+        // Git prints forward slashes on Windows too; normalise so path comparisons hold.
+        return stdout.trim() ? normalize(stdout.trim()) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every checkout of the repository `dir` is in, the main one first; empty outside git. */
+export async function worktrees(dir) {
+    try {
+        const { stdout } = await run("git", ["-C", dir, "worktree", "list", "--porcelain"], {
+            timeout: 5000,
+        });
+        return stdout
+            .split("\n")
+            .filter((line) => line.startsWith("worktree "))
+            .map((line) => normalize(line.slice("worktree ".length)));
+    }
+    catch {
+        return [];
+    }
+}
+/** Main worktree root: worktrees of one repository share Claude Code's auto memory. */
+export async function mainWorktreeRoot(dir) {
+    try {
+        const { stdout } = await run("git", ["-C", dir, "rev-parse", "--path-format=absolute", "--git-common-dir"], { timeout: 5000 });
+        const common = stdout.trim();
+        if (!common)
+            return null;
+        return common.endsWith("/.git") || common.endsWith("\\.git")
+            ? normalize(dirname(common))
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The key ~/.claude.json keeps a folder's trust answers and local MCP servers under: the main
+ * checkout's root, else the repository root, else the folder itself outside git. The scan reads
+ * under it and `claude mcp add --scope local` writes under it, so both take it from here.
+ */
+export function trustKey(dir, mainRoot, root) {
+    return mainRoot ?? root ?? dir;
+}
+/** Git visibility of each path, batched into two git calls per repository. */
+export async function visibilityOf(root, paths) {
+    const result = new Map();
+    if (paths.length === 0)
+        return result;
+    if (!root) {
+        for (const p of paths)
+            result.set(p, "no-git");
+        return result;
+    }
+    const inside = paths.filter((p) => p !== root && isWithin(root, p));
+    for (const p of paths)
+        if (!inside.includes(p))
+            result.set(p, "no-git");
+    if (inside.length === 0)
+        return result;
+    const rels = new Map(inside.map((p) => [p, relative(root, p).replaceAll("\\", "/")]));
+    const tracked = await gitLines(root, ["ls-files", "--full-name", "-z", "--", ...inside], "\0");
+    // check-ignore echoes the paths it matched, and on Windows an absolute path does not come back
+    // as written, so it gets relative ones. It accepts -z only with --stdin, so its output is split
+    // by line.
+    const ignored = await gitLines(root, ["check-ignore", "--no-index", "--", ...rels.values()], "\n");
+    for (const [p, rel] of rels) {
+        if (tracked.has(rel))
+            result.set(p, "tracked");
+        else if (ignored.has(rel))
+            result.set(p, "ignored");
+        else
+            result.set(p, "untracked");
+    }
+    return result;
+}
+// Failures (including check-ignore's exit 1 for "nothing ignored") read as an empty set.
+async function gitLines(root, args, separator) {
+    try {
+        const { stdout } = await run("git", ["-C", root, ...args], { timeout: 5000 });
+        return new Set(stdout.split(separator).filter(Boolean));
+    }
+    catch {
+        return new Set();
+    }
+}

package/dist/core/scan/index.d.ts

@@ -0,0 +1,5 @@
+import { type DirectoryView, type Overview, type SessionProfile } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+export declare function scanOverview(env: ScanEnv, launchDir: string): Promise<Overview>;
+/** Everything Claude Code reads when started in `dir`. */
+export declare function scanDirectory(env: ScanEnv, dir: string, profile?: SessionProfile): Promise<DirectoryView>;