novahiz 0.1.0

package/docs/ROADMAPS.md

@@ -0,0 +1,74 @@
+# Roadmaps
+
+A roadmap is an ordered list of steps attached to a category. The classifier picks the categories for a prompt, and the primary category drives the roadmap that the agent follows.
+
+## The six-stage pipeline
+
+Eight categories run the same pipeline: `code`, `debug`, `browser`, `design-ui`, `database-supabase`, `planning`, `devops`, and `data`. Every stage is a skill, and `novahiz-planner` is the orchestrator that fixes the order.
+
+| # | Stage | Skill | Produces |
+|---|---|---|---|
+| 1 | Plan | `novahiz-plan` | direction, scope, dependency order, slicing strategy, risks |
+| 2 | Clarify | `novahiz-clarify` | the open questions, answered, and the decisions they freeze |
+| 3 | Tasks | `novahiz-task` | atomic tasks, each with acceptance criteria and proof |
+| 4 | Analyse | `novahiz-analyse` | the files and symbols that carry the logic, and the unknowns |
+| 5 | Implement | `novahiz-implement` | increments that leave the system working |
+| 6 | Converge | `novahiz-converge` | the gap between intent and code, as traceable remaining tasks |
+
+Stages 1 to 4 write no application file; they produce a plan and decisions. Clarify sends you back to plan when an answer changes the architecture, and converge sends you back to tasks when it finds a gap.
+
+`review` runs analyse and then the diff review. `audit` and `test` keep their own steps and end on a converge. `research` drives a single gather step.
+
+## Model
+
+Roadmaps live inline in `catalog/categories.json`:
+
+```json
+"roadmap": {
+  "id": "feature",
+  "steps": [
+    { "id": "understand", "label": "Lire le code existant", "kind": "advisory" },
+    { "id": "plan", "label": "Ecrire un plan", "kind": "skill", "requireSkills": ["novahiz-plan"] },
+    { "id": "implement", "label": "Implementer", "kind": "edit" },
+    { "id": "test", "label": "Executer les tests", "kind": "verify" }
+  ]
+}
+```
+
+Step kinds:
+
+- `advisory`: guidance only.
+- `skill`: the gate requires the listed skills before an edit. Mark a step `optional: true` to guide without blocking. Skills listed on any step also join the injected requirements.
+- `edit`: a point where files change. The per-file rules apply here.
+- `verify`: a checkpoint such as a test or a build. The agent marks it done with `novahiz step`.
+- `approval`: a user decision.
+
+## Enforcement
+
+The chosen level is skill-gate. For the category the classifier ranks first, every `skill` step that is not optional becomes a required skill in the gate, in addition to the content-aware rules. A required skill that is absent from the installed index is reported in `unmatchedRequired` and in `warnings`, and the gate stops requiring it for that edit, so a missing installation never blocks. Run `novahiz sync` after installing or removing a skill so the index matches the disk.
+
+Steps of other kinds do not block. They shape the injected checklist and the report.
+
+## Primary category
+
+When several categories match, the one with the highest score provides the roadmap. Required skills are the union across the selected categories, so a Supabase task that also touches design gets both sets.
+
+## Content-aware rules
+
+`humanizer` and `impeccable` are governed by rules, not by roadmap steps, so they are required only when they matter:
+
+- `humanizer` applies to text and documentation, and to code whose change contains prose.
+- `impeccable` applies to style files, to components whose change touches styling, and to a design request that targets a UI file.
+
+Rules express this with `when.contentMatches` (`prose`, `style`, or a regex), `when.contentExcludes`, `when.minChange`, and `when.match` (`any` or `all`) to combine the class, path, and category selectors.
+
+## Exemptions
+
+`gate.ignoreFiles` in `novahiz.config.json` holds globs the gate skips: lockfiles, `dist/`, `build/`, `coverage/`, vendored code, minified files, snapshots, and generated files.
+
+## Tools
+
+- `novahiz roadmap --category code` prints the roadmap.
+- `novahiz step --session <id> --done <step>` records progress.
+- MCP `novahiz_roadmap` and `novahiz_step` expose the same over stdio.
+- `novahiz report` summarizes enforcement and roadmap progress.

