novahiz 0.3.2 → 0.3.3

package/bin/novahiz.mjs

@@ -1,7 +1,35 @@
 #!/usr/bin/env node
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+// engines: node >=22.18. Node strips types only OUTSIDE node_modules
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so:
+//  - in the repo (or any checkout), run src/cli.ts directly;
+//  - under node_modules, run the compiled dist/cli.js shipped by `prepare`.
+const [major, minor] = process.versions.node.split(".").map((value) => Number.parseInt(value, 10));
+if (major < 22 || (major === 22 && minor < 18)) {
+  process.stderr.write(
+    `novahiz requires Node 22.18 or later (found ${process.versions.node}). Upgrade Node: https://nodejs.org/\n`
+  );
+  process.exit(1);
+}
+
 const here = dirname(fileURLToPath(import.meta.url));
-const cli = join(here, "..", "src", "cli.ts");
-await import(pathToFileURL(cli).href);
+const root = join(here, "..");
+const underNodeModules = root.replace(/\\/g, "/").toLowerCase().includes("/node_modules/");
+const dist = join(root, "dist", "cli.js");
+const src = join(root, "src", "cli.ts");
+
+let target;
+if (underNodeModules) {
+  if (!existsSync(dist)) {
+    process.stderr.write("novahiz: dist/cli.js is missing from the installed package. Reinstall: npm install novahiz\n");
+    process.exit(1);
+  }
+  target = dist;
+} else {
+  target = src;
+}
+
+await import(pathToFileURL(target).href);

