javi-forge 1.5.0 → 1.6.1

package/dist/lib/claudemd.js

@@ -0,0 +1,222 @@
+import { STACK_CLAUDEMD_MAP } from "../constants.js";
+// =============================================================================
+// Architecture pattern mapping (signal → patterns)
+// =============================================================================
+const ARCHITECTURE_PATTERNS = {
+    "react-19": [
+        "Container-Presentational pattern",
+        "Atomic Design for component hierarchy",
+    ],
+    "nextjs-15": [
+        "App Router file-based routing",
+        "Server Components by default, client opt-in",
+    ],
+    "django-drf": ["ViewSets + Serializers", "URL namespace per app"],
+    "zustand-5": [
+        "Slice pattern for store modules",
+        "Selectors for derived state",
+    ],
+    typescript: [
+        "Strict mode enabled",
+        "Prefer interfaces for public APIs, types for unions",
+    ],
+    "tailwind-4": ["Utility-first CSS", "Use `cn()` for conditional classes"],
+    "zod-4": [
+        "Schema-first validation",
+        "Infer types from schemas with `z.infer`",
+    ],
+    playwright: [
+        "Page Object Model for E2E tests",
+        "Locator-based selectors over CSS",
+    ],
+    pytest: ["Fixtures for setup/teardown", "Parametrize for data-driven tests"],
+    "ai-sdk-5": [
+        "Streaming responses by default",
+        "Tool calling with structured schemas",
+    ],
+};
+// =============================================================================
+// Plugin instruction mapping (detected skill → plugin hints)
+// =============================================================================
+const PLUGIN_INSTRUCTIONS = {
+    "react-19": "Check `~/.claude/plugins/` for merge-checks and mermaid diagram support",
+    "nextjs-15": "Check `~/.claude/plugins/` for merge-checks and mermaid diagram support",
+    typescript: "Run `javi-forge skills doctor` to validate skill compatibility",
+    playwright: "Use `javi-forge tdd` for test-driven development workflow",
+};
+// =============================================================================
+// Internal helpers
+// =============================================================================
+function getStackClaudeMd(stack) {
+    return STACK_CLAUDEMD_MAP[stack] ?? STACK_CLAUDEMD_MAP["default"];
+}
+export function buildClaudeMd(projectName, stack, entry, contextDir, modules) {
+    const lines = [];
+    lines.push(`# ${projectName}`);
+    lines.push("");
+    // Stack section
+    lines.push("## Stack");
+    lines.push(`- **Language/Runtime**: ${stack}`);
+    lines.push(`- **Conventions**: ${entry.conventions}`);
+    lines.push(`- **Testing**: ${entry.testFramework}`);
+    lines.push("");
+    // Skills section
+    if (entry.skills.length > 0) {
+        lines.push("## Recommended Skills");
+        for (const skill of entry.skills) {
+            lines.push(`- Load \`~/.claude/skills/${skill}/SKILL.md\` before writing code`);
+        }
+        lines.push("");
+    }
+    // Project Context section (conditional on contextDir)
+    if (contextDir) {
+        lines.push("## Project Context");
+        lines.push("- See `.context/INDEX.md` for file structure and entry points");
+        lines.push("- See `.context/summary.md` for project overview");
+        lines.push("");
+    }
+    // Conventions section
+    lines.push("## Conventions");
+    lines.push(`- ${entry.conventions}`);
+    lines.push("- Scaffolded with javi-forge — see `.javi-forge/manifest.json` for config");
+    lines.push("");
+    // Modules section
+    if (modules.length > 0) {
+        lines.push("## Modules");
+        lines.push(`- ${modules.join(", ")}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Build an enriched CLAUDE.md using detected skills, architecture patterns,
+ * and plugin instructions. Pure function — no I/O.
+ */
+export function buildSmartClaudeMd(projectName, stack, entry, detectedSkills, contextDir, modules) {
+    const lines = [];
+    // Merge: detected skills + static entry skills (deduplicated)
+    const allSkills = [...new Set([...detectedSkills, ...entry.skills])].sort();
+    lines.push(`# ${projectName}`);
+    lines.push("");
+    // Stack section
+    lines.push("## Stack");
+    lines.push(`- **Language/Runtime**: ${stack}`);
+    lines.push(`- **Conventions**: ${entry.conventions}`);
+    lines.push(`- **Testing**: ${entry.testFramework}`);
+    lines.push("");
+    // Skills section — auto-detected + static
+    if (allSkills.length > 0) {
+        lines.push("## Skills (auto-detected)");
+        lines.push("");
+        lines.push("Load these skill files BEFORE writing code in this project:");
+        lines.push("");
+        for (const skill of allSkills) {
+            lines.push(`- \`~/.claude/skills/${skill}/SKILL.md\``);
+        }
+        lines.push("");
+    }
+    // Architecture patterns section — derived from detected skills
+    const patterns = [];
+    for (const skill of allSkills) {
+        const skillPatterns = ARCHITECTURE_PATTERNS[skill];
+        if (skillPatterns) {
+            patterns.push(...skillPatterns);
+        }
+    }
+    if (patterns.length > 0) {
+        lines.push("## Architecture Patterns");
+        lines.push("");
+        for (const pattern of patterns) {
+            lines.push(`- ${pattern}`);
+        }
+        lines.push("");
+    }
+    // Project Context section
+    if (contextDir) {
+        lines.push("## Project Context");
+        lines.push("- See `.context/INDEX.md` for file structure and entry points");
+        lines.push("- See `.context/summary.md` for project overview");
+        lines.push("");
+    }
+    // Conventions section
+    lines.push("## Conventions");
+    lines.push(`- ${entry.conventions}`);
+    lines.push("- Scaffolded with javi-forge — see `.javi-forge/manifest.json` for config");
+    lines.push("");
+    // Plugin instructions — derived from detected skills
+    const pluginHints = new Set();
+    for (const skill of allSkills) {
+        const hint = PLUGIN_INSTRUCTIONS[skill];
+        if (hint)
+            pluginHints.add(hint);
+    }
+    if (pluginHints.size > 0) {
+        lines.push("## Plugins");
+        lines.push("");
+        for (const hint of pluginHints) {
+            lines.push(`- ${hint}`);
+        }
+        lines.push("");
+    }
+    // Modules section
+    if (modules.length > 0) {
+        lines.push("## Modules");
+        lines.push(`- ${modules.join(", ")}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Generate CLAUDE.md content from InitOptions metadata.
+ * Pure function — does NOT perform filesystem I/O.
+ */
+export function generateClaudeMd(options) {
+    const { projectName, stack, contextDir } = options;
+    const entry = getStackClaudeMd(stack);
+    // Collect enabled modules for listing
+    const modules = [];
+    if (options.aiSync)
+        modules.push("ai-sync");
+    if (options.sdd)
+        modules.push("sdd");
+    if (options.ghagga)
+        modules.push("ghagga");
+    if (options.mock)
+        modules.push("mock");
+    if (options.contextDir)
+        modules.push("context");
+    if (options.claudeMd)
+        modules.push("claude-md");
+    return buildClaudeMd(projectName, stack, entry, contextDir, modules);
+}
+/**
+ * Generate a project-aware CLAUDE.md using stack detection results.
+ * Falls back to static generation if no detection result provided.
+ * Pure function — does NOT perform filesystem I/O.
+ */
+export function generateSmartClaudeMd(options, detection) {
+    // Fallback: no detection result, use static generation
+    if (!detection || detection.recommendedSkills.length === 0) {
+        return generateClaudeMd(options);
+    }
+    const { projectName, stack, contextDir } = options;
+    const entry = getStackClaudeMd(stack);
+    const modules = [];
+    if (options.aiSync)
+        modules.push("ai-sync");
+    if (options.sdd)
+        modules.push("sdd");
+    if (options.ghagga)
+        modules.push("ghagga");
+    if (options.mock)
+        modules.push("mock");
+    if (options.contextDir)
+        modules.push("context");
+    if (options.claudeMd)
+        modules.push("claude-md");
+    return buildSmartClaudeMd(projectName, stack, entry, detection.recommendedSkills, contextDir, modules);
+}
+//# sourceMappingURL=claudemd.js.map

package/dist/lib/codex-export.d.ts

@@ -0,0 +1,16 @@
+import type { CodexExportResult, CodexTomlEntry } from "../types/index.js";
+/**
+ * Convert a SKILL.md raw content string into a CodexTomlEntry.
+ * Returns null if the file has no valid frontmatter or missing name.
+ */
+export declare function skillToCodexToml(raw: string): CodexTomlEntry | null;
+/**
+ * Serialize a CodexTomlEntry to a TOML string.
+ */
+export declare function serializeToml(entry: CodexTomlEntry): string;
+/**
+ * Export an installed plugin's SKILL.md files as Codex-compatible TOML subagent files.
+ * Writes .toml files to a `codex/` subdirectory inside the plugin directory.
+ */
+export declare function exportPluginAsCodexToml(name: string): Promise<CodexExportResult>;
+//# sourceMappingURL=codex-export.d.ts.map

package/dist/lib/codex-export.js

@@ -0,0 +1,109 @@
+import fs from "fs-extra";
+import path from "path";
+import { PLUGIN_MANIFEST_FILE, PLUGINS_DIR } from "../constants.js";
+import { parseFrontmatter } from "./frontmatter.js";
+const DEFAULT_MODEL = "o4-mini";
+// ── Conversion ─────────────────────────────────────────────────────────────
+/**
+ * Convert a SKILL.md raw content string into a CodexTomlEntry.
+ * Returns null if the file has no valid frontmatter or missing name.
+ */
+export function skillToCodexToml(raw) {
+    const parsed = parseFrontmatter(raw);
+    if (!parsed)
+        return null;
+    const name = parsed.data["name"];
+    if (typeof name !== "string" || !name)
+        return null;
+    const description = typeof parsed.data["description"] === "string"
+        ? parsed.data["description"]
+        : "";
+    const model = typeof parsed.data["model"] === "string"
+        ? parsed.data["model"]
+        : DEFAULT_MODEL;
+    const instructions = description
+        ? `${description}\n\n${parsed.content}`.trim()
+        : parsed.content.trim();
+    return { name, model, instructions };
+}
+/**
+ * Serialize a CodexTomlEntry to a TOML string.
+ */
+export function serializeToml(entry) {
+    const escapedName = escapeTomlString(entry.name);
+    const escapedModel = escapeTomlString(entry.model);
+    const escapedInstructions = escapeTomlMultiline(entry.instructions);
+    return [
+        `name = "${escapedName}"`,
+        `model = "${escapedModel}"`,
+        `instructions = """`,
+        escapedInstructions,
+        `"""`,
+        "",
+    ].join("\n");
+}
+// ── File I/O ───────────────────────────────────────────────────────────────
+/**
+ * Export an installed plugin's SKILL.md files as Codex-compatible TOML subagent files.
+ * Writes .toml files to a `codex/` subdirectory inside the plugin directory.
+ */
+export async function exportPluginAsCodexToml(name) {
+    const pluginDir = path.join(PLUGINS_DIR, name);
+    if (!(await fs.pathExists(pluginDir))) {
+        return { success: false, error: `plugin "${name}" is not installed` };
+    }
+    // Read plugin manifest for skill list
+    const manifestPath = path.join(pluginDir, PLUGIN_MANIFEST_FILE);
+    if (!(await fs.pathExists(manifestPath))) {
+        return { success: false, error: "plugin.json not found" };
+    }
+    let manifest;
+    try {
+        manifest = (await fs.readJson(manifestPath));
+    }
+    catch {
+        return { success: false, error: "invalid plugin.json" };
+    }
+    const skillNames = manifest.skills ?? [];
+    if (skillNames.length === 0) {
+        return { success: false, error: "plugin has no skills to export" };
+    }
+    const codexDir = path.join(pluginDir, "codex");
+    await fs.ensureDir(codexDir);
+    const writtenFiles = [];
+    for (const skillName of skillNames) {
+        const skillPath = path.join(pluginDir, "skills", skillName, "SKILL.md");
+        if (!(await fs.pathExists(skillPath)))
+            continue;
+        let raw;
+        try {
+            raw = await fs.readFile(skillPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const entry = skillToCodexToml(raw);
+        if (!entry)
+            continue;
+        const toml = serializeToml(entry);
+        const outPath = path.join(codexDir, `${skillName}.toml`);
+        await fs.writeFile(outPath, toml, "utf-8");
+        writtenFiles.push(outPath);
+    }
+    if (writtenFiles.length === 0) {
+        return { success: false, error: "no skills with valid frontmatter found" };
+    }
+    return { success: true, files: writtenFiles };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+function escapeTomlString(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n");
+}
+function escapeTomlMultiline(value) {
+    // In TOML multiline basic strings ("""), only backslashes and triple quotes need escaping
+    return value.replace(/\\/g, "\\\\").replace(/"""/g, '"\\""');
+}
+//# sourceMappingURL=codex-export.js.map

package/dist/lib/common.d.ts

@@ -1,4 +1,4 @@
-import type { Stack, StackDetection } from '../types/index.js';
+import type { Stack, StackDetection } from "../types/index.js";
 /**
  * Detect the project stack by looking for well-known build/config files.
  * Returns the first match (precedence order matters).

package/dist/lib/common.js

@@ -1,5 +1,5 @@
-import fs from 'fs-extra';
-import path from 'path';
+import fs from "fs-extra";
+import path from "path";
 /**
  * Detect the project stack by looking for well-known build/config files.
  * Returns the first match (precedence order matters).
@@ -7,70 +7,78 @@ import path from 'path';
 export async function detectStack(projectDir) {
     const exists = async (file) => fs.pathExists(path.join(projectDir, file));
     // Java — Gradle
-    if (await exists('build.gradle') || await exists('build.gradle.kts')) {
+    if ((await exists("build.gradle")) || (await exists("build.gradle.kts"))) {
         const javaVersion = await detectJavaVersion(projectDir);
-        return { stackType: 'java-gradle', buildTool: 'gradle', javaVersion };
+        return { stackType: "java-gradle", buildTool: "gradle", javaVersion };
     }
     // Java — Maven
-    if (await exists('pom.xml')) {
+    if (await exists("pom.xml")) {
         const javaVersion = await detectJavaVersion(projectDir);
-        return { stackType: 'java-maven', buildTool: 'maven', javaVersion };
+        return { stackType: "java-maven", buildTool: "maven", javaVersion };
     }
     // Node.js
-    if (await exists('package.json')) {
-        const pkg = await fs.readJson(path.join(projectDir, 'package.json')).catch(() => ({}));
-        const buildTool = await exists('pnpm-lock.yaml') ? 'pnpm'
-            : await exists('yarn.lock') ? 'yarn'
-                : 'npm';
-        return { stackType: 'node', buildTool };
+    if (await exists("package.json")) {
+        const pkg = await fs
+            .readJson(path.join(projectDir, "package.json"))
+            .catch(() => ({}));
+        const buildTool = (await exists("pnpm-lock.yaml"))
+            ? "pnpm"
+            : (await exists("yarn.lock"))
+                ? "yarn"
+                : "npm";
+        return { stackType: "node", buildTool };
     }
     // Python
-    if (await exists('pyproject.toml') || await exists('requirements.txt') || await exists('setup.py')) {
-        const buildTool = await exists('pyproject.toml') ? 'pyproject'
-            : await exists('Pipfile') ? 'pipenv'
-                : 'pip';
-        return { stackType: 'python', buildTool };
+    if ((await exists("pyproject.toml")) ||
+        (await exists("requirements.txt")) ||
+        (await exists("setup.py"))) {
+        const buildTool = (await exists("pyproject.toml"))
+            ? "pyproject"
+            : (await exists("Pipfile"))
+                ? "pipenv"
+                : "pip";
+        return { stackType: "python", buildTool };
     }
     // Go
-    if (await exists('go.mod')) {
-        return { stackType: 'go', buildTool: 'go' };
+    if (await exists("go.mod")) {
+        return { stackType: "go", buildTool: "go" };
     }
     // Rust
-    if (await exists('Cargo.toml')) {
-        return { stackType: 'rust', buildTool: 'cargo' };
+    if (await exists("Cargo.toml")) {
+        return { stackType: "rust", buildTool: "cargo" };
     }
     // Elixir
-    if (await exists('mix.exs')) {
-        return { stackType: 'elixir', buildTool: 'mix' };
+    if (await exists("mix.exs")) {
+        return { stackType: "elixir", buildTool: "mix" };
     }
     return null;
 }
 /** Try to detect Java version from gradle or maven config */
 async function detectJavaVersion(projectDir) {
     // Try build.gradle
-    const gradleFile = path.join(projectDir, 'build.gradle');
+    const gradleFile = path.join(projectDir, "build.gradle");
     if (await fs.pathExists(gradleFile)) {
-        const content = await fs.readFile(gradleFile, 'utf-8');
-        const match = content.match(/sourceCompatibility\s*=\s*['"]?(\d+)/)
-            || content.match(/JavaVersion\.VERSION_(\d+)/);
+        const content = await fs.readFile(gradleFile, "utf-8");
+        const match = content.match(/sourceCompatibility\s*=\s*['"]?(\d+)/) ||
+            content.match(/JavaVersion\.VERSION_(\d+)/);
         if (match)
             return match[1];
     }
     // Try build.gradle.kts
-    const ktsFile = path.join(projectDir, 'build.gradle.kts');
+    const ktsFile = path.join(projectDir, "build.gradle.kts");
     if (await fs.pathExists(ktsFile)) {
-        const content = await fs.readFile(ktsFile, 'utf-8');
-        const match = content.match(/jvmTarget\s*=\s*['"](\d+)['"]/)
-            || content.match(/JavaVersion\.VERSION_(\d+)/);
+        const content = await fs.readFile(ktsFile, "utf-8");
+        const match = content.match(/jvmTarget\s*=\s*['"](\d+)['"]/) ||
+            content.match(/JavaVersion\.VERSION_(\d+)/);
         if (match)
             return match[1];
     }
     // Try pom.xml
-    const pomFile = path.join(projectDir, 'pom.xml');
+    const pomFile = path.join(projectDir, "pom.xml");
     if (await fs.pathExists(pomFile)) {
-        const content = await fs.readFile(pomFile, 'utf-8');
-        const match = content.match(/<java\.version>(\d+)</)
-            || content.match(/<maven\.compiler\.source>(\d+)</);
+        const content = await fs.readFile(pomFile, "utf-8");
+        const match = content.match(/<java\.version>(\d+)</) ||
+            content.match(/<maven\.compiler\.source>(\d+)</);
         if (match)
             return match[1];
     }
@@ -90,22 +98,22 @@ export async function ensureDirExists(dirPath) {
 }
 /** Check if a directory is a git repository */
 export async function isGitRepo(dir) {
-    return fs.pathExists(path.join(dir, '.git'));
+    return fs.pathExists(path.join(dir, ".git"));
 }
 /** Resolve the forge assets root (the package root directory) */
 export function getForgeRoot() {
     // When running from dist/, go up one level
     const thisDir = path.dirname(new URL(import.meta.url).pathname);
-    return path.resolve(thisDir, '..');
+    return path.resolve(thisDir, "..");
 }
 /** Stack display names */
 export const STACK_LABELS = {
-    'node': 'Node.js / TypeScript',
-    'python': 'Python',
-    'go': 'Go',
-    'rust': 'Rust',
-    'java-gradle': 'Java (Gradle)',
-    'java-maven': 'Java (Maven)',
-    'elixir': 'Elixir',
+    node: "Node.js / TypeScript",
+    python: "Python",
+    go: "Go",
+    rust: "Rust",
+    "java-gradle": "Java (Gradle)",
+    "java-maven": "Java (Maven)",
+    elixir: "Elixir",
 };
 //# sourceMappingURL=common.js.map

package/dist/lib/context.d.ts

@@ -0,0 +1,27 @@
+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;
+/**
+ * Detect top-level dependencies from project manifest files.
+ * Returns up to 10 dependency names (key deps only, not devDeps).
+ */
+export declare function detectDependencies(projectDir: string, stack: string): Promise<string[]>;
+/**
+ * Generate .context/ directory content from InitOptions metadata.
+ * Pure function — does NOT perform filesystem I/O.
+ */
+export declare function generateContextDir(options: InitOptions): Promise<{
+    index: string;
+    summary: string;
+}>;
+/**
+ * Refresh .context/ directory from the forge manifest and live project state.
+ * Reads manifest, detects current dependencies, regenerates INDEX.md + summary.md.
+ * Returns null if the project is not forge-managed or has no .context/ dir.
+ */
+export declare function refreshContextDir(projectDir: string): Promise<{
+    index: string;
+    summary: string;
+    updated: boolean;
+} | null>;
+//# sourceMappingURL=context.d.ts.map