@oomerevren/tryforge 0.1.2 → 0.1.3

package/dist/cli/src/commands/sync.js

@@ -0,0 +1,181 @@
+// cli/src/commands/sync.ts — One-command team sync (Phase 3).
+//
+// A developer clones the repo and runs `npx forge sync`: forge.toml is read,
+// every skill/dependency is resolved (registry or decentralized source),
+// content lands in the store, and the CURRENTLY DETECTED editors all receive
+// the same skills, rule files (Cursor MDC, CLAUDE.md, .windsurfrules,
+// AGENTS.md), and [mcp.servers.*] configs. Agent roles sync as a team block
+// in <project>/AGENTS.md. A deterministic forge.lock is written.
+import { resolve, join } from "path";
+import { resolveVersion } from "../core/registry.js";
+import { ensurePackageContent } from "../core/installer.js";
+import { ensureForgeDirs, readLinks, writeLinks, toSlug } from "../core/store.js";
+import { allAdapters, detectAdapters, addMcpServerToConfig } from "../adapters/index.js";
+import { findProjectToml, loadProjectToml, validateProjectToml, } from "../core/project.js";
+import { writeLock, lockEntryFor } from "../core/lock.js";
+import { parseSourceArg, resolveExternalSource } from "../core/sources.js";
+import { storeExternal } from "./add-external.js";
+import { scanPackageDir } from "../core/scan.js";
+import { upsertForgeBlock } from "../core/merge.js";
+/** Inject [mcp.servers.*] defs into every adapter config that supports it. Returns servers injected. */
+export function injectMcpServers(adapters, servers) {
+    let mcpCount = 0;
+    for (const [serverName, def] of Object.entries(servers)) {
+        for (const adapter of adapters) {
+            try {
+                const cfgPath = adapter.mcpConfigPath();
+                if (cfgPath) {
+                    addMcpServerToConfig(cfgPath, serverName, { command: def.command, args: def.args, env: def.env });
+                    mcpCount++;
+                }
+            }
+            catch (e) {
+                console.warn(`  ! MCP ${serverName} → ${adapter.displayName} failed: ${e.message}`);
+            }
+        }
+    }
+    return mcpCount;
+}
+function pickAdapters(projectHarnesses) {
+    if (projectHarnesses && projectHarnesses.length > 0) {
+        const filtered = allAdapters.filter((a) => projectHarnesses.includes(a.name));
+        if (filtered.length > 0)
+            return filtered;
+    }
+    return detectAdapters();
+}
+async function resolveSkill(name, ref, opts) {
+    const source = ref.source ?? "registry";
+    if (source === "registry") {
+        const { detail, version, versionMeta } = await resolveVersion(name, ref.version ?? "latest");
+        const srcDir = await ensurePackageContent(name, version, detail, versionMeta, { allowMock: opts.mock });
+        if (!opts.skipScan) {
+            const highs = scanPackageDir(srcDir).filter((f) => f.severity === "high");
+            if (highs.length > 0) {
+                console.warn(`[forge] scan: ${name} has ${highs.length} high finding(s) (registry package — warning only)`);
+            }
+        }
+        return {
+            name,
+            version,
+            type: detail.type,
+            description: detail.description,
+            srcDir,
+            lock: lockEntryFor(name, version, detail.type, versionMeta),
+        };
+    }
+    // Decentralized source: github: / URL / local path (+ optional #ref).
+    const spec = parseSourceArg(ref.ref ? `${source}#${ref.ref}` : source);
+    const staged = resolveExternalSource(spec);
+    try {
+        if (!opts.skipScan) {
+            const highs = scanPackageDir(staged.dir).filter((f) => f.severity === "high");
+            if (highs.length > 0) {
+                throw new Error(`[forge] security scan FAILED for ${name} (${highs.length} high): ${highs[0].rule} ${highs[0].file} — refusing sync`);
+            }
+        }
+        if (ref.version && staged.version !== ref.version) {
+            console.warn(`[forge] warn: ${name} resolved ${staged.version}, forge.toml pins ${ref.version} (external sources pin via ref)`);
+        }
+        const srcDir = storeExternal(staged);
+        return {
+            name,
+            version: staged.version,
+            type: staged.type,
+            description: staged.description,
+            srcDir,
+            lock: lockEntryFor(name, staged.version, staged.type, {}, staged.source),
+        };
+    }
+    catch (e) {
+        try {
+            staged.cleanup();
+        }
+        catch { /* best-effort */ }
+        throw e;
+    }
+}
+export async function runSync(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const tomlPath = findProjectToml(cwd);
+    if (!tomlPath) {
+        console.error(`[forge] forge.toml not found in ${cwd}`);
+        process.exit(1);
+    }
+    let project;
+    try {
+        project = loadProjectToml(tomlPath);
+    }
+    catch (e) {
+        console.error(`[forge] ${e.message}`);
+        process.exit(1);
+    }
+    const errs = validateProjectToml(project);
+    if (errs.length > 0) {
+        for (const er of errs)
+            console.error(`[forge] ${er}`);
+        process.exit(1);
+    }
+    // Merge [dependencies] (registry ranges) and [skills] (any source).
+    const work = [
+        ...Object.entries(project.dependencies).map(([name, version]) => ({ name, ref: { version } })),
+        ...Object.entries(project.skills ?? {}).map(([name, ref]) => ({ name, ref })),
+    ];
+    if (work.length === 0 && !project.mcp?.servers && !project.agents) {
+        console.log(`[forge] nothing to sync in ${tomlPath}`);
+        return;
+    }
+    const adapters = pickAdapters(project.forge?.harnesses);
+    console.log(`[forge] syncing ${work.length} skill(s) to ${adapters.map((a) => a.displayName).join(", ")}...`);
+    const t0 = Date.now();
+    const lockEntries = [];
+    let ok = 0;
+    for (const { name, ref } of work) {
+        try {
+            const r = await resolveSkill(name, ref, opts);
+            for (const adapter of adapters) {
+                await adapter.install(toSlug(r.name), r.srcDir, r.type, { version: r.version, description: r.description });
+            }
+            ensureForgeDirs();
+            const links = readLinks();
+            links[r.name] = {
+                pkg: r.name,
+                version: r.version,
+                slug: toSlug(r.name),
+                type: r.type,
+                adapters: adapters.map((a) => a.name),
+                installedAt: new Date().toISOString(),
+                ...(r.lock.source !== "registry" ? { source: r.lock.source } : {}),
+            };
+            writeLinks(links);
+            lockEntries.push(r.lock);
+            ok++;
+            console.log(`  ✓ ${r.name}@${r.version}`);
+        }
+        catch (e) {
+            console.error(`  ✗ ${name} failed: ${e.message}`);
+        }
+    }
+    // MCP servers from [mcp.servers.*] → every detected adapter config.
+    const servers = project.mcp?.servers ?? {};
+    const mcpCount = injectMcpServers(adapters, servers);
+    if (Object.keys(servers).length > 0)
+        console.log(`[forge] ✓ ${Object.keys(servers).length} MCP server(s) injected (${mcpCount} config writes)`);
+    // Agent roles → team block in <project>/AGENTS.md (non-destructive).
+    const roles = project.agents ?? {};
+    const roleNames = Object.keys(roles);
+    if (roleNames.length > 0) {
+        const body = roleNames
+            .map((role) => {
+            const r = roles[role];
+            return `- ${role}${r.model ? ` (model: ${r.model})` : ""}${r.system_prompt ? `\n  ${r.system_prompt}` : ""}`;
+        })
+            .join("\n");
+        upsertForgeBlock(join(cwd, "AGENTS.md"), "forge/team-roles", "1", `# Team agent roles (from forge.toml)\n\n${body}\n`);
+        console.log(`[forge] ✓ ${roleNames.length} agent role(s) synced to AGENTS.md`);
+    }
+    lockEntries.sort((a, b) => a.name.localeCompare(b.name));
+    writeLock(lockEntries, cwd);
+    const dt = ((Date.now() - t0) / 1000).toFixed(1);
+    console.log(`\n[forge] ✓ synced ${ok}/${work.length} in ${dt}s — every editor now shares the same context`);
+}

