@sporesec/arcana 2.4.0 → 3.0.1

package/dist/commands/verify.js

@@ -0,0 +1,116 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { getInstallDir, isSkillInstalled } from "../utils/fs.js";
+import { verifySkillIntegrity } from "../utils/integrity.js";
+import { validateSlug } from "../utils/validate.js";
+import { renderBanner } from "../utils/help.js";
+export async function verifyCommand(skillNames, opts) {
+    if (opts.json) {
+        return verifyJson(skillNames, opts);
+    }
+    console.log(renderBanner());
+    console.log();
+    const installDir = getInstallDir();
+    if (skillNames.length === 0 && !opts.all) {
+        p.intro(chalk.bold("Verify skill integrity"));
+        p.cancel("Specify a skill name or use --all");
+        p.log.info("Usage: arcana verify <skill-name> [skill2 ...]");
+        p.log.info("       arcana verify --all");
+        process.exit(1);
+    }
+    let skills;
+    if (opts.all) {
+        try {
+            skills = readdirSync(installDir).filter((d) => statSync(join(installDir, d)).isDirectory());
+        }
+        catch {
+            skills = [];
+        }
+        if (skills.length === 0) {
+            p.intro(chalk.bold("Verify skill integrity"));
+            p.log.info("No installed skills found.");
+            p.outro("Nothing to verify.");
+            return;
+        }
+    }
+    else {
+        for (const name of skillNames) {
+            try {
+                validateSlug(name, "skill name");
+            }
+            catch (err) {
+                p.log.error(err instanceof Error ? err.message : `Invalid skill name: ${name}`);
+                process.exit(1);
+            }
+        }
+        for (const name of skillNames) {
+            if (!isSkillInstalled(name)) {
+                p.log.error(`Skill ${chalk.bold(name)} is not installed.`);
+                process.exit(1);
+            }
+        }
+        skills = skillNames;
+    }
+    p.intro(chalk.bold("Verify skill integrity"));
+    const results = [];
+    for (const skill of skills) {
+        const status = verifySkillIntegrity(skill, installDir);
+        results.push({ skill, status });
+        if (status === "ok") {
+            p.log.info(`${chalk.green("[OK]")} ${skill}`);
+        }
+        else if (status === "modified") {
+            p.log.warn(`${chalk.yellow("[MODIFIED]")} ${skill}`);
+        }
+        else {
+            p.log.info(`${chalk.dim("[MISSING]")} ${skill}`);
+        }
+    }
+    const total = results.length;
+    const okCount = results.filter((r) => r.status === "ok").length;
+    const modifiedCount = results.filter((r) => r.status === "modified").length;
+    const missingCount = results.filter((r) => r.status === "missing").length;
+    console.log();
+    p.outro(`${total} skills verified, ${okCount} OK, ${modifiedCount} modified, ${missingCount} not tracked`);
+    if (modifiedCount > 0) {
+        process.exit(1);
+    }
+}
+async function verifyJson(skillNames, opts) {
+    const installDir = getInstallDir();
+    let skills;
+    if (opts.all) {
+        try {
+            skills = readdirSync(installDir).filter((d) => statSync(join(installDir, d)).isDirectory());
+        }
+        catch {
+            skills = [];
+        }
+    }
+    else if (skillNames.length === 0) {
+        console.log(JSON.stringify({ error: "Specify a skill name or use --all" }));
+        process.exit(1);
+        return;
+    }
+    else {
+        skills = skillNames;
+    }
+    const results = [];
+    for (const skill of skills) {
+        const status = verifySkillIntegrity(skill, installDir);
+        results.push({ skill, status });
+    }
+    const total = results.length;
+    const ok = results.filter((r) => r.status === "ok").length;
+    const modified = results.filter((r) => r.status === "modified").length;
+    const missing = results.filter((r) => r.status === "missing").length;
+    console.log(JSON.stringify({
+        results: results.map((r) => ({ skill: r.skill, status: r.status })),
+        summary: { total, ok, modified, missing },
+    }));
+    if (modified > 0) {
+        process.exit(1);
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const AGENT_LOG_MAX_AGE_DAYS = 7;
+export declare const MAIN_LOG_MAX_AGE_DAYS = 30;
+export declare const STALE_PROJECT_DAYS = 90;
+export declare const PRUNE_DEFAULT_DAYS = 14;
+export declare const PRUNE_SIZE_THRESHOLD_BYTES: number;
+export declare const PRUNE_KEEP_NEWEST = 3;
+export declare const LARGE_SKILL_KB_THRESHOLD = 50;
+export declare const TOKENS_PER_KB = 256;
+export declare const CONTEXT_WINDOW_TOKENS = 200000;
+export declare const DESCRIPTION_TRUNCATION = 50;

package/dist/constants.js

@@ -0,0 +1,13 @@
+// Retention & pruning
+export const AGENT_LOG_MAX_AGE_DAYS = 7;
+export const MAIN_LOG_MAX_AGE_DAYS = 30;
+export const STALE_PROJECT_DAYS = 90;
+export const PRUNE_DEFAULT_DAYS = 14;
+export const PRUNE_SIZE_THRESHOLD_BYTES = 10 * 1024 * 1024; // 10 MB
+export const PRUNE_KEEP_NEWEST = 3;
+// Skill size warnings
+export const LARGE_SKILL_KB_THRESHOLD = 50;
+export const TOKENS_PER_KB = 256;
+export const CONTEXT_WINDOW_TOKENS = 200_000;
+// Display
+export const DESCRIPTION_TRUNCATION = 50;

package/dist/index.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -36,4 +36,3 @@ catch (err) {
     }
     process.exit(1);
 }
-//# sourceMappingURL=index.js.map

package/dist/interactive/browse.d.ts

@@ -0,0 +1,4 @@
+import type { SkillInfo } from "../types.js";
+declare function doBatchInstall(names: string[], providerName: string): Promise<number>;
+export declare function browseByCategory(allSkills: SkillInfo[], providerName: string): Promise<void>;
+export { doBatchInstall };

package/dist/interactive/browse.js

@@ -0,0 +1,103 @@
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { isSkillInstalled } from "../utils/fs.js";
+import { getProvider } from "../registry.js";
+import { installOneCore } from "../utils/install-core.js";
+import { appendHistory } from "../utils/history.js";
+import { ui } from "../utils/ui.js";
+import { handleCancel, truncate } from "./helpers.js";
+import { SKILL_CATEGORIES } from "./categories.js";
+import { skillDetailFlow } from "./skill-detail.js";
+async function doBatchInstall(names, providerName) {
+    if (names.length === 0)
+        return 0;
+    const provider = getProvider(providerName);
+    const s = p.spinner();
+    s.start(`Installing ${names.length} skill${names.length > 1 ? "s" : ""}...`);
+    let installed = 0;
+    for (const name of names) {
+        try {
+            s.message(`Installing ${chalk.bold(name)} (${installed + 1}/${names.length})...`);
+            const result = await installOneCore(name, provider, {});
+            if (result.success) {
+                installed++;
+                appendHistory("install", name);
+            }
+        }
+        catch (err) {
+            s.stop(`Failed: ${name}`);
+            if (err instanceof Error)
+                p.log.error(ui.dim(err.message));
+            if (installed + 1 < names.length)
+                s.start(`Installing next...`);
+        }
+    }
+    s.stop(`Installed ${installed} skill${installed !== 1 ? "s" : ""}`);
+    return installed;
+}
+export async function browseByCategory(allSkills, providerName) {
+    const availableNames = new Set(allSkills.map((s) => s.name));
+    while (true) {
+        const categoryOptions = Object.entries(SKILL_CATEGORIES).map(([name, skills]) => {
+            const valid = skills.filter((s) => availableNames.has(s));
+            const installedCount = valid.filter((s) => isSkillInstalled(s)).length;
+            return {
+                value: name,
+                label: name,
+                hint: `${valid.length} skills, ${installedCount} installed`,
+            };
+        });
+        const category = await p.select({
+            message: "Browse by category",
+            options: [...categoryOptions, { value: "__back", label: "Back" }],
+        });
+        handleCancel(category);
+        if (category === "__back")
+            return;
+        await categorySkillList(category, SKILL_CATEGORIES[category] ?? [], allSkills, providerName);
+    }
+}
+async function categorySkillList(categoryName, skillNames, allSkills, providerName) {
+    const availableNames = new Set(allSkills.map((s) => s.name));
+    const validSkills = skillNames.filter((s) => availableNames.has(s));
+    if (validSkills.length === 0) {
+        p.log.warn("No skills found in this category.");
+        return;
+    }
+    while (true) {
+        const options = validSkills.map((name) => {
+            const info = allSkills.find((s) => s.name === name);
+            const installed = isSkillInstalled(name);
+            return {
+                value: name,
+                label: `${name}${installed ? chalk.green(" \u2713") : ""}`,
+                hint: truncate(info?.description ?? "", 50),
+            };
+        });
+        const notInstalled = validSkills.filter((s) => !isSkillInstalled(s));
+        const extraOptions = [];
+        if (notInstalled.length > 0) {
+            extraOptions.push({
+                value: "__install_all",
+                label: `Install all uninstalled`,
+                hint: `${notInstalled.length} skill${notInstalled.length > 1 ? "s" : ""}`,
+            });
+        }
+        extraOptions.push({ value: "__back", label: "Back to categories" });
+        const picked = await p.select({
+            message: `${categoryName} (${validSkills.length} skills)`,
+            options: [...options, ...extraOptions],
+        });
+        handleCancel(picked);
+        if (picked === "__back")
+            return;
+        if (picked === "__install_all") {
+            await doBatchInstall(notInstalled, providerName);
+            continue;
+        }
+        const result = await skillDetailFlow(picked, allSkills, providerName);
+        if (result === "menu")
+            return;
+    }
+}
+export { doBatchInstall };

package/dist/interactive/categories.d.ts

@@ -0,0 +1,4 @@
+declare const SKILL_CATEGORIES: Record<string, string[]>;
+export { SKILL_CATEGORIES };
+export declare function getCategoryFor(skillName: string): string | undefined;
+export declare function getRelatedSkills(skillName: string, limit?: number): string[];

package/dist/interactive/categories.js

@@ -0,0 +1,87 @@
+import { isSkillInstalled } from "../utils/fs.js";
+// Category map (7 categories, 4-12 skills each, no orphans)
+const SKILL_CATEGORIES = {
+    "Code Quality & Review": [
+        "code-reviewer",
+        "codebase-dissection",
+        "testing-strategy",
+        "refactoring-patterns",
+        "git-workflow",
+        "pre-production-review",
+        "frontend-code-review",
+        "dependency-audit",
+        "performance-optimization",
+    ],
+    "Security & Infrastructure": [
+        "security-review",
+        "local-security",
+        "container-security",
+        "docker-kubernetes",
+        "ci-cd-pipelines",
+        "ci-cd-automation",
+        "monitoring-observability",
+        "incident-response",
+    ],
+    "Languages & Frameworks": [
+        "golang-pro",
+        "go-linter-configuration",
+        "typescript",
+        "typescript-advanced",
+        "python-best-practices",
+        "rust-best-practices",
+        "frontend-design",
+        "fullstack-developer",
+        "remotion-best-practices",
+        "npm-package",
+    ],
+    "API, Data & Docs": [
+        "api-design",
+        "api-testing",
+        "programming-architecture",
+        "database-design",
+        "env-config",
+        "cost-optimization",
+        "docx",
+        "xlsx",
+        "doc-generation",
+        "update-docs",
+    ],
+    "Game Design & Production": [
+        "game-design-theory",
+        "game-engines",
+        "game-programming-languages",
+        "gameplay-mechanics",
+        "level-design",
+        "game-tools-workflows",
+        "game-servers",
+        "networking-servers",
+        "synchronization-algorithms",
+        "monetization-systems",
+        "publishing-platforms",
+        "daw-music",
+    ],
+    "Graphics, Audio & Performance": [
+        "graphics-rendering",
+        "shader-techniques",
+        "particle-systems",
+        "audio-systems",
+        "asset-optimization",
+        "optimization-performance",
+        "memory-management",
+    ],
+    "Skill Development": ["skill-creation-guide", "skill-creator", "find-skills", "project-migration"],
+};
+export { SKILL_CATEGORIES };
+export function getCategoryFor(skillName) {
+    for (const [cat, skills] of Object.entries(SKILL_CATEGORIES)) {
+        if (skills.includes(skillName))
+            return cat;
+    }
+    return undefined;
+}
+export function getRelatedSkills(skillName, limit = 3) {
+    const cat = getCategoryFor(skillName);
+    if (!cat)
+        return [];
+    return (SKILL_CATEGORIES[cat] ?? []).filter((s) => s !== skillName && !isSkillInstalled(s)).slice(0, limit);
+}

package/dist/interactive/health.d.ts

@@ -0,0 +1 @@
+export declare function checkHealth(): Promise<void>;

package/dist/interactive/health.js

@@ -0,0 +1,57 @@
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { runDoctorChecks } from "../commands/doctor.js";
+import { handleCancel } from "./helpers.js";
+export async function checkHealth() {
+    const checks = runDoctorChecks();
+    p.log.step(chalk.bold("Environment Health Check"));
+    for (const check of checks) {
+        const icon = check.status === "pass" ? chalk.green("OK") : check.status === "warn" ? chalk.yellow("!!") : chalk.red("XX");
+        p.log.info(`${icon}  ${chalk.bold(check.name)}: ${check.message}`);
+        if (check.fix)
+            p.log.info(chalk.dim(`    Fix: ${check.fix}`));
+    }
+    const fails = checks.filter((c) => c.status === "fail").length;
+    const warns = checks.filter((c) => c.status === "warn").length;
+    if (fails > 0) {
+        p.log.error(`${fails} issue${fails > 1 ? "s" : ""} found`);
+    }
+    else if (warns > 0) {
+        p.log.warn(`${warns} warning${warns > 1 ? "s" : ""}`);
+    }
+    else {
+        p.log.success("All checks passed");
+        return;
+    }
+    // Offer fixes once
+    const fixChecks = checks.filter((c) => c.fix && c.status !== "pass");
+    if (fixChecks.length === 0)
+        return;
+    const fixOptions = fixChecks.map((c) => {
+        const cmd = c.fix.replace(/^Run:\s*/, "");
+        return { value: cmd, label: `Run: ${cmd}`, hint: c.name };
+    });
+    const fixAction = await p.select({
+        message: "Run a fix?",
+        options: [...fixOptions, { value: "__skip", label: "Skip" }],
+    });
+    handleCancel(fixAction);
+    if (fixAction !== "__skip") {
+        const cmd = fixAction;
+        const SAFE_PREFIXES = ["arcana ", "git config "];
+        if (!SAFE_PREFIXES.some((pre) => cmd.startsWith(pre))) {
+            p.log.warn(`Skipped unsafe command: ${cmd}`);
+        }
+        else {
+            p.log.info(chalk.dim(`Running: ${cmd}`));
+            try {
+                const { execSync } = await import("node:child_process");
+                execSync(cmd, { stdio: "inherit" });
+            }
+            catch {
+                // Non-zero exit expected for some commands
+            }
+        }
+        p.log.info(chalk.dim("Run health check again to verify."));
+    }
+}

package/dist/interactive/helpers.d.ts

@@ -0,0 +1,11 @@
+export declare const AMBER: import("chalk").ChalkInstance;
+export declare function cancelAndExit(): never;
+export declare function handleCancel(value: unknown): void;
+export declare function countInstalled(): number;
+export declare function truncate(str: string, max: number): string;
+export declare function getInstalledNames(): string[];
+export declare function buildMenuOptions(installedCount: number, _availableCount: number): {
+    value: string;
+    label: string;
+    hint?: string;
+}[];

package/dist/interactive/helpers.js

@@ -0,0 +1,66 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { getInstallDir } from "../utils/fs.js";
+import { clearProviderCache } from "../registry.js";
+export const AMBER = chalk.hex("#d4943a");
+export function cancelAndExit() {
+    clearProviderCache();
+    p.cancel("Goodbye.");
+    process.exit(0);
+}
+export function handleCancel(value) {
+    if (p.isCancel(value))
+        cancelAndExit();
+}
+export function countInstalled() {
+    const dir = getInstallDir();
+    if (!existsSync(dir))
+        return 0;
+    return readdirSync(dir).filter((d) => {
+        try {
+            return statSync(join(dir, d)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }).length;
+}
+export function truncate(str, max) {
+    return str.length > max ? str.slice(0, max) + "..." : str;
+}
+export function getInstalledNames() {
+    const dir = getInstallDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((d) => {
+        try {
+            return statSync(join(dir, d)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
+export function buildMenuOptions(installedCount, _availableCount) {
+    const isNew = installedCount === 0;
+    const options = [];
+    if (isNew) {
+        options.push({ value: "setup", label: AMBER("Get Started"), hint: "detect project, install recommended skills" });
+    }
+    else {
+        options.push({ value: "installed", label: "Manage installed skills", hint: `${installedCount} installed` });
+    }
+    options.push({ value: "browse", label: "Browse skills by category" });
+    options.push({ value: "search", label: "Search for a skill" });
+    if (!isNew) {
+        options.push({ value: "setup", label: "Get Started", hint: "detect project, add more skills" });
+    }
+    options.push({ value: "health", label: "Check environment health" });
+    options.push({ value: "ref", label: "CLI reference" });
+    options.push({ value: "exit", label: "Exit" });
+    return options;
+}

package/dist/interactive/index.d.ts

@@ -0,0 +1 @@
+export { showInteractiveMenu } from "./menu.js";

package/dist/interactive/index.js

@@ -0,0 +1 @@
+export { showInteractiveMenu } from "./menu.js";

package/dist/interactive/manage.d.ts

@@ -0,0 +1,2 @@
+import type { SkillInfo } from "../types.js";
+export declare function manageInstalled(allSkills: SkillInfo[], providerName: string): Promise<void>;