ccdesk 0.0.0-stage → 0.2.0

package/dist/server/watch.js

@@ -0,0 +1,214 @@
+import { watch } from "node:fs";
+import { stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { storeDirName } from "../shared/memory.js";
+import {} from "../shared/types.js";
+import {} from "./scan/env.js";
+import { isNetworkPath, mainWorktreeRoot } from "./scan/files.js";
+import { scanDirectory } from "./scan/index.js";
+/** How long one request waits for a change before answering "nothing changed". */
+const WAIT_MS = 25_000;
+/** Editors write a file in several steps; one change covers them all. */
+const SETTLE_MS = 300;
+/** Watchers outlive a request by this much, so nothing is missed between two polls. */
+const IDLE_MS = 60_000;
+const CONFIG_FOLDERS = ["rules", "agents", "skills", "commands", "output-styles"];
+/**
+ * The files and folders whose changes alter what ccdesk shows for `dir`. A `.claude` folder is
+ * watched only for its config files and folders, never recursively, because Claude Code keeps
+ * whole checkouts in `.claude/worktrees`. ~/.claude.json is left out: Claude Code rewrites it
+ * during every session, and focusing the tab picks up its changes.
+ */
+async function targets(env, dir, extra) {
+    const claude = (folder) => [
+        {
+            path: folder,
+            recursive: false,
+            names: ["settings.json", "settings.local.json", "CLAUDE.md", "AGENTS.md", ...CONFIG_FOLDERS],
+        },
+        ...CONFIG_FOLDERS.map((sub) => ({ path: join(folder, sub), recursive: true })),
+    ];
+    const memoryKey = (await mainWorktreeRoot(dir)) ?? dir;
+    const out = [
+        ...claude(env.claudeDir),
+        { path: join(env.claudeDir, "plugins"), recursive: false },
+        { path: join(env.claudeDir, "projects", storeDirName(memoryKey), "memory"), recursive: false },
+        { path: env.managedDir, recursive: false },
+        { path: join(env.managedDir, "managed-settings.d"), recursive: false },
+        ...extra,
+    ];
+    // The start directory and every parent can hold instructions, rules and settings.
+    for (let d = dir;; d = dirname(d)) {
+        out.push({
+            path: d,
+            recursive: false,
+            names: ["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", ".mcp.json", ".claude"],
+        });
+        if (join(d, ".claude") !== env.claudeDir)
+            out.push(...claude(join(d, ".claude")));
+        if (dirname(d) === d)
+            break;
+    }
+    if (memoryKey !== dir)
+        out.push(...claude(join(memoryKey, ".claude")));
+    return out.filter((t) => !isNetworkPath(t.path));
+}
+/** Files a scan read that the fixed list does not cover: a custom memory folder, imports. */
+export function dependencies(view) {
+    const files = view.instructions.flatMap((i) => [
+        i.realPath ?? i.path,
+        ...i.imports.filter((r) => r.exists).map((r) => r.resolved),
+    ]);
+    const byFolder = new Map();
+    for (const file of files) {
+        const names = byFolder.get(dirname(file)) ?? new Set();
+        names.add(basename(file));
+        byFolder.set(dirname(file), names);
+    }
+    return [
+        ...[...byFolder].map(([path, names]) => ({ path, recursive: false, names: [...names] })),
+        ...(view.memory ? [{ path: view.memory.dir, recursive: false }] : []),
+    ];
+}
+/** One set of file watchers per directory a page is looking at, shared by its requests. */
+export class Watcher {
+    env;
+    scanOf;
+    subscriptions = new Map();
+    /** What the latest scan of each directory read, kept for a watch that starts after the scan. */
+    scanned = new Map();
+    latest = new Map();
+    constructor(env, scanOf = scanDirectory) {
+        this.env = env;
+        this.scanOf = scanOf;
+    }
+    /** Scans `dir` and remembers what the scan read, so those files are watched too. */
+    async scan(dir, profile = "interactive") {
+        const startedAt = Date.now();
+        const stateFile = await this.stateFile();
+        const view = await this.scanOf(this.env, dir, profile);
+        const subscription = this.subscriptions.get(view.path);
+        // Only a watched directory's view can be known to be current later.
+        if (subscription)
+            this.latest.set(view.path, { view, startedAt, stateFile });
+        const extra = dependencies(view);
+        this.scanned.set(view.path, extra);
+        if (subscription && JSON.stringify(extra) !== JSON.stringify(subscription.extra)) {
+            subscription.extra = extra;
+            void this.rewatch(view.path, subscription);
+        }
+        return view;
+    }
+    /**
+     * The view of `dir`: the latest scan while it is known to be current, else a new scan. It is
+     * current only while watchers that started before it have seen no change since it started, and
+     * ~/.claude.json, which is not watched, is as it was. Only an interactive scan is reused, as the
+     * path tester describes an interactive session.
+     */
+    async view(dir) {
+        const latest = this.latest.get(dir);
+        const subscription = this.subscriptions.get(dir);
+        if (latest?.view.profile === "interactive" &&
+            subscription &&
+            subscription.watchingSince < latest.startedAt &&
+            subscription.touchedAt < latest.startedAt &&
+            latest.stateFile === (await this.stateFile()))
+            return latest.view;
+        return this.scan(dir);
+    }
+    /** ~/.claude.json's size and time; Claude Code rewrites it too often to watch. */
+    async stateFile() {
+        const info = await stat(this.env.claudeJson).catch(() => null);
+        return info ? `${info.size}:${info.mtimeMs}` : "missing";
+    }
+    /**
+     * Answers once something changed after `since` (ms since the epoch), or after `timeoutMs` with
+     * the last change time, whichever comes first.
+     */
+    async wait(dir, since, signal, timeoutMs = WAIT_MS) {
+        const subscription = await this.subscribe(dir);
+        clearTimeout(subscription.idle);
+        try {
+            if (subscription.changedAt <= since && !signal.aborted)
+                await new Promise((resolve) => {
+                    const done = () => {
+                        clearTimeout(timer);
+                        signal.removeEventListener("abort", done);
+                        subscription.waiters.delete(done);
+                        resolve();
+                    };
+                    const timer = setTimeout(done, timeoutMs);
+                    signal.addEventListener("abort", done);
+                    subscription.waiters.add(done);
+                });
+        }
+        finally {
+            if (subscription.waiters.size === 0)
+                subscription.idle = setTimeout(() => this.drop(dir), IDLE_MS);
+        }
+        return { changed: subscription.changedAt > since, at: subscription.changedAt };
+    }
+    close() {
+        for (const dir of [...this.subscriptions.keys()])
+            this.drop(dir);
+    }
+    async subscribe(dir) {
+        const existing = this.subscriptions.get(dir);
+        if (existing)
+            return existing;
+        const subscription = {
+            watchers: [],
+            changedAt: 0,
+            touchedAt: 0,
+            watchingSince: Number.POSITIVE_INFINITY,
+            waiters: new Set(),
+            extra: this.scanned.get(dir) ?? [],
+        };
+        this.subscriptions.set(dir, subscription);
+        await this.rewatch(dir, subscription);
+        return subscription;
+    }
+    drop(dir) {
+        const subscription = this.subscriptions.get(dir);
+        if (!subscription)
+            return;
+        clearTimeout(subscription.idle);
+        clearTimeout(subscription.settle);
+        for (const w of subscription.watchers)
+            w.close();
+        this.subscriptions.delete(dir);
+        this.latest.delete(dir);
+    }
+    /** (Re)creates the watchers, so a folder created since, such as a new .claude, is watched. */
+    async rewatch(dir, subscription) {
+        const list = await targets(this.env, dir, subscription.extra);
+        for (const w of subscription.watchers)
+            w.close();
+        subscription.watchers = [];
+        if (this.subscriptions.get(dir) !== subscription)
+            return;
+        for (const target of list) {
+            try {
+                const watcher = watch(target.path, { recursive: target.recursive }, (_event, name) => {
+                    const changed = name === null ? "" : String(name);
+                    if (target.names && !target.names.includes(basename(changed)))
+                        return;
+                    subscription.touchedAt = Date.now();
+                    clearTimeout(subscription.settle);
+                    subscription.settle = setTimeout(() => {
+                        subscription.changedAt = Date.now();
+                        for (const wake of [...subscription.waiters])
+                            wake();
+                        void this.rewatch(dir, subscription);
+                    }, SETTLE_MS);
+                });
+                watcher.on("error", () => watcher.close());
+                subscription.watchers.push(watcher);
+            }
+            catch {
+                // A folder that does not exist yet is caught by watching its parent.
+            }
+        }
+        subscription.watchingSince = Date.now();
+    }
+}

package/dist/server/write.js

@@ -0,0 +1,233 @@
+import { randomBytes } from "node:crypto";
+import { chmod, link, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import {} from "../shared/types.js";
+import {} from "./scan/env.js";
+import { isCredentials, isSecretPath, revisionOf } from "./scan/files.js";
+/** A change ccdesk refuses on purpose; the server answers 409 with the message. */
+export class RefusedError extends Error {
+}
+/** A write refused because its file changed after review: nothing was written. */
+export class StaleError extends RefusedError {
+}
+const CREDENTIALS = "ccdesk does not read or change Claude Code's credentials.";
+const STATE_FILE = "ccdesk does not change ~/.claude.json; Claude Code rewrites it all the time.";
+let queue = Promise.resolve();
+/**
+ * Runs changes one at a time, so two of them can never both pass a revision check before either
+ * writes. Every exported change goes through here; helpers it calls must not.
+ */
+export function serially(change) {
+    const run = queue.then(change);
+    queue = run.catch(() => undefined);
+    return run;
+}
+export function backupRoot(env) {
+    return join(env.claudeDir, "backups", "ccdesk");
+}
+/** Where a path leads after links, or null when it does not exist. */
+function realOrNull(path) {
+    return realpath(path).catch(() => null);
+}
+/** The file a path leads to after links; a missing file keeps its own path. */
+async function target(env, path) {
+    if (await isCredentials(env, path))
+        throw new RefusedError(CREDENTIALS);
+    try {
+        const real = await realpath(path);
+        if (isSecretPath(real) || isSecretPath(path))
+            throw new RefusedError(CREDENTIALS);
+        return real;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        if ((await lstat(path).catch(() => null))?.isSymbolicLink())
+            throw new RefusedError(`${path} is a link to a file that does not exist; fix the link first.`);
+        if (isSecretPath(path))
+            throw new RefusedError(CREDENTIALS);
+        return path;
+    }
+}
+/** The file's text, or null when it does not exist. Any other read error is thrown, not hidden. */
+export async function readIfExists(env, path) {
+    try {
+        return await readFile(await target(env, path), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+/**
+ * Replaces a file's content, but only while it still has `expected` revision. The new text is
+ * written to a temporary file first and the revision is checked again just before the rename, so
+ * an edit made elsewhere while ccdesk was saving is kept and the save refused. A symlink is written
+ * through, so links into a dotfiles repository survive; the temporary file is new, unguessable and
+ * created exclusively, so nothing planted beside the target can redirect the write. A file with
+ * other hard links is refused, since the rename would leave them on the old text.
+ */
+export async function writeAtomic(env, path, content, expected) {
+    const file = await target(env, path);
+    if (basename(file) === ".claude.json" || file === (await realOrNull(env.claudeJson)))
+        throw new RefusedError(STATE_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    const existing = await lstat(file).catch(() => null);
+    if (existing && existing.nlink > 1)
+        throw new RefusedError(`${path} has other hard links, and saving it would split it from its other names; edit it in your editor.`);
+    const temp = join(dirname(file), `.${basename(file)}.ccdesk-${randomBytes(6).toString("hex")}`);
+    const handle = await open(temp, "wx", 0o600);
+    try {
+        try {
+            await handle.writeFile(content, "utf8");
+            await handle.chmod(existing ? existing.mode & 0o7777 : 0o666 & ~process.umask());
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (revisionOf(await readIfExists(env, file)) !== expected)
+            throw new StaleError(`${path} changed while ccdesk was saving; nothing was written. Review it again.`);
+        await rename(temp, file);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+}
+/**
+ * Deletes a file only while it still has `expected` revision, and says whether it did. The file is
+ * renamed aside first, so what is removed is exactly what was checked; one that differs is put
+ * back, unless a new file took its place meanwhile, which ccdesk then refuses to overwrite.
+ */
+export async function removeExactly(path, expected) {
+    const aside = join(dirname(path), `.${basename(path)}.ccdesk-${randomBytes(6).toString("hex")}`);
+    await rename(path, aside);
+    let text;
+    try {
+        text = await readFile(aside, "utf8");
+    }
+    catch (error) {
+        await rename(aside, path);
+        throw error;
+    }
+    if (revisionOf(text) === expected) {
+        await rm(aside);
+        return true;
+    }
+    try {
+        await link(aside, path);
+    }
+    catch (error) {
+        const replaced = error.code === "EEXIST" ||
+            (await lstat(path).catch(() => null)) !== null;
+        if (replaced)
+            throw new RefusedError(`${path} changed and was replaced while ccdesk removed it; the earlier text is kept in ${aside}.`);
+        // A file system without hard links: put it back by name. Unlike a link, this would replace a
+        // file created in the instant since the check above.
+        await rename(aside, path);
+        return false;
+    }
+    await rm(aside);
+    return false;
+}
+export const MANIFEST = "ccdesk-backup.json";
+/** Takes a change out of Recent changes, for one whose effect was undone again right away. */
+export function forgetChange(env, id) {
+    return rm(join(backupRoot(env), id), { recursive: true, force: true });
+}
+/** The copy of the target inside a backup folder. */
+export const SNAPSHOT = "before";
+/** For a change made through `claude mcp`: the affected servers after it, values hidden. */
+export const SHOWN_AFTER = "after";
+/** A new, empty backup folder that only you can read, and its id. */
+async function newBackup(env, kind) {
+    const createdAt = new Date().toISOString();
+    const id = `${createdAt.replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}-${kind}`;
+    const root = backupRoot(env);
+    const dir = join(root, id);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(root, 0o700);
+    return { createdAt, id, dir };
+}
+/**
+ * Lists a change Claude Code made through `claude mcp` in Recent changes. ccdesk cannot undo it,
+ * so it keeps only the affected servers before and after as the page shows them, secrets hidden,
+ * and the commands that would put them back; never a value the page does not show.
+ */
+export async function recordClaudeMcpChange(env, record) {
+    const { createdAt, dir } = await newBackup(env, "mcp-claude");
+    const manifest = {
+        kind: "mcp-claude",
+        target: record.target,
+        createdAt,
+        before: revisionOf(record.shownBefore),
+        after: revisionOf(record.shownAfter),
+        undoCommands: record.undoCommands,
+    };
+    try {
+        await writeFile(join(dir, SNAPSHOT), record.shownBefore, { mode: 0o600 });
+        await writeFile(join(dir, SHOWN_AFTER), record.shownAfter, { mode: 0o600 });
+        // Written last, so a folder without it is never listed.
+        await writeFile(join(dir, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch (error) {
+        await rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+/**
+ * Makes a change and records it in Recent changes. The file's previous text and a manifest are put
+ * in a new backup folder first, so a change interrupted halfway can still be restored; the manifest
+ * gets the new revision once the change is made. A change that fails is removed from Recent changes
+ * when its first write was refused as stale, or when `unchanged` confirms nothing on disk moved;
+ * otherwise it stays, marked partial, so it can be put back. Backups can hold settings with secrets, so only the user can read them.
+ */
+export async function recordChange(env, record, change) {
+    const { createdAt, id, dir } = await newBackup(env, record.kind);
+    const manifest = {
+        kind: record.kind,
+        target: record.target,
+        createdAt,
+        before: revisionOf(record.before),
+        after: "pending",
+        ...(record.removedIndexLines ? { removedIndexLines: record.removedIndexLines } : {}),
+    };
+    // Replaced by rename, so an interrupted rewrite leaves the earlier manifest rather than half of one.
+    const writeManifest = async () => {
+        const temp = join(dir, `${MANIFEST}.next`);
+        await writeFile(temp, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+        await rename(temp, join(dir, MANIFEST));
+    };
+    try {
+        if (record.before !== null)
+            await writeFile(join(dir, SNAPSHOT), record.before, { mode: 0o600 });
+        await writeManifest();
+    }
+    catch (error) {
+        await rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+    let result;
+    try {
+        result = await change();
+    }
+    catch (error) {
+        const unchanged = record.unchanged ??
+            (async () => revisionOf(await readIfExists(env, record.target)) === revisionOf(record.before));
+        // A stale refusal from the change's own first write means ccdesk wrote nothing; changes that
+        // write more than once turn a later stale refusal into a plain one (see deleteMemory).
+        if (error instanceof StaleError || (await unchanged().catch(() => false))) {
+            await rm(dir, { recursive: true, force: true });
+        }
+        else {
+            manifest.after = "partial";
+            await writeManifest().catch(() => undefined);
+        }
+        throw error;
+    }
+    manifest.after = result.revision;
+    await writeManifest();
+    return { ...result, id, created: record.before === null };
+}