@sporesec/arcana 3.0.1 → 3.0.2

package/dist/commands/uninstall.js

@@ -5,6 +5,7 @@ import chalk from "chalk";
 import { getSkillDir, listSymlinks, readSkillMeta } from "../utils/fs.js";
 import { renderBanner } from "../utils/help.js";
 import { validateSlug } from "../utils/validate.js";
+import { backupSkill } from "../utils/backup.js";
 export async function uninstallCommand(skillNames, opts = {}) {
     if (opts.json) {
         return uninstallJson(skillNames);
@@ -49,7 +50,8 @@ async function uninstallOneInteractive(skillName, skipConfirm) {
         }
     }
     const spin = p.spinner();
-    spin.start(`Removing ${skillName}...`);
+    spin.start(`Backing up and removing ${skillName}...`);
+    backupSkill(skillName);
     rmSync(skillDir, { recursive: true, force: true });
     const symlinksRemoved = removeSymlinksFor(skillName);
     spin.stop(`Removed ${chalk.bold(skillName)}`);
@@ -88,6 +90,7 @@ async function uninstallMultipleInteractive(skillNames, skipConfirm) {
     for (let i = 0; i < toRemove.length; i++) {
         const skillName = toRemove[i];
         spin.start(`Removing ${chalk.bold(skillName)} (${i + 1}/${toRemove.length})...`);
+        backupSkill(skillName);
         rmSync(getSkillDir(skillName), { recursive: true, force: true });
         totalSymlinks += removeSymlinksFor(skillName);
     }

package/dist/interactive/browse.js

@@ -48,7 +48,7 @@ export async function browseByCategory(allSkills, providerName) {
             };
         });
         const category = await p.select({
-            message: "Browse by category",
+            message: "Browse > Select category",
             options: [...categoryOptions, { value: "__back", label: "Back" }],
         });
         handleCancel(category);
@@ -85,7 +85,7 @@ async function categorySkillList(categoryName, skillNames, allSkills, providerNa
         }
         extraOptions.push({ value: "__back", label: "Back to categories" });
         const picked = await p.select({
-            message: `${categoryName} (${validSkills.length} skills)`,
+            message: `Browse > ${categoryName}`,
             options: [...options, ...extraOptions],
         });
         handleCancel(picked);

package/dist/interactive/health.js

@@ -3,40 +3,47 @@ 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") {
+    while (true) {
+        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;
+        }
+        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: "__recheck", label: "Re-check now" },
+                { value: "__back", label: "Back to menu" },
+            ],
+        });
+        handleCancel(fixAction);
+        if (fixAction === "__back")
+            return;
+        if (fixAction === "__recheck")
+            continue;
         const cmd = fixAction;
         const SAFE_PREFIXES = ["arcana ", "git config "];
         if (!SAFE_PREFIXES.some((pre) => cmd.startsWith(pre))) {
@@ -52,6 +59,6 @@ export async function checkHealth() {
                 // Non-zero exit expected for some commands
             }
         }
-        p.log.info(chalk.dim("Run health check again to verify."));
+        // Loop continues, re-runs checks automatically
     }
 }

package/dist/interactive/helpers.d.ts

@@ -4,6 +4,20 @@ 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 getTokenEstimate(skillName: string): {
+    tokens: number;
+    kb: number;
+};
+export declare function getTotalTokenBudget(): {
+    totalKB: number;
+    totalTokens: number;
+    count: number;
+    skills: {
+        name: string;
+        tokens: number;
+        kb: number;
+    }[];
+};
 export declare function buildMenuOptions(installedCount: number, _availableCount: number): {
     value: string;
     label: string;

package/dist/interactive/helpers.js

@@ -2,7 +2,7 @@ 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 { getInstallDir, getSkillDir, getDirSize } from "../utils/fs.js";
 import { clearProviderCache } from "../registry.js";
 export const AMBER = chalk.hex("#d4943a");
 export function cancelAndExit() {
@@ -45,21 +45,48 @@ export function getInstalledNames() {
     })
         .sort();
 }
