javi-forge 1.26.0 → 1.28.0

package/dist/lib/agent-skills.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { AGENT_SKILLS_MANIFEST_FILE, PLUGIN_MANIFEST_FILE, PLUGINS_DIR, } from "../constants.js";
+import { evaluateInstallGate } from "./skill-install-gate.js";
+import { formatBatchReport, scanSkillsWithCoverage } from "./skill-scanner.js";
 // ── Conversion ─────────────────────────────────────────────────────────────
 /**
  * Convert a javi-forge PluginManifest to an Agent Skills spec manifest.
@@ -68,7 +70,7 @@ export async function exportPluginAsAgentSkills(name) {
  * Reads skills.json, converts to plugin.json, copies to plugins dir.
  */
 export async function importAgentSkillsPackage(sourceDir, options = {}) {
-    const { dryRun = false } = options;
+    const { dryRun = false, force = false } = options;
     const skillsPath = path.join(sourceDir, AGENT_SKILLS_MANIFEST_FILE);
     if (!(await fs.pathExists(skillsPath))) {
         return { success: false, error: "skills.json not found" };
@@ -88,11 +90,130 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
             error: "skills.json missing required fields (name, version, description)",
         };
     }
+    // R1-002: `name` becomes the import destination (`destDir = path.join(
+    // PLUGINS_DIR, name)`) and is handed to `fs.remove` + `fs.copy` below with
+    // NO path validation — a hostile skills.json name (e.g. `"../../.bashrc"`,
+    // an absolute path, or a separator-bearing name) would delete/copy
+    // ARBITRARY paths outside PLUGINS_DIR. The gate validates declared
+    // `skills[].path` escapes but never the name that determines the
+    // write/delete destination. Same-trust note: `name` is attacker-influenced
+    // when installing from a registry package, not a typed-in label — refuse
+    // BEFORE any `fs.remove`/`fs.copy`/`destDir` use, so an existing install
+    // is preserved (style-consistent with the gate's manifest-integrity
+    // refusals, block-level, force never lifts).
     const pluginName = agentManifest.name;
+    // R1-F2-N2: `name` is attacker-influenced JSON — it need not be a string at
+    // all (`{"name": 123}` is truthy, so it sails past the required-fields
+    // check above). Guard the type BEFORE the `.trim()` check: a non-string
+    // name refuses cleanly with the same manifest-integrity message instead of
+    // throwing a TypeError out of `.trim()` (which propagated to the UI as a
+    // "Fatal error").
+    if (typeof pluginName !== "string") {
+        return {
+            success: false,
+            error: `skillguard: install refused — invalid manifest name "${pluginName}" (manifest-integrity, force never lifts)`,
+        };
+    }
+    if (pluginName.trim() === "" ||
+        pluginName === "." ||
+        pluginName.includes("..") ||
+        pluginName.includes("/") ||
+        pluginName.includes("\\") ||
+        path.isAbsolute(pluginName)) {
+        return {
+            success: false,
+            error: `skillguard: install refused — invalid manifest name "${pluginName}" (manifest-integrity, force never lifts)`,
+        };
+    }
+    // JD-006: import requires a non-empty, well-formed skills array. Each entry
+    // must carry a `name` and a `path` that resolves INSIDE sourceDir (normalized
+    // + realpath containment — "../../x" or an absolute path refuses; the gate
+    // never reads outside the staged clone, JD-003).
+    if (!Array.isArray(agentManifest.skills) ||
+        agentManifest.skills.length === 0) {
+        return {
+            success: false,
+            error: "skills.json must declare a non-empty skills array (every skill-shaped file must be declared)",
+        };
+    }
+    const sourceRootAbs = path.resolve(sourceDir);
+    const sourceRootReal = await fs.realpath(sourceRootAbs);
+    const declaredPaths = [];
+    for (const entry of agentManifest.skills) {
+        if (!entry || typeof entry.name !== "string" || !entry.name) {
+            return {
+                success: false,
+                error: "skills.json skills entry missing name",
+            };
+        }
+        if (typeof entry.path !== "string" || !entry.path) {
+            return {
+                success: false,
+                error: `skills.json skills entry "${entry.name}" missing path`,
+            };
+        }
+        const contained = await skillPathContained(sourceRootAbs, sourceRootReal, entry.path);
+        if (!contained.ok) {
+            return {
+                success: false,
+                error: `skills.json skills entry "${entry.name}" path escapes package root (${contained.reason}) — refusing`,
+            };
+        }
+        declaredPaths.push(entry.path);
+    }
     if (dryRun) {
         return { success: true, name: pluginName };
     }
     const destDir = path.join(PLUGINS_DIR, pluginName);
