ccdesk 0.2.2 → 0.2.4

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

@@ -0,0 +1,39 @@
+import { type Plugin, type Problem, type SettingsLayer } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+/** A plugin with its manifest, which a scan reads once. */
+export interface LoadedPlugin {
+    plugin: Plugin;
+    /** `.claude-plugin/plugin.json`, or `{}` when there is none or it does not parse. */
+    manifest: Record<string, unknown>;
+}
+/** Reads a plugin's manifest; one that is there but does not parse goes into `problems`. */
+export declare function loadPlugin(env: ScanEnv, plugin: Plugin, problems: Problem[]): Promise<LoadedPlugin>;
+/**
+ * The prefix of a plugin's skills, commands and agents: the manifest's name, which wins over the
+ * name the plugin is enabled under (docs: plugins-reference#name, #metadata-precedence).
+ */
+export declare function pluginNamespace({ plugin, manifest }: LoadedPlugin): string;
+/**
+ * Installed plugins that apply in `projectDir`, with whether each is enabled and by which file. An
+ * install list or manifest that is there but does not parse goes into `problems`.
+ */
+export declare function readPlugins(env: ScanEnv, layers: SettingsLayer[], projectDir: string, gitRoot: string | null, problems: Problem[]): Promise<LoadedPlugin[]>;
+/** The paths a manifest key names (one path or a list), inside the plugin; null when unset. */
+export declare function manifestPaths({ plugin, manifest }: LoadedPlugin, key: string): Promise<string[] | null>;
+/**
+ * The value of a manifest key that is a path, an inline object, or a list of either. A file it
+ * names that is there but does not parse goes into `problems`.
+ */
+export declare function manifestConfigs(env: ScanEnv, { plugin, manifest }: LoadedPlugin, key: string, problems: Problem[]): Promise<Array<{
+    value: unknown;
+    path: string;
+}>>;
+type ManifestCommand = {
+    name: string;
+    path: string;
+    description: string;
+    text: string | null;
+};
+/** The manifest's `commands` object form: command name to a file or inline content. */
+export declare function manifestCommandMap({ plugin, manifest, }: LoadedPlugin): Promise<ManifestCommand[]>;
+export {};

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

@@ -2,28 +2,32 @@ import { join, resolve } from "node:path";
 import { HIGHEST_FIRST } from "../../shared/scopes.js";
 import {} from "../../shared/types.js";
 import {} from "./env.js";
-import { isRecord, isWithin, readJsonObject, resolvedPath, stringField } from "./files.js";
+import { isWithin, readJsonOrReport, resolvedPath, stringField } from "./files.js";
+import { isRecord } from "./data.js";
 function manifestPath(plugin) {
     return join(plugin.installPath, ".claude-plugin", "plugin.json");
 }