+export function getTokenEstimate(skillName) {
+    const dir = getSkillDir(skillName);
+    if (!existsSync(dir))
+        return { tokens: 0, kb: 0 };
+    const bytes = getDirSize(dir);
+    return { tokens: Math.round(bytes / 4), kb: Math.round(bytes / 1024) };
+}
+export function getTotalTokenBudget() {
+    const names = getInstalledNames();
+    const skills = names.map((name) => {
+        const est = getTokenEstimate(name);
+        return { name, tokens: est.tokens, kb: est.kb };
+    });
+    skills.sort((a, b) => b.tokens - a.tokens);
+    const totalKB = skills.reduce((sum, s) => sum + s.kb, 0);
+    const totalTokens = skills.reduce((sum, s) => sum + s.tokens, 0);
+    return { totalKB, totalTokens, count: names.length, skills };
+}
 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" });
+        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: "installed",
+            label: "Your skills",
+            hint: `${installedCount} installed, manage & update`,
+        });
     }
-    options.push({ value: "browse", label: "Browse skills by category" });
-    options.push({ value: "search", label: "Search for a skill" });
+    options.push({ value: "browse", label: "Browse marketplace" });
+    options.push({ value: "search", label: "Search skills" });
     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: "health", label: "Health check" });
+    options.push({ value: "optimize", label: "Token budget" });
     options.push({ value: "ref", label: "CLI reference" });
     options.push({ value: "exit", label: "Exit" });
     return options;

package/dist/interactive/manage.js

