ccdesk 0.0.0-stage → 0.1.0

package/dist/server/scan/mcp.js

@@ -0,0 +1,255 @@
+import { join } from "node:path";
+import {} from "../../shared/types.js";
+import {} from "./env.js";
+import { isRecord, readJsonObject, shownUrl, stringField, stringsIn, wildcard } from "./files.js";
+import { manifestConfigs } from "./plugins.js";
+import { readManagedSettings } from "./settings.js";
+function define(servers, scope, sourcePath, organisation = false) {
+    if (!isRecord(servers))
+        return [];
+    return Object.entries(servers)
+        .filter(([, config]) => isRecord(config))
+        .map(([name, config]) => {
+        const c = config;
+        const type = stringField(c, "type");
+        const url = stringField(c, "url") || null;
+        const command = stringField(c, "command")
+            ? [stringField(c, "command"), ...stringsIn(c.args)]
+            : null;
+        const server = {
+            name,
+            scope,
+            // An entry without a type is read as stdio, even one with a url (docs: mcp).
+            transport: type || "stdio",
+            target: url ? shownUrl(url) : (command?.join(" ") ?? ""),
+            sourcePath,
+            status: "active",
+        };
+        if (!type && url) {
+            server.status = "invalid";
+            server.note =
+                'Has a url but no "type", so Claude Code reads it as a stdio server and it fails';
+        }
+        // A ${VAR} in an organisation entry means it still has to pass the allowlist.
+        const usesVariables = JSON.stringify(c).includes("${");
+        return {
+            server,
+            command: type && type !== "stdio" ? null : command,
+            url: type ? url : null,
+            organisation: organisation && !usesVariables,
+        };
+    });
+}
+/** Control and invisible formatting characters, such as zero-width spaces and bidi overrides. */
+const INVISIBLE = /[\p{Cc}\p{Cf}]/u;
+/** Every key and string value in a JSON value, the entry's name included by the caller. */
+function textsIn(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(textsIn);
+    if (!isRecord(value))
+        return [];
+    return Object.entries(value).flatMap(([key, inner]) => [key, ...textsIn(inner)]);
+}
+/**
+ * Why Claude Code drops a managedMcpServers entry, or null when it loads it
+ * (docs: managed-mcp#what-an-entry-can-contain). `config` is the entry as written, headers included.
+ */
+function managedEntryProblem(name, config) {
+    if (!isRecord(config))
+        return "Not an object";
+    const type = stringField(config, "type");
+    if (!["http", "sse", "streamable-http"].includes(type))
+        return "managedMcpServers entries must be http or sse servers";
+    if (!stringField(config, "url").startsWith("https://"))
+        return "managedMcpServers entries need an https:// URL";
+    const member = ["command", "args", "env", "headersHelper"].find((key) => key in config);
+    if (member)
+        return `managedMcpServers entries may not have "${member}"`;
+    if (JSON.stringify(config).includes("${"))
+        return "managedMcpServers entries may not use environment variable references";
+    if (!/^[\w-]+$/.test(name))
+        return "A managedMcpServers name may hold only letters, numbers, hyphens and underscores";
+    if (textsIn(config).some((text) => INVISIBLE.test(text)))
+        return "managedMcpServers entries may not contain control or invisible characters";
+    return null;
+}
+/** managedMcpServers from managed settings, with entries Claude Code drops marked invalid. */
+function defineManaged(servers, sourcePath) {
+    const defined = define(servers, "managed", sourcePath, true);
+    for (const d of defined) {
+        const problem = managedEntryProblem(d.server.name, servers[d.server.name]);
+        if (problem) {
+            d.server.status = "invalid";
+            d.server.note = problem;
+        }
+    }
+    return defined;
+}
+/** Two URLs are one endpoint when they differ only in scheme or host case, a default port or a trailing slash. */
+export function endpoint(d) {
+    if (d.command)
+        return `command:${JSON.stringify(d.command)}`;
+    if (!d.url)
+        return `none:${d.server.name}`;
+    try {
+        const u = new URL(d.url);
+        const path = u.pathname.replace(/\/$/, "");
+        const user = u.username ? `${u.username}${u.password ? `:${u.password}` : ""}@` : "";
+        return `url:${u.protocol}//${user}${u.host}${path}${u.search}`;
+    }
+    catch {
+        return `url:${d.url}`;
+    }
+}
+function policyEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((e) => isRecord(e) &&
+        (typeof e.serverName === "string" ||
+            (Array.isArray(e.serverCommand) && e.serverCommand.every((p) => typeof p === "string")) ||
+            typeof e.serverUrl === "string"));
+}
+/** A `serverUrl` pattern (docs: managed-mcp#how-serverurl-entries-match). */
+function urlMatches(pattern, url) {
+    const p = /^([^:/]+):\/\/([^/:]+)(?::([^/]*))?(\/.*)?$/.exec(pattern);
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (!p)
+        return false;
+    const [, scheme = "", host = "", port, path] = p;
+    const scheme_ = u.protocol.slice(0, -1);
+    if (!wildcard(scheme).test(scheme_))
+        return false;
+    if (!wildcard(host.replace(/\.$/, ""), "i").test(u.hostname.replace(/\.$/, "")))
+        return false;
+    const actualPort = u.port || (scheme_ === "https" ? "443" : scheme_ === "http" ? "80" : "");
+    // No port: a full hostname means the default port only, a wildcard hostname any port.
+    if (port !== undefined) {
+        if (!wildcard(port).test(actualPort))
+            return false;
+    }
+    else if (!host.includes("*") && u.port !== "")
+        return false;
+    return path === undefined || wildcard(path).test(u.pathname + u.search);
+}
+function matches(entry, d) {
+    if ("serverName" in entry)
+        return entry.serverName === d.server.name;
+    if ("serverCommand" in entry)
+        return d.command !== null && JSON.stringify(entry.serverCommand) === JSON.stringify(d.command);
+    return d.url !== null && urlMatches(entry.serverUrl, d.url);
+}
+/** The allowlist check by server type (docs: managed-mcp#how-a-server-is-evaluated). */
+function allowed(list, d) {
+    const kind = d.url ? "serverUrl" : "serverCommand";
+    const byKind = list.filter((e) => kind in e);
+    if (byKind.some((e) => matches(e, d)))
+        return true;
+    return byKind.length === 0 && list.some((e) => "serverName" in e && matches(e, d));
+}
+/**
+ * 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 async function readMcpServers(input, plugins) {
+    const { env, projectDir, layers, claudeJson, trust } = input;
+    const projects = isRecord(claudeJson?.projects) ? claudeJson.projects : {};
+    const entry = [trust.root, projectDir].map((key) => projects[key]).find(isRecord);
+    const project = entry ?? {};
+    const managed = layers.find((l) => l.scope === "managed");
+    // Checked as written: the layer has header values hidden, which would hide a ${VAR} in one.
+    const managedServers = (await readManagedSettings(env)).data?.managedMcpServers;
+    const managedFile = join(env.managedDir, "managed-mcp.json");
+    const managedJson = await readJsonObject(managedFile);
+    const mcpJson = join(projectDir, ".mcp.json");
+    const shared = await readJsonObject(mcpJson);
+    const defined = [
+        ...(managedJson.ok ? define(managedJson.data.mcpServers, "managed", managedFile, true) : []),
+        ...defineManaged(managedServers, managed?.path ?? ""),
+        ...define(project.mcpServers, "local", env.claudeJson),
+        ...(shared.ok ? define(shared.data.mcpServers, "project", mcpJson) : []),
+        ...define(claudeJson?.mcpServers, "user", env.claudeJson),
+    ];
+    for (const plugin of plugins) {
+        const path = join(plugin.installPath, ".mcp.json");
+        const file = await readJsonObject(path);
+        // A server name declared later in the same plugin replaces an earlier one.
+        const own = new Map();
+        const add = (list) => {
+            for (const d of list)
+                own.set(d.server.name, d);
+        };
+        if (file.ok)
+            add(define(file.data.mcpServers ?? file.data, "plugin", path));
+        for (const part of await manifestConfigs(plugin, "mcpServers"))
+            add(define(part.value, "plugin", part.path));
+        for (const d of own.values())
+            d.server.plugin = plugin.id;
+        defined.push(...own.values());
+    }
+    const exclusive = managedJson.ok;
+    const denied = layers.flatMap((l) => policyEntries(l.data?.deniedMcpServers));
+    const managedOnly = managed?.data?.allowManagedMcpServersOnly === true;
+    const allowLayers = layers.filter((l) => !managedOnly || l.scope === "managed");
+    const allowSet = allowLayers.some((l) => Array.isArray(l.data?.allowedMcpServers));
+    const allowList = allowLayers.flatMap((l) => policyEntries(l.data?.allowedMcpServers));
+    const disabledHere = stringsIn(project.disabledMcpServers);
+    // A cloned repository cannot approve its own servers: project and local approvals count once the
+    // folder is trusted, local ones in your home directory right away (docs: mcp#project-server-approvals-and-workspace-trust).
+    const approvalLayers = layers.filter((l) => (l.scope !== "project" && l.scope !== "local") ||
+        trust.trusted ||
+        (l.scope === "local" && projectDir === env.home));
+    const approveAll = approvalLayers.some((l) => l.data?.enableAllProjectMcpServers === true);
+    const approved = new Set([
+        ...approvalLayers.flatMap((l) => stringsIn(l.data?.enabledMcpjsonServers)),
+        ...stringsIn(project.enabledMcpjsonServers),
+    ]);
+    const rejected = new Set([
+        ...layers.flatMap((l) => stringsIn(l.data?.disabledMcpjsonServers)),
+        ...stringsIn(project.disabledMcpjsonServers),
+    ]);
+    const set = (server, status, note) => {
+        server.status = status;
+        server.note = note;
+    };
+    const byName = new Map();
+    const enabledEndpoints = new Map();
+    for (const d of defined) {
+        const { server } = d;
+        if (server.status === "invalid")
+            continue;
+        if (exclusive && !d.organisation && server.scope !== "managed") {
+            set(server, "blocked", "managed-mcp.json takes exclusive control of MCP servers");
+            continue;
+        }
+        // Scopes dedupe by name; plugins by endpoint against the enabled servers above them.
+        const earlier = server.scope === "plugin" ? enabledEndpoints.get(endpoint(d)) : byName.get(server.name);
+        if (earlier) {
+            set(server, "shadowed", `The ${earlier.server.scope} definition of ${earlier.server.name} is used instead`);
+            continue;
+        }
+        if (server.scope !== "plugin")
+            byName.set(server.name, d);
+        if (denied.some((e) => matches(e, d)))
+            set(server, "blocked", "Blocked by deniedMcpServers");
+        else if (allowSet && !d.organisation && !allowed(allowList, d))
+            set(server, "blocked", managedOnly ? "Not in the managed allowedMcpServers" : "Not in allowedMcpServers");
+        else if (disabledHere.includes(server.name))
+            set(server, "disabled", "Turned off for this project in /mcp");
+        else if (server.scope === "project" && rejected.has(server.name))
+            set(server, "rejected", "Rejected by disabledMcpjsonServers");
+        else if (server.scope === "project" && !approveAll && !approved.has(server.name))
+            set(server, "pending", "Claude Code asks before starting servers from .mcp.json");
+        if (server.status === "active" || server.status === "pending")
+            enabledEndpoints.set(endpoint(d), d);
+    }
+    return defined.map((d) => d.server);
+}

package/dist/server/scan/memory.js

@@ -0,0 +1,91 @@
+import { join } from "node:path";
+import {} from "../../shared/types.js";
+import { isDir, listDir, parseFrontmatter, readTextFile, revisionOf, shortHash, stringField, } from "./files.js";
+const INDEX_FILE = "MEMORY.md";
+/** Claude Code reads only this much of MEMORY.md at session start (docs: memory#auto-memory). */
+const INDEX_LINE_LIMIT = 200;
+const INDEX_BYTE_LIMIT = 25 * 1024;
+const TYPES = ["user", "feedback", "project", "reference"];
+/** Claude Code names a project's store after its path with every non-alphanumeric character as "-". */
+export function storeDirName(projectPath) {
+    return projectPath.replace(/[^a-zA-Z0-9]/g, "-");
+}
+export async function readMemoryStore(dir, projectPath) {
+    if (!(await isDir(dir)))
+        return null;
+    const indexFile = await readTextFile(join(dir, INDEX_FILE));
+    const files = (await listDir(dir)).filter((f) => f.endsWith(".md") && f !== INDEX_FILE);
+    const memories = [];
+    for (const file of files) {
+        const text = await readTextFile(join(dir, file));
+        if (!text)
+            continue;
+        const { data, body } = parseFrontmatter(text.text);
+        const metadata = typeof data.metadata === "object" && data.metadata !== null
+            ? data.metadata
+            : {};
+        const rawType = stringField(metadata, "type") || stringField(data, "type");
+        memories.push({
+            file,
+            path: text.path,
+            name: stringField(data, "name") || file.replace(/\.md$/, ""),
+            description: stringField(data, "description"),
+            type: TYPES.includes(rawType) ? rawType : "unknown",
+            body,
+            mtime: text.mtime,
+            bytes: text.bytes,
+            revision: revisionOf(text.text),
+            inIndex: indexFile ? indexMentions(indexFile.text, file) : false,
+            hash: shortHash(body.trim()),
+            links: wikiLinks(body),
+            brokenLinks: [],
+            linkedFrom: [],
+        });
+    }
+    const names = new Set(memories.map((m) => m.name));
+    for (const memory of memories) {
+        memory.brokenLinks = memory.links.filter((link) => !names.has(link));
+        for (const link of memory.links) {
+            const target = memories.find((m) => m.name === link);
+            if (target && target !== memory && !target.linkedFrom.includes(memory.name))
+                target.linkedFrom.push(memory.name);
+        }
+    }
+    return {
+        dir,
+        loaded: true,
+        projectPath,
+        index: indexFile ? summarizeIndex(indexFile, files) : null,
+        memories,
+    };
+}
+function summarizeIndex(file, files) {
+    const lines = file.text.split("\n");
+    let loadedLines = 0;
+    let bytes = 0;
+    for (const line of lines) {
+        bytes += Buffer.byteLength(line, "utf8") + 1;
+        if (loadedLines >= INDEX_LINE_LIMIT || bytes > INDEX_BYTE_LIMIT)
+            break;
+        loadedLines++;
+    }
+    return {
+        ...file,
+        revision: revisionOf(file.text),
+        truncated: loadedLines < lines.length,
+        loadedLines,
+        missingFiles: [...new Set(file.text.split("\n").flatMap((l) => deadLinks(l, files)))],
+    };
+}
+/** Memory files an index line links to that are not in the store. */
+export function deadLinks(line, files) {
+    return [...line.matchAll(/\]\(([^)\s/\\]+\.md)\)/g)]
+        .map((m) => m[1] ?? "")
+        .filter((f) => !files.includes(f));
+}
+function indexMentions(index, file) {
+    return index.includes(`(${file})`) || index.includes(`[[${file.replace(/\.md$/, "")}]]`);
+}
+function wikiLinks(body) {
+    return [...new Set([...body.matchAll(/\[\[([^\]\n|]+)\]\]/g)].map((m) => (m[1] ?? "").trim()))];
+}

