ccdesk 0.0.0-stage → 0.2.0

package/dist/server/open.js

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join, posix, win32 } from "node:path";
+/** Editors that need a terminal; started from a background server they would have none. */
+const TERMINAL_EDITORS = new Set([
+    "vi",
+    "vim",
+    "nvim",
+    "nano",
+    "emacs",
+    "hx",
+    "helix",
+    "micro",
+    "kak",
+    "ed",
+]);
+/** Graphical editors ccdesk looks for when VISUAL and EDITOR name none. */
+const GUI_EDITORS = [
+    "code",
+    "cursor",
+    "zed",
+    "codium",
+    "subl",
+    "kate",
+    "gnome-text-editor",
+    "gedit",
+];
+/** An editor still running this long after it started is taken to have opened the file. */
+const START_MS = 1500;
+/** Whether `name` is an executable on PATH. */
+function onPath(env, platform, name) {
+    const extensions = platform === "win32" ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    for (const dir of (env.PATH ?? "").split(platform === "win32" ? ";" : delimiter)) {
+        for (const ext of extensions) {
+            try {
+                accessSync(join(dir, name + ext), platform === "win32" ? constants.F_OK : constants.X_OK);
+                return true;
+            }
+            catch {
+                // Not in this folder.
+            }
+        }
+    }
+    return false;
+}
+/**
+ * The commands to try, in order: `CCDESK_EDITOR` alone when set; else `VISUAL` or `EDITOR` when
+ * they name a graphical editor, then graphical editors found on PATH, then the system's opener.
+ * The system opener comes last because on Linux it often picks a terminal editor or nothing for
+ * JSON and Markdown.
+ */
+export function editorCommands(env, platform, found = (name) => onPath(env, platform, name)) {
+    const split = (value) => {
+        const [command = "", ...args] = words(value);
+        // A wait flag would keep the editor tied to this server's process.
+        return [command, args.filter((a) => a !== "-w" && a !== "--wait")];
+    };
+    const name = (command) => (platform === "win32" ? win32 : posix)
+        .basename(command)
+        .replace(/\.(exe|cmd|bat)$/i, "")
+        .toLowerCase();
+    if (env.CCDESK_EDITOR)
+        return [split(env.CCDESK_EDITOR)];
+    const out = [];
+    for (const value of [env.VISUAL, env.EDITOR]) {
+        if (!value)
+            continue;
+        const command = split(value);
+        if (!TERMINAL_EDITORS.has(name(command[0])))
+            out.push(command);
+    }
+    for (const editor of GUI_EDITORS)
+        if (found(editor))
+            out.push([editor, []]);
+    out.push(platform === "darwin"
+        ? ["open", []]
+        : platform === "win32"
+            ? ["explorer", []]
+            : ["xdg-open", []]);
+    return out.filter((c, i) => out.findIndex((o) => o[0] === c[0]) === i);
+}
+/** Splits an editor setting into words, keeping quoted parts such as "C:\Program Files\…" whole. */
+function words(value) {
+    return [...value.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3] ?? "");
+}
+/**
+ * How to start `command` on `path`. On Windows a .cmd or .bat file (VS Code's `code`) or a bare
+ * name that may resolve to one cannot be started directly, so it goes through cmd.exe, quoted.
+ */
+export function spawnPlan(command, args, path, platform) {
+    const direct = { file: command, args: [...args, path], verbatim: false };
+    if (platform !== "win32" || /\.(exe|com)$/i.test(command) || command === "explorer")
+        return direct;
+    // Inside cmd.exe quotes, " cannot be escaped and %NAME% still expands.
+    if ([command, ...args, path].some((part) => /["%]/.test(part)))
+        throw new Error("This path cannot be passed safely to a .cmd editor; open it yourself.");
+    const line = [command, ...args, path].map((part) => `"${part}"`).join(" ");
+    return { file: "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
+}
+/** Starts one command; resolves null once it is running or exited cleanly, else why it failed. */
+function launch([command, args], path) {
+    return new Promise((resolve) => {
+        let plan;
+        try {
+            plan = spawnPlan(command, args, path, process.platform);
+        }
+        catch (error) {
+            return resolve(error.message);
+        }
+        const child = spawn(plan.file, plan.args, {
+            detached: true,
+            stdio: "ignore",
+            windowsVerbatimArguments: plan.verbatim,
+        });
+        const timer = setTimeout(() => {
+            child.unref();
+            resolve(null);
+        }, START_MS);
+        child.once("error", (error) => {
+            clearTimeout(timer);
+            resolve(`${command}: ${error.message}`);
+        });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            resolve(code === 0 ? null : `${command} exited with code ${code}`);
+        });
+    });
+}
+/** Opens a file or folder in the first editor that starts; resolves with the command used. */
+export async function openInEditor(path) {
+    const failures = [];
+    for (const command of editorCommands(process.env, process.platform)) {
+        const failure = await launch(command, path);
+        if (failure === null)
+            return command[0];
+        failures.push(failure);
+    }
+    throw new Error(`Could not open it (${failures.join("; ")}). Set CCDESK_EDITOR to your editor.`);
+}

package/dist/server/scan/compare.js

@@ -0,0 +1,34 @@
+import { resolve } from "node:path";
+import {} from "../../shared/compare.js";
+import {} from "./env.js";
+import { effectiveSettings, readSettingsLayers } from "./settings.js";
+/** Each key Claude Code applies in `dir`, with its value and the files it comes from. */
+async function valuesIn(env, dir) {
+    const layers = await readSettingsLayers(env, dir);
+    const values = new Map();
+    for (const setting of effectiveSettings(layers)) {
+        // A key every file sets where Claude Code does not read it applies nowhere.
+        if (setting.from.length === 0)
+            continue;
+        const sources = setting.from.flatMap((scope) => {
+            const layer = layers.find((l) => l.scope === scope && l.data?.[setting.key] !== undefined);
+            return layer ? [{ scope, path: layer.path }] : [];
+        });
+        values.set(setting.key, { value: setting.value, sources });
+    }
+    return values;
+}
+/**
+ * The effective settings of two directories side by side. Values are compared as ccdesk shows
+ * them, so hidden values stay hidden and two of them count as the same.
+ */
+export async function compareSettings(env, a, b) {
+    const [left, right] = await Promise.all([valuesIn(env, resolve(a)), valuesIn(env, resolve(b))]);
+    const keys = [...new Set([...left.keys(), ...right.keys()])].sort();
+    const settings = keys.map((key) => {
+        const x = left.get(key) ?? null;
+        const y = right.get(key) ?? null;
+        return { key, a: x, b: y, same: JSON.stringify(x?.value) === JSON.stringify(y?.value) };
+    });
+    return { a: resolve(a), b: resolve(b), settings };
+}

package/dist/server/scan/context.js

@@ -0,0 +1,140 @@
+import { basename, join } from "node:path";
+import {} from "../../shared/types.js";
+import {} from "./env.js";
+import { isWithin, parseFrontmatter, readTextFile } from "./files.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.
+ */
+function showable(env, projectRoot, path) {
+    if (basename(path) === ".credentials.json")
+        return false;
+    return [projectRoot, env.claudeDir, join(env.home, ".agents"), env.managedDir].some((root) => isWithin(root, path));
+}
+/** What Claude Code injects from an instruction file: no frontmatter, no block-level HTML comments. */
+function injectedText(text) {
+    const body = parseFrontmatter(text).body;
+    // Comments inside code fences are kept, so only text outside fences is stripped.
+    return body
+        .split(/(^(?:```|~~~)[\s\S]*?^(?:```|~~~)[^\n]*$)/m)
+        .map((part, i) => (i % 2 === 1 ? part : part.replace(/^[ \t]*<!--[\s\S]*?-->[ \t]*\n?/gm, "")))
+        .join("");
+}
+function block(fields, text) {
+    return {
+        ...fields,
+        text,
+        lines: text === null || text === "" ? 0 : text.split("\n").length,
+        bytes: text === null ? 0 : Buffer.byteLength(text, "utf8"),
+    };
+}
+/** Claude Code caps each skill's description and when_to_use at this many characters in its listing. */
+const SKILL_DESCRIPTION_CAP = 1536;
+const BUILT_IN_STYLES = ["default", "explanatory", "learning"];
+/** Skills and command files Claude can pick on its own; skillOverrides "name-only" drops the description. */
+function skillListing(skills) {
+    return skills
+        .map((s) => {
+        const name = s.id ?? s.name;
+        if (s.override === "name-only")
+            return `- ${name}`;
+        const text = [s.description, s.whenToUse].filter(Boolean).join(" ");
+        return `- ${name}: ${text.slice(0, SKILL_DESCRIPTION_CAP)}`;
+    })
+        .join("\n");
+}
+/** The scope a listing shows: the one its entries share, else user. */
+function commonScope(entries) {
+    const first = entries[0]?.scope ?? "user";
+    return entries.every((e) => e.scope === first) ? first : "user";
+}
+/** What Claude Code puts in context at session start in this directory, in load order. */
+export async function buildContext(input) {
+    const { env, projectRoot, instructions, memory, inventory, effective } = input;
+    const blocks = [
+        block({
+            kind: "not-counted",
+            path: "Claude Code's system prompt and built-in tools",
+            scope: "managed",
+            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));
+    }
+    // A file both imported and loaded on its own (a rule, an AGENTS.md) is counted once, as itself.
+    const loaded = new Set(instructions.filter((i) => i.status === "loaded").map((i) => i.path));
+    const added = new Set();
+    // An imported file comes before the text that imports it ("Claude reads the imported file
+    // first, then the rest"), and its own imports before it.
+    const importsOf = async (file, via) => {
+        for (const ref of file.imports.filter((r) => r.via === via)) {
+            if (!ref.exists || loaded.has(ref.resolved) || added.has(ref.resolved))
+                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));
+            }
+        }
+    };
+    for (const file of instructions) {
+        if (file.status !== "loaded")
+            continue;
+        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")));
+    }
+    const listed = [...inventory.skills, ...inventory.commands].filter((s) => s.listed !== false && !s.shadowedBy);
+    const listing = skillListing(listed);
+    if (listing)
+        blocks.push(block({
+            kind: "skills",
+            path: "Skill listing",
+            scope: commonScope(listed),
+            note: "Names and descriptions only; a skill's body loads when it is used. Claude Code drops descriptions if the listing passes 1% of the context window.",
+        }, listing));
+    const agents = inventory.agents
+        .filter((a) => !a.shadowedBy && !a.skipped)
+        .map((a) => `- ${a.id ?? a.name}: ${a.description}`)
+        .join("\n");
+    if (agents)
+        blocks.push(block({
+            kind: "agents",
+            path: "Subagent descriptions",
+            scope: commonScope(inventory.agents),
+            note: "Your subagents' descriptions; built-in subagents are not counted",
+        }, agents));
+    const servers = inventory.mcpServers.filter((s) => s.status === "active").length;
+    if (servers > 0)
+        blocks.push(block({
+            kind: "not-counted",
+            path: `Tool names from ${servers} MCP ${servers === 1 ? "server" : "servers"}`,
+            scope: "user",
+            note: "ccdesk does not connect to MCP servers, so it cannot count their tools",
+        }, null));
+    return blocks;
+}

package/dist/server/scan/env.js

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+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();
+    const configDir = configDirFlag !== undefined ? resolve(configDirFlag) : process.env.CLAUDE_CONFIG_DIR;
+    return {
+        home,
+        claudeDir: configDir ?? join(home, ".claude"),
+        // Claude Code keeps .claude.json beside the config dir it was given.
+        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,
+    };
+}
+/** Your configuration home: your home directory, or the folder whose .claude is CLAUDE_CONFIG_DIR. */
+export function isConfigHome(env, path) {
+    return path === env.home || join(path, ".claude") === env.claudeDir;
+}
+function managedDirFor(platform) {
+    if (platform === "darwin")
+        return "/Library/Application Support/ClaudeCode";
+    if (platform === "win32")
+        return "C:\\Program Files\\ClaudeCode";
+    return "/etc/claude-code";
+}