skillex 0.3.1 → 0.4.0

package/dist/lockfile.js

@@ -0,0 +1,169 @@
+/**
+ * Lockfile shape, normalization, source-list management, and migration helpers.
+ *
+ * Keeps `install.ts` focused on install/update/remove orchestration. All
+ * callers should import from here directly; `install.ts` re-exports these
+ * symbols for backward compatibility with existing test imports.
+ */
+import { DEFAULT_REF, DEFAULT_REPO } from "./config.js";
+/** Repos that are known placeholder values written by older versions and must be ignored. */
+export const PLACEHOLDER_REPOS = new Set(["owner/repo"]);
+/**
+ * Builds an empty lockfile seeded with a single source and `autoSync` on by default.
+ */
+export function createBaseLockfile(source, now) {
+    return {
+        formatVersion: 1,
+        createdAt: now(),
+        updatedAt: now(),
+        sources: [toLockfileSource(source)],
+        adapters: {
+            active: null,
+            detected: [],
+        },
+        settings: {
+            autoSync: true,
+        },
+        sync: null,
+        syncHistory: {},
+        syncMode: null,
+        installed: {},
+    };
+}
+/**
+ * Normalizes a possibly-legacy lockfile shape into the current `LockfileState`.
+ * Handles arrays-of-strings adapters from very old versions, missing
+ * `syncHistory`, and the deprecated single `sync` field.
+ */
+export function normalizeLockfile(existing, source, now) {
+    if (!existing) {
+        return createBaseLockfile(source, now);
+    }
+    const detectedAdapters = Array.isArray(existing.adapters)
+        ? existing.adapters
+        : Array.isArray(existing.adapters?.detected)
+            ? existing.adapters.detected
+            : [];
+    const activeAdapter = Array.isArray(existing.adapters)
+        ? existing.adapters[0] || null
+        : existing.adapters?.active || detectedAdapters[0] || null;
+    return {
+        formatVersion: Number(existing.formatVersion || 1),
+        createdAt: existing.createdAt || now(),
+        updatedAt: existing.updatedAt || now(),
+        sources: getLockfileSources(existing, source),
+        adapters: {
+            active: activeAdapter,
+            detected: [...new Set(detectedAdapters.filter(Boolean))],
+        },
+        settings: {
+            autoSync: existing.settings?.autoSync ?? true,
+        },
+        sync: existing.sync || null,
+        syncHistory: normalizeSyncHistory(existing),
+        syncMode: existing.syncMode || null,
+        installed: existing.installed || {},
+    };
+}
+/**
+ * Coerces the historic and current shapes of `syncHistory` into the
+ * normalized form, including a fallback that rebuilds the history from a
+ * legacy single-`sync` field.
+ */
+export function normalizeSyncHistory(existing) {
+    const history = {};
+    const candidate = existing && "syncHistory" in existing && existing.syncHistory && typeof existing.syncHistory === "object"
+        ? existing.syncHistory
+        : null;
+    if (candidate) {
+        for (const [adapterId, metadata] of Object.entries(candidate)) {
+            if (!metadata || typeof metadata !== "object") {
+                continue;
+            }
+            if (!("adapter" in metadata) || !("targetPath" in metadata) || !("syncedAt" in metadata)) {
+                continue;
+            }
+            history[adapterId] = metadata;
+        }
+    }
+    if (existing?.sync?.adapter && !history[existing.sync.adapter]) {
+        history[existing.sync.adapter] = existing.sync;
+    }
+    return history;
+}
+/**
+ * Resolves the configured source list, dropping placeholders and falling back
+ * to legacy single-catalog metadata when no `sources` array exists.
+ */
+export function getLockfileSources(existing, fallbackSource) {
+    const legacyCatalog = getLegacyCatalog(existing);
+    const configuredSources = Array.isArray(existing?.sources)
+        ? existing.sources
+            .filter((entry) => Boolean(entry?.repo))
+            .filter((entry) => !PLACEHOLDER_REPOS.has(entry.repo))
+            .map((entry) => ({
+            repo: entry.repo,
+            ref: entry.ref || DEFAULT_REF,
+            ...(entry.label ? { label: entry.label } : {}),
+        }))
+        : [];
+    if (configuredSources.length > 0) {
+        return dedupeSources(configuredSources);
+    }
+    if (legacyCatalog?.repo && !PLACEHOLDER_REPOS.has(legacyCatalog.repo)) {
+        return dedupeSources([
+            {
+                repo: legacyCatalog.repo,
+                ref: legacyCatalog.ref || DEFAULT_REF,
+            },
+        ]);
+    }
+    return [toLockfileSource(fallbackSource)];
+}
+function getLegacyCatalog(existing) {
+    if (!existing || !("catalog" in existing)) {
+        return null;
+    }
+    const legacyState = existing;
+    return legacyState.catalog || null;
+}
+/**
+ * Deduplicates a source list keyed by `${repo}@${ref}`, preserving the
+ * first occurrence (which carries any label).
+ */
+export function dedupeSources(sources) {
+    const unique = new Map();
+    for (const source of sources) {
+        const key = `${source.repo}@${source.ref}`;
+        if (!unique.has(key)) {
+            unique.set(key, source);
+        }
+    }
+    return [...unique.values()];
+}
+/**
+ * Converts a `CatalogSource` to a `LockfileSource`, attaching a label only
+ * when one is explicitly provided or when the source is the default
+ * first-party repo (which gets the `official` label automatically).
+ */
+export function toLockfileSource(source, label) {
+    const wantsLabel = Boolean(label) || source.repo === DEFAULT_REPO;
+    return {
+        repo: source.repo,
+        ref: source.ref,
+        ...(wantsLabel ? { label: label || "official" } : {}),
+    };
+}
+/**
+ * Parses a `catalog:owner/repo@ref` source string into a `LockfileSource`.
+ */
+export function parseCatalogSource(source) {
+    const match = source.match(/^catalog:([^@]+\/[^@]+)@(.+)$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        repo: match[1],
+        ref: match[2],
+    };
+}

