ccdesk 0.2.1 → 0.2.3

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

@@ -0,0 +1,38 @@
+import { type EffectiveSetting, type Entry, type Inventory, type Problem, type Scope, type SessionProfile, type SettingsLayer, type Trust } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+type Source = Scope | "plugin";
+interface ReadOptions {
+    plugin?: string | undefined;
+    /** Joins the folders of a file in a subfolder into its name; commands use ":". */
+    separator?: string;
+    /** Receives files that are there but cannot be read. */
+    problems?: Problem[] | undefined;
+}
+export declare function readSkill(env: ScanEnv, folder: string, scope: Source, { plugin, problems }?: ReadOptions): Promise<Entry | null>;
+interface InventoryInput {
+    env: ScanEnv;
+    projectDir: string;
+    /** The repository (or worktree) root, where the search for project skills stops. */
+    gitRoot: string | null;
+    layers: SettingsLayer[];
+    effective: EffectiveSetting[];
+    /** Managed settings as written, nothing hidden: for checks that must see header values. */
+    managed: Record<string, unknown> | null;
+    claudeJson: Record<string, unknown> | null;
+    trust: Trust;
+    profile: SessionProfile;
+    /** Receives files that are there but cannot be read or parsed. */
+    problems: Problem[];
+}
+/**
+ * What Claude Code requires of a subagent file; it skips one that falls short, and treats one
+ * without a name as documentation (docs: sub-agents#subagent-files-claude-code-skips).
+ */
+export declare function agentProblems(text: string): string[];
+/**
+ * Applies skillOverrides to your skills and command files; plugin skills are not affected
+ * (docs: skills#override-skill-visibility-from-settings).
+ */
+export declare function applySkillOverrides(entries: Entry[], overrides: unknown): void;
+export declare function readInventory(input: InventoryInput): Promise<Inventory>;
+export {};

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

@@ -1,12 +1,13 @@
 import { basename, dirname, join, relative } from "node:path";
 import { HIGHEST_FIRST } from "../../shared/scopes.js";
 import {} from "../../shared/types.js";
+import { redactSecrets, shownUrl } from "../secrets.js";
 import {} from "./env.js";
-import { isDir, isFile, isRecord, isWithin, listDir, parseFrontmatter, readJsonObject, readTextFile, redactSecrets, resolvedPath, shownUrl, stringField, toStringList, } from "./files.js";
+import { isDir, isFile, isWithin, listDir, readJsonOrReport, readTextFile, resolvedPath, stringField, toStringList, } from "./files.js";
+import { isRecord, parseFrontmatter } from "./data.js";
 import { ancestorsRootFirst } from "./instructions.js";
 import { readMcpServers } from "./mcp.js";
 import { manifestCommandMap, manifestConfigs, manifestPaths, pluginNamespace, readPlugins, } from "./plugins.js";
-import { effectiveSettings } from "./settings.js";
 function isTrue(value) {
     return value === true || (typeof value === "string" && /^(true|yes|on|1)$/i.test(value));
 }
