novahiz 0.1.0

package/src/spec.ts

@@ -0,0 +1,306 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type Keyword = { term: string; weight?: number };
+export type CategoryKeyword = string | Keyword;
+
+type RoadmapStepKind = "advisory" | "skill" | "edit" | "verify" | "approval";
+
+export type RoadmapStep = {
+  id: string;
+  label: string;
+  kind: RoadmapStepKind;
+  requireSkills?: string[];
+  optional?: boolean;
+};
+
+export type Roadmap = {
+  id: string;
+  steps: RoadmapStep[];
+};
+
+export type Category = {
+  id: string;
+  label: string;
+  priority: number;
+  keywords: CategoryKeyword[];
+  negativeKeywords?: CategoryKeyword[];
+  defaultSkills: string[];
+  roadmap?: Roadmap;
+};
+
+type RuleWhen = {
+  match?: "any" | "all";
+  fileClasses?: string[];
+  pathGlobs?: string[];
+  promptCategories?: string[];
+  contentMatches?: string[];
+  contentExcludes?: string[];
+  minChange?: number;
+};
+
+export type Rule = {
+  id: string;
+  description: string;
+  when: RuleWhen;
+  require: string[];
+};
+
+type SkillOverride = {
+  power?: number;
+  stars?: number | null;
+  tags?: string[];
+  categories?: string[];
+};
+
+type Overrides = {
+  skills?: Record<string, SkillOverride>;
+};
+
+type ProviderKind = "mcp" | "skill" | "commands";
+
+export type Provider = {
+  id: string;
+  label: string;
+  kind: ProviderKind;
+  transport?: "local" | "remote";
+  command?: string[];
+  url?: string;
+  install?: string[];
+  requires?: string[];
+  bootstrap?: Record<string, string[]>;
+  purpose?: string;
+  categories?: string[];
+  source?: string;
+  license?: string;
+};
+
+type ProvidersConfig = {
+  autoRegister: boolean;
+  autoInstall: boolean;
+  disabled: string[];
+};
+
+type TraceConfig = {
+  enabled: boolean;
+  categories: string[];
+};
+
+export type GateConfig = {
+  enabled: boolean;
+  mode: "block" | "warn" | "audit";
+  envEscape: string;
+  tools: string[];
+  ignoreFiles: string[];
+  placeholders: boolean;
+  trace: TraceConfig;
+};
+
+type ClassifyConfig = {
+  minScore: number;
+  maxCategories: number;
+  fallbackCategory: string;
+};
+
+type LedgerReviewConfig = {
+  edits: number;
+  todos: number;
+};
+
+type LedgerConfig = {
+  enabled: boolean;
+  review: LedgerReviewConfig;
+};
+
+export type NovahizConfig = {
+  dbPath: string;
+  skillRoots: string[];
+  gate: GateConfig;
+  classify: ClassifyConfig;
+  providers: ProvidersConfig;
+  ledger: LedgerConfig;
+};
+
+export type Spec = {
+  root: string;
+  config: NovahizConfig;
+  categories: Category[];
+  rules: Rule[];
+  overrides: Overrides;
+  providers: Provider[];
+};
+
+const DEFAULT_IGNORE_FILES = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/coverage/**",
+  "**/vendor/**",
+  "**/*.min.*",
+  "**/*.map",
+  "**/package-lock.json",
+  "**/pnpm-lock.yaml",
+  "**/yarn.lock",
+  "**/bun.lockb",
+  "**/__snapshots__/**",
+  "**/*.snap",
+  "**/*.generated.*"
+];
+
+export const DEFAULT_CONFIG: NovahizConfig = {
+  dbPath: "novahiz.sqlite",
+  skillRoots: [],
+  gate: {
+    enabled: true,
+    mode: "block",
+    envEscape: "NOVAHIZ_GATE",
+    tools: ["edit", "write", "patch", "apply_patch", "bash", "shell"],
+    ignoreFiles: DEFAULT_IGNORE_FILES,
+    placeholders: true,
+    trace: {
+      enabled: false,
+      categories: ["code", "debug", "audit", "review", "database-supabase"]
+    }
+  },
+  classify: {
+    minScore: 1,
+    maxCategories: 3,
+    fallbackCategory: "general"
+  },
+  providers: {
+    autoRegister: true,
+    autoInstall: false,
+    disabled: []
+  },
+  ledger: {
+    enabled: true,
+    review: {
+      edits: 3,
+      todos: 2
+    }
+  }
+};
+
+export function novahizHome(): string {
+  const fromEnv = process.env.NOVAHIZ_HOME;
+  if (fromEnv && fromEnv.length > 0) return fromEnv;
+  return join(homedir(), ".config", "novahiz");
+}
+
+export function expandHome(value: string): string {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) return join(homedir(), value.slice(2));
+  return value;
+}
+
+function stripBom(text: string): string {
+  return text.replace(/^\uFEFF/, "");
+}
+
+function readJson<T>(path: string): T {
+  return JSON.parse(stripBom(readFileSync(path, "utf8"))) as T;
+}
+
+export function mergeConfig(raw: Partial<NovahizConfig> | null | undefined): NovahizConfig {
+  const source = raw && typeof raw === "object" ? raw : {};
+  const gateSource: Partial<GateConfig> = source.gate && typeof source.gate === "object" ? source.gate : {};
+  const gate: GateConfig = { ...DEFAULT_CONFIG.gate, ...gateSource };
+  if (typeof gate.enabled !== "boolean") gate.enabled = DEFAULT_CONFIG.gate.enabled;
+  if (gate.mode !== "block" && gate.mode !== "warn" && gate.mode !== "audit") gate.mode = DEFAULT_CONFIG.gate.mode;
+  if (typeof gate.envEscape !== "string") gate.envEscape = DEFAULT_CONFIG.gate.envEscape;
+  if (!Array.isArray(gate.tools)) gate.tools = DEFAULT_CONFIG.gate.tools;
+  if (!Array.isArray(gate.ignoreFiles)) gate.ignoreFiles = DEFAULT_CONFIG.gate.ignoreFiles;
+  if (typeof gate.placeholders !== "boolean") gate.placeholders = DEFAULT_CONFIG.gate.placeholders;
+
+  const traceSource: Partial<TraceConfig> = gateSource.trace && typeof gateSource.trace === "object" ? gateSource.trace : {};
+  const trace: TraceConfig = { ...DEFAULT_CONFIG.gate.trace, ...traceSource };
+  if (typeof trace.enabled !== "boolean") trace.enabled = DEFAULT_CONFIG.gate.trace.enabled;
+  if (!Array.isArray(trace.categories)) trace.categories = [...DEFAULT_CONFIG.gate.trace.categories];
+  gate.trace = trace;
+
+  const classifySource: Partial<ClassifyConfig> = source.classify && typeof source.classify === "object" ? source.classify : {};
+  const classify: ClassifyConfig = { ...DEFAULT_CONFIG.classify, ...classifySource };
+  if (typeof classify.minScore !== "number" || !Number.isFinite(classify.minScore)) {
+    classify.minScore = DEFAULT_CONFIG.classify.minScore;
+  }
+  if (typeof classify.maxCategories !== "number" || !Number.isFinite(classify.maxCategories)) {
+    classify.maxCategories = DEFAULT_CONFIG.classify.maxCategories;
+  }
+  if (typeof classify.fallbackCategory !== "string") {
+    classify.fallbackCategory = DEFAULT_CONFIG.classify.fallbackCategory;
+  }
+
+  const providersSource: Partial<ProvidersConfig> = source.providers && typeof source.providers === "object" ? source.providers : {};
+  const providers: ProvidersConfig = {
+    autoRegister: typeof providersSource.autoRegister === "boolean" ? providersSource.autoRegister : DEFAULT_CONFIG.providers.autoRegister,
+    autoInstall: typeof providersSource.autoInstall === "boolean" ? providersSource.autoInstall : DEFAULT_CONFIG.providers.autoInstall,
+    disabled: Array.isArray(providersSource.disabled) ? providersSource.disabled : [...DEFAULT_CONFIG.providers.disabled]
+  };
+
+  const ledgerSource: Partial<LedgerConfig> = source.ledger && typeof source.ledger === "object" ? source.ledger : {};
+  const reviewSource: Partial<LedgerReviewConfig> = ledgerSource.review && typeof ledgerSource.review === "object" ? ledgerSource.review : {};
+  const review: LedgerReviewConfig = {
+    edits: typeof reviewSource.edits === "number" && Number.isFinite(reviewSource.edits) && reviewSource.edits > 0 ? Math.trunc(reviewSource.edits) : DEFAULT_CONFIG.ledger.review.edits,
+    todos: typeof reviewSource.todos === "number" && Number.isFinite(reviewSource.todos) && reviewSource.todos > 0 ? Math.trunc(reviewSource.todos) : DEFAULT_CONFIG.ledger.review.todos
+  };
+  const ledger: LedgerConfig = {
+    enabled: typeof ledgerSource.enabled === "boolean" ? ledgerSource.enabled : DEFAULT_CONFIG.ledger.enabled,
+    review
+  };
+
+  return {
+    dbPath: typeof source.dbPath === "string" ? source.dbPath : DEFAULT_CONFIG.dbPath,
+    skillRoots: Array.isArray(source.skillRoots) ? source.skillRoots : [...DEFAULT_CONFIG.skillRoots],
+    gate,
+    classify,
+    providers,
+    ledger
+  };
+}
+
+function loadConfig(root: string = novahizHome()): NovahizConfig {
+  const config = readUserConfig(root);
+  const dbOverride = process.env.NOVAHIZ_DB;
+  if (dbOverride && dbOverride.length > 0) config.dbPath = dbOverride;
+  return config;
+}
+
+function readUserConfig(root: string): NovahizConfig {
+  const userPath = join(root, "novahiz.config.json");
+  if (existsSync(userPath)) {
+    try {
+      return mergeConfig(JSON.parse(stripBom(readFileSync(userPath, "utf8"))) as Partial<NovahizConfig>);
+    } catch (error) {
+      throw new Error(`Invalid JSON in ${userPath}: ${(error as Error).message}`);
+    }
+  }
+  const examplePath = join(root, "novahiz.config.example.json");
+  if (existsSync(examplePath)) return mergeConfig(readJson<Partial<NovahizConfig>>(examplePath));
+  return mergeConfig(null);
+}
+
+function readCatalog<T>(path: string): T {
+  try {
+    return JSON.parse(stripBom(readFileSync(path, "utf8"))) as T;
+  } catch (error) {
+    throw new Error(`Invalid or missing catalog file ${path}: ${(error as Error).message}`);
+  }
+}
+
+export function loadSpec(root: string = novahizHome()): Spec {
+  const categories = readCatalog<Category[]>(join(root, "catalog", "categories.json"));
+  const rules = readCatalog<Rule[]>(join(root, "catalog", "rules.json"));
+  const overrides = readCatalog<Overrides>(join(root, "catalog", "overrides.json"));
+  let providers: Provider[] = [];
+  try {
+    const loaded = readCatalog<Provider[]>(join(root, "catalog", "providers.json"));
+    if (Array.isArray(loaded)) providers = loaded;
+  } catch {
+    providers = [];
+  }
+  if (!Array.isArray(categories)) throw new Error("catalog/categories.json must be an array");
+  if (!Array.isArray(rules)) throw new Error("catalog/rules.json must be an array");
+  if (!overrides || typeof overrides !== "object") throw new Error("catalog/overrides.json must be an object");
+  return { root, config: loadConfig(root), categories, rules, overrides, providers };
+}