package/dist/output.d.ts

@@ -63,3 +63,14 @@ export declare function statusLine(message: string): void;
  * Clears the current status line written by {@link statusLine}.
  */
 export declare function clearStatus(): void;
+/**
+ * Returns the candidate closest to `actual` by Levenshtein distance, but only
+ * when the distance is at or below `threshold`. Useful for "did you mean"
+ * hints on unknown commands, flags, or config keys.
+ *
+ * @param actual - The token typed by the user.
+ * @param candidates - Known valid tokens.
+ * @param threshold - Maximum Levenshtein distance to consider (default 2).
+ * @returns The closest match within threshold, or `null`.
+ */
+export declare function suggestClosest(actual: string, candidates: readonly string[], threshold?: number): string | null;

package/dist/output.js

@@ -119,3 +119,52 @@ export function clearStatus() {
         return;
     process.stdout.write("\r\x1b[K");
 }
+// ---------------------------------------------------------------------------
+// "Did you mean" suggestion helper
+// ---------------------------------------------------------------------------
+/**
+ * Returns the candidate closest to `actual` by Levenshtein distance, but only
+ * when the distance is at or below `threshold`. Useful for "did you mean"
+ * hints on unknown commands, flags, or config keys.
+ *
+ * @param actual - The token typed by the user.
+ * @param candidates - Known valid tokens.
+ * @param threshold - Maximum Levenshtein distance to consider (default 2).
+ * @returns The closest match within threshold, or `null`.
+ */
+export function suggestClosest(actual, candidates, threshold = 2) {
+    if (!actual || candidates.length === 0)
+        return null;
+    let best = null;
+    for (const candidate of candidates) {
+        const distance = levenshtein(actual, candidate);
+        if (distance > threshold)
+            continue;
+        if (!best || distance < best.distance) {
+            best = { name: candidate, distance };
+        }
+    }
+    return best ? best.name : null;
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const prev = new Array(b.length + 1);
+    const curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j += 1)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i += 1) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        for (let j = 0; j <= b.length; j += 1)
+            prev[j] = curr[j] ?? 0;
+    }
+    return prev[b.length] ?? 0;
+}

package/dist/recommended.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Curated starter pack installed when the user passes
+ * `skillex init --install-recommended`.
+ *
+ * Keep this list short and broadly useful. Anything specialised (LaTeX,
+ * power electronics, ...) belongs in the full catalog.
+ */
+export declare const RECOMMENDED_SKILL_IDS: readonly ["commit-craft", "code-review", "secure-defaults", "error-handling", "test-discipline"];
+/**
+ * Returns the recommended skill ids as a mutable string array (suitable for
+ * passing to `installSkills`).
+ */
+export declare function getRecommendedSkillIds(): string[];

package/dist/recommended.js

