javi-forge 1.6.0 → 1.7.0

package/dist/lib/skill-publish.js

@@ -0,0 +1,164 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { PLUGIN_MANIFEST_FILE } from "../constants.js";
+import { parseFrontmatter } from "./frontmatter.js";
+// ── Core ───────────────────────────────────────────────────────────────────
+/**
+ * Package a skill directory for marketplace distribution.
+ *
+ * Reads the SKILL.md, extracts metadata from frontmatter, and generates
+ * a plugin.json compatible with both `javi-forge plugin install` and
+ * `claude plugin install` (Anthropic's plugin format).
+ *
+ * Expected input structure:
+ *   skill-name/
+ *     SKILL.md
+ *     (optional other files)
+ *
+ * Output:
+ *   skill-name/
+ *     SKILL.md
+ *     plugin.json   ← generated
+ */
+export async function publishSkill(options) {
+    const { skillDir, author, repository, tags = [], dryRun = false } = options;
+    // Validate skill directory
+    const skillMdPath = path.join(skillDir, "SKILL.md");
+    if (!(await fs.pathExists(skillMdPath))) {
+        return { success: false, error: `SKILL.md not found in ${skillDir}` };
+    }
+    // Refuse to follow a symlink. If SKILL.md is a symlink to a file outside
+    // the skill directory (e.g., /etc/passwd), readFile + the later fs.copy
+    // would expose the target's contents in the published manifest bundle.
+    // Mirrors the symlink-reject pattern in security.ts writeBaseline /
+    // ci.ts installCIHooks.
+    try {
+        const stat = await fs.lstat(skillMdPath);
+        if (stat.isSymbolicLink()) {
+            return {
+                success: false,
+                error: `SKILL.md is a symlink; refusing to publish. Use a regular file.`,
+            };
+        }
+    }
+    catch {
+        // pathExists already returned true above; lstat failures here are
+        // unexpected. Fall through to readFile which will surface the error.
+    }
+    // Read and parse SKILL.md
+    let raw;
+    try {
+        raw = await fs.readFile(skillMdPath, "utf-8");
+    }
+    catch {
+        return { success: false, error: "Failed to read SKILL.md" };
+    }
+    const parsed = parseFrontmatter(raw);
+    const frontmatter = parsed?.data ?? {};
+    // Extract metadata
+    const name = frontmatter.name ?? path.basename(skillDir);
+    const version = frontmatter.version ?? "1.0.0";
+    const description = frontmatter.description ?? `${name} AI skill`;
+    // Validate name format (kebab-case)
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+        return {
+            success: false,
+            error: `Skill name "${name}" must be kebab-case (e.g., "react-19", "tailwind-4")`,
+        };
+    }
+    // Validate description length
+    if (description.length < 10) {
+        return {
+            success: false,
+            error: "Description must be at least 10 characters",
+        };
+    }
+    // Build plugin.json manifest
+    const manifest = {
+        name,
+        version,
+        description: description.length > 200
+            ? `${description.slice(0, 197)}...`
+            : description,
+        skills: [name],
+        tags: tags.length > 0 ? tags : extractTagsFromDescription(description),
+        ...(author ? { author } : {}),
+        ...(repository ? { repository } : {}),
+    };
+    if (!dryRun) {
+        const pluginJsonPath = path.join(skillDir, PLUGIN_MANIFEST_FILE);
+        await fs.writeJson(pluginJsonPath, manifest, { spaces: 2 });
+        // Also create a skills/ subdirectory structure for plugin compatibility
+        const skillsSubdir = path.join(skillDir, "skills", name);
+        if (!(await fs.pathExists(skillsSubdir))) {
+            await fs.ensureDir(skillsSubdir);
+            // Symlink or copy SKILL.md into skills/name/
+            const targetSkillMd = path.join(skillsSubdir, "SKILL.md");
+            if (!(await fs.pathExists(targetSkillMd))) {
+                await fs.copy(skillMdPath, targetSkillMd);
+            }
+        }
+        return { success: true, pluginJsonPath, manifest };
+    }
+    return {
+        success: true,
+        pluginJsonPath: path.join(skillDir, PLUGIN_MANIFEST_FILE),
+        manifest,
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Extract reasonable tags from a skill description.
+ * Looks for common tech keywords.
+ */
+function extractTagsFromDescription(description) {
+    const keywords = [
+        "react",
+        "next",
+        "nextjs",
+        "angular",
+        "vue",
+        "svelte",
+        "typescript",
+        "javascript",
+        "python",
+        "go",
+        "rust",
+        "java",
+        "elixir",
+        "tailwind",
+        "css",
+        "styling",
+        "testing",
+        "test",
+        "e2e",
+        "unit",
+        "api",
+        "rest",
+        "graphql",
+        "ai",
+        "llm",
+        "ml",
+        "agent",
+        "security",
+        "auth",
+        "database",
+        "sql",
+        "nosql",
+        "docker",
+        "kubernetes",
+        "devops",
+        "ci",
+        "cd",
+        "state",
+        "management",
+        "store",
+        "validation",
+        "schema",
+        "zod",
+    ];
+    const lower = description.toLowerCase();
+    const found = keywords.filter((kw) => lower.includes(kw));
+    return found.slice(0, 10); // Max 10 tags per plugin spec
+}
+//# sourceMappingURL=skill-publish.js.map

package/dist/lib/skill-scanner.d.ts

@@ -0,0 +1,63 @@
+/**
+ * CI-level skill security scanner — pre-install analysis of SKILL.md files.
+ *
+ * Detects credential theft, code injection, data exfiltration, and scope escape
+ * patterns before skills are installed. Inspired by the SkillGuard skill
+ * (javi-ai) but implemented as a programmatic module with structured output.
+ */
+import type { SecuritySeverity } from "../types/index.js";
+export type SkillThreatCategory = "credential-theft" | "code-injection" | "data-exfiltration" | "scope-escape" | "privilege-escalation" | "destructive-command" | "self-modification" | "hook-tampering" | "obfuscation" | "missing-provenance" | "excessive-permissions" | "file-traversal";
+export interface SkillThreat {
+    category: SkillThreatCategory;
+    severity: SecuritySeverity;
+    pattern: string;
+    line: number;
+    context: string;
+    message: string;
+}
+export type SkillScanVerdict = "pass" | "warn" | "block";
+export interface SkillScanResult {
+    skillPath: string;
+    skillName: string;
+    verdict: SkillScanVerdict;
+    threats: SkillThreat[];
+    summary: SkillScanSummary;
+}
+export interface SkillScanSummary {
+    total: number;
+    critical: number;
+    high: number;
+    moderate: number;
+    low: number;
+}
+interface ThreatPattern {
+    category: SkillThreatCategory;
+    severity: SecuritySeverity;
+    pattern: RegExp;
+    message: string;
+}
+/**
+ * Ordered by severity (critical first). Each pattern is tested against
+ * every non-comment line in the skill file.
+ */
+export declare const THREAT_PATTERNS: ThreatPattern[];
+interface ProvenanceInfo {
+    hasAuthor: boolean;
+    hasVersion: boolean;
+    hasDescription: boolean;
+}
+export declare function checkProvenance(content: string): ProvenanceInfo;
+export declare function scanSkillContent(content: string, _filePath: string): SkillThreat[];
+export declare function computeVerdict(threats: SkillThreat[]): SkillScanVerdict;
+export declare function computeScanSummary(threats: SkillThreat[]): SkillScanSummary;
+export declare function extractSkillName(content: string, filePath: string): string;
+export declare function scanSkillFile(filePath: string): Promise<SkillScanResult>;
+/**
+ * Scan all SKILL.md files in a directory (recursive).
+ * Useful for scanning a plugin's skills directory before installation.
+ */
+export declare function scanSkillsDirectory(dir: string): Promise<SkillScanResult[]>;
+export declare function formatScanReport(result: SkillScanResult): string;
+export declare function formatBatchReport(results: SkillScanResult[]): string;
+export {};
+//# sourceMappingURL=skill-scanner.d.ts.map

package/dist/lib/skill-scanner.js

@@ -0,0 +1,383 @@
+/**
+ * CI-level skill security scanner — pre-install analysis of SKILL.md files.
+ *
+ * Detects credential theft, code injection, data exfiltration, and scope escape
+ * patterns before skills are installed. Inspired by the SkillGuard skill
+ * (javi-ai) but implemented as a programmatic module with structured output.
+ */
+import path from "node:path";
+import fs from "fs-extra";
+/**
+ * Ordered by severity (critical first). Each pattern is tested against
+ * every non-comment line in the skill file.
+ */
+export const THREAT_PATTERNS = [
+    // ── Critical: Credential Theft ──
+    {
+        category: "credential-theft",
+        severity: "critical",
+        pattern: /(?:~\/\.ssh|~\/\.aws|~\/\.config\/gh|~\/\.gnupg|~\/\.netrc|~\/\.npmrc|\/etc\/shadow|\/etc\/passwd|id_rsa|id_ed25519)/i,
+        message: "References sensitive credential paths — potential data theft",
+    },
+    {
+        category: "credential-theft",
+        severity: "critical",
+        pattern: /(?:AWS_SECRET_ACCESS_KEY|GITHUB_TOKEN|NPM_TOKEN|PRIVATE_KEY|API_SECRET|DATABASE_URL|MONGO_URI|REDIS_URL)\s*[=:]/i,
+        message: "References environment variable containing secrets — potential exfiltration",
+    },
+    {
+        category: "credential-theft",
+        severity: "critical",
+        pattern: /(?:read|cat|type|get-content|less|more|head|tail)\s+.*(?:\.env|credentials|secrets?\.(json|yaml|yml|toml))/i,
+        message: "Reads secret/credential files directly — potential credential theft",
+    },
+    // ── Critical: Code Injection ──
+    {
+        category: "code-injection",
+        severity: "critical",
+        pattern: /\beval\s*\(\s*(?:user|input|req|params|args|data|body)/i,
+        message: "eval() with user-controlled input — enables arbitrary code execution",
+    },
+    {
+        category: "code-injection",
+        severity: "critical",
+        pattern: /\b(?:exec|execSync|spawn|spawnSync)\s*\(\s*(?:user|input|req|params|args|data)/i,
+        message: "Process execution with user input — enables command injection",
+    },
+    {
+        category: "code-injection",
+        severity: "critical",
+        pattern: /\b(?:subprocess\.(?:call|run|Popen)|os\.system|os\.popen)\s*\(\s*(?:f['"]|user|input|req)/i,
+        message: "Python subprocess with user input — enables command injection",
+    },
+    // ── Critical: Data Exfiltration ──
+    {
+        category: "data-exfiltration",
+        severity: "critical",
+        pattern: /(?:curl|wget|fetch|axios|got|request)\s+.*(?:--data|--upload|-d\s|-F\s|\.post\(|\.put\()\s*.*(?:\/etc\/|~\/\.|\.env|secret|credential|token|key)/i,
+        message: "Sending sensitive data to external endpoint — data exfiltration",
+    },
+    {
+        category: "data-exfiltration",
+        severity: "high",
+        pattern: /(?:curl|wget)\s+(?:-[sSfLkO]*\s+)*(?:https?:\/\/)?(?!localhost|127\.0\.0\.1|0\.0\.0\.0|::1)[\w.-]+\.\w{2,}/i,
+        message: "Outbound HTTP request to external URL — verify the destination is trusted",
+    },
+    {
+        category: "data-exfiltration",
+        severity: "high",
+        pattern: /fetch\s*\(\s*['"`]https?:\/\/(?!localhost|127\.0\.0\.1)/i,
+        message: "fetch() to external URL — verify the destination is trusted",
+    },
+    // ── Critical: Scope Escape ──
+    {
+        category: "scope-escape",
+        severity: "critical",
+        pattern: /(?:ignore\s+(?:all\s+)?previous|disregard\s+(?:all\s+)?(?:prior|above)|override\s+(?:safety|security|rules)|bypass\s+(?:safety|security|restrictions))/i,
+        message: "Prompt injection attempt — tries to override safety instructions",
+    },
+    {
+        category: "scope-escape",
+        severity: "critical",
+        pattern: /(?:you\s+are\s+now|from\s+now\s+on|new\s+instructions?:?\s+)/i,
+        message: "Attempts to redefine agent identity — prompt injection risk",
+    },
+    // ── Critical: Self-Modification ──
+    {
+        category: "self-modification",
+        severity: "critical",
+        pattern: /(?:write|append|modify|edit|overwrite|patch)\s+.*(?:CLAUDE\.md|AGENTS\.md|settings\.json|\.claude\/)/i,
+        message: "Attempts to modify agent config files — persistence/privilege escalation",
+    },
+    {
+        category: "hook-tampering",
+        severity: "critical",
+        pattern: /(?:rm|remove|delete|disable)\s+.*(?:pre-commit|pre-push|commit-msg|\.git\/hooks)/i,
+        message: "Attempts to disable or remove git hooks — bypasses safety guardrails",
+    },
+    // ── High: Privilege Escalation ──
+    {
+        category: "privilege-escalation",
+        severity: "high",
+        pattern: /\bsudo\s+/i,
+        message: "Uses sudo — may escalate to root privileges",
+    },
+    {
+        category: "privilege-escalation",
+        severity: "high",
+        pattern: /chmod\s+(?:777|666|a\+[rwx])/i,
+        message: "Sets overly permissive file permissions — security risk",
+    },
+    {
+        category: "privilege-escalation",
+        severity: "high",
+        pattern: /chown\s+root/i,
+        message: "Changes file ownership to root — privilege escalation",
+    },
+    // ── High: Destructive Commands ──
+    {
+        category: "destructive-command",
+        severity: "high",
+        pattern: /\brm\s+-rf?\s+(?:\/|~|\$HOME|\.\.)/i,
+        message: "Destructive file deletion targeting root, home, or parent directories",
+    },
+    {
+        category: "destructive-command",
+        severity: "high",
+        pattern: /git\s+push\s+--force\b/i,
+        message: "Force push can destroy remote history",
+    },
+    {
+        category: "destructive-command",
+        severity: "high",
+        pattern: /DROP\s+(?:TABLE|DATABASE|INDEX)/i,
+        message: "SQL DROP statement — potential data loss",
+    },
+    // ── High: File Traversal ──
+    {
+        category: "file-traversal",
+        severity: "high",
+        pattern: /(?:\.\.\/){2,}/,
+        message: "Multiple path traversal sequences — may access files outside project",
+    },
+    {
+        category: "file-traversal",
+        severity: "high",
+        pattern: /(?:readFile|writeFile|open|fs\.)\s*\(\s*['"`]\/(?:etc|usr|var|tmp|root|home)\//i,
+        message: "Absolute path to system directory — scope escape risk",
+    },
+    // ── Moderate: Obfuscation ──
+    {
+        category: "obfuscation",
+        severity: "moderate",
+        pattern: /(?:atob|btoa|Buffer\.from)\s*\(\s*['"`][A-Za-z0-9+/]{40,}/,
+        message: "Base64 encoded content — may hide malicious payloads",
+    },
+    {
+        category: "obfuscation",
+        severity: "moderate",
+        pattern: /\\x[0-9a-fA-F]{2}(?:\\x[0-9a-fA-F]{2}){4,}/,
+        message: "Hex-encoded string sequence — may hide malicious payloads",
+    },
+    // ── Moderate: Excessive Permissions ──
+    {
+        category: "excessive-permissions",
+        severity: "moderate",
+        pattern: /allowed-tools:\s*.*(?:Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch).*(?:Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch).*(?:Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch).*(?:Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch)/i,
+        message: "Requests many tools — verify skill actually needs all of them",
+    },
+];
+export function checkProvenance(content) {
+    // Check YAML frontmatter
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) {
+        return { hasAuthor: false, hasVersion: false, hasDescription: false };
+    }
+    const fm = frontmatterMatch[1];
+    return {
+        hasAuthor: /\bauthor\s*:/i.test(fm),
+        hasVersion: /\bversion\s*:/i.test(fm),
+        hasDescription: /\bdescription\s*:/i.test(fm),
+    };
+}
+// =============================================================================
+// Core scanner
+// =============================================================================
+export function scanSkillContent(content, _filePath) {
+    const threats = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Skip empty lines
+        if (!trimmed)
+            continue;
+        for (const tp of THREAT_PATTERNS) {
+            if (tp.pattern.test(trimmed)) {
+                threats.push({
+                    category: tp.category,
+                    severity: tp.severity,
+                    pattern: tp.pattern.source.slice(0, 80),
+                    line: i + 1,
+                    context: trimmed.slice(0, 120),
+                    message: tp.message,
+                });
+            }
+        }
+    }
+    // Check provenance
+    const prov = checkProvenance(content);
+    if (!prov.hasAuthor) {
+        threats.push({
+            category: "missing-provenance",
+            severity: "moderate",
+            pattern: "missing author",
+            line: 1,
+            context: "YAML frontmatter",
+            message: "No author metadata — skill origin is unknown",
+        });
+    }
+    if (!prov.hasVersion) {
+        threats.push({
+            category: "missing-provenance",
+            severity: "moderate",
+            pattern: "missing version",
+            line: 1,
+            context: "YAML frontmatter",
+            message: "No version metadata — cannot track updates",
+        });
+    }
+    return threats;
+}
+// =============================================================================
+// Verdict computation
+// =============================================================================
+export function computeVerdict(threats) {
+    if (threats.some((t) => t.severity === "critical"))
+        return "block";
+    if (threats.some((t) => t.severity === "high"))
+        return "warn";
+    return "pass";
+}
+export function computeScanSummary(threats) {
+    const summary = {
+        total: threats.length,
+        critical: 0,
+        high: 0,
+        moderate: 0,
+        low: 0,
+    };
+    for (const t of threats) {
+        switch (t.severity) {
+            case "critical":
+                summary.critical++;
+                break;
+            case "high":
+                summary.high++;
+                break;
+            case "moderate":
+                summary.moderate++;
+                break;
+            case "low":
+                summary.low++;
+                break;
+        }
+    }
+    return summary;
+}
+// =============================================================================
+// Skill name extraction
+// =============================================================================
+export function extractSkillName(content, filePath) {
+    // Try frontmatter name
+    const fmMatch = content.match(/^---\n[\s\S]*?\bname:\s*(.+)/m);
+    if (fmMatch?.[1])
+        return fmMatch[1].trim();
+    // Fall back to directory name
+    const dirName = path.basename(path.dirname(filePath));
+    if (dirName && dirName !== ".")
+        return dirName;
+    return path.basename(filePath, path.extname(filePath));
+}
+// =============================================================================
+// Main scan function
+// =============================================================================
+export async function scanSkillFile(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const skillName = extractSkillName(content, filePath);
+    const threats = scanSkillContent(content, filePath);
+    const verdict = computeVerdict(threats);
+    const summary = computeScanSummary(threats);
+    return {
+        skillPath: filePath,
+        skillName,
+        verdict,
+        threats,
+        summary,
+    };
+}
+/**
+ * Scan all SKILL.md files in a directory (recursive).
+ * Useful for scanning a plugin's skills directory before installation.
+ */
+export async function scanSkillsDirectory(dir) {
+    const results = [];
+    async function walk(currentDir) {
+        let entries;
+        try {
+            entries = await fs.readdir(currentDir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry === "node_modules" || entry === ".git")
+                continue;
+            const fullPath = path.join(currentDir, entry);
+            let stat;
+            try {
+                stat = await fs.stat(fullPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry === "SKILL.md" ||
+                entry === "PLUGIN.md" ||
+                entry.toLowerCase() === "skill.md") {
+                const result = await scanSkillFile(fullPath);
+                results.push(result);
+            }
+        }
+    }
+    await walk(dir);
+    return results;
+}
+// =============================================================================
+// Report formatting
+// =============================================================================
+export function formatScanReport(result) {
+    const lines = [];
+    const { summary, threats, verdict } = result;
+    lines.push(`=== SkillGuard Scan: ${result.skillName} ===`);
+    lines.push(`Path: ${result.skillPath}`);
+    lines.push(`Verdict: ${verdict.toUpperCase()}`);
+    lines.push(`Findings: ${summary.total} (${summary.critical} critical, ${summary.high} high, ${summary.moderate} moderate, ${summary.low} low)`);
+    lines.push("");
+    if (threats.length > 0) {
+        lines.push("--- Threats ---");
+        for (const t of threats) {
+            lines.push(`[${t.severity.toUpperCase()}] ${t.category} (line ${t.line})`);
+            lines.push(`  ${t.message}`);
+            lines.push(`  Context: ${t.context}`);
+        }
+    }
+    if (verdict === "block") {
+        lines.push("");
+        lines.push("BLOCKED: Critical threats detected. Review and remove before installing.");
+    }
+    else if (verdict === "warn") {
+        lines.push("");
+        lines.push("WARNING: High-severity threats detected. Confirm you trust this skill.");
+    }
+    return lines.join("\n");
+}
+export function formatBatchReport(results) {
+    const lines = [];
+    const blocked = results.filter((r) => r.verdict === "block");
+    const warned = results.filter((r) => r.verdict === "warn");
+    const passed = results.filter((r) => r.verdict === "pass");
+    lines.push(`=== SkillGuard Batch Scan ===`);
+    lines.push(`Scanned: ${results.length} skill(s)`);
+    lines.push(`Blocked: ${blocked.length}`);
+    lines.push(`Warned: ${warned.length}`);
+    lines.push(`Passed: ${passed.length}`);
+    lines.push("");
+    for (const result of results) {
+        lines.push(`[${result.verdict.toUpperCase()}] ${result.skillName} (${result.summary.total} finding(s))`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=skill-scanner.js.map

package/dist/lib/stack-detector.d.ts

@@ -0,0 +1,38 @@
+import type { Stack } from "../types/index.js";
+/**
+ * Maps detected project signals to recommended AI skills.
+ * Each key is a detection signal (file/dependency/pattern),
+ * and the value is the list of skills it implies.
+ */
+export declare const SIGNAL_SKILL_MAP: Record<string, string[]>;
+/**
+ * Docker-related files that indicate a containerized project.
+ * Used by the init command to suggest Docker zero-downtime deploy scaffolding.
+ */
+export declare const DOCKER_FILES: string[];
+/**
+ * Detect whether the project uses Docker (Dockerfile or compose file present).
+ */
+export declare function detectDockerPresence(projectDir: string): Promise<boolean>;
+export interface StackDetectionResult {
+    /** Primary stack type (node, python, etc.) */
+    stack: Stack | null;
+    /** All detected signals with their source */
+    signals: DetectedSignal[];
+    /** De-duplicated list of recommended skill names */
+    recommendedSkills: string[];
+}
+export interface DetectedSignal {
+    /** What was detected (e.g., "react", "tailwindcss", "tsconfig.json") */
+    signal: string;
+    /** Where it was found (e.g., "package.json dependencies", "file exists") */
+    source: string;
+    /** Skills this signal maps to */
+    skills: string[];
+}
+/**
+ * Scan a project directory and detect its tech stack + recommended skills.
+ * Reads package.json deps, pyproject.toml, and well-known config files.
+ */
+export declare function detectProjectStack(projectDir: string): Promise<StackDetectionResult>;
+//# sourceMappingURL=stack-detector.d.ts.map