javi-forge 1.6.0 → 1.7.0

package/dist/lib/atlassian-mcp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Atlassian MCP pre-config — generates MCP server configuration
+ * for Jira and Confluence integration in scaffolded projects.
+ *
+ * Produces a config snippet that can be merged into .claude/settings.json
+ * or any AI agent's MCP configuration.
+ */
+export interface AtlassianConfig {
+    confluenceUrl: string;
+    confluenceUsername: string;
+    jiraUrl: string;
+    jiraUsername: string;
+}
+export interface McpSnippet {
+    mcpServers: Record<string, {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    }>;
+}
+/**
+ * Generate Atlassian MCP config snippet with user-provided values.
+ * Token placeholders remain as env vars for security.
+ */
+export declare function generateAtlassianMcpConfig(config: AtlassianConfig): McpSnippet;
+/**
+ * Generate a template snippet with placeholders (no user input needed).
+ */
+export declare function generateTemplateMcpConfig(): McpSnippet;
+/**
+ * Write the Atlassian MCP snippet to a project directory.
+ */
+export declare function writeAtlassianMcpSnippet(projectDir: string, config?: AtlassianConfig): Promise<string>;
+/**
+ * Merge Atlassian MCP config into an existing settings.json or MCP config file.
+ */
+export declare function mergeIntoSettings(settingsPath: string, config: AtlassianConfig): Promise<void>;
+/**
+ * Copy the template snippet from templates/common/atlassian/.
+ */
+export declare function copyTemplateSnippet(projectDir: string): Promise<string | null>;
+//# sourceMappingURL=atlassian-mcp.d.ts.map

package/dist/lib/atlassian-mcp.js

@@ -0,0 +1,98 @@
+/**
+ * Atlassian MCP pre-config — generates MCP server configuration
+ * for Jira and Confluence integration in scaffolded projects.
+ *
+ * Produces a config snippet that can be merged into .claude/settings.json
+ * or any AI agent's MCP configuration.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "fs-extra";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, "../../templates");
+/**
+ * Generate Atlassian MCP config snippet with user-provided values.
+ * Token placeholders remain as env vars for security.
+ */
+export function generateAtlassianMcpConfig(config) {
+    return {
+        mcpServers: {
+            atlassian: {
+                command: "uvx",
+                args: ["mcp-atlassian"],
+                env: {
+                    CONFLUENCE_URL: config.confluenceUrl,
+                    CONFLUENCE_USERNAME: config.confluenceUsername,
+                    CONFLUENCE_API_TOKEN: "${CONFLUENCE_API_TOKEN}",
+                    JIRA_URL: config.jiraUrl,
+                    JIRA_USERNAME: config.jiraUsername,
+                    JIRA_API_TOKEN: "${JIRA_API_TOKEN}",
+                },
+            },
+        },
+    };
+}
+/**
+ * Generate a template snippet with placeholders (no user input needed).
+ */
+export function generateTemplateMcpConfig() {
+    return {
+        mcpServers: {
+            atlassian: {
+                command: "uvx",
+                args: ["mcp-atlassian"],
+                env: {
+                    CONFLUENCE_URL: "__CONFLUENCE_URL__",
+                    CONFLUENCE_USERNAME: "__CONFLUENCE_USERNAME__",
+                    CONFLUENCE_API_TOKEN: "__CONFLUENCE_API_TOKEN__",
+                    JIRA_URL: "__JIRA_URL__",
+                    JIRA_USERNAME: "__JIRA_USERNAME__",
+                    JIRA_API_TOKEN: "__JIRA_API_TOKEN__",
+                },
+            },
+        },
+    };
+}
+/**
+ * Write the Atlassian MCP snippet to a project directory.
+ */
+export async function writeAtlassianMcpSnippet(projectDir, config) {
+    const snippet = config
+        ? generateAtlassianMcpConfig(config)
+        : generateTemplateMcpConfig();
+    const destDir = path.join(projectDir, ".atlassian");
+    await fs.ensureDir(destDir);
+    const destFile = path.join(destDir, "mcp-config-snippet.json");
+    await fs.writeJson(destFile, snippet, { spaces: 2 });
+    return destFile;
+}
+/**
+ * Merge Atlassian MCP config into an existing settings.json or MCP config file.
+ */
+export async function mergeIntoSettings(settingsPath, config) {
+    const snippet = generateAtlassianMcpConfig(config);
+    let existing = {};
+    if (await fs.pathExists(settingsPath)) {
+        existing = await fs.readJson(settingsPath);
+    }
+    const existingServers = existing.mcpServers ?? {};
+    existing.mcpServers = {
+        ...existingServers,
+        ...snippet.mcpServers,
+    };
+    await fs.writeJson(settingsPath, existing, { spaces: 2 });
+}
+/**
+ * Copy the template snippet from templates/common/atlassian/.
+ */
+export async function copyTemplateSnippet(projectDir) {
+    const srcFile = path.join(TEMPLATES_DIR, "common", "atlassian", "mcp-atlassian-snippet.json");
+    if (!(await fs.pathExists(srcFile)))
+        return null;
+    const destDir = path.join(projectDir, ".atlassian");
+    await fs.ensureDir(destDir);
+    const destFile = path.join(destDir, "mcp-config-snippet.json");
+    await fs.copy(srcFile, destFile, { overwrite: true });
+    return destFile;
+}
+//# sourceMappingURL=atlassian-mcp.js.map

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