package/dist/autodocs.js

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const NOVAHIZ_DIR = ".novahiz";
+export const CONFIG_NAME = "config.json";
+export const STATE_NAME = "state.json";
+export const EMPTY_STATE = {
+    dirty: false,
+    pending: [],
+    lastSync: null,
+    sessions: 0
+};
+const MAJOR_DIRS = /^(src|lib|app|routes|pages|api|server|internal|pkg|cmd)\//;
+const MAJOR_FILES = new Set([
+    "package.json",
+    "pyproject.toml",
+    "Cargo.toml",
+    "go.mod",
+    "composer.json",
+    "Gemfile"
+]);
+const MAJOR_EXT = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".rs",
+    ".go",
+    ".php",
+    ".rb",
+    ".java",
+    ".kt",
+    ".swift",
+    ".dart",
+    ".sql"
+]);
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "project-memory",
+    "novahiz-docs",
+    ".novahiz",
+    "dist",
+    "build",
+    "coverage",
+    ".next"
+]);
+export function projectDir(cwd) {
+    return join(cwd, NOVAHIZ_DIR);
+}
+export function configPath(cwd) {
+    return join(projectDir(cwd), CONFIG_NAME);
+}
+export function statePath(cwd) {
+    return join(projectDir(cwd), STATE_NAME);
+}
+function ensureDir(path) {
+    if (!existsSync(path))
+        mkdirSync(path, { recursive: true });
+}
+export function autoDocsEnabled(cwd) {
+    const escape = (process.env.NOVAHIZ_AUTODOCS ?? "").toLowerCase();
+    if (["off", "0", "false", "no", "disabled"].includes(escape))
+        return false;
+    const config = readProjectConfig(cwd);
+    return config.autoDocs === true;
+}
+export function readProjectConfig(cwd) {
+    try {
+        const raw = readFileSync(configPath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return {};
+        return { autoDocs: parsed.autoDocs === true };
+    }
+    catch {
+        return {};
+    }
+}
+export function writeProjectConfig(cwd, config) {
+    ensureDir(projectDir(cwd));
+    writeFileSync(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+export function readState(cwd) {
+    try {
+        const raw = readFileSync(statePath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return { ...EMPTY_STATE };
+        return {
+            dirty: parsed.dirty === true,
+            pending: Array.isArray(parsed.pending)
+                ? parsed.pending.filter((entry) => typeof entry === "string").slice(0, 64)
+                : [],
+            lastSync: typeof parsed.lastSync === "string" ? parsed.lastSync : null,
+            sessions: typeof parsed.sessions === "number" && Number.isFinite(parsed.sessions) ? parsed.sessions : 0
+        };
+    }
+    catch {
+        return { ...EMPTY_STATE };
+    }
+}
+export function writeState(cwd, state) {
+    ensureDir(projectDir(cwd));
+    writeFileSync(statePath(cwd), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+export function normalizePath(filePath) {
+    return filePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+export function isMajorPath(filePath) {
+    const path = normalizePath(filePath);
+    const parts = path.split("/");
+    if (parts.some((part) => SKIP_DIRS.has(part)))
+        return false;
+    const base = parts[parts.length - 1] ?? "";
+    if (MAJOR_FILES.has(base))
+        return true;
+    const dot = base.lastIndexOf(".");
+    const ext = dot >= 0 ? base.slice(dot).toLowerCase() : "";
+    if (MAJOR_EXT.has(ext))
+        return true;
+    return MAJOR_DIRS.test(path);
+}
+export function markDirty(cwd, filePath) {
+    const path = normalizePath(filePath);
+    const state = readState(cwd);
+    const pending = state.pending.includes(path) ? state.pending : [...state.pending, path].slice(-64);
+    const next = {
+        ...state,
+        dirty: true,
+        pending,
+        sessions: state.sessions + 1
+    };
+    writeState(cwd, next);
+    return next;
+}
+export function clearDirty(cwd) {
+    const state = readState(cwd);
+    const next = {
+        ...state,
+        dirty: false,
+        pending: [],
+        lastSync: new Date().toISOString()
+    };
+    writeState(cwd, next);
+    return next;
+}
+export function dateStamp() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function upsertChangesSection(doc, lines) {
+    const header = "## Recent changes";
+    const stamp = `*Last updated: ${dateStamp()}*`;
+    const bullet = lines.map((line) => `- ${line}`).join("\n");
+    const footerMatch = doc.match(/\n---\n\n\*Last updated:.*$/s);
+    const footer = footerMatch ? footerMatch[0] : `\n---\n\n${stamp}\n`;
+    if (!doc.includes(header)) {
+        const base = doc.replace(/\n---\n\n\*Last updated:.*$/s, "").replace(/\s+$/, "");
+        return `${base}\n\n${header}\n\n${bullet}\n${footer}`;
+    }
+    const start = doc.indexOf(header);
+    const after = doc.slice(start + header.length);
+    const nextHeader = after.search(/\n#{1,6} /);
+    const sectionEnd = nextHeader === -1 ? doc.length : start + header.length + nextHeader;
+    const before = doc.slice(0, start);
+    const rest = doc.slice(sectionEnd);
+    return `${before}${header}\n\n${bullet}\n${rest}`;
+}

package/dist/catalog.js

@@ -0,0 +1,245 @@
+import { mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { expandHome } from "./spec.js";
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "build", ".next", ".cache"]);
+function stripQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+export function parseFrontmatter(content) {
+    const result = {};
+    const text = content.replace(/^\uFEFF/, "");
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return result;
+    let end = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index].trim() === "---") {
+            end = index;
+            break;
+        }
+    }
+    if (end === -1)
+        return result;
+    const block = lines.slice(1, end);
+    for (let index = 0; index < block.length; index += 1) {
+        const line = block[index];
+        const separator = line.indexOf(":");
+        if (separator === -1)
+            continue;
+        const key = line.slice(0, separator).trim();
+        if (key.length === 0)
+            continue;
+        const raw = line.slice(separator + 1).trim();
+        const isBlock = ["|", "|-", "|+", ">", ">-", ">+"].includes(raw);
+        if (isBlock) {
+            const folded = raw.startsWith(">");
+            const parts = [];
+            while (index + 1 < block.length) {
+                const next = block[index + 1];
+                if (next.trim() === "" || /^\s/.test(next)) {
+                    index += 1;
+                    parts.push(next.replace(/^\s+/, ""));
+                }
+                else {
+                    break;
+                }
+            }
+            result[key] = folded ? parts.join(" ").replace(/\s+/g, " ").trim() : parts.join("\n").trim();
+            continue;
+        }
+        result[key] = stripQuotes(raw);
+    }
+    return result;
+}
+function walkForSkillFiles(root, found, visited, errors) {
+    let real;
+    try {
+        real = realpathSync(root);
+    }
+    catch (error) {
+        errors.push(`scan could not resolve ${root}: ${String(error)}`);
+        return;
+    }
+    if (visited.has(real))
+        return;
+    visited.add(real);
+    let entries;
+    try {
+        entries = readdirSync(root).sort();
+    }
+    catch (error) {
+        errors.push(`scan could not list ${root}: ${String(error)}`);
+        return;
+    }
+    for (const entry of entries) {
+        if (IGNORED_DIRECTORIES.has(entry))
+            continue;
+        const full = join(root, entry);
+        let stats;
+        try {
+            stats = statSync(full);
+        }
+        catch (error) {
+            errors.push(`scan could not stat ${full}: ${String(error)}`);
+            continue;
+        }
+        if (stats.isDirectory()) {
+            walkForSkillFiles(full, found, visited, errors);
+        }
+        else if (entry === "SKILL.md") {
+            found.push(full);
+        }
+    }
+}
+export function scanSkills(spec, errors = []) {
+    const files = [];
+    const visited = new Set();
+    for (const root of spec.config.skillRoots) {
+        const expanded = expandHome(root);
+        walkForSkillFiles(isAbsolute(expanded) ? expanded : join(spec.root, expanded), files, visited, errors);
+    }
+    files.sort();
+    const byId = new Map();
+    for (const file of files) {
+        let content;
+        try {
+            content = readFileSync(file, "utf8");
+        }
+        catch (error) {
+            errors.push(`scan could not read ${file}: ${String(error)}`);
+            continue;
+        }
+        const frontmatter = parseFrontmatter(content);
+        const folder = basename(join(file, ".."));
+        const id = (frontmatter.name || folder).trim();
+        if (id.length === 0)
+            continue;
+        const override = spec.overrides.skills?.[id];
+        // M4: power was uncapped — a rogue override (power: 100) always won the
+        // "better" comparison and could force an attacker-controlled skill.
+        // Clamp to the documented 0..5 range, non-numeric falls back to 3.
+        const rawPower = override?.power;
+        const power = typeof rawPower === "number" && Number.isFinite(rawPower) ? Math.min(Math.max(Math.trunc(rawPower), 0), 5) : 3;
+        const record = {
+            id,
+            name: frontmatter.name || folder,
+            description: frontmatter.description || "",
+            sourcePath: file,
+            power,
+            stars: override?.stars ?? null,
+            tags: override?.tags ?? [],
+            categories: override?.categories ?? []
+        };
+        const existing = byId.get(id);
+        const better = !existing ||
+            record.power > existing.power ||
+            (record.power === existing.power && record.sourcePath < existing.sourcePath);
+        if (better)
+            byId.set(id, record);
+    }
+    return [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+export function writeSkillIndex(spec, skills) {
+    const directory = join(spec.root, "build");
+    mkdirSync(directory, { recursive: true });
+    const target = join(directory, "installed-skills.json");
+    const ids = skills.map((skill) => skill.id).sort();
+    writeFileSync(target, `${JSON.stringify(ids, null, 2)}\n`, "utf8");
+    return target;
+}
+export function writeCatalog(spec, skills) {
+    const directory = join(spec.root, "build");
+    mkdirSync(directory, { recursive: true });
+    const target = join(directory, "catalog.json");
+    const records = skills.map((skill) => ({
+        id: skill.id,
+        name: skill.name,
+        description: skill.description,
+        power: skill.power,
+        stars: skill.stars,
+        tags: skill.tags,
+        categories: skill.categories
+    }));
+    writeFileSync(target, `${JSON.stringify(records, null, 2)}\n`, "utf8");
+    return target;
+}
+export function loadCatalog(spec) {
+    try {
+        const raw = readFileSync(join(spec.root, "build", "catalog.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch (err) {
+        console.error(`[Novahiz] loadCatalog failed: ${err instanceof Error ? err.message : err}`);
+        return [];
+    }
+}
+export function loadInstalledSkills(spec) {
+    let raw;
+    try {
+        raw = readFileSync(join(spec.root, "build", "installed-skills.json"), "utf8");
+    }
+    catch {
+        return { available: false, skills: new Set() };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return { available: false, skills: new Set() };
+        return { available: true, skills: new Set(parsed.map((value) => String(value))) };
+    }
+    catch {
+        return { available: false, skills: new Set() };
+    }
+}
+export function persistCatalog(db, spec, skills) {
+    const now = new Date().toISOString();
+    // M3: the destructive DELETE used to run outside the try — a failure between
+    // DELETE and COMMIT left an empty catalog with no rollback. Everything is now
+    // inside the transaction, and ROLLBACK itself is guarded.
+    try {
+        db.exec("BEGIN; DELETE FROM skills; DELETE FROM categories; DELETE FROM rules;");
+        const upsertSkill = db.prepare(`INSERT INTO skills (id, name, description, source_path, power, stars, tags, categories, scanned_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         name = excluded.name,
+         description = excluded.description,
+         source_path = excluded.source_path,
+         power = excluded.power,
+         stars = excluded.stars,
+         tags = excluded.tags,
+         categories = excluded.categories,
+         scanned_at = excluded.scanned_at`);
+        for (const skill of skills) {
+            upsertSkill.run(skill.id, skill.name, skill.description, skill.sourcePath, skill.power, skill.stars, JSON.stringify(skill.tags), JSON.stringify(skill.categories), now);
+        }
+        const upsertCategory = db.prepare(`INSERT INTO categories (id, label, priority, keywords, default_skills)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         label = excluded.label,
+         priority = excluded.priority,
+         keywords = excluded.keywords,
+         default_skills = excluded.default_skills`);
+        for (const category of spec.categories) {
+            upsertCategory.run(category.id, category.label, category.priority, JSON.stringify(category.keywords), JSON.stringify(category.defaultSkills));
+        }
+        const insertRule = db.prepare("INSERT INTO rules (id, json) VALUES (?, ?)");
+        for (const rule of spec.rules) {
+            insertRule.run(rule.id, JSON.stringify(rule));
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // no transaction was open — nothing to roll back
+        }
+        throw error;
+    }
+}

package/dist/classify.js

@@ -0,0 +1,181 @@
+import { providersForCategories } from "./providers.js";
+import { determineTier } from "./complexity.js";
+export function fold(value) {
+    return value
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "");
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function termMatches(text, keyword) {
+    const needle = fold(keyword).trim();
+    if (needle.length === 0)
+        return false;
+    const pattern = new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRegex(needle)}([^\\p{L}\\p{N}]|$)`, "u");
+    return pattern.test(text);
+}
+function keywordTerm(keyword) {
+    return typeof keyword === "string" ? keyword : keyword.term;
+}
+function keywordWeight(keyword) {
+    if (typeof keyword === "string")
+        return 1;
+    return typeof keyword.weight === "number" ? keyword.weight : 1;
+}
+function matchedAlternative(text, keyword) {
+    const raw = keywordTerm(keyword);
+    const alternatives = raw.includes("|") ? raw.split("|") : [raw];
+    for (const alternative of alternatives) {
+        const term = alternative.trim();
+        if (term.length > 0 && termMatches(text, term))
+            return term;
+    }
+    return null;
+}
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+// Confidence maps a raw keyword score to [0, 1) using a half-saturation curve.
+// At score=2 the confidence is ~0.5; at score=5 it's ~0.71; at score=10 it's ~0.83.
+// The "+2" constant prevents low-score categories from having disproportionate confidence.
+function confidence(score) {
+    if (score <= 0)
+        return 0;
+    return Math.round((score / (score + 2)) * 100) / 100;
+}
+function skillsOfCategory(category) {
+    const skills = [...category.defaultSkills];
+    for (const step of category.roadmap?.steps ?? []) {
+        for (const skill of step.requireSkills ?? []) {
+            if (!skills.includes(skill))
+                skills.push(skill);
+        }
+    }
+    return skills;
+}
+function enforcedOfCategory(category) {
+    const skills = [];
+    for (const step of category.roadmap?.steps ?? []) {
+        if (step.kind !== "skill" || step.optional)
+            continue;
+        for (const skill of step.requireSkills ?? []) {
+            if (!skills.includes(skill))
+                skills.push(skill);
+        }
+    }
+    return skills;
+}
+export function classify(spec, prompt, options = {}) {
+    const minScore = options.minScore ?? spec.config.classify.minScore;
+    const maxCategories = options.maxCategories ?? spec.config.classify.maxCategories;
+    const fallbackCategory = options.fallbackCategory ?? spec.config.classify.fallbackCategory;
+    const text = fold(prompt);
+    // Determine complexity tier
+    const tier = determineTier(prompt);
+    const scored = [];
+    for (const category of spec.categories) {
+        let score = 0;
+        const terms = [];
+        const negatives = [];
+        for (const keyword of category.keywords) {
+            const matched = matchedAlternative(text, keyword);
+            if (!matched)
+                continue;
+            let weight = keywordWeight(keyword);
+            if (matched.includes(" "))
+                weight += 0.5;
+            score += weight;
+            terms.push(matched);
+        }
+        for (const negative of category.negativeKeywords ?? []) {
+            const matched = matchedAlternative(text, negative);
+            if (!matched)
+                continue;
+            score -= keywordWeight(negative);
+            negatives.push(matched);
+        }
+        if (score >= minScore) {
+            scored.push({ id: category.id, score, confidence: confidence(score), margin: 0, terms, negatives });
+        }
+    }
+    const priorityOf = (id) => spec.categories.find((category) => category.id === id)?.priority ?? 0;
+    scored.sort((a, b) => b.score - a.score || priorityOf(b.id) - priorityOf(a.id) || byCodeUnit(a.id, b.id));
+    for (let index = 0; index < scored.length; index += 1) {
+        const next = scored[index + 1]?.score ?? 0;
+        scored[index].margin = Math.round((scored[index].score - next) * 1000) / 1000;
+    }
+    const selected = scored.slice(0, Math.max(0, maxCategories));
+    // H8: when nothing matched and fallback is misconfigured, force "general" so
+    // the gate still applies R6 rules instead of silently allowing everything.
+    if (selected.length === 0) {
+        if (fallbackCategory.length > 0 && spec.categories.some((entry) => entry.id === fallbackCategory)) {
+            selected.push({ id: fallbackCategory, score: 0, confidence: 0, margin: 0, terms: [], negatives: [] });
+        }
+        else if (spec.categories.some((entry) => entry.id === "general")) {
+            selected.push({ id: "general", score: 0, confidence: 0, margin: 0, terms: [], negatives: [] });
+        }
+    }
+    const requiredSkills = [];
+    const invocations = [];
+    const roadmaps = [];
+    for (const item of selected) {
+        const category = spec.categories.find((entry) => entry.id === item.id);
+        if (!category)
+            continue;
+        // Tier-based skill filtering
+        if (tier === "trivial") {
+            // Trivial: no skills required from roadmap
+            continue;
+        }
+        if (tier === "lite") {
+            // Lite: only implement + converge skills (skip plan, clarify, etc.)
+            for (const step of category.roadmap?.steps ?? []) {
+                const allowed = (step.requireSkills ?? []).filter(s => s === "novahiz-implement" || s === "novahiz-converge");
+                for (const skill of allowed) {
+                    if (!requiredSkills.includes(skill))
+                        requiredSkills.push(skill);
+                }
+            }
+        }
+        else {
+            // Full: all skills
+            for (const skill of skillsOfCategory(category)) {
+                if (!requiredSkills.includes(skill))
+                    requiredSkills.push(skill);
+            }
+        }
+        for (const step of category.roadmap?.steps ?? []) {
+            if (step.kind !== "skill")
+                continue;
+            invocations.push({
+                category: category.id,
+                step: step.id,
+                label: step.label,
+                kind: step.kind,
+                skills: step.requireSkills ?? [],
+                optional: step.optional === true
+            });
+        }
+        if (category.roadmap) {
+            roadmaps.push({ category: category.id, id: category.roadmap.id, steps: category.roadmap.steps });
+        }
+    }
+    const primary = selected[0]?.id ?? null;
+    const primaryCategory = primary ? spec.categories.find((entry) => entry.id === primary) : undefined;
+    // C1: enforcedSkills must respect tier gating — trivial prompts should not
+    // expose enforced skills, otherwise downstream consumers load skills unnecessarily.
+    const enforcedSkills = (tier !== "trivial" && primaryCategory) ? enforcedOfCategory(primaryCategory) : [];
+    const providers = providersForCategories(spec, selected.map((entry) => entry.id)).map((provider) => provider.id);
+    return {
+        categories: selected,
+        primary,
+        tier,
+        requiredSkills,
+        enforcedSkills,
+        invocations,
+        providers,
+        roadmaps
+    };
+}