ccdesk 0.0.0-stage → 0.1.0

package/dist/server/mutations.js

@@ -0,0 +1,188 @@
+import { access, constants, readdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import {} from "../shared/types.js";
+import {} from "./scan/env.js";
+import { isWithin, parseFrontmatter, revisionOf, shownText, stringField } from "./scan/files.js";
+import { deadLinks } from "./scan/memory.js";
+import { RefusedError, readIfExists, recordChange, removeExactly, serially, writeAtomic, } from "./write.js";
+async function projectsRoot(env) {
+    return realpath(join(env.claudeDir, "projects")).catch(() => {
+        throw new RefusedError("There is no auto memory folder.");
+    });
+}
+/** A real `<config>/projects/<store>/memory` folder, after following links. */
+export async function assertMemoryDir(env, dir) {
+    const real = await realpath(dir).catch(() => {
+        throw new RefusedError("That memory folder no longer exists.");
+    });
+    const root = await projectsRoot(env);
+    if (real === root || !isWithin(root, real) || basename(real) !== "memory")
+        throw new RefusedError("ccdesk only changes auto memory under ~/.claude/projects.");
+    return real;
+}
+/**
+ * A memory folder's MEMORY.md. When it is a link, the file it leads to must be in the same folder,
+ * so changing the index can never rewrite a file elsewhere.
+ */
+export async function indexPathIn(store) {
+    const path = join(store, "MEMORY.md");
+    const real = await realpath(path).catch(() => path);
+    if (dirname(real) !== store)
+        throw new RefusedError("This MEMORY.md links outside its memory folder; ccdesk leaves it alone.");
+    return path;
+}
+/** A topic file inside a memory folder: the only kind of file ccdesk deletes. */
+async function assertMemoryFile(env, path) {
+    const real = await realpath(path).catch(() => {
+        throw new RefusedError("That memory file no longer exists.");
+    });
+    await assertMemoryDir(env, dirname(real));
+    if (!real.endsWith(".md") || basename(real) === "MEMORY.md")
+        throw new RefusedError("MEMORY.md is the index Claude maintains; delete individual memories instead.");
+    if (!(await stat(real)).isFile())
+        throw new RefusedError("Not a file.");
+    return real;
+}
+/** One fingerprint for two files, so a change can require both as they were reviewed. */
+export function revisionOfBoth(first, second) {
+    return `${revisionOf(first)}+${revisionOf(second)}`;
+}
+const reviewAgain = () => new RefusedError("The memory or MEMORY.md changed since you reviewed this; review it again.");
+/** Runs a plan only while everything it was worked out from is as reviewed. */
+function saveReviewed(plan, expectedRevision) {
+    return serially(async () => {
+        const planned = await plan();
+        if (planned.preview.revision !== expectedRevision)
+            throw reviewAgain();
+        return planned.save();
+    });
+}
+/** MEMORY.md's lines without the empty ones a trailing newline leaves. */
+function indexLines(index) {
+    const lines = (index ?? "").split("\n");
+    while (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+/** Deletes a memory with the MEMORY.md lines that point at it. */
+async function planDelete(env, path) {
+    const real = await assertMemoryFile(env, path);
+    const text = await readIfExists(env, real);
+    const indexPath = await indexPathIn(dirname(real));
+    const index = await readIfExists(env, indexPath);
+    const removedIndexLines = [];
+    const kept = (index ?? "").split("\n").filter((line) => {
+        if (!line.includes(`(${basename(real)})`))
+            return true;
+        removedIndexLines.push(line);
+        return false;
+    });
+    const next = removedIndexLines.length > 0 ? kept.join("\n") : index;
+    const revision = revisionOfBoth(text, index);
+    const save = async () => {
+        // A folder that refuses the delete would leave MEMORY.md changed with the memory still there.
+        await access(dirname(real), constants.W_OK);
+        // Nothing of the delete is left when the index is as reviewed and the memory is still there,
+        // even if Claude rewrote the memory meanwhile.
+        const unchanged = async () => revisionOf(await readIfExists(env, indexPath)) === revisionOf(index) &&
+            (await readIfExists(env, real)) !== null;
+        return recordChange(env, { kind: "memory-delete", target: real, before: text, removedIndexLines, unchanged }, async () => {
+            // The index goes first: if it changed meanwhile, nothing has been removed yet.
+            if (next !== index)
+                await writeAtomic(env, indexPath, next ?? "", revisionOf(index));
+            let removed = false;
+            try {
+                removed = await removeExactly(real, revisionOf(text));
+            }
+            finally {
+                // Claude may have rewritten the memory while the index was saved; then the index goes back.
+                if (!removed && next !== index)
+                    await writeAtomic(env, indexPath, index ?? "", revisionOf(next)).catch((error) => {
+                        // The index was already changed, so this is not a "nothing written" refusal.
+                        throw new RefusedError(`MEMORY.md changed again, so ccdesk could not put its line back: ${error instanceof Error ? error.message : error}`);
+                    });
+            }
+            if (!removed)
+                throw reviewAgain();
+            return { target: real, revision: revisionOfBoth(null, next), removedIndexLines };
+        });
+    };
+    return {
+        preview: {
+            files: [
+                { path: real, before: text, after: null },
+                ...(next !== index ? [{ path: indexPath, before: index, after: next }] : []),
+            ],
+            revision,
+        },
+        save,
+    };
+}
+/** Rewrites MEMORY.md through `edit`, recorded in Recent changes. */
+async function planIndex(env, store, edit, 
+/** Other text the new index was worked out from, bound into the revision. */
+source) {
+    const path = await indexPathIn(store);
+    const before = await readIfExists(env, path);
+    const after = `${edit(indexLines(before)).join("\n")}\n`;
+    if (after === before)
+        throw new RefusedError("MEMORY.md already says that.");
+    const save = () => recordChange(env, { kind: "memory-index", target: path, before }, async () => {
+        await writeAtomic(env, path, after, revisionOf(before));
+        return { target: path, revision: revisionOf(after) };
+    });
+    return {
+        preview: { files: [{ path, before, after }], revision: revisionOfBoth(before, source) },
+        save,
+    };
+}
+/** One line of text: frontmatter can hold multi-line strings, an index line cannot. */
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** Adds a memory that MEMORY.md does not mention, in the `- [name](file) — description` form. */
+async function planAdd(env, memoryPath) {
+    const real = await assertMemoryFile(env, memoryPath);
+    const text = await readIfExists(env, real);
+    const { data } = parseFrontmatter(text ?? "");
+    const name = oneLine(stringField(data, "name")) || basename(real, ".md");
+    const description = oneLine(stringField(data, "description"));
+    const line = `- [${name}](${basename(real)})${description ? ` — ${description}` : ""}`;
+    return planIndex(env, dirname(real), (lines) => [...lines, line], text);
+}
+/** Removes every MEMORY.md line that points at a memory file that no longer exists. */
+async function planRemoveDead(env, indexPath) {
+    if (basename(indexPath) !== "MEMORY.md")
+        throw new RefusedError("Only a memory folder's MEMORY.md can be changed.");
+    const store = await assertMemoryDir(env, dirname(indexPath));
+    const files = (await readdir(store)).sort();
+    return planIndex(env, store, (lines) => lines.filter((line) => deadLinks(line, files).length === 0), files.join("\n"));
+}
+const PLANS = {
+    delete: planDelete,
+    add: planAdd,
+    "remove-dead": planRemoveDead,
+};
+export function isMemoryAction(value) {
+    return Object.hasOwn(PLANS, value);
+}
+/** What a memory action would change, for review. */
+export async function previewMemoryChange(env, action, path) {
+    // Shown like any other text: a memory folder could hold a JSON file with secrets.
+    const { files, revision } = (await PLANS[action](env, path)).preview;
+    return {
+        files: files.map((f) => ({
+            path: f.path,
+            before: shownText(f.before),
+            after: shownText(f.after),
+        })),
+        revision,
+    };
+}
+/**
+ * Makes a reviewed memory action. `path` is the memory file, or MEMORY.md for remove-dead; the
+ * action runs only while everything its review was worked out from is unchanged.
+ */
+export function changeMemory(env, action, path, expectedRevision) {
+    return saveReviewed(() => PLANS[action](env, path), expectedRevision);
+}

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/context.js

@@ -0,0 +1,139 @@
+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) => {
+        if (s.override === "name-only")
+            return `- ${s.name}`;
+        const text = [s.description, s.whenToUse].filter(Boolean).join(" ");
+        return `- ${s.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(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);
+    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)
+        .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,23 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function scanEnvFromProcess() {
+    const home = homedir();
+    const configDir = 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,
+    };
+}
+function managedDirFor(platform) {
+    if (platform === "darwin")
+        return "/Library/Application Support/ClaudeCode";
+    if (platform === "win32")
+        return "C:\\Program Files\\ClaudeCode";
+    return "/etc/claude-code";
+}