package/dist/server/scan/path-test.js

@@ -0,0 +1,99 @@
+import { dirname, isAbsolute, join, matchesGlob, relative, resolve, sep } from "node:path";
+import {} from "../../shared/types.js";
+import {} from "./env.js";
+import { isFile, isWithin, listDir, parseFrontmatter, readTextFile, stringsIn, toStringList, walkMarkdown, } from "./files.js";
+import { scanDirectory } from "./index.js";
+import { applySkillOverrides, readSkill } from "./inventory.js";
+/** Globs are written with forward slashes on every platform. */
+function slashed(path) {
+    return path.split(sep).join("/");
+}
+function firstMatch(globs, path) {
+    return globs.find((glob) => {
+        try {
+            return matchesGlob(path, glob);
+        }
+        catch {
+            // An invalid pattern matches nothing; the others still count (docs: memory#path-specific-rules).
+            return false;
+        }
+    });
+}
+/**
+ * What Claude Code adds to context once Claude reads or edits `file` in a session started in `dir`:
+ * path-scoped rules, skills with matching `paths`, and CLAUDE.md files in the folders between.
+ */
+export async function testPath(env, dir, file) {
+    const cwd = resolve(dir);
+    const target = isAbsolute(file) ? resolve(file) : resolve(cwd, file);
+    if (target === cwd || !isWithin(cwd, target))
+        return { file: target, inside: false, exists: false, matches: [] };
+    const view = await scanDirectory(env, cwd);
+    const projectRoot = view.gitRoot ?? cwd;
+    const matches = [];
+    const excludes = stringsIn(view.effective.find((e) => e.key === "claudeMdExcludes")?.value);
+    const overrides = view.effective.find((e) => e.key === "skillOverrides")?.value;
+    const excluded = (path) => excludes.some((glob) => firstMatch([glob], path) !== undefined);
+    // Path rules Claude Code would use at all: not excluded, not waiting for approval.
+    for (const rule of view.instructions) {
+        if (!rule.paths || rule.status !== "on-match")
+            continue;
+        // A project rule's globs are relative to the folder holding its .claude; others to the project.
+        const base = rule.scope === "project" || rule.scope === "local" ? rule.dir : projectRoot;
+        const glob = firstMatch(rule.paths, slashed(relative(base, target)));
+        if (glob)
+            matches.push({ kind: "rule", path: rule.path, scope: rule.scope, glob });
+    }
+    // Folders below the start directory load their own instructions, rules and skills on demand.
+    const mode = view.agentsMdMode;
+    const between = [];
+    for (let d = dirname(target); d !== cwd && isWithin(cwd, d); d = dirname(d))
+        between.unshift(d);
+    for (const folder of between) {
+        const nested = async (name, scope) => {
+            const path = join(folder, name);
+            if (excluded(path) || !(await readTextFile(path)))
+                return false;
+            matches.push({ kind: "nested", path, scope });
+            return true;
+        };
+        // managed-only leaves out files at launch, but a subfolder's CLAUDE.md and rules still load
+        // on demand (docs: memory#choose-which-instruction-files-load).
+        let hasClaudeMd = false;
+        for (const name of ["CLAUDE.md", ".claude/CLAUDE.md"])
+            if (await nested(name, "project"))
+                hasClaudeMd = true;
+        if (mode !== "managed-only" && (await nested("CLAUDE.local.md", "local")))
+            hasClaudeMd = true;
+        const agents = mode === "claude-md-and-agents-md" || (mode === "claude-md-or-agents-md" && !hasClaudeMd);
+        if (agents)
+            await nested("AGENTS.md", "project");
+        for (const path of await walkMarkdown(join(folder, ".claude", "rules"))) {
+            const text = await readTextFile(path);
+            if (!text || excluded(path))
+                continue;
+            const globs = toStringList(parseFrontmatter(text.text).data.paths);
+            const glob = globs.length === 0 ? undefined : firstMatch(globs, slashed(relative(folder, target)));
+            if (globs.length === 0 || glob)
+                matches.push({ kind: "nested", path, scope: "project", ...(glob ? { glob } : {}) });
+        }
+        // Only skills Claude may pick itself: not off, user-invocable-only or disable-model-invocation.
+        for (const name of await listDir(join(folder, ".claude", "skills"))) {
+            const skill = await readSkill(join(folder, ".claude", "skills", name), "project");
+            if (!skill)
+                continue;
+            applySkillOverrides([skill], overrides);
+            if (skill.listed !== false)
+                matches.push({ kind: "skill", path: skill.path, scope: "project", name: skill.name });
+        }
+    }
+    // Skills Claude can pick on its own; one with disable-model-invocation only runs when you call it.
+    for (const skill of view.inventory.skills) {
+        if (!skill.paths || skill.listed === false)
+            continue;
+        const glob = firstMatch(skill.paths, slashed(relative(projectRoot, target)));
+        if (glob)
+            matches.push({ kind: "skill", path: skill.path, scope: skill.scope, glob, name: skill.name });
+    }
+    return { file: target, inside: true, exists: await isFile(target), matches };
+}