-async function manifest(env, plugin) {
-    const result = await readJsonObject(env, manifestPath(plugin));
-    return result.ok ? result.data : {};
+/** Reads a plugin's manifest; one that is there but does not parse goes into `problems`. */
+export async function loadPlugin(env, plugin, problems) {
+    return { plugin, manifest: (await readJsonOrReport(env, manifestPath(plugin), problems)) ?? {} };
 }
 /**
  * The prefix of a plugin's skills, commands and agents: the manifest's name, which wins over the
  * name the plugin is enabled under (docs: plugins-reference#name, #metadata-precedence).
  */
-export async function pluginNamespace(env, plugin) {
-    return stringField(await manifest(env, plugin), "name") || (plugin.id.split("@")[0] ?? plugin.id);
+export function pluginNamespace({ plugin, manifest }) {
+    return stringField(manifest, "name") || (plugin.id.split("@")[0] ?? plugin.id);
 }
-/** Installed plugins that apply in `projectDir`, with whether each is enabled and by which file. */
-export async function readPlugins(env, layers, projectDir, gitRoot) {
-    const installed = await readJsonObject(env, join(env.claudeDir, "plugins", "installed_plugins.json"));
-    if (!installed.ok || !isRecord(installed.data.plugins))
+/**
+ * Installed plugins that apply in `projectDir`, with whether each is enabled and by which file. An
+ * install list or manifest that is there but does not parse goes into `problems`.
+ */
+export async function readPlugins(env, layers, projectDir, gitRoot, problems) {
+    const installed = await readJsonOrReport(env, join(env.claudeDir, "plugins", "installed_plugins.json"), problems);
+    if (!installed || !isRecord(installed.plugins))
         return [];
     const out = [];
-    for (const [id, installs] of Object.entries(installed.data.plugins)) {
+    for (const [id, installs] of Object.entries(installed.plugins)) {
         if (!Array.isArray(installs))
             continue;
         // A project or local install applies only in its own project; it beats a user install there.
@@ -41,6 +45,7 @@ export async function readPlugins(env, layers, projectDir, gitRoot) {
             enabled: true,
             note: "",
         };
+        const loaded = await loadPlugin(env, plugin, problems);
         const setting = HIGHEST_FIRST.flatMap((scope) => layers
             .filter((l) => l.scope === scope)
             .map((l) => l.data?.enabledPlugins)
@@ -53,12 +58,12 @@ export async function readPlugins(env, layers, projectDir, gitRoot) {
             plugin.note = `${plugin.enabled ? "Enabled" : "Turned off"} in ${setting.scope} settings`;
         }
         else {
-            plugin.enabled = (await manifest(env, plugin)).defaultEnabled !== false;
+            plugin.enabled = loaded.manifest.defaultEnabled !== false;
             plugin.note = plugin.enabled
                 ? "On by default (no enabledPlugins entry)"
                 : "Off by default (no enabledPlugins entry)";
         }
-        out.push(plugin);
+        out.push(loaded);
     }
     return out;
 }
@@ -69,13 +74,12 @@ async function inside(plugin, path) {
     return isWithin(root, await resolvedPath(target)) ? target : null;
 }
 /** The paths a manifest key names (one path or a list), inside the plugin; null when unset. */
-export async function manifestPaths(env, plugin, key) {
-    const value = (await manifest(env, plugin))[key];
-    const list = typeof value === "string" ? [value] : Array.isArray(value) ? value : null;
-    if (!list)
+export async function manifestPaths({ plugin, manifest }, key) {
+    const value = manifest[key];
+    if (typeof value !== "string" && !Array.isArray(value))
         return null;
     const out = [];
-    for (const item of list) {
+    for (const item of typeof value === "string" ? [value] : value) {
         if (typeof item !== "string")
             continue;
         const path = await inside(plugin, item);
@@ -84,25 +88,30 @@ export async function manifestPaths(env, plugin, key) {
     }
     return out;
 }
-/** The value of a manifest key that is a path, an inline object, or a list of either. */
-export async function manifestConfigs(env, plugin, key) {
-    const value = (await manifest(env, plugin))[key];
+/**
+ * The value of a manifest key that is a path, an inline object, or a list of either. A file it
+ * names that is there but does not parse goes into `problems`.
+ */
+export async function manifestConfigs(env, { plugin, manifest }, key, problems) {
+    const value = manifest[key];
+    if (value === undefined)
+        return [];
     const out = [];
-    for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
+    for (const item of Array.isArray(value) ? value : [value]) {
         if (isRecord(item))
             out.push({ value: item, path: manifestPath(plugin) });
         if (typeof item !== "string")
             continue;
         const path = await inside(plugin, item);
-        const file = path ? await readJsonObject(env, path) : null;
-        if (path && file?.ok)
-            out.push({ value: file.data[key] ?? file.data, path });
+        const file = path ? await readJsonOrReport(env, path, problems) : null;
+        if (path && file)
+            out.push({ value: file[key] ?? file, path });
     }
     return out;
 }
 /** The manifest's `commands` object form: command name to a file or inline content. */
-export async function manifestCommandMap(env, plugin) {
-    const value = (await manifest(env, plugin)).commands;
+export async function manifestCommandMap({ plugin, manifest, }) {
+    const value = manifest.commands;
     if (!isRecord(value))
         return [];
     const out = [];

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

@@ -0,0 +1,9 @@
+import { type MemoryStore, type ProjectSummary } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+interface KnownProject extends ProjectSummary {
+    /** The project's auto memory, read once for both the counts and the search catalog. */
+    store: MemoryStore | null;
+}
+/** Directories Claude Code has been used in: its project stores, `~/.claude.json`, and the launch directory. */
+export declare function listProjects(env: ScanEnv, claudeJson: Record<string, unknown> | null, launchDir: string): Promise<KnownProject[]>;
+export {};

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

@@ -1,17 +1,18 @@
-import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { storeDirName } from "../../shared/memory.js";
 import {} from "../../shared/types.js";
 import {} from "./env.js";
-import { isCredentials, isDir, isRecord, listDir } from "./files.js";
+import { isDir, listDir, openUnlessCredentials } from "./files.js";
+import { isRecord } from "./data.js";
 import { readMemoryStore } from "./memory.js";
 /** Directories Claude Code has been used in: its project stores, `~/.claude.json`, and the launch directory. */
 export async function listProjects(env, claudeJson, launchDir) {
     const byPath = new Map();
     const storesRoot = join(env.claudeDir, "projects");
-    const knownPaths = isRecord(claudeJson?.projects) ? Object.keys(claudeJson.projects) : [];
+    // Claude Code keys Windows folders with forward slashes; listed here as Windows writes them.
+    const knownPaths = (isRecord(claudeJson?.projects) ? Object.keys(claudeJson.projects) : []).map((key) => (env.platform === "win32" ? key.replaceAll("/", "\\") : key));
     for (const name of await listDir(storesRoot)) {
         const storeDir = join(storesRoot, name);
         if (!(await isDir(storeDir)))
@@ -73,9 +74,10 @@ async function newestFirst(dir, files) {
 /** The `cwd` recorded in the newest transcripts, for store names that do not map back cleanly. */
 async function sessionCwd(env, storeDir, sessions) {
     for (const { file } of sessions.slice(0, 3)) {
-        if (await isCredentials(env, join(storeDir, file)))
+        const handle = await openUnlessCredentials(env, join(storeDir, file)).catch(() => null);
+        if (!handle)
             continue;
-        const input = createReadStream(join(storeDir, file), { encoding: "utf8" });
+        const input = handle.createReadStream({ encoding: "utf8" });
         const lines = createInterface({ input });
         let read = 0;
         try {

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

@@ -0,0 +1,14 @@
+import { type Scope } from "../../shared/types.ts";
+/** A part of one file's `sandbox` value that Claude Code ignores, and why. */
+export interface Dropped {
+    value: unknown;
+    reason: string;
+}
+/**
+ * A filter for each file's `sandbox` value: what is left once the fields Claude Code ignores from
+ * that file are taken out, and what was taken out.
+ */
+export declare function sandboxFilter(valueIn: (key: string, scope: Scope) => unknown): (scope: Scope, value: unknown) => {
+    value: unknown;
+    dropped: Dropped[];
+};

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

@@ -1,5 +1,6 @@
 import {} from "../../shared/types.js";
-import { isRecord, stringsIn } from "./files.js";
+import { stringsIn } from "./files.js";
+import { isRecord } from "./data.js";
 const REPOSITORY = ["project", "local"];
 const NOT_MANAGED = ["user", "project", "local"];
 function at(value, path) {
@@ -35,13 +36,30 @@ function replaced(value, path, leaf) {
  */
 function rulesFor(valueIn) {
     const managed = valueIn("sandbox", "managed");
-    const user = valueIn("sandbox", "user");
-    const managedSays = (path, value) => at(managed, path.split(".")) === value;
     const rules = [];
-    const add = (fields, from, reason, drops) => {
-        for (const field of fields)
-            rules.push({ field, from, reason, ...(drops ? { drops } : {}) });
+    const managedFiles = at(managed, ["credentials", "files"]);
+    const lock = {
+        managed,
+        user: valueIn("sandbox", "user"),
+        valueIn,
+        managedSays: (path, value) => at(managed, path.split(".")) === value,
+        // docs: sandboxing#which-settings-can-disable-it
+        filesystemLocked: isRecord(at(managed, ["filesystem"])) ||
+            (Array.isArray(managedFiles) && managedFiles.some((f) => isRecord(f) && f.mode === "deny")),
+        add: (fields, from, reason, drops) => {
+            for (const field of fields)
+                rules.push({ field, from, reason, ...(drops ? { drops } : {}) });
+        },
     };
+    addScopeRules(lock);
+    addManagedLocks(lock);
+    addAdminRequiredRules(lock);
+    addLocksWithoutAdmin(lock);
+    addReadBlockRules(lock);
+    return rules;
+}
+/** Fields read from fewer files than the others, and entries dropped from repository files. */
+function addScopeRules({ add, filesystemLocked }) {
     // Keys read from fewer files (docs: settings-reference, each key's Scope).
     for (const field of [
         "filesystem.allowManagedReadPathsOnly",
@@ -60,14 +78,13 @@ function rulesFor(valueIn) {
         "network.tlsTerminate",
     ])
         add([field], REPOSITORY, `Claude Code reads sandbox.${field} only from user or managed settings`);
-    // docs: sandboxing#which-settings-can-disable-it
-    const managedFiles = at(managed, ["credentials", "files"]);
-    const filesystemLocked = isRecord(at(managed, ["filesystem"])) ||
-        (Array.isArray(managedFiles) && managedFiles.some((f) => isRecord(f) && f.mode === "deny"));
     add(["filesystem.disabled"], filesystemLocked ? NOT_MANAGED : REPOSITORY, filesystemLocked
         ? "Managed settings configure the sandbox filesystem, so only they can turn it off"
         : "Claude Code reads sandbox.filesystem.disabled only from user or managed settings");
     add(["credentials.files", "credentials.envVars"], REPOSITORY, "Claude Code drops mask entries from repository settings", { entries: (e) => isRecord(e) && e.mode === "mask" });
+}
+/** A false allowUnsandboxedCommands that holds, and the managed-only allowlists. */
+function addManagedLocks({ add, user, managedSays }) {
     // docs: sandboxing#turn-off-the-retry-with-strict-sandbox-mode
     if (managedSays("allowUnsandboxedCommands", false) ||
         at(user, ["allowUnsandboxedCommands"]) === false)
@@ -75,33 +92,37 @@ function rulesFor(valueIn) {
     // Managed-only locks (docs: sandboxing#keep-developers-from-widening-the-policy).
     if (managedSays("filesystem.allowManagedReadPathsOnly", true))
         add(["filesystem.allowRead"], NOT_MANAGED, "Managed settings honor only their own allowRead entries (allowManagedReadPathsOnly)");
-    const domainsLocked = managedSays("network.allowManagedDomainsOnly", true);
-    if (domainsLocked)
+    if (managedSays("network.allowManagedDomainsOnly", true))
         add(["network.allowedDomains", "network.httpProxyPort", "network.socksProxyPort"], NOT_MANAGED, "Managed settings honor only their own domains and proxy ports (allowManagedDomainsOnly)");
-    // docs: sandboxing#repository-settings-under-an-admin-required-sandbox
-    if (managedSays("allowUnsandboxedCommands", false) || domainsLocked) {
-        const reason = "Managed settings require the sandbox, so Claude Code ignores repository settings that loosen it";
-        add([
-            "excludedCommands",
-            "ignoreViolations",
-            "network.allowedDomains",
-            "network.allowUnixSockets",
-            "network.allowMachLookup",
-            "network.httpProxyPort",
-            "network.socksProxyPort",
-            "filesystem.allowWrite",
-        ], REPOSITORY, reason);
-        add([
-            "enableWeakerNestedSandbox",
-            "enableWeakerNetworkIsolation",
-            "network.allowAllUnixSockets",
-            "network.allowLocalBinding",
-        ], REPOSITORY, reason, { value: true });
-        for (const field of ["enabled", "failIfUnavailable"])
-            if (at(user, [field]) === true)
-                add([field], REPOSITORY, reason, { value: false });
-    }
-    // docs: sandboxing#locks-that-apply-without-an-admin-required-sandbox
+}
+/** docs: sandboxing#repository-settings-under-an-admin-required-sandbox */
+function addAdminRequiredRules({ add, user, managedSays }) {
+    if (!managedSays("allowUnsandboxedCommands", false) &&
+        !managedSays("network.allowManagedDomainsOnly", true))
+        return;
+    const reason = "Managed settings require the sandbox, so Claude Code ignores repository settings that loosen it";
+    add([
+        "excludedCommands",
+        "ignoreViolations",
+        "network.allowedDomains",
+        "network.allowUnixSockets",
+        "network.allowMachLookup",
+        "network.httpProxyPort",
+        "network.socksProxyPort",
+        "filesystem.allowWrite",
+    ], REPOSITORY, reason);
+    add([
+        "enableWeakerNestedSandbox",
+        "enableWeakerNetworkIsolation",
+        "network.allowAllUnixSockets",
+        "network.allowLocalBinding",
+    ], REPOSITORY, reason, { value: true });
+    for (const field of ["enabled", "failIfUnavailable"])
+        if (at(user, [field]) === true)
+            add([field], REPOSITORY, reason, { value: false });
+}
+/** docs: sandboxing#locks-that-apply-without-an-admin-required-sandbox */
+function addLocksWithoutAdmin({ add, managed, user, valueIn }) {
     const managedDeny = stringsIn(at(valueIn("permissions", "managed"), ["deny"]));
     if (stringsIn(at(managed, ["network", "deniedDomains"])).length > 0 ||
         managedDeny.some((rule) => rule.startsWith("WebFetch(domain:")))
@@ -109,16 +130,38 @@ function rulesFor(valueIn) {
     const strictAllowlist = at(managed, ["network", "strictAllowlist"]) ?? at(user, ["network", "strictAllowlist"]);
     if (strictAllowlist === true)
         add(["network.allowedDomains", "network.httpProxyPort", "network.socksProxyPort"], REPOSITORY, "strictAllowlist is on, so Claude Code ignores a repository's domains and proxy ports");
-    // While the block covers sandboxed commands, repository allowRead and allowWrite entries do not
-    // count; it does not when filesystem isolation is off or allowManagedReadPathsOnly is set
-    // (docs: settings-reference#sandboxed-commands-under-the-block).
+}
+/**
+ * While the block covers sandboxed commands, repository allowRead and allowWrite entries do not
+ * count; it does not when filesystem isolation is off or allowManagedReadPathsOnly is set
+ * (docs: settings-reference#sandboxed-commands-under-the-block).
+ */
+function addReadBlockRules({ add, managed, user, valueIn, managedSays, filesystemLocked, }) {
     const blocked = ["user", "project", "local", "managed"].some((s) => at(valueIn("permissions", s), ["blockReadsOutsideWorkingDirectories"]) === true);
     const filesystemOff = (filesystemLocked ? [managed] : [managed, user])
         .map((v) => at(v, ["filesystem", "disabled"]))
         .find((v) => v !== undefined) === true;
     if (blocked && !filesystemOff && !managedSays("filesystem.allowManagedReadPathsOnly", true))
         add(["filesystem.allowRead", "filesystem.allowWrite"], REPOSITORY, "blockReadsOutsideWorkingDirectories is on, so repository allowRead and allowWrite entries do not count");
-    return rules;
+}
+/**
+ * What a rule takes out of a field's value and what it leaves, undefined for nothing; null when the
+ * rule does not apply to it.
+ */
+function splitField(rule, field) {
+    if (field === undefined)
+        return null;
+    const { drops } = rule;
+    if (!drops)
+        return { removed: field, kept: undefined };
+    if ("value" in drops)
+        return field === drops.value ? { removed: field, kept: undefined } : null;
+    if (!Array.isArray(field))
+        return null;
+    const entries = field.filter(drops.entries);
+    if (entries.length === 0)
+        return null;
+    return { removed: entries, kept: field.filter((e) => !drops.entries(e)) };
 }
 /**
  * A filter for each file's `sandbox` value: what is left once the fields Claude Code ignores from
@@ -135,26 +178,11 @@ export function sandboxFilter(valueIn) {
             if (!rule.from.includes(scope))
                 continue;
             const path = rule.field.split(".");
-            const field = at(out, path);
-            if (field === undefined)
+            const split = splitField(rule, at(out, path));
+            if (!split)
                 continue;
-            const drops = rule.drops;
-            let removed = field;
-            let kept;
-            if (drops && "value" in drops) {
-                if (field !== drops.value)
-                    continue;
-            }
-            else if (drops) {
-                if (!Array.isArray(field))
-                    continue;
-                removed = field.filter(drops.entries);
-                if (removed.length === 0)
-                    continue;
-                kept = field.filter((e) => !drops.entries(e));
-            }
-            out = replaced(out, path, kept);
-            dropped.push({ value: nested(path, removed), reason: rule.reason });
+            out = replaced(out, path, split.kept);
+            dropped.push({ value: nested(path, split.removed), reason: rule.reason });
         }
         return { value: out, dropped };
     };

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

@@ -0,0 +1,37 @@
+import { type EffectiveSetting, type Scope, type SettingsLayer } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+/**
+ * Why Claude Code ignores a `permissions.defaultMode` from this file, or undefined when it may apply:
+ * a repository's settings cannot start sessions in auto or bypass mode (docs: permission-modes).
+ */
+export declare function ignoredModeReason(scope: Scope, mode: unknown): string | undefined;
+export interface SettingsFile {
+    scope: Scope;
+    path: string;
+    legacy?: boolean;
+}
+/** The settings files Claude Code reads in `dir`, highest precedence first. */
+export declare function settingsFiles(env: ScanEnv, dir: string): Promise<SettingsFile[]>;
+/**
+ * Settings files that apply in `dir`, highest precedence first. `managed` is what
+ * readManagedSettings read, so a scan reads the managed files once.
+ */
+export declare function readSettingsLayers(env: ScanEnv, dir: string, managed: ManagedSettings): Promise<SettingsLayer[]>;
+export interface ManagedSettings {
+    data: Record<string, unknown> | null;
+    sources: string[];
+    dropIns: string[];
+    /** Managed sources ccdesk does not read that rank above the files (higherSources). */
+    higher: string[];
+    errors: string[];
+    /** A managed file that is there but not a JSON object: Claude Code refuses to start (docs: managed-settings#find-entries-claude-code-dropped). */
+    blocksStart: boolean;
+}
+/**
+ * managed-settings.json, then every *.json in managed-settings.d in alphabetical order, merged, with
+ * nothing hidden: for checks such as managedMcpServers that must see header values. Never sent to the
+ * page as is.
+ */
+export declare function readManagedSettings(env: ScanEnv): Promise<ManagedSettings>;
+/** The value Claude Code ends up with for each top-level key, and where it came from. */
+export declare function effectiveSettings(layers: SettingsLayer[]): EffectiveSetting[];