simple-skills-manager 1.0.1

package/config.ts

@@ -0,0 +1,736 @@
+/**
+ * simple-skills-manager configuration.
+ *
+ * Everything — extension settings, every library root ("the registrar"),
+ * and each root's approved skill manifest — lives in ONE file:
+ *
+ *   ~/.pi/agent/simple-skills-manager.json
+ *
+ * Vocabulary (see README):
+ *   - The *library* is the corpus of all skills known to the manager.
+ *   - The *registrar* is the corpus of directory roots the library is
+ *     scanned from; in the TUI all roots sit flat next to each other.
+ *   - The *store* is the built-in root where skills added through the
+ *     TUI accumulate: ~/.pi/agent/managed-skills.
+ *   - *Native* roots are pi's own discovery locations
+ *     (~/.pi/agent/skills, ~/.agents/skills). pi exposes skills found
+ *     there by itself; the manager mirrors that exposure (shown in red
+ *     in the TUI) instead of pretending to gate it.
+ *
+ * The config file is JSONC (comments allowed when edited by hand; saving
+ * from /skills-manager rewrites it and strips comments). It is created
+ * automatically with commented defaults on first run, is editable at
+ * runtime from the /skills-manager TUI, and is written atomically on
+ * every save.
+ *
+ * Per-entry isolation: each registrar[] entry is validated independently.
+ * A malformed entry is kept in the file, flagged with issues, and skipped —
+ * it never prevents other entries from loading.
+ */
+
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { errText, isRecord, stripJsonComments, writeFileAtomic } from "./util.ts";
+
+export const CONFIG_FILE = "simple-skills-manager.json";
+export const CONFIG_PATH = join(getAgentDir(), CONFIG_FILE);
+export const STORE_DIR = join(getAgentDir(), "managed-skills");
+/** pi's own global skill discovery locations — recognized and mirrored, never overridden. */
+export const NATIVE_DIRS = [join(getAgentDir(), "skills"), join(homedir(), ".agents", "skills")];
+export const MAX_CONFIG_BYTES = 1024 * 1024;
+export const MAX_MANIFEST_BYTES = 1024 * 1024;
+export const MAX_SKILL_NAME_CHARS = 64;
+export const MAX_SKILL_DESC_CHARS = 1024;
+export const MAX_DIR_PATH_CHARS = 512;
+export const MAX_PATH_CHARS = 2048;
+export const MAX_ROOT_NAME_CHARS = 48;
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type Transport = "skills-dir" | "single-skill";
+export type SkillMode = "all" | "selected";
+
+/** The approved snapshot of one skill, bound to the exact root it was
+ *  scanned under (via the manifest fingerprint) and to the exact content
+ *  that was inspected (via contentHash). */
+export type SkillSnapshot = {
+    name: string;
+    description: string;
+    /** Skill directory, relative to the root path ("." for single-skill roots and root-level .md files). */
+    dirPath: string;
+    /** The skill instruction file inside the skill directory. Defaults to "SKILL.md"; root-level .md skills set their own file name. */
+    file?: string;
+    /** SHA-256 of the skill instruction file's bytes. The drift check on every invocation compares against this. */
+    contentHash: string;
+    /** Number of files in the skill directory (informational). */
+    fileCount: number;
+    /** Files inside the skill directory that start with a shebang — the model may be instructed to execute these. */
+    executableScripts: string[];
+    /** Frontmatter declared disable-model-invocation: hidden from the model, only invocable via /skill:<name>. */
+    hidden?: boolean;
+};
+
+/** A skill that was found on disk but failed validation. Kept in the
+ *  manifest for TUI visibility (native pi is lenient; the manager is
+ *  strict — the tree shows exactly where the two disagree). */
+export type RejectedSkill = {
+    dirPath: string;
+    reason: string;
+};
+
+/** The approved snapshot of a root's scan, bound to the exact root
+ *  configuration it was inspected under (via fingerprint). */
+export type SkillManifest = {
+    version: 1;
+    fingerprint: string;
+    scannedAt: string;
+    skills: SkillSnapshot[];
+    rejected?: RejectedSkill[];
+};
+
+export type RootConfig = {
+    name: string;
+    enabled: boolean;
+    transport: Transport;
+    path: string;
+    /** Marks the built-in store root (exactly one allowed; path pinned to STORE_DIR). */
+    store?: boolean;
+    /** Marks a native pi discovery location — exposure is mirrored, not gated. */
+    native?: boolean;
+    connection: "lazy";
+    skills: { mode: SkillMode; include: string[] };
+    /** Approved manifest from "Scan or refresh"; required to enable a root. */
+    manifest?: SkillManifest;
+};
+
+/** Extension-level tunables. Every limit that was once a hardcoded constant
+ *  lives here so users can adjust it without touching code. */
+export type ManagerSettings = {
+    maxResultBytes: number;
+    maxResultLines: number;
+    maxSkills: number;
+    toolNameLimit: number;
+    maxSkillBytes: number;
+    maxScanFiles: number;
+};
+
+export const DEFAULT_SETTINGS: ManagerSettings = {
+    maxResultBytes: 50 * 1024,
+    maxResultLines: 2_000,
+    maxSkills: 200,
+    toolNameLimit: 64,
+    maxSkillBytes: 128 * 1024,
+    maxScanFiles: 4_096,
+};
+
+/** One registrar[] entry as the extension sees it: the normalized config (an
+ *  inert placeholder when the raw entry could not be parsed), its validation
+ *  issues, and the raw entry itself so unparseable data round-trips safely
+ *  through saves instead of being clobbered. `auto` marks roots the loader
+ *  seeded automatically because the directory is a native pi location that
+ *  exists on disk — persisted to the file only once a save blesses them. */
+export type ManagedRoot = {
+    config: RootConfig;
+    issues: string[];
+    normalized: boolean;
+    raw: Record<string, unknown>;
+    auto?: boolean;
+};
+
+export type ManagerConfig = {
+    version: 1;
+    settings: ManagerSettings;
+    settingsIssues: string[];
+    roots: ManagedRoot[];
+    /** True when the starter config file was created by this load. */
+    created: boolean;
+};
+
+// ─── Constants ─────────────────────────────────────────────────────────────
+
+/** Agent Skills standard: 1-64 chars, lowercase letters, numbers, single hyphens. */
+export const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CONTENT_HASH_RE = /^[0-9a-f]{64}$/;
+const DIR_SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TEMPLATE_REF_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+const MUTABLE_SEGMENTS = ["node_modules", "/tmp/", "temp/", ".cache/", ".npm/", ".local/share/Trash"];
+
+// ─── Loading ───────────────────────────────────────────────────────────────
+
+/** Create a minimal, commented starter config if none exists yet, seeded
+ *  with the built-in store root. Returns true when the file was created
+ *  (first run). A fresh config has no approved manifest yet; /skills-manager
+ *  guides the first addition. Only the default config path also creates the
+ *  store directory, so test loads with custom paths have no side effects. */
+async function ensureConfigFile(path: string = CONFIG_PATH): Promise<boolean> {
+    const info = await lstat(path).catch(() => undefined);
+    if (info) return false;
+    const starter = `{
+  // simple-skills-manager configuration — created automatically on first run.
+  // Manage everything interactively with the /skills-manager command (add or
+  // import skills, scan and approve roots, expose, edit, remove), or edit this
+  // file by hand and restart pi (or run /reload).
+  // JSONC comments are allowed here; note that saving from /skills-manager
+  // rewrites the file and strips comments.
+  // Full field reference: simple-skills-manager.example.json beside the
+  // extension, and docs/ in the package.
+
+  "version": 1,
+
+  // Extension-level settings (all optional; defaults shown).
+  "settings": {
+    // "maxResultBytes": 51200,    // per-invocation skill text output cap
+    // "maxResultLines": 2000,    // per-invocation skill text output line cap
+    // "maxSkills": 200,          // max skills a root manifest may hold
+    // "toolNameLimit": 64,       // max length of registered skill_* tool names
+    // "maxSkillBytes": 131072,   // max size of one SKILL.md (bytes)
+    // "maxScanFiles": 4096       // max filesystem entries a scan may visit
+  },
+
+  // The registrar: every library root sits flat next to the others. The
+  // built-in "store" root is where skills added through /skills-manager
+  // accumulate; group skills by nesting them in subdirectories of the
+  // store (subdirectories are displayed as groups in the TUI). Each other
+  // root needs one "Scan or refresh" pass (in /skills-manager) to record
+  // its approved skill manifest before it can be enabled.
+  "registrar": [
+    {
+      "name": "store",
+      "store": true,
+      "enabled": false,
+      "transport": "skills-dir",
+      "path": ${JSON.stringify(STORE_DIR)},
+      "connection": "lazy",
+      "skills": { "mode": "selected", "include": [] }
+    }
+  ]
+}
+`;
+    try {
+        await writeFile(path, starter, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    } catch (error) {
+        // Another first load won the race; its file is as good as ours.
+        if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+        throw error;
+    }
+    if (path === CONFIG_PATH) {
+        await mkdir(STORE_DIR, { recursive: true }).catch(() => undefined);
+    }
+    return true;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+    if (value === undefined) return undefined;
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) return undefined;
+    return value as string[];
+}
+
+function numberSetting(
+    raw: Record<string, unknown>,
+    key: keyof ManagerSettings,
+    def: number,
+    min: number,
+    max: number,
+    issues: string[],
+): number {
+    const value = raw[key];
+    if (value === undefined) return def;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+        issues.push(`settings.${key} must be an integer between ${min} and ${max}; using the default (${def}).`);
+        return def;
+    }
+    return value;
+}
+
+function normalizeSettings(raw: unknown): { settings: ManagerSettings; issues: string[] } {
+    const issues: string[] = [];
+    if (raw === undefined) return { settings: { ...DEFAULT_SETTINGS }, issues };
+    if (!isRecord(raw)) {
+        issues.push("settings must be a JSON object; using defaults.");
+        return { settings: { ...DEFAULT_SETTINGS }, issues };
+    }
+    return {
+        settings: {
+            maxResultBytes: numberSetting(raw, "maxResultBytes", DEFAULT_SETTINGS.maxResultBytes, 1024, 10 * 1024 * 1024, issues),
+            maxResultLines: numberSetting(raw, "maxResultLines", DEFAULT_SETTINGS.maxResultLines, 1, 1_000_000, issues),
+            maxSkills: numberSetting(raw, "maxSkills", DEFAULT_SETTINGS.maxSkills, 1, 1_000, issues),
+            toolNameLimit: numberSetting(raw, "toolNameLimit", DEFAULT_SETTINGS.toolNameLimit, 16, 128, issues),
+            maxSkillBytes: numberSetting(raw, "maxSkillBytes", DEFAULT_SETTINGS.maxSkillBytes, 1024, 1_048_576, issues),
+            maxScanFiles: numberSetting(raw, "maxScanFiles", DEFAULT_SETTINGS.maxScanFiles, 10, 100_000, issues),
+        },
+        issues,
+    };
+}
+
+/** Normalize one raw registrar[] entry. Returns the normalized config when
+ *  the entry has the required shape (validation issues may still apply), or
+ *  an inert placeholder when it could not be parsed at all. Paths that point
+ *  at pi's native discovery locations are automatically flagged native. */
+function normalizeRoot(raw: Record<string, unknown>, settings: ManagerSettings): { config: RootConfig; normalized: boolean; issues: string[] } {
+    const issues: string[] = [];
+    if (typeof raw.name !== "string" || !raw.name || typeof raw.enabled !== "boolean"
+        || (raw.transport !== "skills-dir" && raw.transport !== "single-skill")
+        || typeof raw.path !== "string" || !raw.path) {
+        return {
+            config: inertRoot(typeof raw.name === "string" && raw.name ? raw.name : "unnamed"),
+            normalized: false,
+            issues: ["Malformed root entry: name, enabled, transport (skills-dir | single-skill), and path are required."],
+        };
+    }
+    if (raw.connection !== undefined && raw.connection !== "lazy") {
+        issues.push("Only lazy skill loading is supported.");
+    }
+    if (raw.skills !== undefined && !isRecord(raw.skills)) {
+        issues.push("skills must be a JSON object with mode and include.");
+    }
+    const skills = isRecord(raw.skills) ? raw.skills : {};
+    if (skills.mode !== undefined && skills.mode !== "all" && skills.mode !== "selected") {
+        issues.push("skills.mode must be \"all\" or \"selected\".");
+    }
+    const include = stringArray(skills.include);
+    if (skills.include !== undefined && !include) {
+        issues.push("skills.include must be an array of skill names.");
+    }
+    // Auto-recognize native pi discovery locations, whatever the file says.
+    const native = raw.native === true || isNativePath(raw.path);
+    const config: RootConfig = {
+        name: raw.name,
+        enabled: raw.enabled,
+        transport: raw.transport,
+        path: raw.path,
+        store: raw.store === true ? true : undefined,
+        native: native ? true : undefined,
+        connection: "lazy",
+        skills: {
+            mode: skills.mode === "all" ? "all" : "selected",
+            include: include ?? [],
+        },
+        manifest: isRecord(raw.manifest) ? raw.manifest as unknown as SkillManifest : undefined,
+    };
+    issues.push(...validateRoot(config, settings));
+    if (config.manifest) {
+        const checked = validateManifest(config.manifest, config, settings);
+        if (!checked.manifest) issues.push(...checked.issues);
+        else config.manifest = checked.manifest;
+    } else {
+        issues.push("No approved skill manifest; scan the root before enabling it.");
+    }
+    return { config, normalized: true, issues };
+}
+
+function inertRoot(name: string): RootConfig {
+    return {
+        name,
+        enabled: false,
+        transport: "skills-dir",
+        path: "",
+        connection: "lazy",
+        skills: { mode: "selected", include: [] },
+    };
+}
+
+/** Load the single config file. Throws with a readable reason when the file
+ *  exists but is unparseable or structurally invalid — never a silent
+ *  fallback. A missing file is auto-created as a starter config. */
+export async function loadManagerConfig(path: string = CONFIG_PATH): Promise<ManagerConfig> {
+    const created = await ensureConfigFile(path);
+    const info = await lstat(path).catch(() => undefined);
+    if (!info?.isFile() || info.isSymbolicLink()) {
+        throw new Error(`${path} must be a regular file, not a symbolic link.`);
+    }
+    if (info.size > MAX_CONFIG_BYTES) {
+        throw new Error(`${path} exceeds ${MAX_CONFIG_BYTES} bytes.`);
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(stripJsonComments(await readFile(path, "utf8")));
+    } catch (error) {
+        throw new Error(`${path} is not valid JSON: ${errText(error)}`);
+    }
+    if (!isRecord(parsed)) throw new Error(`${path} must contain a JSON object.`);
+    if (parsed.version !== undefined && parsed.version !== 1) {
+        throw new Error(`${path}: unsupported config version ${String(parsed.version)}; expected 1.`);
+    }
+    if (parsed.registrar !== undefined && !Array.isArray(parsed.registrar)) {
+        throw new Error(`${path}: "registrar" must be an array (it may be empty).`);
+    }
+    const { settings, issues: settingsIssues } = normalizeSettings(parsed.settings);
+    const roots: ManagedRoot[] = [];
+    const seen = new Set<string>();
+    let storeSeen = false;
+    for (const raw of (parsed.registrar ?? []) as unknown[]) {
+        if (!isRecord(raw)) {
+            roots.push({ config: inertRoot("unnamed"), issues: ["Root entry must be a JSON object."], normalized: false, raw: {} });
+            continue;
+        }
+        const { config, normalized, issues } = normalizeRoot(raw, settings);
+        if (config.store) {
+            if (storeSeen) issues.push("Duplicate store root (earlier definition wins).");
+            else storeSeen = true;
+        }
+        if (seen.has(config.name)) issues.push(`Duplicate root name: ${config.name} (earlier definition wins).`);
+        else seen.add(config.name);
+        roots.push({ config, issues, normalized, raw });
+    }
+    // Auto-adoption: native pi skill locations that exist on disk but are not
+    // in the registrar appear automatically — disabled, unapproved, flagged.
+    // The manager never enables or scans them by itself; the tree shows them
+    // for visibility and "Scan or refresh" is the adoption ceremony.
+    for (const [index, dir] of NATIVE_DIRS.entries()) {
+        const info = await lstat(dir).catch(() => undefined);
+        if (!info?.isDirectory()) continue;
+        const resolved = resolve(dir);
+        const registered = roots.some((root) => {
+            const rawPath = typeof root.raw.path === "string" ? root.raw.path : root.config.path;
+            try {
+                return typeof rawPath === "string" && rawPath && expandUserPath(rawPath, process.cwd()) === resolved;
+            } catch {
+                return false;
+            }
+        });
+        if (registered) continue;
+        const base = index === 0 ? "pi-skills" : "agents-skills";
+        let name = base;
+        let suffix = 2;
+        while (roots.some((root) => root.config.name === name)) name = `${base}-${suffix++}`;
+        const config: RootConfig = {
+            name, enabled: false, transport: "skills-dir", path: dir,
+            native: true, connection: "lazy", skills: { mode: "selected", include: [] },
+        };
+        roots.push({
+            config,
+            issues: [
+                "Auto-detected native pi location — pi exposes skills here through its own discovery, regardless of this extension.",
+                "No approved skill manifest; Scan or refresh (in /skills-manager) to adopt it into the library.",
+            ],
+            normalized: true,
+            raw: {},
+            auto: true,
+        });
+    }
+    return { version: 1, settings, settingsIssues, roots, created };
+}
+
+// ─── Saving ────────────────────────────────────────────────────────────────
+
+/** Atomically write raw config text (mode 0600) with the global size bound
+ *  enforced. Used both by saveManagerConfig and by the TUI's hand-edit path,
+ *  so every write of the file is atomic. */
+export async function writeConfigText(text: string, path: string = CONFIG_PATH): Promise<void> {
+    if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) {
+        throw new Error(`Refusing to write: the config would exceed ${MAX_CONFIG_BYTES} bytes.`);
+    }
+    await writeFileAtomic(path, text);
+}
+
+/** Atomically write the whole config file. Normalized entries are written
+ *  from their canonical config; unparseable entries are written back raw so
+ *  hand-edited data is never silently destroyed. Saving strips comments. */
+export async function saveManagerConfig(config: ManagerConfig, path: string = CONFIG_PATH): Promise<void> {
+    const payload = {
+        version: 1,
+        settings: config.settings,
+        registrar: config.roots.map((root) => root.normalized ? root.config : root.raw),
+    };
+    await writeConfigText(`${JSON.stringify(payload, null, 2)}\n`, path);
+}
+
+// ─── Entry helpers ──────────────────────────────────────────────────────────
+
+export function findRoot(config: ManagerConfig, name: string): ManagedRoot | undefined {
+    return config.roots.find((root) => root.config.name === name);
+}
+
+export function findStoreRoot(config: ManagerConfig): ManagedRoot | undefined {
+    return config.roots.find((root) => root.config.store && root.normalized);
+}
+
+/** Insert or replace a registrar entry by name, refusing entries with
+ *  validation issues (hand-repair those first through the TUI or the file). */
+export function upsertRoot(config: ManagerConfig, root: RootConfig): void {
+    const issues = validateRoot(root, config.settings);
+    if (issues.length) throw new Error(`Refusing to save invalid library root definition:\n${issues.join("\n")}`);
+    if (root.manifest) {
+        const checked = validateManifest(root.manifest, root, config.settings);
+        if (!checked.manifest) throw new Error(`Refusing to save invalid skill manifest:\n${checked.issues.join("\n")}`);
+    }
+    const entry: ManagedRoot = { config: root, issues: [], normalized: true, raw: root as unknown as Record<string, unknown> };
+    const index = config.roots.findIndex((item) => item.config.name === root.name);
+    if (index >= 0) config.roots[index] = entry;
+    else config.roots.push(entry);
+}
+
+export function removeRootEntry(config: ManagerConfig, name: string): boolean {
+    const index = config.roots.findIndex((item) => item.config.name === name);
+    if (index < 0) return false;
+    config.roots.splice(index, 1);
+    return true;
+}
+
+// ─── Validation ────────────────────────────────────────────────────────────
+
+export function validateRoot(config: RootConfig, _settings: ManagerSettings = DEFAULT_SETTINGS): string[] {
+    const issues: string[] = [];
+    if (!SKILL_NAME_RE.test(config.name) || config.name.length > MAX_ROOT_NAME_CHARS) {
+        issues.push("Name must be 1-48 lowercase letters, numbers, or single hyphens.");
+    }
+    if (config.connection !== "lazy") issues.push("Only lazy skill loading is supported.");
+    if (config.transport !== "skills-dir" && config.transport !== "single-skill") {
+        issues.push("Transport must be \"skills-dir\" or \"single-skill\".");
+    }
+    if (typeof config.path !== "string" || !config.path || config.path.length > MAX_PATH_CHARS || /[\0\r\n]/.test(config.path)) {
+        issues.push("A root path is required (no NUL or newline characters).");
+    } else {
+        try {
+            const resolved = expandUserPath(resolveTemplate(config.path), process.cwd());
+            if (resolved === homedir() || resolved === "/") issues.push("The root path may not be the home or filesystem root.");
+            if (config.store && resolved !== resolve(STORE_DIR)) {
+                issues.push("A store root's path must be the built-in store directory.");
+            }
+            if (config.native && !isNativePath(config.path)) {
+                issues.push("A native root's path must be one of pi's native skill discovery locations.");
+            }
+        } catch {
+            // A template reference (${...}) that cannot be resolved yet is fine;
+            // it fails closed at scan time with a readable error.
+        }
+    }
+    if (config.store && config.native) issues.push("A root may not be both the store and a native location.");
+    if (new Set(config.skills.include).size !== config.skills.include.length) issues.push("The selected skill list contains duplicates.");
+    if (config.skills.mode === "all" && (config.skills.include?.length ?? 0) > 0) {
+        issues.push("skills.include must be empty when skills.mode is \"all\".");
+    }
+    return issues;
+}
+
+/**
+ * The identity of a root: everything that determines what directory the
+ * library is scanned from. The approved skill manifest is bound to this
+ * identity, so changing any of these fields invalidates the manifest.
+ * Deliberately excludes enabled, native, store, the skills selection, and
+ * the manifest itself.
+ */
+function rootIdentity(config: RootConfig): unknown {
+    return { name: config.name, transport: config.transport, path: config.path };
+}
+
+export function fingerprint(config: RootConfig): string {
+    return createHash("sha256").update(JSON.stringify(rootIdentity(config))).digest("hex");
+}
+
+export function validateManifest(
+    manifest: unknown,
+    config: RootConfig,
+    settings: ManagerSettings = DEFAULT_SETTINGS,
+): { manifest?: SkillManifest; issues: string[] } {
+    const issues: string[] = [];
+    if (!isRecord(manifest) || manifest.version !== 1 || !Array.isArray(manifest.skills)) {
+        return { issues: ["Missing or malformed approved skill manifest."] };
+    }
+    if (Buffer.byteLength(JSON.stringify(manifest)) > MAX_MANIFEST_BYTES) issues.push(`The approved skill manifest exceeds ${MAX_MANIFEST_BYTES} bytes.`);
+    if (String(manifest.fingerprint) !== fingerprint(config)) issues.push("The approved skill manifest does not match the current root configuration; refresh it.");
+    if (manifest.skills.length > settings.maxSkills) issues.push(`The root contains more than ${settings.maxSkills} skills.`);
+    const names = new Set<string>();
+    const skills: SkillSnapshot[] = [];
+    for (const raw of manifest.skills) {
+        if (!isRecord(raw)) {
+            issues.push("The skill manifest contains a malformed skill.");
+            continue;
+        }
+        const name = typeof raw.name === "string" ? raw.name : "";
+        if (!SKILL_NAME_RE.test(name) || name.length > MAX_SKILL_NAME_CHARS || /[\0\r\n]/.test(name)) {
+            issues.push(`Skill name is invalid (1-64 chars, lowercase letters, numbers, single hyphens): ${name.slice(0, 80) || "(empty)"}`);
+            continue;
+        }
+        if (typeof raw.description !== "string" || !raw.description.trim() || raw.description.length > MAX_SKILL_DESC_CHARS) {
+            issues.push(`Skill ${name} must have a non-empty description of at most ${MAX_SKILL_DESC_CHARS} characters.`);
+            continue;
+        }
+        const dirPath = typeof raw.dirPath === "string" ? raw.dirPath : "";
+        if (!validDirPath(dirPath)) {
+            issues.push(`Skill ${name} has an invalid directory path: ${dirPath.slice(0, 80) || "(empty)"}`);
+            continue;
+        }
+        if (typeof raw.contentHash !== "string" || !CONTENT_HASH_RE.test(raw.contentHash)) {
+            issues.push(`Skill ${name} must carry a SHA-256 content hash.`);
+            continue;
+        }
+        const file = typeof raw.file === "string" ? raw.file : "SKILL.md";
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.md$/.test(file) || file.length > 128) {
+            issues.push(`Skill ${name} has an invalid instruction file name: ${file.slice(0, 80)}`);
+            continue;
+        }
+        const executableScripts = stringArray(raw.executableScripts) ?? [];
+        if (raw.executableScripts !== undefined && !executableScripts) {
+            issues.push(`Skill ${name}: executableScripts must be an array of file paths.`);
+            continue;
+        }
+        if (executableScripts.some((script) => !validDirPath(script) || script.length > MAX_DIR_PATH_CHARS)) {
+            issues.push(`Skill ${name} has an invalid executable script path.`);
+            continue;
+        }
+        if (names.has(name)) issues.push(`Duplicate skill name in manifest: ${name}`);
+        names.add(name);
+        skills.push({
+            name,
+            description: raw.description.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").slice(0, MAX_SKILL_DESC_CHARS),
+            dirPath,
+            file: file === "SKILL.md" ? undefined : file,
+            contentHash: raw.contentHash,
+            fileCount: typeof raw.fileCount === "number" && Number.isInteger(raw.fileCount) && raw.fileCount >= 1 ? raw.fileCount : 1,
+            executableScripts,
+            hidden: raw.hidden === true ? true : undefined,
+        });
+    }
+    const rejected: RejectedSkill[] = [];
+    if (manifest.rejected !== undefined) {
+        if (!Array.isArray(manifest.rejected)) issues.push("manifest.rejected must be an array.");
+        else for (const raw of manifest.rejected) {
+            if (isRecord(raw) && typeof raw.dirPath === "string" && validDirPath(raw.dirPath) && typeof raw.reason === "string" && raw.reason.length <= 512) {
+                rejected.push({ dirPath: raw.dirPath, reason: raw.reason.slice(0, 512) });
+            } else {
+                issues.push("manifest.rejected contains a malformed entry.");
+            }
+        }
+    }
+    if (config.skills.mode === "selected") {
+        const manifestNames = new Set(skills.map((skill) => skill.name));
+        for (const name of config.skills.include) {
+            if (!manifestNames.has(name)) issues.push(`Selected skill is absent from the approved manifest: ${name}`);
+        }
+    }
+    return {
+        manifest: issues.length ? undefined : {
+            version: 1,
+            fingerprint: String(manifest.fingerprint),
+            scannedAt: typeof manifest.scannedAt === "string" ? manifest.scannedAt : "unknown",
+            skills,
+            rejected: rejected.length ? rejected : undefined,
+        },
+        issues,
+    };
+}
+
+/** A relative path with sane segments, no "..", no absolute prefix, no NUL/newline. */
+export function validDirPath(value: string): boolean {
+    if (!value || value.length > MAX_DIR_PATH_CHARS || /[\0\r\n]/.test(value)) return false;
+    if (value === ".") return true;
+    if (value.startsWith("/") || value.includes("\\")) return false;
+    return value.split("/").every((segment) => DIR_SEGMENT_RE.test(segment) && segment !== "..");
+}
+
+// ─── Path plumbing ──────────────────────────────────────────────────────────
+
+export function expandUserPath(input: string, cwd: string): string {
+    const trimmed = input.trim();
+    const expanded = trimmed === "~"
+        ? homedir()
+        : trimmed.startsWith(`~${sep}`) || trimmed.startsWith("~/")
+            ? join(homedir(), trimmed.slice(2))
+            : trimmed;
+    return resolve(isAbsolute(expanded) ? expanded : join(cwd, expanded));
+}
+
+/** Resolve `${NAME}` templates against extras and the launching environment. Missing variables fail closed. */
+export function resolveTemplate(value: string, extras: Record<string, string> = {}): string {
+    return value.replace(TEMPLATE_REF_RE, (_match, name: string) => {
+        const resolved = extras[name] ?? process.env[name];
+        if (resolved === undefined) throw new Error(`Required environment variable is not set: ${name}`);
+        return resolved;
+    });
+}
+
+/** The root path with ~, ${workspace}, and ${home} expanded. */
+export function resolvedRootPath(config: RootConfig, workspace: string): string {
+    return expandUserPath(resolveTemplate(config.path, { workspace, home: homedir() }), workspace);
+}
+
+/** True when the path is one of pi's native global skill discovery locations. */
+export function isNativePath(path: string): boolean {
+    try {
+        const resolved = expandUserPath(path, process.cwd());
+        return NATIVE_DIRS.some((dir) => resolve(dir) === resolved);
+    } catch {
+        return false;
+    }
+}
+
+/** Absolute path of a skill's instruction file. */
+export function skillFilePath(config: RootConfig, snapshot: { dirPath: string; file?: string }, workspace: string): string {
+    const rootPath = resolvedRootPath(config, workspace);
+    return join(rootPath, snapshot.dirPath === "." ? "" : snapshot.dirPath, snapshot.file ?? "SKILL.md");
+}
+
+/** The display group of a skill: the first path segment under its root
+ *  when the skill is nested in a subdirectory, or "ungrouped" at the root
+ *  level (including root-level .md files and single-skill roots). */
+export function skillGroup(dirPath: string): string {
+    if (dirPath === "." || !dirPath.includes("/")) return "ungrouped";
+    return dirPath.split("/")[0]!;
+}
+
+/** Warn when a root lives somewhere its content may change without notice. */
+export function mutablePathWarning(path: string): string | undefined {
+    const normalized = path.replaceAll("\\", "/");
+    for (const segment of MUTABLE_SEGMENTS) {
+        if (normalized === segment || normalized.includes(`/${segment}`) || normalized.startsWith(segment)) {
+            return "This root lives in a mutable or cache location; its content may change without notice. Re-scan before trusting it.";
+        }
+    }
+    return undefined;
+}
+
+/** Warn when adopting a directory pi already discovers natively. */
+export function nativeDiscoveryWarning(path: string): string | undefined {
+    if (!isNativePath(path)) return undefined;
+    return "pi already discovers this location natively: skills here will be listed by pi itself as well. " +
+        "The manager mirrors that exposure (shown in red in the tree) and cannot revoke it; launch pi with --no-skills for full library-only control.";
+}
+
+export function scanSummary(config: RootConfig, workspace: string): string {
+    return [
+        `Transport: ${config.transport}`,
+        `Path: ${resolvedRootPath(config, workspace)}`,
+        `Store root: ${config.store ? "yes (skills added via /skills-manager accumulate here)" : "no"}`,
+        `Native pi location: ${config.native ? "yes — exposure is mirrored, not gated" : "no"}`,
+    ].join("\n");
+}
+
+// ─── Reusable selection logic ───────────────────────────────────────────────
+
+/** The skills of a root's approved manifest, defensively. A manifest that
+ *  failed validation is deliberately retained raw in the entry (so hand
+ *  edits are not destroyed on save), so its `skills` can be anything —
+ *  never assume it is an array. */
+export function manifestSkills(root: RootConfig): SkillSnapshot[] {
+    const skills = root.manifest?.skills;
+    return Array.isArray(skills) ? skills : [];
+}
+
+export function selectedSkills(root: RootConfig): SkillSnapshot[] {
+    const skills = manifestSkills(root);
+    if (root.skills.mode === "all") return skills;
+    const included = new Set(root.skills.include);
+    return skills.filter((skill) => included.has(skill.name));
+}
+
+/**
+ * The skills exposed to the model for one root, live. Standard roots expose
+ * their selected skills. Native roots additionally mirror whatever pi's
+ * native discovery is exposing right now (each skill's instruction file
+ * path present in the system prompt's loaded-skills list): pi exposes those
+ * skills whether the manager likes it or not, so mirroring adds the
+ * drift-checked surface without pretending to gate the native listing.
+ */
+export function computeExposedSkills(root: RootConfig, workspace: string, nativeActivePaths: Set<string>): SkillSnapshot[] {
+    if (!root.enabled) return [];
+    const standard = selectedSkills(root);
+    if (!root.native) return standard;
+    const standardNames = new Set(standard.map((skill) => skill.name));
+    return manifestSkills(root).filter((skill) =>
+        standardNames.has(skill.name) || nativeActivePaths.has(skillFilePath(root, skill, workspace)),
+    );
+}