package/src/targets.ts

@@ -0,0 +1,296 @@
+export function tokenizeShell(command: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote = "";
+  const flush = (): void => {
+    if (current.length > 0) {
+      tokens.push(current);
+      current = "";
+    }
+  };
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (quote.length > 0) {
+      if (char === quote) quote = "";
+      else current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === "\n" || char === ";") {
+      flush();
+      tokens.push(";");
+      continue;
+    }
+    if (char === "|") {
+      flush();
+      if (command[index + 1] === "|") {
+        tokens.push("||");
+        index += 1;
+      } else tokens.push("|");
+      continue;
+    }
+    if (char === "&") {
+      flush();
+      if (command[index + 1] === ">") {
+        tokens.push("&>");
+        index += 1;
+      } else if (command[index + 1] === "&") {
+        tokens.push("&&");
+        index += 1;
+      } else tokens.push("&");
+      continue;
+    }
+    if (char === ">") {
+      if (/^\d+$/.test(current)) current = "";
+      flush();
+      if (command[index + 1] === ">") {
+        tokens.push(">>");
+        index += 1;
+      } else tokens.push(">");
+      continue;
+    }
+    if (char === "<") {
+      flush();
+      tokens.push("<");
+      continue;
+    }
+    if (/\s/.test(char)) {
+      flush();
+      continue;
+    }
+    current += char;
+  }
+  flush();
+  return tokens;
+}
+
+const OPERATORS = new Set([">", ">>", "&>", "<", "|", "||", "&", "&&", ";"]);
+
+function isOperator(token: string): boolean {
+  return OPERATORS.has(token) || token.startsWith("&");
+}
+
+function isDashFlag(token: string): boolean {
+  return token.startsWith("-");
+}
+
+function isWindowsFlag(token: string): boolean {
+  return /^\/[a-zA-Z]$/.test(token);
+}
+
+function allPositionals(tokens: string[], windows: boolean): string[] {
+  return tokens.filter((token) => !isDashFlag(token) && !(windows && isWindowsFlag(token)) && !isOperator(token));
+}
+
+function firstPositional(tokens: string[], windows: boolean): string | null {
+  return allPositionals(tokens, windows)[0] ?? null;
+}
+
+function lastPositional(tokens: string[], windows: boolean): string | null {
+  const positional = allPositionals(tokens, windows);
+  return positional.length > 0 ? positional[positional.length - 1] : null;
+}
+
+const VALUE_FLAGS = new Set([
+  "-encoding",
+  "-value",
+  "-filter",
+  "-name",
+  "-itemtype",
+  "-delimiter",
+  "-width",
+  "-stream",
+  "-destination",
+  "-newname",
+  "-property",
+  "-inputobject",
+  "-credential"
+]);
+
+function firstPathLike(tokens: string[], windows: boolean): string | null {
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (isDashFlag(token) || (windows && isWindowsFlag(token)) || isOperator(token)) continue;
+    const previous = tokens[index - 1];
+    if (previous && VALUE_FLAGS.has(previous.toLowerCase())) continue;
+    return token;
+  }
+  return null;
+}
+
+function flagValue(tokens: string[], flags: string[]): string | null {
+  const index = tokens.findIndex((token) => flags.includes(token.toLowerCase()));
+  return index >= 0 && tokens[index + 1] ? tokens[index + 1] : null;
+}
+
+const WRAPPERS = new Set(["sudo", "doas", "env", "nohup", "time", "command", "exec", "cmd", "cmd.exe", "xargs", "nice", "timeout", "stdbuf"]);
+const WRAPPER_VALUE_FLAGS: Record<string, Set<string>> = {
+  sudo: new Set(["-u", "--user", "-g", "--group", "-p", "--prompt", "-c", "--close-from", "-h", "--host", "-r", "--role", "-t", "--type", "-T", "--command-timeout"]),
+  doas: new Set(["-u", "-C"]),
+  env: new Set(["-u", "--unset", "-C", "--chdir", "-S", "--split-string"]),
+  time: new Set(["-o", "--output", "-f", "--format", "-a", "--append"]),
+  nice: new Set(["-n", "--adjustment"]),
+  timeout: new Set(["-s", "--signal", "-k", "--kill-after"]),
+  stdbuf: new Set(["-i", "-o", "-e"]),
+  xargs: new Set(["-a", "--arg-file", "-d", "-E", "-I", "-L", "-n", "-P", "-s"])
+};
+const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const WRITE_CMDLETS = new Set([
+  "set-content",
+  "add-content",
+  "out-file",
+  "tee-object",
+  "set-itemproperty",
+  "set-item",
+  "new-item",
+  "ni",
+  "mkdir",
+  "md"
+]);
+const DEST_CMDLETS = new Set(["copy-item", "move-item", "rename-item", "copy", "move", "ren", "rename", "xcopy"]);
+const DELETE_CMDLETS = new Set(["remove-item", "ri", "rm", "del", "erase", "rd", "rmdir"]);
+const COPY_CMDS = new Set(["cp", "mv", "rsync", "robocopy"]);
+const WINDOWS_CMDS = new Set([
+  "rd",
+  "rmdir",
+  "del",
+  "erase",
+  "xcopy",
+  "robocopy",
+  "copy",
+  "move",
+  "ren",
+  "rename",
+  "remove-item",
+  "ri",
+  "set-content",
+  "add-content",
+  "out-file",
+  "new-item",
+  "ni",
+  "mkdir",
+  "md",
+  "copy-item",
+  "move-item",
+  "rename-item"
+]);
+
+export function extractShellPaths(command: string): string[] {
+  const out: string[] = [];
+  const add = (value: unknown): void => {
+    if (typeof value !== "string") return;
+    let path = value.trim();
+    if ((path.startsWith('"') && path.endsWith('"')) || (path.startsWith("'") && path.endsWith("'"))) {
+      path = path.slice(1, -1);
+    }
+    if (path.length === 0) return;
+    if (isDashFlag(path) || path.startsWith("$") || path.startsWith("&")) return;
+    if (path.startsWith("/dev/") || path === "NUL") return;
+    if (path.includes("://")) return;
+    if (!out.includes(path)) out.push(path);
+  };
+
+  const tokens = tokenizeShell(command);
+  let expectCommand = true;
+  let skipValue = false;
+  let wrapper: string | null = null;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (isOperator(token)) {
+      if (token === ">" || token === ">>" || token === "&>") {
+        const target = tokens[index + 1];
+        if (target && !isOperator(target)) add(target);
+      }
+      expectCommand = true;
+      skipValue = false;
+      wrapper = null;
+      continue;
+    }
+    if (!expectCommand) continue;
+    if (skipValue) {
+      skipValue = false;
+      continue;
+    }
+
+    const lower = token.toLowerCase();
+    if (WRAPPERS.has(lower)) {
+      wrapper = lower;
+      continue;
+    }
+    if (ENV_ASSIGN.test(token)) continue;
+    if (isDashFlag(token)) {
+      if (wrapper !== null && WRAPPER_VALUE_FLAGS[wrapper]?.has(lower)) skipValue = true;
+      continue;
+    }
+    if (wrapper !== null && isWindowsFlag(token)) continue;
+    if ((wrapper === "timeout" || wrapper === "nice") && /^\d+(\.\d+)?[a-z]?$/i.test(token)) continue;
+
+    expectCommand = false;
+    const windows = WINDOWS_CMDS.has(lower);
+    const rest = tokens.slice(index + 1);
+
+    if (COPY_CMDS.has(lower)) {
+      add(lastPositional(rest, windows));
+    } else if (DEST_CMDLETS.has(lower)) {
+      add(flagValue(rest, ["-destination", "-newname"]) ?? lastPositional(rest, windows));
+    } else if (DELETE_CMDLETS.has(lower)) {
+      for (const candidate of allPositionals(rest, windows)) add(candidate);
+    } else if (WRITE_CMDLETS.has(lower)) {
+      add(flagValue(rest, ["-path", "-literalpath", "-filepath", "-destination", "-file"]) ?? firstPathLike(rest, windows));
+    } else if (lower === "tee") {
+      add(firstPositional(rest, windows));
+    } else if (lower === "touch" || lower === "truncate") {
+      for (const candidate of allPositionals(rest, windows)) add(candidate);
+    } else if (lower === "sed") {
+      if (rest.some((value) => value === "-i" || value.startsWith("-i"))) add(lastPositional(rest, windows));
+    } else if (lower === "dd") {
+      for (const candidate of rest) {
+        const match = candidate.match(/^of=(.+)$/);
+        if (match) add(match[1]);
+      }
+    } else {
+      const ofMatch = token.match(/^of=(.+)$/);
+      if (ofMatch) add(ofMatch[1]);
+    }
+  }
+
+  return out;
+}
+
+export function extractTargetPaths(tool: string, args: unknown): string[] {
+  const paths: string[] = [];
+  const push = (value: unknown): void => {
+    if (typeof value === "string" && value.length > 0 && !paths.includes(value)) paths.push(value);
+  };
+  const record = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+  push(record.filePath);
+  push(record.file_path);
+  push(record.path);
+  push(record.file);
+  push(record.notebook_path);
+
+  const patchText =
+    typeof record.patchText === "string"
+      ? record.patchText
+      : typeof record.patch === "string"
+        ? record.patch
+        : "";
+  if (patchText.length > 0) {
+    for (const line of patchText.split(/\r?\n/)) {
+      const fileMatch = line.match(/^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s+(.+?)\s*$/);
+      if (fileMatch) push(fileMatch[1]);
+      const moveMatch = line.match(/^\*\*\*\s+Move to:\s+(.+?)\s*$/);
+      if (moveMatch) push(moveMatch[1]);
+    }
+  }
+
+  if (typeof record.command === "string" && record.command.length > 0) {
+    for (const path of extractShellPaths(record.command)) push(path);
+  }
+
+  return paths;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
+  },
+  "include": ["src", "adapters", "tests"]
+}