package/docs/RULES.md

@@ -0,0 +1,85 @@
+# Rules
+
+A rule describes a condition and the skills that condition requires before a file edit.
+
+## Shape
+
+```json
+{
+  "id": "R2-style",
+  "description": "Charger impeccable sur les fichiers de style visuel.",
+  "when": {
+    "pathGlobs": ["**/*.css", "**/*.scss"]
+  },
+  "require": ["impeccable"]
+}
+```
+
+Condition fields:
+
+- `fileClasses` matches the target file class: `code`, `text`, `design`, `data`, `config`, `other`.
+- `pathGlobs` matches the path.
+- `promptCategories` matches the categories the classifier found for the message.
+- `contentMatches` matches the changed text. Use the named matchers `prose` and `style`, or a regex.
+- `contentExcludes` cancels the rule when it matches the changed text.
+- `minChange` skips trivial diffs.
+- `match` combines the selector fields. `any` (default) applies the rule when one selector matches. `all` requires every selector to match.
+
+Content conditions are combined with AND against the selectors. A rule with `contentMatches` does not apply when no content is provided.
+
+## Default rules
+
+| Id | Condition | Requires |
+| --- | --- | --- |
+| R1-docs | text, data or config file, or a docs-writing prompt | `humanizer` |
+| R1-code-prose | code or design file whose change contains prose | `humanizer` |
+| R2-style | a style file | `impeccable` |
+| R2-styled-component | jsx/tsx whose change touches styling | `impeccable` |
+| R2-design-target | design prompt on a UI file | `impeccable` |
+| R3-supabase | a Supabase path or a Supabase prompt | `supabase`, `supabase-postgres-best-practices` |
+
+## Resolution
+
+For an edit, the gate collects skills from two places:
+
+1. Every matching rule.
+2. The `skill` steps of the primary category roadmap, skipping `optional` steps.
+
+Duplicates collapse. The result is filtered against the installed skills index:
+
+- When the index is available, a required skill that is not installed is reported in `unmatchedRequired` and in the `warnings` array, and it does not block. This is deliberate: an installation gap should not make a whole category uneditable. A harness that wants the stricter behaviour can treat a non-empty `unmatchedRequired` as a failure.
+- When the index is missing or unreadable, the gate fails closed and enforces every required skill. Run `novahiz sync` to rebuild the index.
+- Files that match `gate.ignoreFiles` are skipped entirely.
+
+A required skill that is installed but not loaded in the session blocks the call. In `block` mode the gate exits with code 2. In `warn` and `audit` modes it reports and exits 0.
+
+### What counts as a loaded skill
+
+The harness records the load, not the gate.
+
+- opencode calls the `skill` tool, and the adapter records it by running `novahiz session-load --session <id> --skill <name>`.
+- A harness that reads skills some other way records the load itself, by calling `novahiz session-load` before its edit.
+
+Anything else leaves the skill unloaded.
+
+A skill whose frontmatter names an `allowed-tools` entry the harness does not recognize fails to launch at all. That is why the bundled `novahiz-*` skills declare no `allowed-tools`.
+
+## Modes and configuration
+
+The `gate` block in `novahiz.config.json` controls behavior:
+
+- `enabled`: disable the whole gate.
+- `mode`: `block`, `warn`, or `audit`.
+- `envEscape`: the variable that disables the gate for one session. Defaults to `NOVAHIZ_GATE`; values `off`, `0`, `false`, `no`, `disabled` disable it. Read by the CLI, the hook mode, the MCP gate tool, and the opencode plugin.
+- `tools`: the tool names the gate intercepts.
+- `ignoreFiles`: globs skipped by the gate.
+
+## Shell writes
+
+The gate intercepts the shell tool when the command writes files. It extracts targets from redirections (`>`, `>>`, `&>`), `tee`, `cp`, `mv`, `rsync`, `robocopy`, `touch`, `truncate`, `sed -i`, `dd`, `rm`, `del`, `erase`, `rd`, and the PowerShell cmdlets `Set-Content`, `Add-Content`, `Out-File`, `New-Item`, `Copy-Item`, `Move-Item`, `Remove-Item`, `Rename-Item`, `Tee-Object`, `mkdir`. It looks through wrappers such as `sudo`, `env`, `timeout`, `nice`, and `cmd /c`, and ignores arguments that only look like a command. Commands that do not appear to write files pass through.
+
+This detection is best-effort. A command that hides its target can still write without passing the gate. To disable shell gating, remove `bash` and `shell` from `gate.tools`.
+
+## Roadmaps
+
+Categories also carry a roadmap. See [ROADMAPS.md](ROADMAPS.md).