@@ -0,0 +1,21 @@
+/**
+ * Curated starter pack installed when the user passes
+ * `skillex init --install-recommended`.
+ *
+ * Keep this list short and broadly useful. Anything specialised (LaTeX,
+ * power electronics, ...) belongs in the full catalog.
+ */
+export const RECOMMENDED_SKILL_IDS = Object.freeze([
+    "commit-craft",
+    "code-review",
+    "secure-defaults",
+    "error-handling",
+    "test-discipline",
+]);
+/**
+ * Returns the recommended skill ids as a mutable string array (suitable for
+ * passing to `installSkills`).
+ */
+export function getRecommendedSkillIds() {
+    return [...RECOMMENDED_SKILL_IDS];
+}

package/dist/runner.js

@@ -14,7 +14,7 @@ import { CliError } from "./types.js";
 export function parseSkillCommandReference(value) {
     const separatorIndex = value.indexOf(":");
     if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
-        throw new CliError('Use o formato "skill-id:comando" para executar scripts.', "INVALID_RUN_REFERENCE");
+        throw new CliError('Use the format "skill-id:command" to run skill scripts.', "INVALID_RUN_REFERENCE");
     }
     return {
         skillId: value.slice(0, separatorIndex),
@@ -39,12 +39,12 @@ export async function runSkillScript(skillId, commandName, options = {}) {
     const lockfile = (await readJson(statePaths.lockfilePath, null)) || null;
     if (!lockfile) {
         throw new CliError(statePaths.scope === "global"
-            ? "Nenhuma instalacao global encontrada. Rode: skillex init --global --adapter <id>"
-            : "Nenhuma instalacao local encontrada. Rode: skillex init", "LOCKFILE_MISSING");
+            ? "No global installation found. Run: skillex init --global --adapter <id>"
+            : "No local installation found. Run: skillex init", "LOCKFILE_MISSING");
     }
     const metadata = lockfile.installed?.[skillId];
     if (!metadata?.path) {
-        throw new CliError(`Skill "${skillId}" nao esta instalada.`, "SKILL_NOT_INSTALLED");
+        throw new CliError(`Skill "${skillId}" is not installed.`, "SKILL_NOT_INSTALLED");
     }
     const skillDir = path.isAbsolute(metadata.path) ? metadata.path : path.resolve(cwd, metadata.path);
     const manifest = (await readJson(path.join(skillDir, "skill.json"), {})) || {};
@@ -53,14 +53,14 @@ export async function runSkillScript(skillId, commandName, options = {}) {
     if (!script) {
         const available = Object.keys(scripts);
         throw new CliError(available.length > 0
-            ? `Comando "${commandName}" nao existe para "${skillId}". Disponiveis: ${available.join(", ")}`
-            : `A skill "${skillId}" nao declara scripts executaveis.`, "RUN_COMMAND_NOT_FOUND");
+            ? `Command "${commandName}" does not exist for "${skillId}". Available: ${available.join(", ")}`
+            : `Skill "${skillId}" does not declare any executable scripts.`, "RUN_COMMAND_NOT_FOUND");
     }
-    const confirm = options.confirm || (() => confirmAction(`Executar em ${skillId}: ${script}?`));
+    const confirm = options.confirm || (() => confirmAction(`Run in ${skillId}: ${script}?`));
     if (!options.yes) {
         const accepted = await confirm();
         if (!accepted) {
-            throw new CliError("Execucao cancelada pelo usuario.", "RUN_CANCELLED");
+            throw new CliError("Run cancelled by user. Pass --yes to skip the confirmation prompt.", "RUN_CANCELLED");
         }
     }
     const stdout = options.stdout || process.stdout;
@@ -89,7 +89,7 @@ export async function runSkillScript(skillId, commandName, options = {}) {
         child.on("close", (code) => {
             clearTimeout(timeout);
             if (timedOut) {
-                stderr.write(`Tempo limite excedido (${timeoutSeconds}s).\n`);
+                stderr.write(`Timeout exceeded (${timeoutSeconds}s).\n`);
                 resolve(1);
                 return;
             }

package/dist/skill.d.ts

@@ -6,6 +6,8 @@ export interface SkillFrontmatter {
     description?: string | undefined;
     autoInject?: boolean | undefined;
     activationPrompt?: string | undefined;
+    /** Optional explicit category for the skill (e.g. "code", "infra", "docs"). */
+    category?: string | undefined;
 }
 /**
  * Parses the YAML-like frontmatter at the top of a `SKILL.md` file.

package/dist/skill.js

@@ -34,6 +34,9 @@ export function parseSkillFrontmatter(content) {
         if (key === "activationPrompt" && typeof value === "string") {
             values.activationPrompt = value;
         }
+        if (key === "category" && typeof value === "string") {
+            values.category = value;
+        }
     }
     return values;
 }

package/dist/sync.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { getAdapter } from "./adapters.js";
 import { copyPath, createSymlink, ensureDir, pathExists, readJson, readSymlink, readText, removePath, writeText, } from "./fs.js";
 import { normalizeSkillContent, parseSkillFrontmatter } from "./skill.js";
+import { warn as outputWarn } from "./output.js";
 import { SyncError } from "./types.js";
 const MANAGED_START = "<!-- SKILLEX:START -->";
 const MANAGED_END = "<!-- SKILLEX:END -->";
@@ -62,13 +63,14 @@ export async function syncAdapterFiles(options) {
             }
             else if (prepared.directoryEntries) {
                 await ensureDir(prepared.absoluteTargetPath);
-                const createLink = options.linkFactory || createSymlink;
+                const createLink = options.linkFactory
+                    || ((t, l) => createSymlink(t, l, { allowedRoot: options.statePaths.stateDir }));
                 let finalMode = prepared.syncMode;
                 for (const entry of prepared.directoryEntries) {
                     if (prepared.syncMode === "symlink") {
                         const linkResult = await createLink(entry.sourcePath, entry.absoluteTargetPath);
                         if (linkResult.fallback) {
-                            (options.warn || console.error)(`Aviso: symlink indisponivel para ${entry.targetPath}; usando copia no lugar.`);
+                            (options.warn || outputWarn)(`Symlink unavailable for ${entry.targetPath}; falling back to copy. Pass --mode copy to make this explicit.`);
                             await copyPath(entry.sourcePath, entry.absoluteTargetPath);
                             finalMode = "copy";
                         }
@@ -89,10 +91,11 @@ export async function syncAdapterFiles(options) {
                     await writeText(prepared.generatedSourcePath, prepared.nextContent);
                 }
                 if (prepared.syncMode === "symlink" && prepared.generatedSourcePath) {
-                    const createLink = options.linkFactory || createSymlink;
+                    const createLink = options.linkFactory
+                        || ((t, l) => createSymlink(t, l, { allowedRoot: options.statePaths.stateDir }));
                     const linkResult = await createLink(prepared.generatedSourcePath, prepared.absoluteTargetPath);
                     if (linkResult.fallback) {
-                        (options.warn || console.error)(`Aviso: symlink indisponivel para ${prepared.targetPath}; usando copia no lugar.`);
+                        (options.warn || outputWarn)(`Symlink unavailable for ${prepared.targetPath}; falling back to copy. Pass --mode copy to make this explicit.`);
                         await writeText(prepared.absoluteTargetPath, prepared.nextContent);
                         await removePath(prepared.generatedSourcePath);
                         prepared.syncMode = "copy";
@@ -119,7 +122,7 @@ export async function syncAdapterFiles(options) {
             throw error;
         }
         const message = error instanceof Error ? error.message : String(error);
-        throw new SyncError(`Falha ao sincronizar adapter ${options.adapterId}: ${message}`);
+        throw new SyncError(`Failed to sync adapter ${options.adapterId}: ${message}`);
     }
 }
 /**
@@ -147,7 +150,7 @@ export async function prepareSyncAdapterFiles(options) {
         throw new SyncError(`Adapter ${adapter.id} nao suporta sync global no momento. Use --scope local.`, "GLOBAL_SYNC_UNSUPPORTED");
     }
     if (!adapter.syncTarget) {
-        throw new SyncError(`Adapter ${adapter.id} nao define um alvo de sync.`, "SYNC_TARGET_MISSING");
+        throw new SyncError(`Adapter ${adapter.id} does not declare a sync target.`, "SYNC_TARGET_MISSING");
     }
     const body = renderInstalledSkills(options.skills);
     const autoInjectBlock = buildAutoInjectBlock(options.skills);
@@ -273,7 +276,7 @@ export function renderInstalledSkills(skills) {
         "",
     ];
     if (sections.length === 0) {
-        lines.push("Nenhuma skill instalada no momento.");
+        lines.push("No skills installed yet.");
     }
     else {
         lines.push(sections.join("\n\n---\n\n"));
@@ -369,7 +372,7 @@ function resolveAdapterTargetPath(adapter, options) {
         return path.resolve(adapter.globalSyncTarget);
     }
     if (!adapter.syncTarget) {
-        throw new SyncError(`Adapter ${adapter.id} nao define um alvo de sync.`, "SYNC_TARGET_MISSING");
+        throw new SyncError(`Adapter ${adapter.id} does not declare a sync target.`, "SYNC_TARGET_MISSING");
     }
     return path.join(options.cwd, adapter.syncTarget);
 }
@@ -406,7 +409,7 @@ function buildManagedFileContent(adapterId, body, autoInjectBlock) {
         case "cline":
             return `${sections.join("\n\n")}\n`;
         default:
-            throw new SyncError(`Adapter desconhecido: ${adapterId}`, "SYNC_ADAPTER_UNKNOWN");
+            throw new SyncError(`Unknown adapter: ${adapterId}`, "SYNC_ADAPTER_UNKNOWN");
     }
 }
 function wrapManagedBlock(start, end, body) {

package/dist/types.d.ts

@@ -77,6 +77,11 @@ export interface ParsedGitHubRepo {
 }
 /**
  * Skill manifest stored in catalog and local installs.
+ *
+ * `category` is optional. When present, it lets catalog publishers group
+ * skills explicitly (e.g. `"code"`, `"infra"`, `"docs"`) instead of relying
+ * on consumer-side regex inference. Consumers SHOULD prefer the declared
+ * value when one is provided.
  */
 export interface SkillManifest {
     id: string;
@@ -89,6 +94,7 @@ export interface SkillManifest {
     entry: string;
     path: string;
     files: string[];
+    category?: string | undefined;
     scripts?: Record<string, string> | undefined;
 }
 /**
@@ -375,12 +381,17 @@ export interface UpdateInstalledSkillsResult {
 }
 /**
  * Result returned by `removeSkills`.
+ *
+ * `autoSync` is preserved as the first adapter's result for backward
+ * compatibility; `autoSyncs` carries the full per-adapter aggregate so
+ * callers can report each adapter individually.
  */
 export interface RemoveSkillsResult {
     statePaths: StatePaths;
     removedSkills: string[];
     missingSkills: string[];
     autoSync: SyncCommandResult | null;
+    autoSyncs: SyncCommandResult[];
 }
 /**
  * Catalog loader signature override used in tests.
@@ -392,10 +403,15 @@ export type CatalogLoader = (source: CatalogSource) => Promise<CatalogData>;
 export type SkillDownloader = (skill: SkillManifest, catalog: CatalogData, stateDir: string) => Promise<void>;
 /**
  * Parsed CLI arguments.
+ *
+ * `positionalAfter` carries any tokens that follow a literal `--` end-of-options
+ * sentinel; this lets `skillex run x:cmd -- --foo --bar` forward `--foo --bar`
+ * to the underlying script without the parser interpreting them.
  */
 export interface ParsedArgs {
     command?: string | undefined;
     positionals: string[];
+    positionalAfter: string[];
     flags: Record<string, string | boolean>;
 }
 /**
@@ -478,3 +494,26 @@ export declare class CliError extends SkillexError {
      */
     constructor(message: string, code?: string);
 }
+/**
+ * Error thrown for HTTP failures, including timeouts, rate limits, and
+ * authentication failures. Preserves `status` and `url` for diagnostics.
+ *
+ * Possible `code` values:
+ * - `HTTP_TIMEOUT` — request aborted because of timeout
+ * - `HTTP_RATE_LIMIT` — GitHub rate limit exhausted
+ * - `HTTP_AUTH_FAILED` — 401 / 403 with auth-related cause
+ * - `HTTP_NOT_FOUND` — 404 surfaced as an error (non-optional fetchers)
+ * - `HTTP_SERVER_ERROR` — 5xx
+ * - `HTTP_ERROR` — fallback for other non-2xx responses
+ */
+export declare class HttpError extends SkillexError {
+    status?: number | undefined;
+    url?: string | undefined;
+    /**
+     * Creates an HTTP error.
+     */
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        url?: string;
+    });
+}

package/dist/types.js

@@ -81,3 +81,31 @@ export class CliError extends SkillexError {
         super(message, code);
     }
 }
+/**
+ * Error thrown for HTTP failures, including timeouts, rate limits, and
+ * authentication failures. Preserves `status` and `url` for diagnostics.
+ *
+ * Possible `code` values:
+ * - `HTTP_TIMEOUT` — request aborted because of timeout
+ * - `HTTP_RATE_LIMIT` — GitHub rate limit exhausted
+ * - `HTTP_AUTH_FAILED` — 401 / 403 with auth-related cause
+ * - `HTTP_NOT_FOUND` — 404 surfaced as an error (non-optional fetchers)
+ * - `HTTP_SERVER_ERROR` — 5xx
+ * - `HTTP_ERROR` — fallback for other non-2xx responses
+ */
+export class HttpError extends SkillexError {
+    status;
+    url;
+    /**
+     * Creates an HTTP error.
+     */
+    constructor(message, code, options = {}) {
+        super(message, code);
+        if (options.status !== undefined) {
+            this.status = options.status;
+        }
+        if (options.url !== undefined) {
+            this.url = options.url;
+        }
+    }
+}

package/dist/ui.js

@@ -24,7 +24,7 @@ export function filterCatalogForUi(skills, query) {
 export async function runInteractiveUi(options) {
     const prompts = options.prompts || (await loadPromptAdapters());
     const query = await (prompts.input || fallbackInput)({
-        message: "Filtro das skills (Enter para mostrar tudo)",
+        message: "Filter skills (press Enter to show all)",
         default: "",
     });
     const filteredSkills = filterCatalogForUi(options.skills, query);

package/dist/user-config.d.ts

@@ -34,6 +34,11 @@ export declare function readUserConfig(): Promise<UserConfig>;
 /**
  * Writes the global user configuration file, merging with any existing values.
  *
+ * The file is always written with mode `0o600` so any stored `githubToken` is
+ * not world-readable. If a previous version of the file existed with looser
+ * permissions, the mode is tightened on save and a one-time warning is
+ * printed during the session.
+ *
  * @param updates - Key/value pairs to write.
  */
 export declare function writeUserConfig(updates: Partial<UserConfig>): Promise<void>;

package/dist/user-config.js

@@ -43,6 +43,11 @@ export async function readUserConfig() {
 /**
  * Writes the global user configuration file, merging with any existing values.
  *
+ * The file is always written with mode `0o600` so any stored `githubToken` is
+ * not world-readable. If a previous version of the file existed with looser
+ * permissions, the mode is tightened on save and a one-time warning is
+ * printed during the session.
+ *
  * @param updates - Key/value pairs to write.
  */
 export async function writeUserConfig(updates) {
@@ -50,5 +55,21 @@ export async function writeUserConfig(updates) {
     const existing = await readUserConfig();
     const merged = { ...existing, ...updates };
     await fs.mkdir(path.dirname(configPath), { recursive: true });
-    await fs.writeFile(configPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+    let previousMode = null;
+    try {
+        const stat = await fs.stat(configPath);
+        previousMode = stat.mode & 0o777;
+    }
+    catch {
+        previousMode = null;
+    }
+    await fs.writeFile(configPath, JSON.stringify(merged, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    // `fs.writeFile` with `mode` only applies on file creation; chmod afterwards to
+    // tighten an existing file's permissions.
+    await fs.chmod(configPath, 0o600);
+    if (previousMode !== null && previousMode !== 0o600 && !looseConfigWarned) {
+        looseConfigWarned = true;
+        console.warn(`[skillex] Tightened permissions on ${configPath} from ${previousMode.toString(8)} to 600.`);
+    }
 }
+let looseConfigWarned = false;

package/dist/web-ui.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { listAdapters, resolveAdapterState } from "./adapters.js";
 import { buildRawGitHubUrl } from "./catalog.js";
 import { getScopedStatePaths } from "./config.js";
+import { runDoctorChecks } from "./doctor.js";
 import { readJson, readText } from "./fs.js";
 import { fetchText } from "./http.js";
 import { addProjectSource, getInstalledSkills, installSkills, listProjectSources, loadProjectCatalogs, removeProjectSource, removeSkills, syncInstalledSkills, updateInstalledSkills, } from "./install.js";
@@ -149,6 +150,10 @@ async function handleRequest(request, response, context) {
         sendJson(response, 200, await buildDashboardState(withRequestScope(context, url.searchParams.get("scope"))));
         return;
     }
+    if (method === "GET" && pathname === "/api/doctor") {
+        sendJson(response, 200, await runDoctorChecks(withRequestScope(context, url.searchParams.get("scope"))));
+        return;
+    }
     if (method === "GET" && pathname === "/api/catalog") {
         sendJson(response, 200, await buildCatalogResponse(withRequestScope(context, url.searchParams.get("scope"))));
         return;