@@ -0,0 +1,37 @@
+import type { StackDetectionResult } from "./stack-detector.js";
+export interface SkillInstallResult {
+    /** Skills that were successfully installed (copied) */
+    installed: string[];
+    /** Skills that were already present */
+    skipped: string[];
+    /** Skills that were recommended but not found in the source */
+    notFound: string[];
+    /** The full detection result for reporting */
+    detection: StackDetectionResult;
+}
+export interface AutoInstallOptions {
+    /** Directory to scan for tech stack detection */
+    projectDir: string;
+    /** Source directory containing skill folders (default: ~/.claude/skills) */
+    skillsSourceDir?: string;
+    /** Target directory where skills are installed (default: ~/.claude/skills) */
+    skillsTargetDir?: string;
+    /** If true, skip actually copying files */
+    dryRun?: boolean;
+}
+/**
+ * Scan a project, detect its stack, and install matching AI skills.
+ *
+ * Skills are "installed" by verifying they exist in the source directory.
+ * Since javi-forge skills live in ~/.claude/skills/, this mainly validates
+ * that the recommended skills are available and reports which ones are missing.
+ *
+ * If skillsSourceDir !== skillsTargetDir, it copies skill folders from
+ * source to target (useful for project-local skill installation).
+ */
+export declare function autoInstallSkills(options: AutoInstallOptions): Promise<SkillInstallResult>;
+/**
+ * Get a human-readable summary of auto-install results.
+ */
+export declare function formatAutoInstallSummary(result: SkillInstallResult): string;
+//# sourceMappingURL=auto-skill-install.d.ts.map

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

