novahiz 0.3.1 → 0.3.3

package/NOTICE.md

@@ -43,6 +43,7 @@ Installed on demand with `npx skills add` (or an upstream tarball when git trans
 | `flutter-skills` | https://github.com/flutter/agent-plugins | BSD-3-Clause |
 | `dart-skills` | https://github.com/dart-lang/skills | BSD-3-Clause |
 | `expo-skills` | https://github.com/expo/skills | MIT |
+| `impeccable` | https://github.com/pbakaus/impeccable | Apache-2.0 |
 
 ## opencode plugins (third-party)
 

package/README.md

@@ -274,7 +274,7 @@ Novahiz auto-registers external MCP servers based on the prompt category:
 | cron | `scheduler-mcp` (local venv clone) | MIT | devops |
 | dart | `dart mcp-server` (Dart SDK) | BSD-3-Clause | code, debug, design-ui, flutter |
 
-Skill packs (installed from official repos, never vendored): `flutter/agent-plugins` (25 skills), `dart-lang/skills` (15 skills), `expo/skills` (17 skills, the `expo-*` group only; `eas-*` paid services excluded). See [docs/PROVIDERS.md](docs/PROVIDERS.md).
+Skill packs (installed from official repos, never vendored): `flutter/agent-plugins` (25 skills), `dart-lang/skills` (15 skills), `expo/skills` (17 skills, the `expo-*` group only; `eas-*` paid services excluded), `pbakaus/impeccable` (1 skill, the upstream `impeccable` design skill). See [docs/PROVIDERS.md](docs/PROVIDERS.md).
 
 Upstream repositories and full provenance for MCP providers and opencode plugins: [docs/PROVIDERS.md](docs/PROVIDERS.md), [docs/HARNESSES.md](docs/HARNESSES.md), [NOTICE.md](NOTICE.md).
 

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/catalog/providers.json

@@ -39,20 +39,21 @@
     "id": "cron",
     "label": "Cron Scheduler",
     "kind": "mcp",
-    "command": ["C:/Users/hiz/.local/share/mcp-scheduler/.venv/Scripts/python.exe", "C:/Users/hiz/.local/share/mcp-scheduler/main.py"],
+    "command": ["python", "C:/path/to/scheduler-mcp/main.py"],
     "source": "https://github.com/PhialsBasement/scheduler-mcp",
     "license": "MIT",
     "categories": ["devops"],
-    "purpose": "Local MIT scheduler clone at C:/Users/hiz/.local/share/mcp-scheduler (requirements pin mcp<2)."
+    "purpose": "MIT scheduler clone (requirements pin mcp<2); no npm package exists. Clone PhialsBasement/scheduler-mcp, install its requirements into a venv, then point `command` at that venv's python and your clone's main.py (setup in docs/PROVIDERS.md). Shipped disabled: enable it after the local setup."
   },
   {
     "id": "novahiz",
     "label": "novahiz",
     "kind": "mcp",
-    "command": ["node", "C:/Users/hiz/.config/novahiz/mcp/novahiz-tools/index.mjs"],
+    "command": ["node", "~/.config/novahiz/mcp/novahiz-tools/index.mjs"],
     "source": "https://github.com/novahiz/novahiz",
     "license": "Apache-2.0",
-    "categories": ["code", "planning"]
+    "categories": ["code", "planning"],
+    "purpose": "Novahiz stdio MCP (novahiz_providers, novahiz_deps, memory tools). The opencode plugin resolves this path from the home directory itself; edit the command for other harnesses."
   },
   {
     "id": "dart",
@@ -94,5 +95,15 @@
     "license": "MIT",
     "categories": ["code", "expo"],
     "purpose": "17 official Expo framework skills (expo-* group); the 7 eas-* paid-service skills are excluded. Installed to ~/.agents/skills; when git clone fails, fetch the tarball from codeload.github.com and copy the skill folders."
+  },
+  {
+    "id": "impeccable",
+    "label": "Impeccable design skill",
+    "kind": "skill",
+    "install": ["npx", "-y", "skills@1.7.0", "add", "pbakaus/impeccable", "--skill", "impeccable", "-g", "-a", "opencode", "-y"],
+    "source": "https://github.com/pbakaus/impeccable",
+    "license": "Apache-2.0",
+    "categories": ["design-ui"],
+    "purpose": "Upstream Impeccable skill (critique, audit and polish playbooks) required by gate rule R14. Installed to ~/.agents/skills; rerun the command to update."
   }
 ]

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;
+    }
+}