ccdesk 0.1.0 → 0.2.0

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

@@ -35,10 +35,11 @@ const BUILT_IN_STYLES = ["default", "explanatory", "learning"];
 function skillListing(skills) {
     return skills
         .map((s) => {
+        const name = s.id ?? s.name;
         if (s.override === "name-only")
-            return `- ${s.name}`;
+            return `- ${name}`;
         const text = [s.description, s.whenToUse].filter(Boolean).join(" ");
-        return `- ${s.name}: ${text.slice(0, SKILL_DESCRIPTION_CAP)}`;
+        return `- ${name}: ${text.slice(0, SKILL_DESCRIPTION_CAP)}`;
     })
         .join("\n");
 }
@@ -92,7 +93,7 @@ export async function buildContext(input) {
                     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);
+                const text = await readTextFile(env, ref.resolved);
                 blocks.push(block(fields, text ? injectedText(text.text) : null));
             }
         }
@@ -107,7 +108,7 @@ export async function buildContext(input) {
     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 listed = [...inventory.skills, ...inventory.commands].filter((s) => s.listed !== false && !s.shadowedBy);
     const listing = skillListing(listed);
     if (listing)
         blocks.push(block({
@@ -117,7 +118,7 @@ export async function buildContext(input) {
             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)
+        .filter((a) => !a.shadowedBy && !a.skipped)
         .map((a) => `- ${a.id ?? a.name}: ${a.description}`)
         .join("\n");
     if (agents)

package/dist/server/scan/env.js

@@ -1,8 +1,9 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
-export function scanEnvFromProcess() {
+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 = process.env.CLAUDE_CONFIG_DIR;
+    const configDir = configDirFlag !== undefined ? resolve(configDirFlag) : process.env.CLAUDE_CONFIG_DIR;
     return {
         home,
         claudeDir: configDir ?? join(home, ".claude"),
@@ -14,6 +15,10 @@ export function scanEnvFromProcess() {
         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";

package/dist/server/scan/files.js

@@ -1,10 +1,12 @@
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
-import { lstat, open, readdir, readFile, readlink, realpath, stat } from "node:fs/promises";
+import {} from "node:fs";
+import { lstat, open, readdir, readlink, realpath, stat } from "node:fs/promises";
 import { basename, dirname, join, normalize, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import {} from "../../shared/types.js";
+import {} from "./env.js";
 const run = promisify(execFile);
 /** 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;
@@ -16,7 +18,7 @@ export function isSecretPath(path) {
  * 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.
  */
-export async function leadsToSecret(path) {
+async function leadsToSecret(path) {
     let current = path;
     for (let hop = 0; hop < 40; hop++) {
         if (isSecretPath(current))
@@ -28,6 +30,38 @@ export async function leadsToSecret(path) {
     }
     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.
+ */
+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 JSON parse failure without the parser's message, which quotes the text around the fault and
  * so can quote a secret.
@@ -37,9 +71,11 @@ export function jsonSyntaxError(error) {
     return at ? `not valid JSON (line ${at[1]}, column ${at[2]})` : "not valid JSON";
 }
 /**
- * The text ccdesk shows for a file reached as an instruction, import, memory or memory backup. A
+ * The text ccdesk shows for a file reached as an instruction, import, memory, agent or skill. A
  * settings or MCP file read this way, whatever it is named, would otherwise show its env and
- * headers values, so anything that parses as JSON is shown parsed with them hidden.
+ * headers values, so anything that parses as JSON is shown parsed with them hidden. Frontmatter can
+ * hold the same values, in a subagent's inline MCP servers (docs: sub-agents#scope-mcp-servers-to-a-subagent),
+ * so frontmatter that holds any is shown re-written with them hidden.
  */
 export function shownText(text) {
     if (text === null)
@@ -49,12 +85,28 @@ export function shownText(text) {
         data = JSON.parse(text);
     }
     catch {
-        return text;
+        return shownFrontmatter(text);
     }
     return typeof data === "object" && data !== null
         ? `${JSON.stringify(redactSecrets(data), null, 2)}\n`
         : text;
 }
+function shownFrontmatter(text) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return text;
+    let data;
+    try {
+        data = parseYaml(match[1] ?? "");
+    }
+    catch {
+        return text;
+    }
+    const redacted = redactSecrets(data);
+    if (JSON.stringify(redacted) === JSON.stringify(data))
+        return text;
+    return `---\n${stringifyYaml(redacted)}---\n${text.slice(match[0].length)}`;
+}
 /** A file named .json that does not parse is not shown: its text could still hold a secret. */
 function shownJsonFile(text) {
     try {
@@ -126,17 +178,17 @@ export async function listDir(path) {
         return [];
     }
 }
-export async function readTextFile(path) {
+export async function readTextFile(env, path) {
     try {
         if (await linksToNetwork(path))
             return null;
-        if (await leadsToSecret(path))
-            return null;
         const real = await realpath(path);
         const info = await stat(path);
         if (!info.isFile())
             return null;
-        const handle = await open(path, "r");
+        const handle = await openUnlessCredentials(env, path);
+        if (!handle)
+            return null;
         let text;
         try {
             const buffer = Buffer.alloc(Math.min(info.size, MAX_TEXT_BYTES));
@@ -170,25 +222,34 @@ export async function resolvedPath(path) {
         return path;
     }
 }
-export async function readJsonObject(path) {
+/** A JSON object file; `emptyIsObject` reads an empty file as `{}`. */
+export async function readJsonObject(env, path, { emptyIsObject = false } = {}) {
     let raw;
     try {
-        if (await leadsToSecret(path))
+        const handle = await openUnlessCredentials(env, path);
+        if (!handle)
             return { ok: false, missing: false, error: "ccdesk does not read credentials" };
-        raw = await readFile(path, "utf8");
+        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, error: "not a JSON object" };
+            return { ok: false, missing: false, unparsed: true, error: "not a JSON object" };
         return { ok: true, data };
     }
     catch (error) {
-        return { ok: false, missing: false, error: jsonSyntaxError(error) };
+        return { ok: false, missing: false, unparsed: true, error: jsonSyntaxError(error) };
     }
 }
 export function isRecord(value) {
@@ -215,31 +276,58 @@ export function shownUrl(url) {
         return url.replace(/\/\/[^/@]*@/, "//•••@").replace(/\?.*$/, "?•••");
     }
 }
+/** A flag whose value is a secret, such as `--token` or `--api-key`. */
+const SECRET_FLAG = /^--(token|api[-_]?key|apikey|password|secret|auth|key)$/i;
+/** A value that starts like a common API key or token. */
+const KEY_PREFIX = /^(sk-|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|xox[bp]-|glpat-|AKIA[0-9A-Z]{16})/;
+/**
+ * A server's command-line arguments as ccdesk shows them: the value after a secret flag, given as
+ * `--token value` or `--token=value`, a value that starts like a known key, and the credentials in
+ * a URL are hidden.
+ */
+export function shownArgs(args) {
+    return args.map((arg, i) => {
+        if (typeof arg !== "string")
+            return arg;
+        const previous = args[i - 1];
+        if (typeof previous === "string" && SECRET_FLAG.test(previous) && !arg.startsWith("-"))
+            return "•••";
+        const equals = arg.indexOf("=");
+        if (equals > 0) {
+            const name = arg.slice(0, equals);
+            if (SECRET_FLAG.test(name) || KEY_PREFIX.test(arg.slice(equals + 1)))
+                return `${name}=•••`;
+        }
+        if (KEY_PREFIX.test(arg))
+            return "•••";
+        if (/^https?:\/\//i.test(arg))
+            return shownUrl(arg);
+        return arg;
+    });
+}
 /**
  * Replace values that commonly hold secrets with a placeholder, keeping the keys: env and headers
- * values, and the user, password and query of a `url`.
+ * values, the user, password and query of a `url`, and secret values in the `args` of a command.
  */
 export function redactSecrets(value) {
     if (Array.isArray(value))
         return value.map(redactSecrets);
     if (!isRecord(value))
         return value;
-    const out = {};
-    for (const [key, inner] of Object.entries(value)) {
-        if ((key === "env" || key === "headers") && isRecord(inner)) {
-            out[key] = Object.fromEntries(Object.keys(inner).map((k) => [k, "•••"]));
-        }
-        else if (key === "url" && typeof inner === "string") {
-            out[key] = shownUrl(inner);
-        }
-        else {
-            out[key] = redactSecrets(inner);
-        }
-    }
-    return out;
+    // Built with fromEntries: assigning a key named __proto__ would set the prototype instead.
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => {
+        if ((key === "env" || key === "headers") && isRecord(inner))
+            return [key, Object.fromEntries(Object.keys(inner).map((k) => [k, "•••"]))];
+        if (key === "url" && typeof inner === "string")
+            return [key, shownUrl(inner)];
+        if (key === "args" && "command" in value && Array.isArray(inner))
+            return [key, shownArgs(inner)];
+        return [key, redactSecrets(inner)];
+    }));
 }
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 export function parseFrontmatter(text) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    const match = FRONTMATTER.exec(text);
     if (!match)
         return { data: {}, body: text };
     try {

package/dist/server/scan/index.js

@@ -1,17 +1,19 @@
+import { lstat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { storeDirName } from "../../shared/memory.js";
 import {} from "../../shared/types.js";
 import { buildContext } from "./context.js";
-import {} from "./env.js";
+import { isConfigHome } from "./env.js";
 import { gitRoot, isDir, isFile, isRecord, mainWorktreeRoot, readJsonObject, stringsIn, visibilityOf, } from "./files.js";
 import { AGENTS_MD_MODES, resolveInstructions } from "./instructions.js";
 import { readInventory } from "./inventory.js";
-import { readMemoryStore, storeDirName } from "./memory.js";
+import { readMemoryStore } from "./memory.js";
 import { permissionsOf, trustWaits } from "./permissions.js";
 import { listProjects } from "./projects.js";
 import { effectiveSettings, readSettingsLayers } from "./settings.js";
 import { builtinTools } from "./tools.js";
 async function readClaudeJson(env) {
-    const result = await readJsonObject(env.claudeJson);
+    const result = await readJsonObject(env, env.claudeJson);
     return result.ok ? result.data : null;
 }
 export async function scanOverview(env, launchDir) {
@@ -48,7 +50,7 @@ export async function scanOverview(env, launchDir) {
     };
 }
 /** Everything Claude Code reads when started in `dir`. */
-export async function scanDirectory(env, dir) {
+export async function scanDirectory(env, dir, profile = "interactive") {
     const path = resolve(dir);
     const exists = await isDir(path);
     const claudeJson = await readClaudeJson(env);
@@ -80,6 +82,7 @@ export async function scanDirectory(env, dir) {
         layers: settings,
         claudeJson,
         trust,
+        profile,
     });
     // Every project file that shapes Claude here, so the UI can say who sees each one.
     const mcpJson = join(path, ".mcp.json");
@@ -114,19 +117,33 @@ export async function scanDirectory(env, dir) {
                 sharing.ignored.push(rel);
         }
     }
-    // docs: permissions#when-your-local-settings-file-needs-trust
-    const localFromRepository = settings.some((l) => l.scope === "local" && l.visibility === "tracked");
-    const trustOptions = { trust, inConfigHome: isConfigHome(env, path), localFromRepository };
+    // A local file tracked in git, or in a .claude that is a link, counts as the repository's
+    // (docs: permissions#when-your-local-settings-file-needs-trust).
+    const localFromRepository = (await Promise.all(settings
+        .filter((l) => l.scope === "local" && l.exists)
+        .map(async (l) => l.visibility === "tracked" ||
+        ((await lstat(dirname(l.path)).catch(() => null))?.isSymbolicLink() ?? false)))).some(Boolean);
+    const trustOptions = {
+        trust,
+        inConfigHome: isConfigHome(env, path),
+        localFromRepository,
+        profile,
+    };
     const memory = await readMemory(env, mainRoot, path, effective, trustOptions);
     const permissions = permissionsOf(settings, trustOptions);
     for (const l of settings)
         if (l.error)
-            problems.push({ path: l.path, error: l.error });
-    const mcp = await readJsonObject(mcpJson);
+            problems.push({
+                path: l.path,
+                error: l.error,
+                ...(l.blocksStart ? { blocksStart: true } : {}),
+            });
+    const mcp = await readJsonObject(env, mcpJson);
     if (!mcp.ok && !mcp.missing)
         problems.push({ path: mcpJson, error: mcp.error });
     return {
         path,
+        profile,
         exists,
         gitRoot: root,
         agentsMdMode: mode,
@@ -150,10 +167,6 @@ export async function scanDirectory(env, dir) {
         sharing,
     };
 }
-/** Your home directory, or the folder whose .claude is CLAUDE_CONFIG_DIR. */
-function isConfigHome(env, path) {
-    return path === env.home || join(path, ".claude") === env.claudeDir;
-}
 /**
  * Your answers to Claude Code's trust dialogs, from ~/.claude.json (docs: permissions#project-allow-rules-and-workspace-trust).
  * In a repository the key is the main checkout's root; outside one it is the folder, and a trusted
@@ -193,7 +206,8 @@ async function readMemory(env, mainRoot, path, effective, trustOptions) {
     const setting = effective.find((s) => s.key === "autoMemoryDirectory");
     // A value from a repository file counts once the folder is trusted, like hooks (docs:
     // settings-reference#automemorydirectory); until then the next file down that sets it decides.
-    const waitsForTrust = trustWaits(trustOptions);
+    // claude -p and the SDK treat the folder as trusted for hooks, so for this too.
+    const waitsForTrust = trustOptions.profile === "print" ? () => false : trustWaits(trustOptions);
     const candidates = setting
         ? [{ scope: setting.from[0], value: setting.value }, ...setting.overridden]
         : [];
@@ -202,7 +216,7 @@ async function readMemory(env, mainRoot, path, effective, trustOptions) {
     const customDir = typeof custom?.value === "string" ? expandHome(env, custom.value) : null;
     const storeName = env.projectDirName ?? storeDirName(key);
     const dir = customDir ?? join(env.claudeDir, "projects", storeName, "memory");
-    const store = (await readMemoryStore(dir, key)) ?? {
+    const store = (await readMemoryStore(env, dir, key)) ?? {
         dir,
         loaded: true,
         projectPath: key,

package/dist/server/scan/instructions.js

@@ -33,7 +33,7 @@ export async function resolveInstructions(options) {
     const { env, cwd, mode, excludes, externalImports, managedClaudeMd, problems } = options;
     /** A file that exists but cannot be read is reported, not taken for a missing one. */
     const readInstruction = async (path) => {
-        const file = await readTextFile(path);
+        const file = await readTextFile(env, path);
         if (file || !(await stat(path).catch(() => null))?.isFile())
             return file;
         const denied = await access(path, constants.R_OK).then(() => null, (error) => error.code ?? String(error));
@@ -43,7 +43,7 @@ export async function resolveInstructions(options) {
     };
     const ctx = {
         realCwd: await resolvedPath(resolve(cwd)),
-        home: env.home,
+        env,
         approved: externalImports === "approved",
     };
     const managedOnly = mode === "managed-only";
@@ -150,8 +150,9 @@ export async function resolveInstructions(options) {
         if (file.kind === "rule" && file.realPath && !isWithin(ctx.realCwd, file.realPath)) {
             if (!ctx.approved)
                 skip(file, `${waiting}; this rule links outside it`);
+            // docs: memory#share-rules-across-projects-with-symlinks
             else if (file.paths)
-                skip(file, "Links outside this project, so its paths field is not used");
+                skip(file, "Links outside this project, and such a rule loads only without a paths field");
         }
     }
     addChecks(out);
@@ -239,7 +240,7 @@ async function collectImports(file, ctx, readExternal) {
         if (hop >= MAX_IMPORT_HOPS)
             return;
         for (const raw of importPaths(source.text)) {
-            const target = expandImport(raw, dirname(source.path), ctx.home);
+            const target = expandImport(raw, dirname(source.path), ctx.env.home);
             if (isNetworkPath(target))
                 continue;
             const real = await resolvedPath(target);
@@ -247,7 +248,7 @@ async function collectImports(file, ctx, readExternal) {
                 continue;
             seen.add(real);
             const external = !isWithin(ctx.realCwd, real);
-            const imported = !external || readExternal ? await readTextFile(target) : null;
+            const imported = !external || readExternal ? await readTextFile(ctx.env, target) : null;
             const ref = {
                 raw,
                 resolved: real,
@@ -271,10 +272,13 @@ function expandImport(raw, baseDir, home) {
         return join(home, unescaped.slice(2));
     return isAbsolute(unescaped) ? unescaped : resolve(baseDir, unescaped);
 }
-/** `@path` references outside code spans and fences; a backslash keeps a space in the path. */
+/**
+ * `@path` references outside code spans and fences; a backslash keeps a space in the path. A code
+ * span opens with a run of backticks and closes at the next run of the same length.
+ */
 function importPaths(text) {
     const withoutFences = text.replace(/^(```|~~~)[\s\S]*?^\1/gm, "");
-    const withoutSpans = withoutFences.replace(/`[^`\n]*`/g, "");
+    const withoutSpans = withoutFences.replace(/(?<!`)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g, "");
     const found = [];
     for (const match of withoutSpans.matchAll(/(?:^|\s)@((?:[^\s\\]|\\ )+)/g)) {
         const path = match[1]?.replace(/[.,;:!?)\]]+$/, "");