package/dist/server/scan/permissions.js

@@ -0,0 +1,85 @@
+import { HIGHEST_FIRST } from "../../shared/scopes.js";
+import {} from "../../shared/types.js";
+import { isRecord, stringsIn } from "./files.js";
+import { ignoredModeReason } from "./settings.js";
+/**
+ * Whether a file's trust-gated settings (permission grants, hooks, autoMemoryDirectory) wait for
+ * the workspace trust dialog. Claude Code runs git to tell a private local file from a committed one
+ * only once the folder or a parent is trusted, so until then the local file waits too, except in
+ * your configuration home; a committed local file waits like project settings.
+ */
+export function trustWaits({ trust, inConfigHome, localFromRepository, }) {
+    const localWaits = !inConfigHome && (trust.trusted ? false : !trust.inheritedFrom || localFromRepository);
+    return (scope) => (scope === "project" && !trust.trusted) || (scope === "local" && localWaits);
+}
+/** Claude Code checks every file's rules together: deny, then ask, then allow (docs: permissions). */
+const CHECK_ORDER = ["deny", "ask", "allow"];
+/**
+ * Every permission entry from every settings file, each marked with whether Claude Code applies it
+ * (docs: permissions#project-allow-rules-and-workspace-trust, settings-reference#permissions-defaultmode,
+ * #allowmanagedpermissionrulesonly).
+ */
+export function permissionsOf(layers, options) {
+    const sources = HIGHEST_FIRST.flatMap((scope) => layers
+        .filter((l) => l.scope === scope && isRecord(l.data?.permissions))
+        .map((l) => ({
+        scope,
+        path: l.path,
+        permissions: l.data?.permissions,
+    })));
+    const managedOnly = layers.some((l) => l.scope === "managed" && l.data?.allowManagedPermissionRulesOnly === true);
+    // Grants from repository files wait for the workspace trust dialog; deny and ask apply at once.
+    const waitsForTrust = trustWaits(options);
+    const notTrusted = "Waits until you trust this folder in Claude Code";
+    const rules = sources.flatMap(({ scope, path, permissions }) => CHECK_ORDER.flatMap((list) => stringsIn(permissions[list]).map((rule) => {
+        const base = { kind: "rule", list, rule, scope, path };
+        if (managedOnly && scope !== "managed")
+            return {
+                ...base,
+                inEffect: false,
+                note: "Managed settings allow only their own permission rules",
+            };
+        if (list === "allow" && waitsForTrust(scope))
+            return { ...base, inEffect: false, note: notTrusted };
+        return { ...base, inEffect: true };
+    })));
+    for (const r of rules) {
+        if (!r.inEffect)
+            continue;
+        const first = CHECK_ORDER.map((list) => rules.find((o) => o.inEffect && o.list === list && o.rule === r.rule)).find((o) => o !== undefined);
+        if (first && first.list !== r.list)
+            r.decidedBy = { list: first.list, scope: first.scope };
+    }
+    const out = [...rules];
+    let modeTaken = false;
+    for (const { scope, permissions } of sources) {
+        const mode = permissions.defaultMode;
+        if (typeof mode !== "string")
+            continue;
+        let note = ignoredModeReason(scope, mode);
+        if (!note && modeTaken)
+            note = "A higher settings file sets the default mode";
+        out.push({
+            kind: "defaultMode",
+            value: mode,
+            scope,
+            inEffect: !note,
+            ...(note ? { note } : {}),
+        });
+        if (!note)
+            modeTaken = true;
+    }
+    for (const { scope, permissions } of sources) {
+        for (const dir of stringsIn(permissions.additionalDirectories)) {
+            const note = waitsForTrust(scope) ? notTrusted : undefined;
+            out.push({
+                kind: "additionalDirectories",
+                value: dir,
+                scope,
+                inEffect: !note,
+                ...(note ? { note } : {}),
+            });
+        }
+    }
+    return out;
+}

