ccdesk 0.2.2 → 0.2.4

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

@@ -1,9 +1,8 @@
-import { constants } from "node:fs";
-import { access, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, matchesGlob, parse, resolve } from "node:path";
 import {} from "../../shared/types.js";
 import {} from "./env.js";
-import { isFile, isNetworkPath, isWithin, MAX_TEXT_BYTES, parseFrontmatter, readTextFile, resolvedPath, toStringList, walkMarkdown, } from "./files.js";
+import { isFile, isNetworkPath, isWithin, MAX_TEXT_BYTES, readTextFile, resolvedPath, toStringList, walkMarkdown, } from "./files.js";
+import { parseFrontmatter } from "./data.js";
 const MAX_IMPORT_HOPS = 4;
 export const AGENTS_MD_MODES = [
     "claude-md-or-agents-md",
@@ -11,6 +10,45 @@ export const AGENTS_MD_MODES = [
     "claude-md",
     "managed-only",
 ];
+/** The CLAUDE.md and AGENTS.md files each folder can hold, in the order Claude Code reads them. */
+export const CLAUDE_MD_NAMES = ["CLAUDE.md", ".claude/CLAUDE.md"];
+export const AGENTS_MD_NAMES = ["AGENTS.md", ".claude/AGENTS.md"];
+/**
+ * Whether AGENTS.md loads, given the instruction mode and whether a CLAUDE.md or CLAUDE.local.md
+ * is there (docs: memory#choose-which-instruction-files-load).
+ */
+export function agentsMdLoads(mode, hasClaudeMd) {
+    return mode === "claude-md-and-agents-md" || (mode === "claude-md-or-agents-md" && !hasClaudeMd);
+}
+/**
+ * Whether a claudeMdExcludes glob matches a file by its own path or, for a link, its target's
+ * (docs: memory#exclude-specific-claude-md-files).
+ */
+export function isExcluded(excludes, path, realPath) {
+    return excludes.some((glob) => [path, realPath].some((p) => p !== undefined && safeMatch(p, glob)));
+}
+/**
+ * Where a rule in `dir` really is when that is outside both the project and `dir`: a link's
+ * target, or the file a linked folder leads to. Undefined for a rule that stays inside.
+ */
+export async function ruleTarget(file, dir, realCwd) {
+    if (file.realPath)
+        return file.realPath;
+    const real = await resolvedPath(file.path);
+    return isWithin(realCwd, real) || isWithin(await resolvedPath(dir), real) ? undefined : real;
+}
+/**
+ * Why a project rule linked from outside the project does not load, or null when it does: it waits
+ * for your approval of outside imports, and once approved loads only without a paths field
+ * (docs: memory#share-rules-across-projects-with-symlinks).
+ */
+export function linkedRuleBlock(target, realCwd, approved, hasPaths) {
+    if (target === undefined || isWithin(realCwd, target))
+        return null;
+    if (!approved)
+        return "needs-approval";
+    return hasPaths ? "has-paths" : null;
+}
 /** Directories from the filesystem root down to `cwd`, the order Claude Code concatenates them in. */
 export function ancestorsRootFirst(cwd) {
     const dirs = [];
@@ -31,25 +69,31 @@ export function ancestorsRootFirst(cwd) {
  */
 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(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));
-        if (denied)
-            problems.push({ path, error: `cannot be read (${denied})` });
-        return null;
-    };
     const ctx = {
         realCwd: await resolvedPath(resolve(cwd)),
         env,
         approved: externalImports === "approved",
+        problems,
     };
-    const managedOnly = mode === "managed-only";
-    const skippedByMode = `Skipped: instruction mode is ${mode}`;
+    const out = await readOwnFiles(ctx, managedClaudeMd);
+    const { claudeFiles, agentsFiles } = await readDirectoryFiles(ctx, cwd);
+    explainClaudeFiles(claudeFiles, cwd);
+    explainAgentsFiles(agentsFiles, claudeFiles, mode);
+    for (const dir of ancestorsRootFirst(cwd))
+        out.push(...claudeFiles.filter((f) => f.dir === dir), ...agentsFiles.filter((f) => f.dir === dir));
+    applyLoadRules(out, ctx, mode, excludes, externalImports);
+    addChecks(out);
+    return out;
+}
+/** A file that exists but cannot be read is reported, not taken for a missing one. */
+function readInstruction(ctx, path) {
+    return readTextFile(ctx.env, path, ctx.problems);
+}
+/** The managed and user files, which come first and do not depend on the folder. */
+async function readOwnFiles(ctx, managedClaudeMd) {
+    const { env } = ctx;
     const out = [];
-    const managed = await readInstruction(join(env.managedDir, "CLAUDE.md"));
+    const managed = await readInstruction(ctx, join(env.managedDir, "CLAUDE.md"));
     if (managed)
         out.push(await instruction(managed, "claude-md", "managed", env.managedDir, ctx, "Organisation policy, always loaded"));
     if (managedClaudeMd) {
@@ -65,69 +109,94 @@ export async function resolveInstructions(options) {
         entry.imports = [];
         out.push(entry);
     }
-    const user = await readInstruction(join(env.claudeDir, "CLAUDE.md"));
+    const user = await readInstruction(ctx, join(env.claudeDir, "CLAUDE.md"));
     if (user)
         out.push(await instruction(user, "claude-md", "user", env.claudeDir, ctx, "Your instructions for every project"));
     for (const path of await walkMarkdown(join(env.claudeDir, "rules"))) {
-        const file = await readInstruction(path);
+        const file = await readInstruction(ctx, path);
         if (file)
             out.push(await rule(file, "user", env.claudeDir, ctx));
     }
-    // Per directory, root first: CLAUDE.md, .claude/CLAUDE.md, rules, then CLAUDE.local.md last
-    // ("your personal notes are the last thing Claude reads at that level"), then AGENTS.md.
+    return out;
+}
+/**
+ * The project and local files of `cwd` and every folder above it. Per directory, root first:
+ * CLAUDE.md, .claude/CLAUDE.md, rules, then CLAUDE.local.md last ("your personal notes are the last
+ * thing Claude reads at that level"), then AGENTS.md.
+ */
+async function readDirectoryFiles(ctx, cwd) {
     const claudeFiles = [];
     const agentsFiles = [];
     for (const dir of ancestorsRootFirst(cwd)) {
-        // ~/.claude/CLAUDE.md and ~/.claude/rules are the user files above, not the home's project files.
-        const isConfigHome = join(dir, ".claude") === env.claudeDir;
-        for (const name of ["CLAUDE.md", ".claude/CLAUDE.md"]) {
-            if (isConfigHome && name === ".claude/CLAUDE.md")
-                continue;
-            const file = await readInstruction(join(dir, name));
-            if (file)
-                claudeFiles.push(await instruction(file, "claude-md", "project", dir, ctx, ""));
-        }
-        if (!isConfigHome && dir !== env.claudeDir)
-            for (const path of await walkMarkdown(join(dir, ".claude", "rules"))) {
-                const file = await readInstruction(path);
-                if (file)
-                    claudeFiles.push(await rule(file, "project", dir, ctx));
-            }
-        const local = await readInstruction(join(dir, "CLAUDE.local.md"));
-        if (local)
-            claudeFiles.push(await instruction(local, "claude-local-md", "local", dir, ctx, ""));
-        for (const name of ["AGENTS.md", ".claude/AGENTS.md"]) {
-            const file = await readInstruction(join(dir, name));
+        claudeFiles.push(...(await readClaudeFiles(ctx, dir)));
+        for (const name of AGENTS_MD_NAMES) {
+            const file = await readInstruction(ctx, join(dir, name));
             if (file)
                 agentsFiles.push(await instruction(file, "agents-md", "project", dir, ctx, ""));
         }
     }
-    const hasClaudeMd = claudeFiles.some((f) => f.kind !== "rule");
+    return { claudeFiles, agentsFiles };
+}
+/** One folder's CLAUDE.md files, rules and CLAUDE.local.md, in the order Claude Code reads them. */
+async function readClaudeFiles(ctx, dir) {
+    const { env } = ctx;
+    const out = [];
+    // ~/.claude/CLAUDE.md and ~/.claude/rules are the user files above, not the home's project files.
+    const holdsClaudeDir = join(dir, ".claude") === env.claudeDir;
+    for (const name of CLAUDE_MD_NAMES) {
+        if (holdsClaudeDir && name === ".claude/CLAUDE.md")
+            continue;
+        const file = await readInstruction(ctx, join(dir, name));
+        if (file)
+            out.push(await instruction(file, "claude-md", "project", dir, ctx, ""));
+    }
+    if (!holdsClaudeDir && dir !== env.claudeDir)
+        for (const path of await walkMarkdown(join(dir, ".claude", "rules"))) {
+            const file = await readInstruction(ctx, path);
+            if (file)
+                out.push(await rule(file, "project", dir, ctx));
+        }
+    const local = await readInstruction(ctx, join(dir, "CLAUDE.local.md"));
+    if (local)
+        out.push(await instruction(local, "claude-local-md", "local", dir, ctx, ""));
+    return out;
+}
+/** Why each CLAUDE.md and CLAUDE.local.md loads; rules have their reason already. */
+function explainClaudeFiles(claudeFiles, cwd) {
     for (const file of claudeFiles) {
         if (file.kind === "rule")
             continue;
-        file.reason =
-            file.kind === "claude-local-md"
-                ? "Your private notes for this directory"
-                : file.dir === resolve(cwd)
-                    ? "Instructions for this directory"
-                    : "Inherited from a parent directory";
+        if (file.kind === "claude-local-md")
+            file.reason = "Your private notes for this directory";
+        else if (file.dir === resolve(cwd))
+            file.reason = "Instructions for this directory";
+        else
+            file.reason = "Inherited from a parent directory";
     }
+}
+/** Whether each AGENTS.md loads next to the CLAUDE.md files found, and why. */
+function explainAgentsFiles(agentsFiles, claudeFiles, mode) {
+    const hasClaudeMd = claudeFiles.some((f) => f.kind !== "rule");
     const includedElsewhere = new Set(claudeFiles.flatMap((f) => [f.realPath ?? f.path, ...f.imports.map((i) => i.resolved)]));
     for (const file of agentsFiles) {
-        if (mode === "managed-only" || mode === "claude-md")
-            skip(file, skippedByMode);
+        if (!agentsMdLoads(mode, false))
+            skip(file, skippedByMode(mode));
         else if (includedElsewhere.has(file.realPath ?? file.path))
             skip(file, "Already included through a CLAUDE.md import or symlink");
+        else if (!agentsMdLoads(mode, hasClaudeMd))
+            skip(file, "Ignored: a CLAUDE.md or CLAUDE.local.md exists here or above, so Claude Code reads that instead");
         else if (mode === "claude-md-and-agents-md")
             file.reason = "Loaded alongside CLAUDE.md (instruction mode claude-md-and-agents-md)";
-        else if (hasClaudeMd)
-            skip(file, "Ignored: a CLAUDE.md or CLAUDE.local.md exists here or above, so Claude Code reads that instead");
         else
             file.reason = "Loaded because there is no CLAUDE.md here or above";
     }
-    for (const dir of ancestorsRootFirst(cwd))
-        out.push(...claudeFiles.filter((f) => f.dir === dir), ...agentsFiles.filter((f) => f.dir === dir));
+}
+/**
+ * Skips what Claude Code leaves out of every file but managed ones: all of them in managed-only
+ * mode, ones matched by claudeMdExcludes, ones over 4 MiB, and project rules linked from outside
+ * the project that do not qualify.
+ */
+function applyLoadRules(out, ctx, mode, excludes, externalImports) {
     const waiting = externalImports === "declined"
         ? "You declined imports from outside this project"
         : "Waits for you to approve imports from outside this project";
@@ -135,28 +204,27 @@ export async function resolveInstructions(options) {
         if (file.scope === "managed")
             continue;
         // Path-scoped rules still load on demand in managed-only mode (docs: memory#choose-which-instruction-files-load).
-        if (managedOnly && file.status === "loaded")
-            skip(file, skippedByMode);
-        // Managed files cannot be excluded; a linked file is excluded by its own path or its target's
-        // (docs: memory#exclude-specific-claude-md-files).
-        const excluded = excludes.some((glob) => [file.path, file.realPath].some((p) => p !== undefined && safeMatch(p, glob)));
-        if (excluded)
+        if (mode === "managed-only" && file.status === "loaded")
+            skip(file, skippedByMode(mode));
+        // Managed files cannot be excluded.
+        if (isExcluded(excludes, file.path, file.realPath))
             skip(file, "Skipped by claudeMdExcludes");
         if (file.status !== "skipped" && file.bytes > MAX_TEXT_BYTES)
             skip(file, "Skipped: Claude Code does not load an instruction file over 4 MiB");
         // A project's links outside it need your approval, like its imports; your own files do not.
         if (file.scope !== "project" && file.scope !== "local")
             continue;
-        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, and such a rule loads only without a paths field");
-        }
+        if (file.kind !== "rule")
+            continue;
+        const block = linkedRuleBlock(file.realPath, ctx.realCwd, ctx.approved, file.paths !== undefined);
+        if (block === "needs-approval")
+            skip(file, `${waiting}; this rule links outside it`);
+        else if (block === "has-paths")
+            skip(file, "Links outside this project, and such a rule loads only without a paths field");
     }
-    addChecks(out);
-    return out;
+}
+function skippedByMode(mode) {
+    return `Skipped: instruction mode is ${mode}`;
 }
 function skip(file, reason) {
     if (file.status === "skipped")
@@ -165,7 +233,7 @@ function skip(file, reason) {
     file.reason = reason;
 }
 /** An invalid pattern matches nothing. */
-function safeMatch(path, glob) {
+export function safeMatch(path, glob) {
     try {
         return matchesGlob(path, glob);
     }
@@ -213,9 +281,9 @@ async function rule(file, scope, dir, ctx) {
         entry.status = "on-match";
     }
     // A rule reached through a linked folder is not a link itself, but its target can be outside.
-    const real = await resolvedPath(file.path);
-    if (!entry.realPath && !isWithin(ctx.realCwd, real) && !isWithin(await resolvedPath(dir), real))
-        entry.realPath = real;
+    const target = await ruleTarget(file, dir, ctx.realCwd);
+    if (target)
+        entry.realPath = target;
     return entry;
 }
 async function instruction(file, kind, scope, dir, ctx, reason) {
@@ -248,7 +316,7 @@ async function collectImports(file, ctx, readExternal) {
                 continue;
             seen.add(real);
             const external = !isWithin(ctx.realCwd, real);
-            const imported = !external || readExternal ? await readTextFile(ctx.env, target) : null;
+            const imported = !external || readExternal ? await readTextFile(ctx.env, target, ctx.problems) : null;
             const ref = {
                 raw,
                 resolved: real,

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 {};