package/docs/TOKENS.md

@@ -0,0 +1,48 @@
+# Token economy
+
+Novahiz trims what the model reads, so a long session spends fewer tokens without losing the content that matters. The layer runs in the opencode adapter through three hooks and reports what it removed.
+
+## What it does
+
+- **Trim tool output** (`tool.execute.after`). When a `read`, `bash`, or `shell` output exceeds the byte or line budget, the adapter keeps the head, the tail, and the lines that look like errors, then replaces the middle with a marker. Tool outputs that are already the payload (`grep`, `glob`, `webfetch`, MCP JSON) are never trimmed.
+- **Deduplicate stale reads** (`experimental.chat.messages.transform`). When the same file is read more than once with the same range, only the last read stays intact. Earlier reads become a one-line stub. The key is path plus offset plus limit, so two different ranges of one file are both kept.
+- **Cap output tokens** (`chat.params`). When `capOutputTokens` is greater than 0 and the model left `maxOutputTokens` unset, the adapter sets it. It is 0 by default, which leaves the cap off.
+
+## Configuration
+
+The `tokens` block of `novahiz.config.json`:
+
+```json
+{
+  "tokens": {
+    "enabled": true,
+    "trimOutputs": true,
+    "maxOutputBytes": 40000,
+    "keepHeadLines": 120,
+    "keepTailLines": 40,
+    "keepErrorLines": 40,
+    "dedupeReads": true,
+    "capOutputTokens": 0,
+    "trimTools": ["read", "bash", "shell"],
+    "readTools": ["read"]
+  }
+}
+```
+
+`NOVAHIZ_TOKENS=off` disables the whole layer for a session.
+
+## Reading the savings
+
+```
+novahiz tokens [--format json|text] [--since <Nd|Nh|ISO>] [--session id] [--calibrate]
+```
+
+- Default output is JSON. `--format text` prints a short summary.
+- `--since 1d` or `--since 2026-09-11` limits the window. `--session <id>` limits to one session.
+- `--calibrate` adds the distribution of trimmed events: removed bytes and tokens (min, median, max), the bytes-per-token ratio over instrumented trims, and the count of re-reads.
+
+The adapter appends one JSON line per event to `build/token-savings.jsonl`. The file rotates once it grows past 4 MB, keeping the last 20000 lines.
+
+## Limits
+
+`~tokens` is an estimate: it divides the removed character count by four. It tracks the real provider tokenizer closely on ordinary text but it is not the tokenizer itself, so treat the number as a magnitude, not an invoice. The cap lever is off by default and has not been exercised against a live session.