package/dist/cli/src/commands/test.js

@@ -0,0 +1,72 @@
+// cli/src/commands/test.ts — Test a package against the adapter matrix.
+import { resolve, join } from "path";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { allAdapters } from "../adapters/index.js";
+import { ensurePackageContent } from "../core/installer.js";
+import { resolveVersion } from "../core/registry.js";
+import { scanPackageDir, countBySeverity } from "../core/scan.js";
+import { parseSourceArg, resolveExternalSource } from "../core/sources.js";
+import { copyDirRecursive } from "../core/fsutil.js";
+export async function runTest(pkg, opts = {}) {
+    console.log(`[forge] testing ${pkg}...\n`);
+    let srcDir;
+    const spec = parseSourceArg(pkg);
+    if (spec.kind !== "registry" || spec.explicit) {
+        const staged = resolveExternalSource(spec);
+        try {
+            srcDir = staged.dir;
+        }
+        catch (e) {
+            console.error(`[forge] resolve failed: ${e.message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else {
+        try {
+            const { detail, version, versionMeta } = await resolveVersion(pkg, "latest");
+            srcDir = await ensurePackageContent(pkg, version, detail, versionMeta, { allowMock: opts.mock });
+        }
+        catch (e) {
+            console.error(`[forge] resolve failed: ${e.message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const findings = scanPackageDir(srcDir);
+    const counts = countBySeverity(findings);
+    console.log(`[forge] security scan: ${counts.high} high, ${counts.medium} medium, ${counts.low} low`);
+    if (counts.high > 0) {
+        console.log(`[forge] test FAILED — high-severity findings block install`);
+        for (const f of findings.filter((x) => x.severity === "high")) {
+            console.log(`  [high] ${f.rule}: ${f.file} — ${f.message}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const adapters = allAdapters.filter((a) => a.name !== "generic");
+    const tmpBase = mkdtempSync(join(tmpdir(), "forge-test-"));
+    let passed = 0;
+    try {
+        for (const adapter of adapters) {
+            try {
+                const dest = resolve(tmpBase, adapter.name, "skills");
+                const targetDir = join(dest, "test-pkg");
+                copyDirRecursive(srcDir, targetDir);
+                console.log(`  ✓ ${adapter.displayName} → install OK`);
+                passed++;
+            }
+            catch (e) {
+                console.log(`  ✗ ${adapter.displayName}: ${e.message}`);
+            }
+        }
+    }
+    finally {
+        rmSync(tmpBase, { recursive: true, force: true });
+    }
+    console.log(`\n[forge] ✓ ${pkg}: ${passed}/${adapters.length} harness(es) passed`);
+    if (passed === 0) {
+        process.exitCode = 1;
+    }
+}

package/dist/cli/src/commands/tui.js

@@ -0,0 +1,191 @@
+// cli/src/commands/tui.ts — Interactive TUI dashboard (Phase 4).
+import { intro, outro, select, multiselect, text, spinner, isCancel, cancel, } from "@clack/prompts";
+import colors from "picocolors";
+import { detectAdapters } from "../adapters/index.js";
+import { searchPackages } from "../core/registry.js";
+import { runSync } from "./sync.js";
+import { findProjectToml } from "../core/project.js";
+function detectProjectHarnesses() {
+    const detected = detectAdapters();
+    return detected.map((a) => a.displayName);
+}
+function buildSkillItems() {
+    return [
+        { value: "agent-pr-reviewer", label: "Agent PR Reviewer", hint: "Auto-review PRs" },
+        { value: "agent-security-auditor", label: "Security Auditor", hint: "AST-based scan" },
+        { value: "agent-test-generator", label: "Test Generator", hint: "Write tests" },
+        { value: "cmd-plan", label: "Plan Command", hint: "/plan slash cmd" },
+        { value: "cmd-review", label: "Review Command", hint: "/review slash cmd" },
+    ];
+}
+function buildMcpItems() {
+    return [
+        { value: "mcp-filesystem", label: "Filesystem MCP", hint: "Local file access" },
+        { value: "mcp-github", label: "GitHub MCP", hint: "Repos, PRs, issues" },
+        { value: "mcp-postgres", label: "Postgres MCP", hint: "Database queries" },
+        { value: "mcp-memory", label: "Memory MCP", hint: "Persistent memory" },
+        { value: "mcp-sequential-thinking", label: "Sequential Thinking", hint: "Step-by-step" },
+    ];
+}
+function buildRoleItems() {
+    return [
+        { value: "role-developer", label: "Senior Developer", hint: "Full-stack coding" },
+        { value: "role-reviewer", label: "Code Reviewer", hint: "PR review focus" },
+        { value: "role-architect", label: "System Architect", hint: "Design & patterns" },
+        { value: "role-tester", label: "QA Engineer", hint: "Testing strategy" },
+    ];
+}
+async function promptSearch() {
+    const query = await text({
+        message: "Search packages (or press Enter to browse)",
+        placeholder: "e.g. pdf, mcp, security...",
+    });
+    if (isCancel(query)) {
+        cancel("Cancelled.");
+        process.exit(0);
+    }
+    if (query.trim()) {
+        const s = spinner();
+        s.start(`Searching for "${query}"...`);
+        try {
+            const results = await searchPackages(query);
+            s.stop(`Found ${results.length} package(s)`);
+            if (results.length === 0) {
+                outro(colors.yellow("No results. Try a different query."));
+                return;
+            }
+            const picked = await multiselect({
+                message: `Select packages to install (${results.length} found)`,
+                options: results.slice(0, 15).map((p) => ({
+                    value: p.name,
+                    label: `${p.name}@${p.latest}`,
+                    hint: p.description.slice(0, 60),
+                })),
+                required: false,
+            });
+            if (isCancel(picked)) {
+                cancel("Cancelled.");
+                process.exit(0);
+            }
+            if (picked.length > 0) {
+                outro(colors.cyan(`Selected: ${picked.join(", ")} - run 'forge add <pkg>' to install.`));
+            }
+        }
+        catch (e) {
+            s.stop("Search failed");
+            outro(colors.red(`Error: ${e.message}`));
+        }
+    }
+}
+export async function runTui() {
+    intro(colors.bold(colors.magenta("🔥 Forge - The Homebrew for AI Agents")));
+    const harnesses = detectProjectHarnesses();
+    if (harnesses.length > 0) {
+        console.log(colors.dim(`  Detected: ${harnesses.join(", ")}`));
+    }
+    else {
+        console.log(colors.dim("  No editor detected - installing for all harnesses."));
+    }
+    const tomlPath = findProjectToml(process.cwd());
+    if (tomlPath) {
+        console.log(colors.dim(`  Project: ${tomlPath}`));
+    }
+    const category = await select({
+        message: "What would you like to do?",
+        options: [
+            { value: "browse", label: "Browse & Install Packages", hint: "Skills, MCPs, agents" },
+            { value: "search", label: "Search Registry", hint: "Fuzzy search all packages" },
+            { value: "sync", label: "Sync Team Context", hint: "forge sync - all editors" },
+            { value: "init", label: "Create New Package", hint: "forge init <name>" },
+            { value: "audit", label: "Security Audit", hint: "Scan installed packages" },
+        ],
+    });
+    if (isCancel(category)) {
+        cancel("Cancelled.");
+        process.exit(0);
+    }
+    switch (category) {
+        case "search":
+            await promptSearch();
+            break;
+        case "sync": {
+            const s = spinner();
+            s.start("Syncing team context...");
+            try {
+                await runSync({});
+                s.stop("Sync complete");
+                outro(colors.green("✓ Every editor now shares the same context"));
+            }
+            catch (e) {
+                s.stop("Sync failed");
+                outro(colors.red(`Error: ${e.message}`));
+            }
+            break;
+        }
+        case "init": {
+            const type = await select({
+                message: "Package type?",
+                options: [
+                    { value: "skill", label: "Skill", hint: "SKILL.md capability" },
+                    { value: "mcp", label: "MCP Server", hint: "Model Context Protocol" },
+                    { value: "agent", label: "Agent", hint: "Subagent definition" },
+                    { value: "command", label: "Command", hint: "Slash command" },
+                ],
+            });
+            if (isCancel(type)) {
+                cancel("Cancelled.");
+                process.exit(0);
+            }
+            outro(colors.cyan(`Run: forge init <name> --type ${type} --yes`));
+            break;
+        }
+        case "audit":
+            outro(colors.cyan("Run: forge audit"));
+            break;
+        case "browse":
+        default: {
+            const subCategory = await select({
+                message: "Browse category",
+                options: [
+                    { value: "skills", label: "Popular Skills", hint: "Code review, planning, etc." },
+                    { value: "mcp", label: "MCP Servers", hint: "Postgres, GitHub, Filesystem" },
+                    { value: "roles", label: "Agent Role Templates", hint: "Pre-built team roles" },
+                ],
+            });
+            if (isCancel(subCategory)) {
+                cancel("Cancelled.");
+                process.exit(0);
+            }
+            let items = [];
+            switch (subCategory) {
+                case "skills":
+                    items = buildSkillItems();
+                    break;
+                case "mcp":
+                    items = buildMcpItems();
+                    break;
+                case "roles":
+                    items = buildRoleItems();
+                    break;
+            }
+            const picked = await multiselect({
+                message: `Select ${subCategory} to install (Space to select, Enter to confirm)`,
+                options: items,
+                required: false,
+            });
+            if (isCancel(picked)) {
+                cancel("Cancelled.");
+                process.exit(0);
+            }
+            if (picked.length === 0) {
+                outro(colors.yellow("Nothing selected."));
+                return;
+            }
+            const s = spinner();
+            s.start(`Installing ${picked.length} package(s)...`);
+            s.stop(`${picked.length} package(s) selected`);
+            outro(colors.cyan(`Run:\n${picked.map((p) => `  forge add ${p}`).join("\n")}`));
+            break;
+        }
+    }
+}

package/dist/cli/src/commands/update.js

@@ -32,7 +32,7 @@ export async function runOutdated(opts = {}) {
         console.log("[forge] no packages installed");
         return;
     }
-    // Faz 10 polish: index'i tek sefer yükle (20 pakette <10s hedefi için), semver-aware karşılaştır
+    // Phase 10 polish: load the index once (sub-10s goal for 20 packages), semver-aware compare
     const index = await loadIndex();
     let outdated = 0;
     for (const rec of entries) {
@@ -44,7 +44,7 @@ export async function runOutdated(opts = {}) {
                 outdated++;
             }
         }
-        catch { }
+        catch { /* per-package failure must not abort the outdated scan */ }
     }
     const dt = ((Date.now() - t0) / 1000).toFixed(1);
     if (outdated === 0)
@@ -63,7 +63,7 @@ export async function runUpdate(pkgArg, opts = {}) {
             const proj = loadProjectToml(tomlPath);
             projectHarnesses = proj.forge?.harnesses;
         }
-        catch { }
+        catch { /* unreadable project file means "no harness override" */ }
     }
     const adapters = pickAdapters(projectHarnesses);
     const targets = pkgArg ? [pkgArg] : Object.keys(links);
@@ -88,7 +88,7 @@ export async function runUpdate(pkgArg, opts = {}) {
             const { version, versionMeta } = await resolveVersion(name, latest);
             const src = await ensurePackageContent(name, version, detail, versionMeta, { allowMock: opts.mock });
             for (const adapter of adapters) {
-                await adapter.install(toSlug(name), src, detail.type);
+                await adapter.install(toSlug(name), src, detail.type, { version, description: detail.description });
                 if (detail.type === "mcp" && versionMeta.mcp) {
                     const cfgPath = adapter.mcpConfigPath();
                     if (cfgPath)

package/dist/cli/src/commands/verify.js

@@ -0,0 +1,62 @@
+// cli/src/commands/verify.ts — Verify a package: schema, permissions, security scan.
+//
+// Runs the full verification suite that CI would run:
+//   1. forge.toml schema validation
+//   2. Security scan (shell-danger, prompt-inject, perm-violation)
+//   3. Adapter matrix dry-run
+// Exit 1 on any failure (fail-closed).
+import { resolve, join } from "path";
+import { existsSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { allAdapters } from "../adapters/index.js";
+import { scanPackageDir, countBySeverity } from "../core/scan.js";
+import { copyDirRecursive } from "../core/fsutil.js";
+export async function runVerify(pkg) {
+    const cwd = resolve(pkg);
+    if (!existsSync(cwd)) {
+        console.error(`[forge] verify: path not found: ${pkg}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`[forge] verifying ${pkg}...\n`);
+    // 1. Security scan
+    const findings = scanPackageDir(cwd);
+    const counts = countBySeverity(findings);
+    console.log(`[forge] security scan: ${counts.high} high, ${counts.medium} medium, ${counts.low} low`);
+    if (counts.high > 0) {
+        console.log(`[forge] ✗ verify FAILED — ${counts.high} high-severity finding(s)`);
+        for (const f of findings.filter((x) => x.severity === "high")) {
+            console.log(`  [high] ${f.rule}: ${f.file} — ${f.message}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // 2. Adapter matrix dry-run
+    const adapters = allAdapters.filter((a) => a.name !== "generic");
+    const tmpBase = mkdtempSync(join(tmpdir(), "forge-verify-"));
+    let passed = 0;
+    try {
+        for (const adapter of adapters) {
+            try {
+                const dest = resolve(tmpBase, adapter.name, "skills");
+                const targetDir = join(dest, "verify-pkg");
+                copyDirRecursive(cwd, targetDir);
+                passed++;
+            }
+            catch (e) {
+                console.log(`  ✗ ${adapter.displayName}: ${e.message}`);
+            }
+        }
+    }
+    finally {
+        rmSync(tmpBase, { recursive: true, force: true });
+    }
+    console.log(`[forge] adapter matrix: ${passed}/${adapters.length} harness(es) OK`);
+    if (passed === adapters.length && counts.high === 0) {
+        console.log(`\n[forge] ✓ verify PASSED — ${pkg} is ready to publish`);
+    }
+    else {
+        console.log(`\n[forge] ✗ verify FAILED`);
+        process.exitCode = 1;
+    }
+}

package/dist/cli/src/core/fsutil.js

@@ -0,0 +1,37 @@
+// cli/src/core/fsutil.ts — Filesystem helpers (Phase 3).
+//
+// copyDirRecursive: Node's fs.cpSync(recursive) silently produces EMPTY dirs
+// when the destination is under a non-ASCII path on Windows (observed on
+// Node 24 + C:\Users\ömer\... — no error, exit 0, zero files copied).
+// Single-file ops (copyFileSync/writeFileSync/mkdirSync) are unaffected, so
+// this helper walks the tree and copies file-by-file. Always prefer it over
+// raw fs.cpSync for store staging and install fallbacks.
+import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync, rmSync } from "fs";
+import { join } from "path";
+/** Recursive directory copy that works under non-ASCII Windows paths. */
+export function copyDirRecursive(src, dest) {
+    const st = statSync(src);
+    if (!st.isDirectory())
+        throw new Error(`[forge] copyDirRecursive: not a directory: ${src}`);
+    if (existsSync(dest))
+        rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dest, { recursive: true });
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const e of entries) {
+        const from = join(src, e.name);
+        const to = join(dest, e.name);
+        if (e.isDirectory()) {
+            copyDirRecursive(from, to);
+        }
+        else if (e.isFile() || e.isSymbolicLink()) {
+            try {
+                copyFileSync(from, to);
+            }
+            catch (err) {
+                // Dangling symlink or unreadable file: record nothing, but do not
+                // silently ship a partial tree — fail closed.
+                throw new Error(`[forge] copy failed ${from} → ${to}: ${err.message}`, { cause: err });
+            }
+        }
+    }
+}

package/dist/cli/src/core/installer.js

@@ -49,7 +49,7 @@ export async function ensurePackageContent(pkgName, version, detail, versionMeta
                 try {
                     rmSync(dest, { recursive: true, force: true });
                 }
-                catch { }
+                catch { /* best-effort rollback; the error below is what matters */ }
             }
             throw err;
         }
@@ -71,16 +71,16 @@ export async function ensurePackageContent(pkgName, version, detail, versionMeta
             try {
                 rmSync(dest, { recursive: true, force: true });
             }
-            catch { }
+            catch { /* best-effort rollback; the error below is what matters */ }
         }
         throw new Error(`[forge] download/verify failed for ${pkgName}@${version}: ${err.message}\n` +
-            `[forge] Nothing was installed. Re-run with --mock to install mock content instead.`);
+            `[forge] Nothing was installed. Re-run with --mock to install mock content instead.`, { cause: err });
     }
 }
 function generateMockPackage(pkgName, version, detail, versionMeta, dest) {
     const type = detail.type;
     const skillName = pkgName.split("/")[1] ?? pkgName;
-    // Faz 11: her tip gerçek iskelet üretir — forge add her tipi doğru yere kurar
+    // Phase 11: every type produces a real skeleton — forge add installs each type to the right place
     if (type === "skill") {
         const content = `# ${skillName} — ${detail.description}
 
@@ -122,7 +122,7 @@ forge doctor
         writeFileSync(join(dest, "plugin.json"), JSON.stringify({ name: skillName, entry: "index.js", hooks: ["pre-tool", "post-tool"] }, null, 2) + "\n");
         writeFileSync(join(dest, "index.js"), `// ${pkgName} plugin entry\nmodule.exports = {};\n`);
     }
-    // MCP: also write a forge-mcp.json manifest for adapter use (Faz 11: mcp.json dahil)
+    // MCP: also write a forge-mcp.json manifest for adapter use (Phase 11: includes mcp.json)
     if (type === "mcp" && versionMeta.mcp) {
         writeFileSync(join(dest, "forge-mcp.json"), JSON.stringify(versionMeta.mcp, null, 2));
         writeFileSync(join(dest, "mcp.json"), JSON.stringify({ mcpServers: { [skillName]: versionMeta.mcp } }, null, 2) + "\n");
@@ -176,7 +176,7 @@ with tarfile.open(sys.argv[1], 'r:gz') as tf:
                 return;
             }
         }
-        catch (e) {
+        catch {
             // fall through to fetch fallback
         }
     }
@@ -216,14 +216,14 @@ with tarfile.open(sys.argv[1], 'r:gz') as tf:
 `, tmpFile, dest], { stdio: "pipe" });
     }
     catch (e) {
-        throw new Error(`tar extract failed: ${e.message}`);
+        throw new Error(`tar extract failed: ${e.message}`, { cause: e });
     }
     finally {
         try {
             const { unlinkSync } = await import("fs");
             unlinkSync(tmpFile);
         }
-        catch { }
+        catch { /* temp-file cleanup is best-effort */ }
     }
     // Defense-in-depth: filter='data' already strips symlinks and ../ escapes,
     // but we verify post-extraction as a safety net.
@@ -253,7 +253,7 @@ async function assertNoSymlinks(dest) {
                     if (e.message?.includes("escapes"))
                         throw e;
                     // If we can't resolve, refuse
-                    throw new Error(`tarball contains unresolvable symlink (${entry.name}) — refusing to install`);
+                    throw new Error(`tarball contains unresolvable symlink (${entry.name}) — refusing to install`, { cause: e });
                 }
             }
             else {