package/dist/server/scan/plugins.js

@@ -0,0 +1,117 @@
+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";
+function manifestPath(plugin) {
+    return join(plugin.installPath, ".claude-plugin", "plugin.json");
+}
+async function manifest(plugin) {
+    const result = await readJsonObject(manifestPath(plugin));
+    return result.ok ? result.data : {};
+}
+/** 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(join(env.claudeDir, "plugins", "installed_plugins.json"));
+    if (!installed.ok || !isRecord(installed.data.plugins))
+        return [];
+    const out = [];
+    for (const [id, installs] of Object.entries(installed.data.plugins)) {
+        if (!Array.isArray(installs))
+            continue;
+        // A project or local install applies only in its own project; it beats a user install there.
+        const records = installs.filter((i) => isRecord(i));
+        const install = records.find((i) => i.projectPath === projectDir || (gitRoot && i.projectPath === gitRoot)) ??
+            records.find((i) => typeof i.projectPath !== "string");
+        if (!install)
+            continue;
+        const plugin = {
+            id,
+            version: stringField(install, "version"),
+            scope: stringField(install, "scope"),
+            installPath: stringField(install, "installPath"),
+            updated: stringField(install, "lastUpdated") || null,
+            enabled: true,
+            note: "",
+        };
+        const setting = HIGHEST_FIRST.flatMap((scope) => layers
+            .filter((l) => l.scope === scope)
+            .map((l) => l.data?.enabledPlugins)
+            .filter(isRecord)
+            .filter((flags) => flags[id] !== undefined)
+            .map((flags) => ({ scope, value: flags[id] })))[0];
+        if (setting) {
+            plugin.enabled = setting.value !== false;
+            plugin.enabledIn = setting.scope;
+            plugin.note = `${plugin.enabled ? "Enabled" : "Turned off"} in ${setting.scope} settings`;
+        }
+        else {
+            plugin.enabled = (await manifest(plugin)).defaultEnabled !== false;
+            plugin.note = plugin.enabled
+                ? "On by default (no enabledPlugins entry)"
+                : "Off by default (no enabledPlugins entry)";
+        }
+        out.push(plugin);
+    }
+    return out;
+}
+/** A path from a manifest, if it stays inside the plugin once links are followed. */
+async function inside(plugin, path) {
+    const target = resolve(plugin.installPath, path);
+    const root = await resolvedPath(plugin.installPath);
+    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(plugin, key) {
+    const value = (await manifest(plugin))[key];
+    const list = typeof value === "string" ? [value] : Array.isArray(value) ? value : null;
+    if (!list)
+        return null;
+    const out = [];
+    for (const item of list) {
+        if (typeof item !== "string")
+            continue;
+        const path = await inside(plugin, item);
+        if (path)
+            out.push(path);
+    }
+    return out;
+}
+/** The value of a manifest key that is a path, an inline object, or a list of either. */
+export async function manifestConfigs(plugin, key) {
+    const value = (await manifest(plugin))[key];
+    const out = [];
+    for (const item of Array.isArray(value) ? value : value === undefined ? [] : [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(path) : null;
+        if (path && file?.ok)
+            out.push({ value: file.data[key] ?? file.data, path });
+    }
+    return out;
+}
+/** The manifest's `commands` object form: command name to a file or inline content. */
+export async function manifestCommandMap(plugin) {
+    const value = (await manifest(plugin)).commands;
+    if (!isRecord(value))
+        return [];
+    const out = [];
+    for (const [name, entry] of Object.entries(value)) {
+        if (!isRecord(entry))
+            continue;
+        const source = typeof entry.source === "string" ? await inside(plugin, entry.source) : null;
+        const content = typeof entry.content === "string" ? entry.content : null;
+        if (!source && content === null)
+            continue;
+        out.push({
+            name,
+            path: source ?? manifestPath(plugin),
+            description: stringField(entry, "description"),
+            text: content,
+        });
+    }
+    return out;
+}