+    // ── SkillGuard runtime gate (D8, JD-001/JD-003/JD-006/JD-007) ──────────
+    // Runs BEFORE the existing-install remove and fs.copy: a refusal preserves
+    // an existing install and installs nothing. dryRun early-returns above, so
+    // no scan happens on dry-run. Scanner/eval errors deny unconditionally (D7).
+    try {
+        const coverage = await scanSkillsWithCoverage(sourceDir, declaredPaths);
+        // Manifest-integrity refusals — block-level, force NEVER lifts
+        // (JD-007: ANY symlink; JD-006: undeclared SKILL.md incl. node_modules).
+        // A walk with I/O errors cannot certify the copied footprint — refuse
+        // first, because the broken subtree may hide symlinks or undeclared
+        // files (JD-013).
+        if (coverage.errors.length > 0) {
+            return {
+                success: false,
+                error: `skillguard: install refused — ${coverage.errors.length} path(s) could not be read (walk incomplete; manifest-integrity, force never lifts):\n${coverage.errors.map((p) => `  ${p}`).join("\n")}`,
+            };
+        }
+        if (coverage.symlinks.length > 0) {
+            return {
+                success: false,
+                error: `skillguard: install refused — symlink(s) in tree (manifest-integrity, force never lifts):\n${coverage.symlinks.map((p) => `  ${p}`).join("\n")}`,
+            };
+        }
+        if (coverage.undeclared.length > 0) {
+            return {
+                success: false,
+                error: `skillguard: install refused — undeclared SKILL.md(s) in tree (every skill-shaped file must be declared; force never lifts):\n${coverage.undeclared.map((p) => `  ${p}`).join("\n")}`,
+            };
+        }
+        const gate = evaluateInstallGate(coverage.declared, { force });
+        if (!gate.allowed) {
+            const blocked = gate.rejected.filter((r) => r.verdict === "block").length;
+            const unscannable = gate.rejected.filter((r) => r.verdict === "unscannable").length;
+            return {
+                success: false,
+                // Lead line names the rejected count; the batch report renders
+                // the FULL declared set so the header/rows reflect every scanned
+                // skill (D6, JD-014).
+                error: `skillguard: install refused — ${gate.rejected.length} rejected (${blocked} blocked, ${unscannable} unscannable)\n${formatBatchReport(coverage.declared)}`,
+            };
+        }
+    }
+    catch (scanError) {
+        const msg = scanError instanceof Error ? scanError.message : String(scanError);
+        return {
+            success: false,
+            error: `skillguard scan failed — ${msg}`,
+        };
+    }
     // Remove existing version if present
     if (await fs.pathExists(destDir)) {
         await fs.remove(destDir);
@@ -117,6 +238,39 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
     });
     return { success: true, name: pluginName };
 }
+/**
+ * Verify a declared skill entry path stays inside the package root — both
+ * lexically (`../../x`, absolute paths) and by realpath, so an in-tree symlink
+ * cannot redirect the import read outside the staged clone (JD-003/JD-006).
+ * Realpath resolution is best-effort: a missing declared dir has no realpath
+ * yet, in which case lexical containment is the whole guard (the coverage walk
+ * will later report it as a missing/unscannable declared skill).
+ */
+async function skillPathContained(rootAbs, rootReal, entryPath) {
+    const entryAbs = path.resolve(rootAbs, entryPath);
+    const rel = path.relative(rootAbs, entryAbs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return {
+            ok: false,
+            reason: `path "${entryPath}" resolves outside the package root`,
+        };
+    }
+    try {
+        const entryReal = await fs.realpath(entryAbs);
+        const relReal = path.relative(rootReal, entryReal);
+        if (relReal.startsWith("..") || path.isAbsolute(relReal)) {
+            return {
+                ok: false,
+                reason: `path "${entryPath}" resolves outside the package root (realpath)`,
+            };
+        }
+    }
+    catch {
+        // Declared dir does not exist yet — lexical containment stands; the
+        // coverage walk reports it as a missing declared skill later.
+    }
+    return { ok: true };
+}
 // ── Aggregation ──────────────────────────────────────────────────────────
 /**
  * Aggregate multiple installed plugins into a single Agent Skills spec manifest.

package/dist/lib/auto-skill-install.d.ts

@@ -1,3 +1,4 @@
+import type { SkillScanResult } from "./skill-scanner.js";
 import type { StackDetectionResult } from "./stack-detector.js";
 export interface SkillInstallResult {
     /** Skills that were successfully installed (copied) */