package/install/bootstrap.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { nodeVersionOk, opencodeConfigDir } from "./lib.mjs";
+
+const REPO_URL = "https://github.com/novahiz/novahiz.git";
+const NOVAHIZ_HOME = join(homedir(), ".config", "novahiz");
+
+function log(msg) {
+  process.stdout.write(`[novahiz] ${msg}\n`);
+}
+
+function error(msg) {
+  process.stderr.write(`[novahiz] ERROR: ${msg}\n`);
+}
+
+function run(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, {
+    encoding: "utf8",
+    stdio: "inherit",
+    ...opts,
+  });
+  return result.status === 0;
+}
+
+function runCapture(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, {
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"],
+    ...opts,
+  });
+  return { ok: result.status === 0, stdout: result.stdout?.trim() ?? "", stderr: result.stderr?.trim() ?? "" };
+}
+
+function which(cmd) {
+  const ext = process.platform === "win32" ? ".cmd" : "";
+  const result = spawnSync(process.platform === "win32" ? "where" : "which", [cmd + ext], {
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+  if (result.status === 0) return true;
+  // Try without extension on Windows
+  if (process.platform === "win32") {
+    const result2 = spawnSync("where", [cmd], {
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    return result2.status === 0;
+  }
+  return false;
+}
+
+function detectShell() {
+  if (process.platform === "win32") return "pwsh";
+  return "bash";
+}
+
+function generateOpenCodeJson(configDir, novahizHome) {
+  const skillsDir = join(configDir, "skills");
+  const bundledDir = join(novahizHome, "bundled-skills");
+  const agentsSkillsDir = join(homedir(), ".config", ".agents", "skills");
+
+  const config = {
+    $schema: "https://opencode.ai/config.json",
+    mcp: {
+      context7: {
+        type: "local",
+        command: ["context7-mcp", "--transport", "stdio"],
+        enabled: true,
+      },
+      narsil: {
+        type: "local",
+        command: ["narsil-mcp", "--repos", ".", "--git", "--persist"],
+        timeout: 120000,
+        enabled: true,
+      },
+      cron: {
+        type: "local",
+        command: ["mcp-cron", "--transport", "stdio"],
+        enabled: true,
+      },
+      playwright: {
+        type: "local",
+        command: ["npx", "@playwright/mcp@latest", "--browser=msedge"],
+        enabled: true,
+      },
+      supabase: {
+        type: "remote",
+        url: "https://mcp.supabase.com/mcp?features=docs%2Caccount%2Cdatabase%2Cdebugging%2Cdevelopment%2Cfunctions%2Cbranching",
+        enabled: true,
+      },
+      expo: {
+        type: "remote",
+        url: "https://mcp.expo.dev/mcp",
+        enabled: true,
+      },
+    },
+    skills: {
+      paths: [skillsDir],
+    },
+    plugin: [
+      "@mohak34/opencode-notifier@0.2.8",
+      "@tarquinen/opencode-dcp@latest",
+      join(novahizHome, "adapters", "opencode", "novahiz.ts"),
+    ],
+    compaction: {
+      auto: true,
+      prune: true,
+      reserved: 10000,
+    },
+    shell: detectShell(),
+  };
+
+  // Add bundled-skills if it exists
+  if (existsSync(bundledDir)) {
+    config.skills.paths.push(bundledDir);
+  }
+
+  // Add .agents/skills if it exists
+  if (existsSync(agentsSkillsDir)) {
+    config.skills.paths.push(agentsSkillsDir);
+  }
+
+  return config;
+}
+
+async function main() {
+  log("Bootstrap Novahiz - Installation from scratch");
+  log("");
+
+  // 1. Check Node version
+  if (!nodeVersionOk()) {
+    error(`Node ${process.versions.node} is too old. Node 22.18 or later is required.`);
+    error("Install Node: https://nodejs.org/");
+    process.exit(1);
+  }
+  log(`Node ${process.versions.node} OK`);
+
+  // 2. Check git
+  if (!which("git")) {
+    // Try direct spawn on Windows
+    const testGit = spawnSync("git", ["--version"], { encoding: "utf8", stdio: "pipe" });
+    if (testGit.status !== 0) {
+      error("git is required but not found. Install git first.");
+      process.exit(1);
+    }
+  }
+  log("git OK");
+
+  // 3. Install opencode globally if not present
+  if (!which("opencode")) {
+    log("Installing opencode globally...");
+    if (!run("npm", ["install", "-g", "opencode"])) {
+      error("Failed to install opencode. Try: npm install -g opencode");
+      process.exit(1);
+    }
+    log("opencode installed");
+  } else {
+    log("opencode already installed");
+  }
+
+  // 4. Clone or update repo
+  if (existsSync(join(NOVAHIZ_HOME, ".git"))) {
+    log("Repo already exists, pulling latest...");
+    run("git", ["-C", NOVAHIZ_HOME, "pull", "--rebase"]);
+  } else {
+    log(`Cloning repo to ${NOVAHIZ_HOME}...`);
+    mkdirSync(NOVAHIZ_HOME, { recursive: true });
+    if (!run("git", ["clone", REPO_URL, NOVAHIZ_HOME])) {
+      error("Failed to clone repo");
+      process.exit(1);
+    }
+    log("Repo cloned");
+  }
+
+  // 5. Install MCP servers (global npm packages)
+  log("");
+  log("Installing MCP servers...");
+  const mcpServers = [
+    { pkg: "@upstash/context7-mcp", bin: "context7-mcp" },
+    { pkg: "@anthropic-ai/narsil-mcp", bin: "narsil-mcp" },
+    { pkg: "@anthropic-ai/mcp-cron", bin: "mcp-cron" },
+  ];
+
+  for (const server of mcpServers) {
+    if (!which(server.bin)) {
+      log(`  Installing ${server.pkg}...`);
+      if (!run("npm", ["install", "-g", server.pkg])) {
+        log(`  WARNING: Failed to install ${server.pkg} (non-fatal, will use npx fallback)`);
+      } else {
+        log(`  ${server.pkg} installed`);
+      }
+    } else {
+      log(`  ${server.pkg} already installed`);
+    }
+  }
+
+  // 6. Install opencode plugins (global npm packages)
+  log("");
+  log("Installing opencode plugins...");
+  const plugins = [
+    "@mohak34/opencode-notifier@0.2.8",
+    "@tarquinen/opencode-dcp@latest",
+  ];
+
+  for (const plugin of plugins) {
+    const pkgName = plugin.split("@")[0] === "" ? `@${plugin.split("@")[1]}` : plugin.split("@")[0];
+    log(`  Installing ${plugin}...`);
+    if (!run("npm", ["install", "-g", plugin])) {
+      log(`  WARNING: Failed to install ${plugin} (non-fatal)`);
+    } else {
+      log(`  ${plugin} installed`);
+    }
+  }
+
+  // 7. Run the main installer
+  log("");
+  log("Running main installer...");
+  const installScript = join(NOVAHIZ_HOME, "install", "install.mjs");
+  if (existsSync(installScript)) {
+    if (!run(process.execPath, [installScript, "--yes"])) {
+      error("Main installer had issues (non-fatal, check output above)");
+    }
+  } else {
+    error(`Installer not found at ${installScript}`);
+  }
+
+  // 8. Create opencode.jsonc
+  log("");
+  log("Generating opencode.jsonc...");
+  const configDir = opencodeConfigDir();
+  const configPath = join(configDir, "opencode.jsonc");
+
+  if (!existsSync(configPath)) {
+    const config = generateOpenCodeJson(configDir, NOVAHIZ_HOME);
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+    log(`Created ${configPath}`);
+  } else {
+    log(`opencode.jsonc already exists at ${configPath}`);
+    log("  Skipping (will not overwrite existing config)");
+  }
+
+  // 9. Copy plugin to opencode plugins dir
+  const pluginSource = join(NOVAHIZ_HOME, "adapters", "opencode", "novahiz.ts");
+  const pluginTarget = join(configDir, "plugins", "novahiz.ts");
+  if (existsSync(pluginSource)) {
+    mkdirSync(join(configDir, "plugins"), { recursive: true });
+    const { cpSync } = await import("node:fs");
+    cpSync(pluginSource, pluginTarget, { recursive: true });
+    log(`Plugin copied to ${pluginTarget}`);
+  }
+
+  // 10. Done
+  log("");
+  log("=========================================");
+  log("  Novahiz installed successfully!");
+  log("=========================================");
+  log("");
+  log("Next steps:");
+  log("  1. Restart opencode to activate everything");
+  log("  2. Gate is ON by default (disable with NOVAHIZ_GATE=off)");
+  log("");
+  log("Enjoy your deterministic agentic layer!");
+}
+
+main().catch((err) => {
+  error(String(err));
+  process.exit(1);
+});