@@ -0,0 +1,91 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { DEFAULT_SKILLS_DIR } from "../commands/skills/constants.js";
+import { detectProjectStack } from "./stack-detector.js";
+// ── Core ───────────────────────────────────────────────────────────────────
+/**
+ * Scan a project, detect its stack, and install matching AI skills.
+ *
+ * Skills are "installed" by verifying they exist in the source directory.
+ * Since javi-forge skills live in ~/.claude/skills/, this mainly validates
+ * that the recommended skills are available and reports which ones are missing.
+ *
+ * If skillsSourceDir !== skillsTargetDir, it copies skill folders from
+ * 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;
+    // 1. Detect project stack
+    const detection = await detectProjectStack(projectDir);
+    if (detection.recommendedSkills.length === 0) {
+        return {
+            installed: [],
+            skipped: [],
+            notFound: [],
+            detection,
+        };
+    }
+    const installed = [];
+    const skipped = [];
+    const notFound = [];
+    const sameDir = path.resolve(skillsSourceDir) === path.resolve(skillsTargetDir);
+    for (const skillName of detection.recommendedSkills) {
+        const sourcePath = path.join(skillsSourceDir, skillName);
+        const targetPath = path.join(skillsTargetDir, skillName);
+        const sourceSkillMd = path.join(sourcePath, "SKILL.md");
+        // Check if skill exists in source
+        if (!(await fs.pathExists(sourceSkillMd))) {
+            notFound.push(skillName);
+            continue;
+        }
+        // If same directory, skill is already "installed"
+        if (sameDir) {
+            skipped.push(skillName);
+            continue;
+        }
+        // Check if already present in target
+        const targetSkillMd = path.join(targetPath, "SKILL.md");
+        if (await fs.pathExists(targetSkillMd)) {
+            skipped.push(skillName);
+            continue;
+        }
+        // Copy skill to target
+        if (!dryRun) {
+            await fs.ensureDir(targetPath);
+            await fs.copy(sourcePath, targetPath, {
+                overwrite: false,
+                errorOnExist: false,
+            });
+        }
+        installed.push(skillName);
+    }
+    return { installed, skipped, notFound, detection };
+}
+/**
+ * Get a human-readable summary of auto-install results.
+ */
+export function formatAutoInstallSummary(result) {
+    const lines = [];
+    if (result.detection.stack) {
+        lines.push(`Detected stack: ${result.detection.stack}`);
+    }
+    else {
+        lines.push("No stack detected");
+    }
+    if (result.detection.signals.length > 0) {
+        lines.push(`Signals: ${result.detection.signals.map((s) => s.signal).join(", ")}`);
+    }
+    const total = result.installed.length + result.skipped.length + result.notFound.length;
+    lines.push(`Recommended skills: ${total}`);
+    if (result.installed.length > 0) {
+        lines.push(`  Installed: ${result.installed.join(", ")}`);
+    }
+    if (result.skipped.length > 0) {
+        lines.push(`  Already present: ${result.skipped.join(", ")}`);
+    }
+    if (result.notFound.length > 0) {
+        lines.push(`  Not found: ${result.notFound.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=auto-skill-install.js.map

package/dist/lib/auto-wire.d.ts

@@ -0,0 +1,20 @@
+import type { AutoWireResult, InstalledPlugin } from "../types/index.js";
+/**
+ * Scan installed plugins in a project and wire their capabilities into
+ * the project's CLAUDE.md (skill/plugin entries) and .claude/settings.json
+ * (hooks). Idempotent — re-running produces the same result.
+ */
+export declare function autoWirePlugins(projectDir: string, installedPlugins: InstalledPlugin[], options?: {
+    dryRun?: boolean;
+}): Promise<AutoWireResult>;
+/**
+ * Build the auto-wire section content for CLAUDE.md.
+ * Pure function — no I/O.
+ */
+export declare function buildAutoWireSection(plugins: InstalledPlugin[]): string;
+/**
+ * Remove the auto-wire section from CLAUDE.md content.
+ * Returns cleaned content.
+ */
+export declare function removeAutoWireSection(content: string): string;
+//# sourceMappingURL=auto-wire.d.ts.map

package/dist/lib/auto-wire.js

@@ -0,0 +1,240 @@
+import path from "node:path";
+import fs from "fs-extra";
+// ── Markers ────────────────────────────────────────────────────────────────
+const WIRE_START = "<!-- javi-forge:auto-wire:start -->";
+const WIRE_END = "<!-- javi-forge:auto-wire:end -->";
+// ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Scan installed plugins in a project and wire their capabilities into
+ * the project's CLAUDE.md (skill/plugin entries) and .claude/settings.json
+ * (hooks). Idempotent — re-running produces the same result.
+ */
+export async function autoWirePlugins(projectDir, installedPlugins, options = {}) {
+    const { dryRun = false } = options;
+    const wired = [];
+    const unwired = [];
+    const errors = [];
+    // ── Collect desired entries from plugin manifests ─────────────────────
+    const desiredSkills = [];
+    const desiredHooks = [];
+    for (const plugin of installedPlugins) {
+        const { manifest } = plugin;
+        if (!manifest)
+            continue;
+        // Skills → CLAUDE.md skill loader lines
+        for (const skill of manifest.skills ?? []) {
+            desiredSkills.push({
+                plugin: manifest.name,
+                target: "claude-md",
+                capability: "skill",
+                value: skill,
+            });
+        }
+        // Hooks → .claude/settings.json
+        for (const hook of manifest.hooks ?? []) {
+            desiredHooks.push({
+                plugin: manifest.name,
+                target: "settings-json",
+                capability: "hook",
+                value: hook,
+            });
+        }
+    }
+    // ── Wire skills into CLAUDE.md ───────────────────────────────────────
+    try {
+        const claudeResult = await wireClaudeMd(projectDir, desiredSkills, installedPlugins, dryRun);
+        wired.push(...claudeResult.wired);
+        unwired.push(...claudeResult.unwired);
+    }
+    catch (e) {
+        errors.push(`CLAUDE.md wiring failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // ── Wire hooks into .claude/settings.json ────────────────────────────
+    try {
+        const hooksResult = await wireSettingsJson(projectDir, desiredHooks, installedPlugins, dryRun);
+        wired.push(...hooksResult.wired);
+        unwired.push(...hooksResult.unwired);
+    }
+    catch (e) {
+        errors.push(`settings.json wiring failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { wired, unwired, errors };
+}
+// ── CLAUDE.md Wiring ───────────────────────────────────────────────────────
+/**
+ * Build the auto-wire section content for CLAUDE.md.
+ * Pure function — no I/O.
+ */
+export function buildAutoWireSection(plugins) {
+    const lines = [];
+    lines.push(WIRE_START);
+    lines.push("");
+    lines.push("## Plugins (auto-wired)");
+    lines.push("");
+    for (const plugin of plugins) {
+        const { manifest } = plugin;
+        if (!manifest)
+            continue;
+        lines.push(`### ${manifest.name} v${manifest.version}`);
+        lines.push(`> ${manifest.description}`);
+        lines.push("");
+        // Skills
+        const skills = manifest.skills ?? [];
+        if (skills.length > 0) {
+            for (const skill of skills) {
+                lines.push(`- Load \`~/.claude/plugins/${manifest.name}/skills/${skill}/SKILL.md\` when working with ${skill}`);
+            }
+            lines.push("");
+        }
+        // Commands
+        const commands = manifest.commands ?? [];
+        if (commands.length > 0) {
+            lines.push("**Commands:**");
+            for (const cmd of commands) {
+                lines.push(`- \`/${cmd}\``);
+            }
+            lines.push("");
+        }
+        // Agents
+        const agents = manifest.agents ?? [];
+        if (agents.length > 0) {
+            lines.push("**Agents:**");
+            for (const agent of agents) {
+                lines.push(`- ${agent}`);
+            }
+            lines.push("");
+        }
+    }
+    lines.push(WIRE_END);
+    return lines.join("\n");
+}
+async function wireClaudeMd(projectDir, desiredSkills, plugins, dryRun) {
+    const claudeMdPath = path.join(projectDir, "CLAUDE.md");
+    const wired = [];
+    const unwired = [];
+    // If no plugins have capabilities, remove section if present
+    const pluginsWithCapabilities = plugins.filter((p) => {
+        const m = p.manifest;
+        if (!m)
+            return false;
+        return ((m.skills?.length ?? 0) > 0 ||
+            (m.commands?.length ?? 0) > 0 ||
+            (m.agents?.length ?? 0) > 0);
+    });
+    let content = "";
+    if (await fs.pathExists(claudeMdPath)) {
+        content = await fs.readFile(claudeMdPath, "utf-8");
+    }
+    // Remove existing auto-wire section (idempotent)
+    const cleaned = removeAutoWireSection(content);
+    if (pluginsWithCapabilities.length === 0) {
+        // Nothing to wire — if we cleaned something, that's an unwire
+        if (cleaned !== content && !dryRun) {
+            await fs.writeFile(claudeMdPath, cleaned, "utf-8");
+        }
+        return { wired, unwired };
+    }
+    // Build new section
+    const section = buildAutoWireSection(pluginsWithCapabilities);
+    const newContent = `${cleaned.trimEnd()}\n\n${section}\n`;
+    if (!dryRun) {
+        await fs.ensureDir(path.dirname(claudeMdPath));
+        await fs.writeFile(claudeMdPath, newContent, "utf-8");
+    }
+    // Track what was wired
+    for (const entry of desiredSkills) {
+        wired.push(entry);
+    }
+    for (const plugin of pluginsWithCapabilities) {
+        for (const cmd of plugin.manifest.commands ?? []) {
+            wired.push({
+                plugin: plugin.manifest.name,
+                target: "claude-md",
+                capability: "command",
+                value: cmd,
+            });
+        }
+        for (const agent of plugin.manifest.agents ?? []) {
+            wired.push({
+                plugin: plugin.manifest.name,
+                target: "claude-md",
+                capability: "agent",
+                value: agent,
+            });
+        }
+    }
+    return { wired, unwired };
+}
+// ── Settings.json Wiring ───────────────────────────────────────────────────
+async function wireSettingsJson(projectDir, desiredHooks, _plugins, dryRun) {
+    const wired = [];
+    const unwired = [];
+    if (desiredHooks.length === 0)
+        return { wired, unwired };
+    const settingsPath = path.join(projectDir, ".claude", "settings.json");
+    let settings = {};
+    if (await fs.pathExists(settingsPath)) {
+        try {
+            settings = await fs.readJson(settingsPath);
+        }
+        catch {
+            settings = {};
+        }
+    }
+    // Ensure hooks object
+    const hooks = (settings.hooks ?? {});
+    const pluginHooks = (hooks["plugin-hooks"] ?? []);
+    const existingSet = new Set(pluginHooks);
+    for (const entry of desiredHooks) {
+        if (existingSet.has(entry.value)) {
+            // Already wired — skip (idempotent)
+            continue;
+        }
+        pluginHooks.push(entry.value);
+        existingSet.add(entry.value);
+        wired.push(entry);
+    }
+    // Detect hooks that belong to removed plugins
+    const _activePluginNames = new Set(desiredHooks.map((h) => h.plugin));
+    const cleanedHooks = pluginHooks.filter((h) => {
+        // Keep hooks that we just wired or that belong to active plugins
+        const belongsToActive = desiredHooks.some((d) => d.value === h);
+        if (!belongsToActive) {
+            unwired.push({
+                plugin: "unknown",
+                target: "settings-json",
+                capability: "hook",
+                value: h,
+            });
+            return false;
+        }
+        return true;
+    });
+    hooks["plugin-hooks"] = cleanedHooks;
+    settings.hooks = hooks;
+    if (!dryRun && (wired.length > 0 || unwired.length > 0)) {
+        await fs.ensureDir(path.dirname(settingsPath));
+        await fs.writeJson(settingsPath, settings, { spaces: 2 });
+    }
+    return { wired, unwired };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Remove the auto-wire section from CLAUDE.md content.
+ * Returns cleaned content.
+ */
+export function removeAutoWireSection(content) {
+    const startIdx = content.indexOf(WIRE_START);
+    if (startIdx === -1)
+        return content;
+    const endIdx = content.indexOf(WIRE_END);
+    if (endIdx === -1)
+        return content;
+    const before = content.slice(0, startIdx).trimEnd();
+    const after = content.slice(endIdx + WIRE_END.length).trimStart();
+    if (after) {
+        return `${before}\n\n${after}`;
+    }
+    return `${before}\n`;
+}
+//# sourceMappingURL=auto-wire.js.map

package/dist/lib/ci-config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Versioned mixed-runner CI config (`.javi-forge/ci.yaml`) — schema and loader.
+ *
+ * Hybrid repositories declare every required runner explicitly and in order.
+ * Single-stack repositories need no config: auto-detection stays the default.
+ *
+ * Validation is fail-closed: any schema violation produces a CIConfigError
+ * listing every problem, and no partially-valid config is ever returned.
+ * YAML parsing uses the `yaml` package, already a runtime dependency.
+ */
+import type { Stack } from "../types/index.js";
+export declare const CI_CONFIG_VERSION = 1;
+/** Default config locations, in discovery order, relative to the project root. */
+export declare const CI_CONFIG_CANDIDATES: readonly [".javi-forge/ci.yaml", ".javi-forge/ci.yml"];
+export interface CIRunnerConfig {
+    /** Unique runner name (used in step ids and reports) */
+    name: string;
+    /** Toolchain stack — selects the default CI image and default commands */
+    stack: Stack;
+    /** Working directory relative to the project root (default: ".") */
+    directory: string;
+    /** Explicit container image (mutually exclusive with `buildContext`) */
+    image?: string;
+    /** Docker build context directory (mutually exclusive with `image`) */
+    buildContext?: string;
+    /** Dependency setup commands, run before lint/build/test */
+    setup: string[];
+    lint: string[];
+    build: string[];
+    test: string[];
+    security: string[];
+    /** Tools that must exist in the runner environment (validated fail-closed) */
+    requires: string[];
+}
+export interface CIConfig {
+    version: number;
+    runners: CIRunnerConfig[];
+}
+export interface CIConfigValidationError {
+    path: string;
+    message: string;
+}
+export declare class CIConfigError extends Error {
+    readonly errors: CIConfigValidationError[];
+    constructor(errors: CIConfigValidationError[], source?: string);
+}
+/** Stacks accepted by the CI config schema and the --stack override. */
+export declare const CI_STACKS: readonly string[];
+/**
+ * Parse and validate CI config YAML text. Throws CIConfigError listing every
+ * validation problem; never returns a partially valid config.
+ */
+export declare function parseCIConfig(rawYaml: string, source?: string): CIConfig;
+/**
+ * Load and validate a CI config file. Fails closed: a missing file or any
+ * validation error throws — no config is ever silently ignored.
+ */
+export declare function loadCIConfig(configPath: string): Promise<CIConfig>;
+/**
+ * Discover the default CI config for a project directory.
+ * Returns the config path, or null when the project has no config
+ * (single-stack auto-detection stays the default).
+ */
+export declare function findCIConfig(projectDir: string): Promise<string | null>;
+//# sourceMappingURL=ci-config.d.ts.map