@@ -6,6 +7,8 @@ export interface SkillInstallResult {
     skipped: string[];
     /** Skills that were recommended but not found in the source */
     notFound: string[];
+    /** Skills refused by the skillguard gate (block / unscannable w/o force) */
+    blocked: SkillScanResult[];
     /** The full detection result for reporting */
     detection: StackDetectionResult;
 }
@@ -18,6 +21,8 @@ export interface AutoInstallOptions {
     skillsTargetDir?: string;
     /** If true, skip actually copying files */
     dryRun?: boolean;
+    /** Bypass the gate for unscannable sources ONLY — block always refuses (D2) */
+    force?: boolean;
 }
 /**
  * Scan a project, detect its stack, and install matching AI skills.

package/dist/lib/auto-skill-install.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { DEFAULT_SKILLS_DIR } from "../commands/skills/constants.js";
+import { evaluateInstallGate } from "./skill-install-gate.js";
+import { scanSkillFile } from "./skill-scanner.js";
 import { detectProjectStack } from "./stack-detector.js";
 // ── Core ───────────────────────────────────────────────────────────────────
 /**
@@ -14,7 +16,7 @@ import { detectProjectStack } from "./stack-detector.js";
  * source to target (useful for project-local skill installation).
  */
 export async function autoInstallSkills(options) {
-    const { projectDir, skillsSourceDir = DEFAULT_SKILLS_DIR, skillsTargetDir = DEFAULT_SKILLS_DIR, dryRun = false, } = options;
+    const { projectDir, skillsSourceDir = DEFAULT_SKILLS_DIR, skillsTargetDir = DEFAULT_SKILLS_DIR, dryRun = false, force = false, } = options;
     // 1. Detect project stack
     const detection = await detectProjectStack(projectDir);
     if (detection.recommendedSkills.length === 0) {
@@ -22,6 +24,7 @@ export async function autoInstallSkills(options) {
             installed: [],
             skipped: [],
             notFound: [],
+            blocked: [],
             detection,
         };
     }
@@ -29,6 +32,10 @@ export async function autoInstallSkills(options) {
     const skipped = [];
     const notFound = [];
     const sameDir = path.resolve(skillsSourceDir) === path.resolve(skillsTargetDir);
+    // 2. Classify: notFound / sameDir-skipped / target-skipped / copyable.
+    // Predicates unchanged from pre-gate behavior; sameDir short-circuits
+    // BEFORE any scanning (D4).
+    const copyable = [];
     for (const skillName of detection.recommendedSkills) {
         const sourcePath = path.join(skillsSourceDir, skillName);
         const targetPath = path.join(skillsTargetDir, skillName);
@@ -49,6 +56,32 @@ export async function autoInstallSkills(options) {
             skipped.push(skillName);
             continue;
         }
+        copyable.push(skillName);
+    }
+    // 3. SkillGuard gate (D4, JD-009): scan-gate every copyable source via its
+    // folder-root SKILL.md. dryRun still scans (read-only) but copies nothing.
+    // A scan THROW rejects the whole function — nothing copied, matching the
+    // UI error path (AutoSkills.tsx:41-44).
+    const scans = [];
+    for (const skillName of copyable) {
+        const sourceSkillMd = path.join(skillsSourceDir, skillName, "SKILL.md");
+        scans.push(await scanSkillFile(sourceSkillMd));
+    }
+    const gate = evaluateInstallGate(scans, { force });
+    if (!gate.allowed) {
+        // Any block (or unscannable without force) ⇒ copy NOTHING.
+        return {
+            installed: [],
+            skipped,
+            notFound,
+            blocked: gate.rejected,
+            detection,
+        };
+    }
+    // 4. Copy every copyable skill — nothing was refused.
+    for (const skillName of copyable) {
+        const sourcePath = path.join(skillsSourceDir, skillName);
+        const targetPath = path.join(skillsTargetDir, skillName);
         // Copy skill to target
         if (!dryRun) {
             await fs.ensureDir(targetPath);
@@ -59,7 +92,7 @@ export async function autoInstallSkills(options) {
         }
         installed.push(skillName);
     }
-    return { installed, skipped, notFound, detection };
+    return { installed, skipped, notFound, blocked: [], detection };
 }
 /**
  * Get a human-readable summary of auto-install results.
@@ -86,6 +119,11 @@ export function formatAutoInstallSummary(result) {
     if (result.notFound.length > 0) {
         lines.push(`  Not found: ${result.notFound.join(", ")}`);
     }
+    if (result.blocked.length > 0) {
+        lines.push(`  Blocked: ${result.blocked
+            .map((b) => `${b.skillName} [${b.verdict.toUpperCase()}]`)
+            .join(", ")}`);
+    }
     return lines.join("\n");
 }
 //# sourceMappingURL=auto-skill-install.js.map

package/dist/lib/context.d.ts

@@ -1,9 +1,28 @@
 import type { InitOptions, StackContextEntry } from "../types/index.js";
 export declare function buildIndexMd(projectName: string, stackCtx: StackContextEntry, ciProvider: string, memory: string): string;
 export declare function buildSummaryMd(projectName: string, stack: string, ciProvider: string, memory: string, modules: string[], dependencies?: string[]): string;
+/**
+ * Dependency detection outcome. `warnings` explains every manifest that could
+ * not be read or parsed, so a failure is distinguishable from "no dependencies"
+ * instead of being swallowed by a blanket catch.
+ */
+export interface DependencyDetection {
+    dependencies: string[];
+    warnings: string[];
+}
+/**
+ * Detect top-level dependencies from project manifest files, reporting why a
+ * manifest was skipped. Returns up to 10 dependency names (key deps only).
+ */
+export declare function detectDependenciesDetailed(projectDir: string, stack: string): Promise<DependencyDetection>;
 /**
  * Detect top-level dependencies from project manifest files.
  * Returns up to 10 dependency names (key deps only, not devDeps).
+ *
+ * List-returning convenience over `detectDependenciesDetailed`. It DISCARDS the
+ * read/parse warnings — an unreadable manifest is indistinguishable from an
+ * honest empty list through this function. Callers that must tell those two
+ * apart (like `refreshContextDir`) call `detectDependenciesDetailed` directly.
  */
 export declare function detectDependencies(projectDir: string, stack: string): Promise<string[]>;
 /**
@@ -23,5 +42,8 @@ export declare function refreshContextDir(projectDir: string): Promise<{
     index: string;
     summary: string;
     updated: boolean;
+    /** Manifest read/parse warnings — surfaced so an unreadable manifest is not
+     * silently reported as a project with no dependencies. */
+    warnings: string[];
 } | null>;
 //# sourceMappingURL=context.d.ts.map

package/dist/lib/context.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { STACK_CONTEXT_MAP } from "../constants.js";
+import { describeSafeReadFailure, safeReadFile } from "./safe-read.js";
 // =============================================================================
 // Internal helpers
 // =============================================================================
@@ -53,95 +54,135 @@ ${stack}-based project scaffolded with javi-forge.
 // =============================================================================
 // Dependency detection
 // =============================================================================
+const MAX_DEPS = 10;
 /**
- * Detect top-level dependencies from project manifest files.
- * Returns up to 10 dependency names (key deps only, not devDeps).
+ * Byte ceiling for a dependency manifest. A package.json or go.mod past this is
+ * not a manifest we can learn anything useful from — it is generated noise.
  */
-export async function detectDependencies(projectDir, stack) {
-    const MAX_DEPS = 10;
-    try {
-        switch (stack) {
-            case "node": {
-                const pkgPath = path.join(projectDir, "package.json");
-                if (!(await fs.pathExists(pkgPath)))
-                    return [];
-                const pkg = await fs.readJson(pkgPath).catch(() => ({}));
-                const deps = Object.keys(pkg.dependencies ?? {});
-                return deps.slice(0, MAX_DEPS);
+const MAX_MANIFEST_BYTES = 512 * 1024;
+/** Read a manifest under a byte budget; returns null and a warning on failure. */
+async function readManifest(manifestPath, warnings) {
+    const read = await safeReadFile(manifestPath, {
+        hardRejectOverBytes: MAX_MANIFEST_BYTES,
+    });
+    if (!read.ok) {
+        warnings.push(`${path.basename(manifestPath)}: ${describeSafeReadFailure(read)}`);
+        return null;
+    }
+    if (read.truncated) {
+        warnings.push(`${path.basename(manifestPath)}: truncated at ${read.bytesRead} of ${read.totalBytes} bytes`);
+    }
+    return read.content;
+}
+/**
+ * Detect top-level dependencies from project manifest files, reporting why a
+ * manifest was skipped. Returns up to 10 dependency names (key deps only).
+ */
+export async function detectDependenciesDetailed(projectDir, stack) {
+    const warnings = [];
+    switch (stack) {
+        case "node": {
+            const pkgPath = path.join(projectDir, "package.json");
+            if (!(await fs.pathExists(pkgPath)))
+                return { dependencies: [], warnings };
+            const content = await readManifest(pkgPath, warnings);
+            if (content === null)
+                return { dependencies: [], warnings };
+            let pkg;
+            try {
+                pkg = JSON.parse(content);
             }
-            case "python": {
-                const pyprojectPath = path.join(projectDir, "pyproject.toml");
-                if (await fs.pathExists(pyprojectPath)) {
-                    const content = await fs.readFile(pyprojectPath, "utf-8");
-                    const match = content.match(/dependencies\s*=\s*\[([\s\S]*?)\]/);
-                    if (match?.[1]) {
-                        const deps = match[1]
-                            .split("\n")
-                            .map((l) => l.replace(/[",]/g, "").trim())
-                            .filter((l) => l.length > 0 && !l.startsWith("#"))
-                            .map((l) => l.split(/[>=<~!]/)[0].trim())
-                            .filter(Boolean);
-                        return deps.slice(0, MAX_DEPS);
-                    }
-                }
-                const reqPath = path.join(projectDir, "requirements.txt");
-                if (await fs.pathExists(reqPath)) {
-                    const content = await fs.readFile(reqPath, "utf-8");
-                    const deps = content
+            catch (err) {
+                warnings.push(`package.json: invalid JSON (${err instanceof Error ? err.message : String(err)})`);
+                return { dependencies: [], warnings };
+            }
+            const deps = Object.keys(pkg?.dependencies ?? {});
+            return { dependencies: deps.slice(0, MAX_DEPS), warnings };
+        }
+        case "python": {
+            const pyprojectPath = path.join(projectDir, "pyproject.toml");
+            if (await fs.pathExists(pyprojectPath)) {
+                const content = await readManifest(pyprojectPath, warnings);
+                const match = content?.match(/dependencies\s*=\s*\[([\s\S]*?)\]/);
+                if (match?.[1]) {
+                    const deps = match[1]
                         .split("\n")
-                        .map((l) => l.trim())
-                        .filter((l) => l.length > 0 && !l.startsWith("#") && !l.startsWith("-"))
+                        .map((l) => l.replace(/[",]/g, "").trim())
+                        .filter((l) => l.length > 0 && !l.startsWith("#"))
                         .map((l) => l.split(/[>=<~!]/)[0].trim())
                         .filter(Boolean);
-                    return deps.slice(0, MAX_DEPS);
+                    return { dependencies: deps.slice(0, MAX_DEPS), warnings };
                 }
-                return [];
             }
-            case "go": {
-                const goModPath = path.join(projectDir, "go.mod");
-                if (!(await fs.pathExists(goModPath)))
-                    return [];
-                const content = await fs.readFile(goModPath, "utf-8");
-                const requireBlock = content.match(/require\s*\(([\s\S]*?)\)/);
-                if (requireBlock?.[1]) {
-                    const deps = requireBlock[1]
-                        .split("\n")
-                        .map((l) => l.trim())
-                        .filter((l) => l.length > 0 && !l.startsWith("//"))
-                        .map((l) => {
-                        const parts = l.split(/\s+/);
-                        const mod = parts[0] ?? "";
-                        return mod.split("/").pop() ?? mod;
-                    })
-                        .filter(Boolean);
-                    return deps.slice(0, MAX_DEPS);
-                }
-                return [];
+            const reqPath = path.join(projectDir, "requirements.txt");
+            if (await fs.pathExists(reqPath)) {
+                const content = await readManifest(reqPath, warnings);
+                if (content === null)
+                    return { dependencies: [], warnings };
+                const deps = content
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0 && !l.startsWith("#") && !l.startsWith("-"))
+                    .map((l) => l.split(/[>=<~!]/)[0].trim())
+                    .filter(Boolean);
+                return { dependencies: deps.slice(0, MAX_DEPS), warnings };
             }
-            case "rust": {
-                const cargoPath = path.join(projectDir, "Cargo.toml");
-                if (!(await fs.pathExists(cargoPath)))
-                    return [];
-                const content = await fs.readFile(cargoPath, "utf-8");
-                const depsSection = content.match(/\[dependencies\]([\s\S]*?)(?=\n\[|$)/);
-                if (depsSection?.[1]) {
-                    const deps = depsSection[1]
-                        .split("\n")
-                        .map((l) => l.trim())
-                        .filter((l) => l.length > 0 && !l.startsWith("#"))
-                        .map((l) => l.split(/\s*=/)[0].trim())
-                        .filter(Boolean);
-                    return deps.slice(0, MAX_DEPS);
-                }
-                return [];
+            return { dependencies: [], warnings };
+        }
+        case "go": {
+            const goModPath = path.join(projectDir, "go.mod");
+            if (!(await fs.pathExists(goModPath)))
+                return { dependencies: [], warnings };
+            const content = await readManifest(goModPath, warnings);
+            const requireBlock = content?.match(/require\s*\(([\s\S]*?)\)/);
+            if (requireBlock?.[1]) {
+                const deps = requireBlock[1]
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0 && !l.startsWith("//"))
+                    .map((l) => {
+                    const parts = l.split(/\s+/);
+                    const mod = parts[0] ?? "";
+                    return mod.split("/").pop() ?? mod;
+                })
+                    .filter(Boolean);
+                return { dependencies: deps.slice(0, MAX_DEPS), warnings };
             }
-            default:
-                return [];
+            return { dependencies: [], warnings };
         }
+        case "rust": {
+            const cargoPath = path.join(projectDir, "Cargo.toml");
+            if (!(await fs.pathExists(cargoPath)))
+                return { dependencies: [], warnings };
+            const content = await readManifest(cargoPath, warnings);
+            const depsSection = content?.match(/\[dependencies\]([\s\S]*?)(?=\n\[|$)/);
+            if (depsSection?.[1]) {
+                const deps = depsSection[1]
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0 && !l.startsWith("#"))
+                    .map((l) => l.split(/\s*=/)[0].trim())
+                    .filter(Boolean);
+                return { dependencies: deps.slice(0, MAX_DEPS), warnings };
+            }
+            return { dependencies: [], warnings };
+        }
+        default:
+            return { dependencies: [], warnings };
     }
-    catch {
-        return [];
-    }
+}
+/**
+ * Detect top-level dependencies from project manifest files.
+ * Returns up to 10 dependency names (key deps only, not devDeps).
+ *
+ * List-returning convenience over `detectDependenciesDetailed`. It DISCARDS the
+ * read/parse warnings — an unreadable manifest is indistinguishable from an
+ * honest empty list through this function. Callers that must tell those two
+ * apart (like `refreshContextDir`) call `detectDependenciesDetailed` directly.
+ */
+export async function detectDependencies(projectDir, stack) {
+    const { dependencies } = await detectDependenciesDetailed(projectDir, stack);
+    return dependencies;
 }
 // =============================================================================
 // Public API
@@ -190,7 +231,7 @@ export async function refreshContextDir(projectDir) {
         return null;
     }
     const stackCtx = getStackContext(manifest.stack);
-    const dependencies = await detectDependencies(projectDir, manifest.stack);
+    const { dependencies, warnings } = await detectDependenciesDetailed(projectDir, manifest.stack);
     const index = buildIndexMd(manifest.projectName, stackCtx, manifest.ciProvider, manifest.memory);
     const summary = buildSummaryMd(manifest.projectName, manifest.stack, manifest.ciProvider, manifest.memory, manifest.modules, dependencies);
     // Write updated files
@@ -199,6 +240,6 @@ export async function refreshContextDir(projectDir) {
     // Update manifest timestamp
     manifest.updatedAt = new Date().toISOString();
     await fs.writeJson(manifestPath, manifest, { spaces: 2 });
-    return { index, summary, updated: true };
+    return { index, summary, updated: true, warnings };
 }
 //# sourceMappingURL=context.js.map

package/dist/lib/plugin.d.ts

@@ -9,6 +9,7 @@ export declare function validatePlugin(pluginDir: string): Promise<PluginValidat
  */
 export declare function installPlugin(source: string, options?: {
     dryRun?: boolean;
+    force?: boolean;
 }): Promise<{
     success: boolean;
     name?: string;