@@ -35,7 +35,7 @@ export async function manageInstalled(allSkills, providerName) {
             hint: `${g.skills.length} installed`,
         }));
         const picked = await p.select({
-            message: `Installed skills (${names.length})`,
+            message: `Your skills > Select category`,
             options: [
                 ...options,
                 { value: "__update", label: chalk.cyan("Check for updates") },
@@ -78,7 +78,7 @@ async function installedCategoryList(categoryName, installedNames, allSkills, pr
             };
         });
         const picked = await p.select({
-            message: `${categoryName} (${stillInstalled.length} installed)`,
+            message: `Your skills > ${categoryName}`,
             options: [...options, { value: "__back", label: "Back" }],
         });
         handleCancel(picked);
@@ -108,7 +108,7 @@ async function bulkUninstall(installedNames) {
         return;
     let removed = 0;
     for (const name of names) {
-        if (doUninstall(name))
+        if (doUninstall(name).success)
             removed++;
     }
     p.log.success(`Removed ${removed} skill${removed !== 1 ? "s" : ""}`);

package/dist/interactive/menu.js

@@ -11,6 +11,7 @@ import { searchFlow } from "./search.js";
 import { quickSetup } from "./setup.js";
 import { manageInstalled } from "./manage.js";
 import { checkHealth } from "./health.js";
+import { optimizeInteractive } from "./optimize-flow.js";
 export async function showInteractiveMenu(version) {
     const config = loadConfig();
     const providerName = config.defaultProvider;
@@ -93,6 +94,9 @@ export async function showInteractiveMenu(version) {
                 case "health":
                     await checkHealth();
                     break;
+                case "optimize":
+                    await optimizeInteractive();
+                    break;
                 case "ref":
                     p.note(getCliReference(), "CLI Reference");
                     break;

package/dist/interactive/optimize-flow.d.ts

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

package/dist/interactive/optimize-flow.js

@@ -0,0 +1,36 @@
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { getTotalTokenBudget, AMBER, handleCancel } from "./helpers.js";
+export async function optimizeInteractive() {
+    const budget = getTotalTokenBudget();
+    const barWidth = 30;
+    const maxTokens = 200_000;
+    const pct = Math.min(100, Math.round((budget.totalTokens / maxTokens) * 100));
+    const filled = Math.round((pct / 100) * barWidth);
+    const bar = AMBER("█".repeat(filled)) + chalk.dim("░".repeat(barWidth - filled));
+    const lines = [];
+    lines.push(`${bar}  ${pct}% of 200K context window`);
+    lines.push("");
+    lines.push(`${chalk.bold(String(budget.count))} skills installed, ${chalk.bold(String(budget.totalKB))} KB total (~${(budget.totalTokens / 1000).toFixed(0)}K tokens)`);
+    if (budget.skills.length > 0) {
+        lines.push("");
+        lines.push(chalk.dim("Largest skills:"));
+        for (const s of budget.skills.slice(0, 7)) {
+            const pctOfTotal = budget.totalTokens > 0 ? Math.round((s.tokens / budget.totalTokens) * 100) : 0;
+            lines.push(`  ${s.name.padEnd(32)} ${String(s.kb).padStart(4)} KB  ${String(pctOfTotal).padStart(3)}%`);
+        }
+    }
+    p.note(lines.join("\n"), "Token Budget");
+    const action = await p.select({
+        message: "What next?",
+        options: [
+            { value: "full", label: "Run full optimization report" },
+            { value: "__back", label: "Back" },
+        ],
+    });
+    handleCancel(action);
+    if (action === "full") {
+        const { optimizeCommand } = await import("../commands/optimize.js");
+        await optimizeCommand({ json: false });
+    }
+}

package/dist/interactive/search.js

@@ -51,7 +51,7 @@ async function searchResultsPicker(results, allSkills, providerName) {
             hint: truncate(skill.description, 50),
         }));
         const picked = await p.select({
-            message: "Pick a skill for details",
+            message: `Search > Results`,
             options: [...options, { value: "__search", label: "Search again" }, { value: "__back", label: "Back" }],
         });
         handleCancel(picked);

package/dist/interactive/skill-detail.d.ts

@@ -1,5 +1,8 @@
 import type { SkillInfo } from "../types.js";
 declare function doInstall(skillName: string, providerName: string): Promise<boolean>;
-declare function doUninstall(skillName: string): boolean;
+declare function doUninstall(skillName: string): {
+    success: boolean;
+    backupPath?: string;
+};
 export declare function skillDetailFlow(skillName: string, allSkills: SkillInfo[], providerName: string): Promise<"back" | "menu">;
 export { doInstall, doUninstall };

package/dist/interactive/skill-detail.js

@@ -1,12 +1,13 @@
 import { existsSync, rmSync } from "node:fs";
 import * as p from "@clack/prompts";
 import chalk from "chalk";
-import { isSkillInstalled, readSkillMeta, getSkillDir } from "../utils/fs.js";
-import { getProvider } from "../registry.js";
+import { isSkillInstalled, readSkillMeta, getSkillDir, getDirSize } from "../utils/fs.js";
 import { appendHistory } from "../utils/history.js";
 import { installOneCore } from "../utils/install-core.js";
+import { backupSkill } from "../utils/backup.js";
 import { removeSymlinksFor } from "../commands/uninstall.js";
 import { ui } from "../utils/ui.js";
+import { getProvider } from "../registry.js";
 import { handleCancel } from "./helpers.js";
 import { getCategoryFor, getRelatedSkills } from "./categories.js";
 async function doInstall(skillName, providerName) {
@@ -35,69 +36,93 @@ async function doInstall(skillName, providerName) {
 function doUninstall(skillName) {
     const skillDir = getSkillDir(skillName);
     if (!existsSync(skillDir))
-        return false;
+        return { success: false };
     try {
+        const backupPath = backupSkill(skillName);
         rmSync(skillDir, { recursive: true, force: true });
         removeSymlinksFor(skillName);
         appendHistory("uninstall", skillName);
-        return true;
+        return { success: true, backupPath: backupPath ?? undefined };
     }
     catch {
-        return false;
+        return { success: false };
     }
 }
+function getTokenEstimate(skillName) {
+    const dir = getSkillDir(skillName);
+    if (!existsSync(dir))
+        return { tokens: 0, kb: 0 };
+    const bytes = getDirSize(dir);
+    return { tokens: Math.round(bytes / 4), kb: Math.round(bytes / 1024) };
+}
 export async function skillDetailFlow(skillName, allSkills, providerName) {
     const info = allSkills.find((s) => s.name === skillName);
     const installed = isSkillInstalled(skillName);
     const meta = installed ? readSkillMeta(skillName) : null;
-    // Build info block
+    // Build info block with visual hierarchy
     const lines = [];
-    lines.push(`${chalk.bold(skillName)} ${info ? `v${info.version}` : ""}`);
+    // Header
+    lines.push(`${chalk.bold(skillName)} ${info ? chalk.dim(`v${info.version}`) : ""}`);
     if (info?.description)
-        lines.push(info.description);
+        lines.push(chalk.dim(info.description));
     lines.push("");
+    // Status (most important, shown first)
+    if (installed && meta) {
+        const date = meta.installedAt ? new Date(meta.installedAt).toLocaleDateString() : "";
+        const est = getTokenEstimate(skillName);
+        const tokenStr = est.tokens > 0 ? `  ~${(est.tokens / 1000).toFixed(1)}K tokens` : "";
+        lines.push(`${chalk.green("Installed")}  v${meta.version}${date ? `  ${date}` : ""}${tokenStr}`);
+    }
+    else {
+        lines.push(chalk.dim("Not installed"));
+    }
+    lines.push("");
+    // Aligned metadata
+    const metadata = [];
     if (info?.verified)
-        lines.push(`Trust: ${chalk.green("Verified")} (official)`);
+        metadata.push(["Trust", chalk.green("Verified (official)")]);
     else
-        lines.push(`Trust: Community`);
+        metadata.push(["Trust", "Community"]);
     if (info?.author)
-        lines.push(`Author: ${info.author}`);
+        metadata.push(["Author", info.author]);
     if (info?.tags && info.tags.length > 0)
-        lines.push(`Tags: ${info.tags.join(", ")}`);
+        metadata.push(["Tags", info.tags.join(", ")]);
     const category = getCategoryFor(skillName);
     if (category)
-        lines.push(`Category: ${category}`);
-    if (info?.source)
-        lines.push(`Source: ${info.source}`);
-    if (info?.companions && info.companions.length > 0) {
-        lines.push(`Companions: ${info.companions.join(", ")}`);
-    }
-    if (info?.conflicts && info.conflicts.length > 0) {
-        lines.push(`${chalk.red("Conflicts:")} ${info.conflicts.join(", ")}`);
-    }
-    if (installed && meta) {
-        const date = meta.installedAt ? new Date(meta.installedAt).toLocaleDateString() : "";
-        lines.push(`Status: ${chalk.green("installed")} (v${meta.version}${date ? `, ${date}` : ""})`);
-    }
-    else {
-        lines.push(`Status: ${chalk.dim("not installed")}`);
+        metadata.push(["Category", category]);
+    const maxLabel = Math.max(...metadata.map(([k]) => k.length));
+    for (const [key, val] of metadata) {
+        lines.push(`${chalk.dim(key.padEnd(maxLabel + 1))} ${val}`);
     }
+    // Relations
     const related = getRelatedSkills(skillName);
-    if (related.length > 0) {
-        lines.push(`Related: ${related.join(", ")}`);
+    const hasRelations = (info?.companions && info.companions.length > 0) ||
+        (info?.conflicts && info.conflicts.length > 0) ||
+        related.length > 0;
+    if (hasRelations) {
+        lines.push("");
+        if (info?.companions && info.companions.length > 0) {
+            lines.push(`${chalk.dim("Works with:")} ${info.companions.join(", ")}`);
+        }
+        if (info?.conflicts && info.conflicts.length > 0) {
+            lines.push(`${chalk.red("Conflicts:")}  ${info.conflicts.join(", ")}`);
+        }
+        if (related.length > 0) {
+            lines.push(`${chalk.dim("Related:")}    ${related.join(", ")}`);
+        }
     }
     p.note(lines.join("\n"), skillName);
     // Action menu
     const actions = [];
     if (installed) {
-        actions.push({ value: "reinstall", label: "Reinstall (overwrite)" });
-        actions.push({ value: "uninstall", label: "Uninstall (remove files)" });
+        actions.push({ value: "reinstall", label: "Update to latest" });
+        actions.push({ value: "uninstall", label: "Uninstall" });
     }
     else {
         actions.push({ value: "install", label: "Install this skill" });
     }
-    actions.push({ value: "back", label: "Back" });
-    const action = await p.select({ message: "Action", options: actions });
+    actions.push({ value: "__back", label: "Back" });
+    const action = await p.select({ message: `${skillName} > Action`, options: actions });
     handleCancel(action);
     switch (action) {
         case "install":
@@ -106,12 +131,21 @@ export async function skillDetailFlow(skillName, allSkills, providerName) {
             return "back";
         }
         case "uninstall": {
+            // Dry-run preview
+            const skillDir = getSkillDir(skillName);
+            const size = getDirSize(skillDir);
+            p.log.info(chalk.dim(`  Will remove: ${skillDir}`));
+            p.log.info(chalk.dim(`  Size: ${(size / 1024).toFixed(0)} KB (${meta?.fileCount ?? "?"} files)`));
+            p.log.info(chalk.dim(`  A backup will be created before removal.`));
             const ok = await p.confirm({ message: `Uninstall ${chalk.bold(skillName)}?` });
             handleCancel(ok);
             if (ok) {
-                const success = doUninstall(skillName);
-                if (success) {
+                const result = doUninstall(skillName);
+                if (result.success) {
                     p.log.success(`Removed ${chalk.bold(skillName)}`);
+                    if (result.backupPath) {
+                        p.log.info(chalk.dim(`  Backup: ${result.backupPath}`));
+                    }
                 }
                 else {
                     p.log.error(`Failed to remove ${skillName}`);

package/dist/utils/backup.d.ts

@@ -0,0 +1,3 @@
+export declare function getBackupDir(): string;
+export declare function backupSkill(skillName: string): string | null;
+export declare function pruneOldBackups(skillName: string): void;

package/dist/utils/backup.js

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, cpSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { getSkillDir } from "./fs.js";
+const BACKUP_DIR = join(homedir(), ".arcana", "backups");
+const MAX_BACKUPS_PER_SKILL = 10;
+export function getBackupDir() {
+    return BACKUP_DIR;
+}
+export function backupSkill(skillName) {
+    const skillDir = getSkillDir(skillName);
+    if (!existsSync(skillDir))
+        return null;
+    mkdirSync(BACKUP_DIR, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const dest = join(BACKUP_DIR, `${skillName}_${timestamp}`);
+    cpSync(skillDir, dest, { recursive: true });
+    pruneOldBackups(skillName);
+    return dest;
+}
+export function pruneOldBackups(skillName) {
+    if (!existsSync(BACKUP_DIR))
+        return;
+    const prefix = `${skillName}_`;
+    const entries = readdirSync(BACKUP_DIR)
+        .filter((d) => d.startsWith(prefix))
+        .sort();
+    while (entries.length > MAX_BACKUPS_PER_SKILL) {
+        const oldest = entries.shift();
+        rmSync(join(BACKUP_DIR, oldest), { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporesec/arcana",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Universal AI development CLI. Skills, scaffolding, diagnostics, and analytics for every agent.",
   "bin": {
     "arcana": "dist/index.js"