javi-forge 1.6.0 → 1.7.0

package/dist/lib/ci-config.js

@@ -0,0 +1,297 @@
+/**
+ * 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 path from "node:path";
+import fs from "fs-extra";
+import YAML from "yaml";
+// =============================================================================
+// Types
+// =============================================================================
+export const CI_CONFIG_VERSION = 1;
+/** Default config locations, in discovery order, relative to the project root. */
+export const CI_CONFIG_CANDIDATES = [
+    ".javi-forge/ci.yaml",
+    ".javi-forge/ci.yml",
+];
+export class CIConfigError extends Error {
+    errors;
+    constructor(errors, source) {
+        const where = source ? ` in ${source}` : "";
+        const lines = errors.map((e) => `  - ${e.path}: ${e.message}`).join("\n");
+        super(`Invalid CI config${where}:\n${lines}`);
+        this.name = "CIConfigError";
+        this.errors = errors;
+    }
+}
+// =============================================================================
+// Validation
+// =============================================================================
+const VALID_STACKS = [
+    "node",
+    "python",
+    "go",
+    "rust",
+    "java-gradle",
+    "java-maven",
+    "elixir",
+];
+/** Stacks accepted by the CI config schema and the --stack override. */
+export const CI_STACKS = VALID_STACKS;
+const TOP_LEVEL_FIELDS = new Set(["version", "runners"]);
+/** Runner names become docker image tags — keep them tag-safe. */
+const RUNNER_NAME_RE = /^[a-zA-Z0-9_][a-zA-Z0-9._-]*$/;
+/** Required tools are checked via `command -v <tool>` — no shell metachars. */
+const TOOL_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._+~-]*$/;
+const RUNNER_FIELDS = new Set([
+    "name",
+    "stack",
+    "directory",
+    "image",
+    "build-context",
+    "setup",
+    "lint",
+    "build",
+    "test",
+    "security",
+    "requires",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeCommands(value, fieldPath, errors) {
+    if (value === undefined)
+        return [];
+    if (typeof value === "string")
+        return value.trim() ? [value] : [];
+    if (Array.isArray(value)) {
+        const bad = value.some((v) => typeof v !== "string" || !v.trim());
+        if (!bad)
+            return value;
+    }
+    errors.push({
+        path: fieldPath,
+        message: "must be a non-empty string or a list of non-empty strings",
+    });
+    return [];
+}
+function normalizeStringList(value, fieldPath, errors) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return value;
+    }
+    errors.push({ path: fieldPath, message: "must be a list of strings" });
+    return [];
+}
+function validateRunner(raw, index, errors) {
+    const base = `runners[${index}]`;
+    if (!isRecord(raw)) {
+        errors.push({ path: base, message: "runner must be an object" });
+        return null;
+    }
+    for (const key of Object.keys(raw)) {
+        if (!RUNNER_FIELDS.has(key)) {
+            errors.push({
+                path: `${base}.${key}`,
+                message: `unknown field "${key}"`,
+            });
+        }
+    }
+    const name = raw.name;
+    if (typeof name !== "string" || !name.trim()) {
+        errors.push({
+            path: `${base}.name`,
+            message: "name is required and must be a non-empty string",
+        });
+    }
+    else if (!RUNNER_NAME_RE.test(name.trim())) {
+        errors.push({
+            path: `${base}.name`,
+            message: "name must start with a letter, digit or underscore and contain only [a-zA-Z0-9._-] (it is used as a docker image tag)",
+        });
+    }
+    const stack = raw.stack;
+    if (typeof stack !== "string" || !VALID_STACKS.includes(stack)) {
+        errors.push({
+            path: `${base}.stack`,
+            message: `stack is required and must be one of: ${VALID_STACKS.join(", ")}`,
+        });
+    }
+    let directory = ".";
+    if (raw.directory !== undefined) {
+        if (typeof raw.directory !== "string" || !raw.directory.trim()) {
+            errors.push({
+                path: `${base}.directory`,
+                message: "directory must be a non-empty string",
+            });
+        }
+        else {
+            const normalized = path.posix.normalize(raw.directory);
+            if (path.isAbsolute(raw.directory) ||
+                normalized === ".." ||
+                normalized.startsWith("../")) {
+                errors.push({
+                    path: `${base}.directory`,
+                    message: "directory must stay inside the project root",
+                });
+            }
+            else {
+                directory = normalized;
+            }
+        }
+    }
+    let image;
+    if (raw.image !== undefined) {
+        if (typeof raw.image !== "string" || !raw.image.trim()) {
+            errors.push({
+                path: `${base}.image`,
+                message: "image must be a non-empty string",
+            });
+        }
+        else {
+            image = raw.image;
+        }
+    }
+    let buildContext;
+    if (raw["build-context"] !== undefined) {
+        if (typeof raw["build-context"] !== "string" ||
+            !raw["build-context"].trim()) {
+            errors.push({
+                path: `${base}.build-context`,
+                message: "build-context must be a non-empty string (directory)",
+            });
+        }
+        else {
+            buildContext = raw["build-context"];
+        }
+    }
+    if (image && buildContext) {
+        errors.push({
+            path: `${base}.image`,
+            message: "image and build-context are mutually exclusive — set only one",
+        });
+    }
+    const requires = normalizeStringList(raw.requires, `${base}.requires`, errors);
+    for (const tool of requires) {
+        if (!TOOL_NAME_RE.test(tool)) {
+            errors.push({
+                path: `${base}.requires`,
+                message: `requires entry "${tool}" has unsafe characters — expected a plain tool name like python, ruff or node`,
+            });
+        }
+    }
+    // If anything failed, the caller discards all runners (fail closed).
+    return {
+        name: typeof name === "string" ? name.trim() : "",
+        stack: stack,
+        directory,
+        image,
+        buildContext,
+        setup: normalizeCommands(raw.setup, `${base}.setup`, errors),
+        lint: normalizeCommands(raw.lint, `${base}.lint`, errors),
+        build: normalizeCommands(raw.build, `${base}.build`, errors),
+        test: normalizeCommands(raw.test, `${base}.test`, errors),
+        security: normalizeCommands(raw.security, `${base}.security`, errors),
+        requires,
+    };
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Parse and validate CI config YAML text. Throws CIConfigError listing every
+ * validation problem; never returns a partially valid config.
+ */
+export function parseCIConfig(rawYaml, source) {
+    let doc;
+    try {
+        doc = YAML.parse(rawYaml);
+    }
+    catch (e) {
+        throw new CIConfigError([
+            {
+                path: "<document>",
+                message: `invalid YAML: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`,
+            },
+        ], source);
+    }
+    const errors = [];
+    if (!isRecord(doc)) {
+        throw new CIConfigError([{ path: "<document>", message: "config must be a YAML object/mapping" }], source);
+    }
+    for (const key of Object.keys(doc)) {
+        if (!TOP_LEVEL_FIELDS.has(key)) {
+            errors.push({ path: key, message: `unknown field "${key}"` });
+        }
+    }
+    if (doc.version !== CI_CONFIG_VERSION) {
+        errors.push({
+            path: "version",
+            message: `version is required and must be the number ${CI_CONFIG_VERSION}`,
+        });
+    }
+    if (!Array.isArray(doc.runners) || doc.runners.length === 0) {
+        errors.push({
+            path: "runners",
+            message: "runners is required and must be a non-empty list",
+        });
+    }
+    const runners = [];
+    if (Array.isArray(doc.runners)) {
+        doc.runners.forEach((raw, index) => {
+            const runner = validateRunner(raw, index, errors);
+            if (runner)
+                runners.push(runner);
+        });
+        const seen = new Set();
+        for (const runner of runners) {
+            if (!runner.name)
+                continue;
+            if (seen.has(runner.name)) {
+                errors.push({
+                    path: "runners",
+                    message: `duplicate runner name "${runner.name}"`,
+                });
+            }
+            seen.add(runner.name);
+        }
+    }
+    if (errors.length > 0) {
+        throw new CIConfigError(errors, source);
+    }
+    return { version: CI_CONFIG_VERSION, runners };
+}
+/**
+ * Load and validate a CI config file. Fails closed: a missing file or any
+ * validation error throws — no config is ever silently ignored.
+ */
+export async function loadCIConfig(configPath) {
+    if (!(await fs.pathExists(configPath))) {
+        throw new CIConfigError([
+            { path: configPath, message: "config file not found" },
+        ]);
+    }
+    const raw = await fs.readFile(configPath, "utf-8");
+    return parseCIConfig(raw, configPath);
+}
+/**
+ * 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 async function findCIConfig(projectDir) {
+    for (const candidate of CI_CONFIG_CANDIDATES) {
+        const candidatePath = path.join(projectDir, candidate);
+        if (await fs.pathExists(candidatePath))
+            return candidatePath;
+    }
+    return null;
+}
+//# sourceMappingURL=ci-config.js.map

package/dist/lib/claudemd.d.ts

@@ -1,8 +1,20 @@
-import type { InitOptions, StackClaudeMdEntry } from '../types/index.js';
+import type { InitOptions, StackClaudeMdEntry } from "../types/index.js";
+import type { StackDetectionResult } from "./stack-detector.js";
 export declare function buildClaudeMd(projectName: string, stack: string, entry: StackClaudeMdEntry, contextDir: boolean, modules: string[]): string;
+/**
+ * Build an enriched CLAUDE.md using detected skills, architecture patterns,
+ * and plugin instructions. Pure function — no I/O.
+ */
+export declare function buildSmartClaudeMd(projectName: string, stack: string, entry: StackClaudeMdEntry, detectedSkills: string[], contextDir: boolean, modules: string[]): string;
 /**
  * Generate CLAUDE.md content from InitOptions metadata.
  * Pure function — does NOT perform filesystem I/O.
  */
 export declare function generateClaudeMd(options: InitOptions): string;
+/**
+ * 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 declare function generateSmartClaudeMd(options: InitOptions, detection: StackDetectionResult | null): string;
 //# sourceMappingURL=claudemd.d.ts.map

package/dist/lib/claudemd.js

@@ -1,47 +1,170 @@
-import { STACK_CLAUDEMD_MAP } from '../constants.js';
+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'];
+    return STACK_CLAUDEMD_MAP[stack] ?? STACK_CLAUDEMD_MAP.default;
 }
 export function buildClaudeMd(projectName, stack, entry, contextDir, modules) {
     const lines = [];
     lines.push(`# ${projectName}`);
-    lines.push('');
+    lines.push("");
     // Stack section
-    lines.push('## Stack');
+    lines.push("## Stack");
     lines.push(`- **Language/Runtime**: ${stack}`);
     lines.push(`- **Conventions**: ${entry.conventions}`);
     lines.push(`- **Testing**: ${entry.testFramework}`);
-    lines.push('');
+    lines.push("");
     // Skills section
     if (entry.skills.length > 0) {
-        lines.push('## Recommended Skills');
+        lines.push("## Recommended Skills");
         for (const skill of entry.skills) {
             lines.push(`- Load \`~/.claude/skills/${skill}/SKILL.md\` before writing code`);
         }
-        lines.push('');
+        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('');
+        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("## Conventions");
     lines.push(`- ${entry.conventions}`);
-    lines.push('- Scaffolded with javi-forge — see `.javi-forge/manifest.json` for config');
-    lines.push('');
+    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('');
+        lines.push("## Modules");
+        lines.push(`- ${modules.join(", ")}`);
+        lines.push("");
     }
-    return lines.join('\n');
+    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
@@ -56,17 +179,44 @@ export function generateClaudeMd(options) {
     // Collect enabled modules for listing
     const modules = [];
     if (options.aiSync)
-        modules.push('ai-sync');
+        modules.push("ai-sync");
     if (options.sdd)
-        modules.push('sdd');
+        modules.push("sdd");
     if (options.ghagga)
-        modules.push('ghagga');
+        modules.push("ghagga");
     if (options.mock)
-        modules.push('mock');
+        modules.push("mock");
     if (options.contextDir)
-        modules.push('context');
+        modules.push("context");
     if (options.claudeMd)
-        modules.push('claude-md');
+        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

@@ -1,4 +1,4 @@
-import type { CodexTomlEntry, CodexExportResult } from '../types/index.js';
+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.