@@ -14,8 +15,8 @@ function isTrue(value) {
  * A `.md` file as an agent, command or output style. `fileName` is its name from its path, which a
  * frontmatter `name` replaces, except for a command (docs: skills#how-a-skill-gets-its-command-name).
  */
-async function readEntry(env, path, fileName, scope, { plugin, isCommand = false } = {}) {
-    const file = await readTextFile(env, path);
+async function readEntry(env, path, fileName, scope, { plugin, isCommand = false, problems } = {}) {
+    const file = await readTextFile(env, path, problems);
     if (!file)
         return null;
     const { data } = parseFrontmatter(file.text);
@@ -40,7 +41,7 @@ async function readEntry(env, path, fileName, scope, { plugin, isCommand = false
  * `*.md` files in a folder and its subfolders. A file in a subfolder is named by its path, joined
  * with `separator`: commands use ":" (`frontend/component.md` is `/frontend:component`).
  */
-async function readFileEntries(env, dir, scope, { plugin, separator = "/" } = {}, base = dir, depth = 0) {
+async function readFileEntries(env, dir, scope, options = {}, base = dir, depth = 0) {
     const out = [];
     for (const name of await listDir(dir)) {
         if (name.startsWith("."))
@@ -48,16 +49,18 @@ async function readFileEntries(env, dir, scope, { plugin, separator = "/" } = {}
         const path = join(dir, name);
         if (await isDir(path)) {
             if (depth < 4)
-                out.push(...(await readFileEntries(env, path, scope, { plugin, separator }, base, depth + 1)));
+                out.push(...(await readFileEntries(env, path, scope, options, base, depth + 1)));
             continue;
         }
         if (!name.endsWith(".md"))
             continue;
+        const separator = options.separator ?? "/";
         const fileName = relative(base, path).replace(/\.md$/, "").split(/[/\\]/).join(separator);
         // Commands are the entries joined with ":".
         const entry = await readEntry(env, path, fileName, scope, {
-            plugin,
+            plugin: options.plugin,
             isCommand: separator === ":",
+            problems: options.problems,
         });
         if (entry)
             out.push(entry);
@@ -74,6 +77,7 @@ async function readPaths(env, paths, scope, options) {
             const entry = await readEntry(env, path, basename(path, ".md"), scope, {
                 plugin: options.plugin,
                 isCommand: options.separator === ":",
+                problems: options.problems,
             });
             if (entry)
                 out.push(entry);
@@ -81,9 +85,9 @@ async function readPaths(env, paths, scope, options) {
     }
     return out;
 }
-export async function readSkill(env, folder, scope, plugin) {
+export async function readSkill(env, folder, scope, { plugin, problems } = {}) {
     const path = join(folder, "SKILL.md");
-    const file = await readTextFile(env, path);
+    const file = await readTextFile(env, path, problems);
     if (!file)
         return null;
     const { data, body } = parseFrontmatter(file.text);
@@ -115,87 +119,104 @@ export async function readSkill(env, folder, scope, plugin) {
     return entry;
 }
 /** `<name>/SKILL.md` folders, or one folder holding SKILL.md itself. */
-async function readSkills(env, dir, scope, plugin) {
-    if (plugin && (await isFile(join(dir, "SKILL.md")))) {
-        const skill = await readSkill(env, dir, scope, plugin);
+async function readSkills(env, dir, scope, options) {
+    if (options.plugin && (await isFile(join(dir, "SKILL.md")))) {
+        const skill = await readSkill(env, dir, scope, options);
         return skill ? [skill] : [];
     }
     const out = [];
     for (const name of await listDir(dir)) {
         if (name.startsWith(".") || (scope === "user" && name === "synced"))
             continue;
-        const skill = await readSkill(env, join(dir, name), scope, plugin);
+        const skill = await readSkill(env, join(dir, name), scope, options);
         if (skill)
             out.push(skill);
     }
     return out;
 }
 /** A plugin's skills, agents, commands and output styles, from its folders and its manifest. */
-async function pluginEntries(env, plugin) {
-    const root = plugin.installPath;
-    const options = { plugin: plugin.id };
+async function pluginEntries(env, loaded, problems) {
+    const root = loaded.plugin.installPath;
+    const options = { plugin: loaded.plugin.id, problems };
+    const namespace = pluginNamespace(loaded);
+    const listed = async (key, folder, separator = "/") => readPaths(env, (await manifestPaths(loaded, key)) ?? [join(root, folder)], "plugin", {
+        ...options,
+        separator,
+    });
+    const skills = await pluginSkills(env, loaded, problems);
+    const commands = [
+        ...(await listed("commands", "commands", ":")),
+        ...(await manifestCommands(env, loaded, problems)),
+    ];
+    // A plugin's skills and commands are called as plugin-name:name; a name that already has the
+    // prefix keeps it once (docs: skills#how-a-skill-gets-its-command-name).
+    for (const entry of [...skills, ...commands])
+        entry.id = entry.name.startsWith(`${namespace}:`) ? entry.name : `${namespace}:${entry.name}`;
+    return {
+        skills,
+        agents: await pluginAgents(env, loaded, problems),
+        commands,
+        outputStyles: await listed("outputStyles", "output-styles"),
+    };
+}
+/** A plugin's skills: its skills folder, the manifest's extra ones, or a SKILL.md at its root. */
+async function pluginSkills(env, loaded, problems) {
+    const root = loaded.plugin.installPath;
+    const options = { plugin: loaded.plugin.id, problems };
     // `skills` adds to the default folder; the other keys replace theirs (docs: plugins-reference).
-    const extraSkills = await manifestPaths(env, plugin, "skills");
+    const extraSkills = await manifestPaths(loaded, "skills");
     const skillDirs = [join(root, "skills"), ...(extraSkills ?? [])];
     const rootSkill = extraSkills === null && !(await isDir(join(root, "skills")));
-    const namespace = await pluginNamespace(env, plugin);
     const skills = [];
     if (rootSkill)
-        for (const skill of await readSkills(env, root, "plugin", plugin.id)) {
+        for (const skill of await readSkills(env, root, "plugin", options)) {
             // Without a name, a root SKILL.md is named after the plugin (docs: skills#how-a-skill-gets-its-command-name).
             if (skill.folder === root && !stringField(parseFrontmatter(skill.text).data, "name"))
-                skill.name = namespace;
+                skill.name = pluginNamespace(loaded);
             skills.push(skill);
         }
     for (const dir of skillDirs)
-        skills.push(...(await readSkills(env, dir, "plugin", plugin.id)));
-    const listed = async (key, folder, separator = "/") => readPaths(env, (await manifestPaths(env, plugin, key)) ?? [join(root, folder)], "plugin", {
-        ...options,
-        separator,
-    });
-    const commands = await listed("commands", "commands", ":");
-    for (const c of await manifestCommandMap(env, plugin))
-        commands.push(c.text === null
-            ? ((await readEntry(env, c.path, c.name, "plugin", {
-                plugin: plugin.id,
-                isCommand: true,
-            })) ?? {
-                name: c.name,
-                description: c.description,
-                path: c.path,
-                scope: "plugin",
-                plugin: plugin.id,
-                text: "",
-            })
-            : {
-                name: c.name,
-                description: c.description,
-                path: c.path,
-                scope: "plugin",
-                plugin: plugin.id,
-                text: c.text,
-            });
-    // A plugin's skills and commands are called as plugin-name:name; a name that already has the
-    // prefix keeps it once (docs: skills#how-a-skill-gets-its-command-name).
-    for (const entry of [...skills, ...commands])
-        entry.id = entry.name.startsWith(`${namespace}:`) ? entry.name : `${namespace}:${entry.name}`;
-    // A plugin subagent is named with the plugin and its subfolders (docs: sub-agents#choose-the-subagent-scope).
+        skills.push(...(await readSkills(env, dir, "plugin", options)));
+    return skills;
+}
+/** The commands a plugin's manifest names with their own file or text. */
+async function manifestCommands(env, loaded, problems) {
+    const plugin = loaded.plugin.id;
+    const commands = [];
+    for (const c of await manifestCommandMap(loaded)) {
+        const listed = {
+            name: c.name,
+            description: c.description,
+            path: c.path,
+            scope: "plugin",
+            plugin,
+            text: c.text ?? "",
+        };
+        const read = c.text === null
+            ? await readEntry(env, c.path, c.name, "plugin", { plugin, problems, isCommand: true })
+            : null;
+        commands.push(read ?? listed);
+    }
+    return commands;
+}
+/** A plugin's subagents, named with the plugin and its subfolders (docs: sub-agents#choose-the-subagent-scope). */
+async function pluginAgents(env, loaded, problems) {
+    const root = loaded.plugin.installPath;
+    const namespace = pluginNamespace(loaded);
     const agents = [];
-    for (const path of (await manifestPaths(env, plugin, "agents")) ?? [join(root, "agents")]) {
+    for (const path of (await manifestPaths(loaded, "agents")) ?? [join(root, "agents")]) {
         const folder = (await isDir(path)) ? path : null;
-        for (const agent of await readPaths(env, [path], "plugin", options)) {
+        for (const agent of await readPaths(env, [path], "plugin", {
+            plugin: loaded.plugin.id,
+            problems,
+        })) {
             const subfolders = folder ? relative(folder, dirname(agent.path)).split(/[/\\]/) : [];
             const own = agent.name.split("/").at(-1) ?? agent.name;
             agent.id = [namespace, ...subfolders.filter(Boolean), own].join(":");
             agents.push(agent);
         }
     }
-    return {
-        skills,
-        agents,
-        commands,
-        outputStyles: await listed("outputStyles", "output-styles"),
-    };
+    return agents;
 }
 /**
  * The `.claude/<sub>` folders of the start directory and every parent up to the repository root
@@ -229,7 +250,7 @@ export function agentProblems(text) {
  * yours. A name defined again lower down is marked as shadowed (docs: sub-agents#choose-the-subagent-scope).
  * A file Claude Code skips takes no part in that.
  */
-async function readAgents(env, projectDir, gitRoot) {
+async function readAgents(env, projectDir, gitRoot, problems) {
     const sources = [
         [join(env.managedDir, ".claude", "agents"), "managed"],
         ...projectFolders(env, projectDir, gitRoot, "agents")
@@ -240,7 +261,7 @@ async function readAgents(env, projectDir, gitRoot) {
     const agents = [];
     const winners = new Map();
     for (const [dir, scope] of sources)
-        for (const agent of await readFileEntries(env, dir, scope)) {
+        for (const agent of await readFileEntries(env, dir, scope, { problems })) {
             const [problem] = agentProblems(agent.text);
             if (problem) {
                 agent.skipped = problem;
@@ -261,7 +282,7 @@ async function readAgents(env, projectDir, gitRoot) {
  * repository root (the closest wins) and yours (docs: output-styles#create-a-custom-output-style).
  * The docs order only the project folders; managed, project, then yours follows subagents.
  */
-async function readOutputStyles(env, projectDir, gitRoot) {
+async function readOutputStyles(env, projectDir, gitRoot, problems) {
     const sources = [
         [join(env.managedDir, ".claude", "output-styles"), "managed"],
         ...projectFolders(env, projectDir, gitRoot, "output-styles")
@@ -271,7 +292,7 @@ async function readOutputStyles(env, projectDir, gitRoot) {
     ];
     const styles = [];
     for (const [dir, scope] of sources)
-        styles.push(...(await readFileEntries(env, dir, scope)));
+        styles.push(...(await readFileEntries(env, dir, scope, { problems })));
     return styles;
 }
 /**
@@ -293,16 +314,16 @@ export function applySkillOverrides(entries, overrides) {
     }
 }
 export async function readInventory(input) {
-    const { env, projectDir, gitRoot, layers } = input;
-    const plugins = await readPlugins(env, layers, projectDir, gitRoot);
-    const active = plugins.filter((p) => p.enabled);
-    const fromPlugins = await Promise.all(active.map((plugin) => pluginEntries(env, plugin)));
+    const { env, projectDir, gitRoot, layers, problems } = input;
+    const plugins = await readPlugins(env, layers, projectDir, gitRoot, problems);
+    const active = plugins.filter((p) => p.plugin.enabled);
+    const fromPlugins = await Promise.all(active.map((plugin) => pluginEntries(env, plugin, problems)));
     const projectClaude = join(projectDir, ".claude");
     const hasProjectDir = projectClaude !== env.claudeDir;
     const files = async (sub, separator = "/") => [
-        ...(await readFileEntries(env, join(env.claudeDir, sub), "user", { separator })),
+        ...(await readFileEntries(env, join(env.claudeDir, sub), "user", { separator, problems })),
         ...(hasProjectDir
-            ? await readFileEntries(env, join(projectClaude, sub), "project", { separator })
+            ? await readFileEntries(env, join(projectClaude, sub), "project", { separator, problems })
             : []),
     ];
     // Project skills come from the start directory and every parent up to the repository root.
@@ -323,7 +344,7 @@ export async function readInventory(input) {
     // (docs: skills#resolve-skills-that-share-a-name).
     const winners = new Map();
     for (const [dir, scope] of skillDirs) {
-        for (const skill of await readSkills(env, dir, scope)) {
+        for (const skill of await readSkills(env, dir, scope, { problems })) {
             // A folder that several locations link to loads once.
             const real = skill.realPath ?? skill.folder ?? skill.path;
             if (seenFolders.has(real))
@@ -347,36 +368,38 @@ export async function readInventory(input) {
         if (skill)
             command.shadowedBy = skill.path;
     }
-    const overrides = effectiveSettings(layers).find((s) => s.key === "skillOverrides")?.value;
+    const overrides = input.effective.find((s) => s.key === "skillOverrides")?.value;
     applySkillOverrides([...skills, ...commands], overrides);
     return {
         agents: [
-            ...(await readAgents(env, projectDir, gitRoot)),
+            ...(await readAgents(env, projectDir, gitRoot, problems)),
             ...fromPlugins.flatMap((p) => p.agents),
         ],
         skills: [...skills, ...fromPlugins.flatMap((p) => p.skills)],
         commands: [...commands, ...fromPlugins.flatMap((p) => p.commands)],
         outputStyles: [
-            ...(await readOutputStyles(env, projectDir, gitRoot)),
+            ...(await readOutputStyles(env, projectDir, gitRoot, problems)),
             ...fromPlugins.flatMap((p) => p.outputStyles),
         ],
-        hooks: await readHooks(env, layers, active, input.trust, input.profile),
+        hooks: await readHooks(input, active),
         mcpServers: await readMcpServers(input, active),
-        plugins,
+        plugins: plugins.map((p) => p.plugin),
     };
 }
-async function readHooks(env, layers, plugins, trust, profile) {
+async function readHooks(input, plugins) {
+    const { env, layers, trust, profile, problems } = input;
     const out = [];
     for (const layer of layers) {
         if (layer.data)
             out.push(...hooksFrom(layer.data.hooks, layer.scope, layer.path));
     }
-    for (const plugin of plugins) {
+    for (const loaded of plugins) {
+        const { plugin } = loaded;
         const path = join(plugin.installPath, "hooks", "hooks.json");
-        const file = await readJsonObject(env, path);
-        if (file.ok)
-            out.push(...hooksFrom(file.data.hooks, "plugin", path, plugin));
-        for (const part of await manifestConfigs(env, plugin, "hooks"))
+        const file = await readJsonOrReport(env, path, problems);
+        if (file)
+            out.push(...hooksFrom(file.hooks, "plugin", path, plugin));
+        for (const part of await manifestConfigs(env, loaded, "hooks", problems))
             out.push(...hooksFrom(part.value, "plugin", part.path, plugin));
     }
     // docs: hooks#disable-or-remove-hooks, settings-reference#allowmanagedhooksonly
@@ -387,7 +410,7 @@ async function readHooks(env, layers, plugins, trust, profile) {
         .flatMap((scope) => layers.filter((l) => l.scope === scope))
         .find((l) => typeof l.data?.disableAllHooks === "boolean")?.data?.disableAllHooks === true;
     const managedOnly = managed?.allowManagedHooksOnly === true;
-    const forcedByManaged = new Set(plugins.filter((p) => p.enabledIn === "managed").map((p) => p.id));
+    const forcedByManaged = new Set(plugins.filter((p) => p.plugin.enabledIn === "managed").map((p) => p.plugin.id));
     // An interactive session holds back hooks from every settings file, managed and yours included,
     // until the folder or a parent covering it is trusted; -p and the SDK do not (docs:
     // hooks#workspace-trust, permissions#what-runs-before-you-trust-a-folder). The docs say nothing
@@ -417,36 +440,32 @@ async function readHooks(env, layers, plugins, trust, profile) {
 function hooksFrom(config, source, sourcePath, plugin) {
     if (!isRecord(config))
         return [];
-    const out = [];
-    for (const [event, groups] of Object.entries(config)) {
-        if (!Array.isArray(groups))
-            continue;
-        for (const [g, group] of groups.entries()) {
-            if (!isRecord(group) || !Array.isArray(group.hooks))
-                continue;
-            for (const [index, h] of group.hooks.entries()) {
-                if (!isRecord(h))
-                    continue;
-                const entry = {
-                    event,
-                    type: stringField(h, "type") || "command",
-                    command: stringField(h, "command") ||
-                        stringField(h, "prompt") ||
-                        shownUrl(stringField(h, "url")),
-                    source,
-                    sourcePath,
-                    active: true,
-                    at: { group: g, index },
-                    definition: redactSecrets(h),
-                };
-                const matcher = stringField(group, "matcher");
-                if (matcher)
-                    entry.matcher = matcher;
-                if (plugin)
-                    entry.plugin = plugin.id;
-                out.push(entry);
-            }
-        }
-    }
-    return out;
+    return Object.entries(config).flatMap(([event, groups]) => Array.isArray(groups)
+        ? groups.flatMap((group, g) => groupHooks(event, g, group, source, sourcePath, plugin))
+        : []);
+}
+/** The hooks of one matcher group, each with where it sits so an edit can find it again. */
+function groupHooks(event, g, group, source, sourcePath, plugin) {
+    if (!isRecord(group) || !Array.isArray(group.hooks))
+        return [];
+    const matcher = stringField(group, "matcher");
+    return group.hooks.flatMap((h, index) => {
+        if (!isRecord(h))
+            return [];
+        const entry = {
+            event,
+            type: stringField(h, "type") || "command",
+            command: stringField(h, "command") || stringField(h, "prompt") || shownUrl(stringField(h, "url")),
+            source,
+            sourcePath,
+            active: true,
+            at: { group: g, index },
+            definition: redactSecrets(h),
+        };
+        if (matcher)
+            entry.matcher = matcher;
+        if (plugin)
+            entry.plugin = plugin.id;
+        return [entry];
+    });
 }

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

@@ -0,0 +1,28 @@
+import { type McpServer, type Problem, type SessionProfile, type SettingsLayer, type Trust } from "../../shared/types.ts";
+import { type ScanEnv } from "./env.ts";
+import { type LoadedPlugin } from "./plugins.ts";
+/**
+ * What makes a server definition one Claude Code cannot start: a missing command or url, a type it
+ * does not know, or a field the docs define holding the wrong kind of value (docs: mcp). It checks
+ * the rest when it starts the server.
+ */
+export declare function serverProblems(definition: unknown): string[];
+interface Input {
+    env: ScanEnv;
+    projectDir: string;
+    layers: SettingsLayer[];
+    /** Managed settings as written, nothing hidden. */
+    managed: Record<string, unknown> | null;
+    claudeJson: Record<string, unknown> | null;
+    trust: Trust;
+    profile: SessionProfile;
+    /** Receives MCP files that are there but do not parse. */
+    problems: Problem[];
+}
+/**
+ * Every MCP server definition, each marked with whether Claude Code would start it here
+ * (docs: mcp#scope-hierarchy-and-precedence, managed-mcp). ccdesk never connects, so an active
+ * server is one that is configured and allowed, not one that is known to work.
+ */
+export declare function readMcpServers(input: Input, plugins: LoadedPlugin[]): Promise<McpServer[]>;
+export {};