novahiz 0.2.2 → 0.2.3

package/src/autodocs.ts

@@ -0,0 +1,192 @@
+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 type ProjectAutoDocsConfig = {
+  autoDocs?: boolean;
+};
+
+export type AutoDocsState = {
+  dirty: boolean;
+  pending: string[];
+  lastSync: string | null;
+  sessions: number;
+};
+
+export const EMPTY_STATE: AutoDocsState = {
+  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: string): string {
+  return join(cwd, NOVAHIZ_DIR);
+}
+
+export function configPath(cwd: string): string {
+  return join(projectDir(cwd), CONFIG_NAME);
+}
+
+export function statePath(cwd: string): string {
+  return join(projectDir(cwd), STATE_NAME);
+}
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+
+export function autoDocsEnabled(cwd: string): boolean {
+  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: string): ProjectAutoDocsConfig {
+  try {
+    const raw = readFileSync(configPath(cwd), "utf8");
+    const parsed = JSON.parse(raw) as Partial<ProjectAutoDocsConfig>;
+    if (!parsed || typeof parsed !== "object") return {};
+    return { autoDocs: parsed.autoDocs === true };
+  } catch {
+    return {};
+  }
+}
+
+export function writeProjectConfig(cwd: string, config: ProjectAutoDocsConfig): void {
+  ensureDir(projectDir(cwd));
+  writeFileSync(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+export function readState(cwd: string): AutoDocsState {
+  try {
+    const raw = readFileSync(statePath(cwd), "utf8");
+    const parsed = JSON.parse(raw) as Partial<AutoDocsState>;
+    if (!parsed || typeof parsed !== "object") return { ...EMPTY_STATE };
+    return {
+      dirty: parsed.dirty === true,
+      pending: Array.isArray(parsed.pending)
+        ? parsed.pending.filter((entry): entry is string => 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: string, state: AutoDocsState): void {
+  ensureDir(projectDir(cwd));
+  writeFileSync(statePath(cwd), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+export function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+export function isMajorPath(filePath: string): boolean {
+  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: string, filePath: string): AutoDocsState {
+  const path = normalizePath(filePath);
+  const state = readState(cwd);
+  const pending = state.pending.includes(path) ? state.pending : [...state.pending, path].slice(-64);
+  const next: AutoDocsState = {
+    ...state,
+    dirty: true,
+    pending,
+    sessions: state.sessions + 1
+  };
+  writeState(cwd, next);
+  return next;
+}
+
+export function clearDirty(cwd: string): AutoDocsState {
+  const state = readState(cwd);
+  const next: AutoDocsState = {
+    ...state,
+    dirty: false,
+    pending: [],
+    lastSync: new Date().toISOString()
+  };
+  writeState(cwd, next);
+  return next;
+}
+
+export function dateStamp(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function upsertChangesSection(doc: string, lines: string[]): string {
+  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/src/cli.ts

@@ -13,6 +13,8 @@ import { commandClean } from "./commands/clean.ts";
 import { commandDoctor } from "./commands/doctor.ts";
 import { commandTokens } from "./commands/tokens.ts";
 import { graftCommand } from "./commands/graft.ts";
+import { commandInit } from "./commands/init.ts";
+import { commandAutodocs } from "./commands/autodocs.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -41,7 +43,9 @@ function usage(): void {
   print({
     name: "novahiz",
     commands: [
-      "init                    Set up Novahiz (config, skills, catalog)",
+      "init                    Initialize Novahiz in the current project",
+      "setup                   Install Novahiz (config, skills, catalog)",
+      "autodocs [--flush]      Sync docs and memory after major project changes",
       "doctor                  Check that everything works",
       "status                  Show current classification and gate state",
       "task new <title>        Start a new tracked task",
@@ -131,8 +135,11 @@ function main(argv: string[]): void {
   }
   switch (command) {
     case "init":
+      return commandInit(parsed);
     case "setup":
       return runInit();
+    case "autodocs":
+      return commandAutodocs(parsed);
     case "doctor":
       return commandDoctor(parsed);
     case "status":

package/src/commands/autodocs.ts

@@ -0,0 +1,250 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  autoDocsEnabled,
+  clearDirty,
+  dateStamp,
+  isMajorPath,
+  markDirty,
+  readProjectConfig,
+  readState,
+  upsertChangesSection,
+  writeProjectConfig
+} from "../autodocs.ts";
+import { emit, flagOn, type Parsed } from "./context.ts";
+import { memoryRoot, writeEntry } from "../memory.ts";
+import * as ui from "../render.ts";
+
+const MAX_DOC_PATHS = 12;
+const ARCHITECTURE = "novahiz-docs/ARCHITECTURE.md";
+
+export type EnsureResult = "created" | "existing" | "failed";
+
+export type FlushOutcome = {
+  status: "flushed" | "marked" | "skipped" | "failed";
+  reason: string;
+  docsPath: string | null;
+  docsUpdated: boolean;
+  memorySlot: string | null;
+  paths: string[];
+  pending: number;
+  lastSync: string | null;
+};
+
+export function ensureProjectAutoDocsConfig(cwd: string): EnsureResult {
+  try {
+    const config = readProjectConfig(cwd);
+    if (config.autoDocs === true) return "existing";
+    writeProjectConfig(cwd, { ...config, autoDocs: true });
+    return "created";
+  } catch {
+    return "failed";
+  }
+}
+
+function skipResult(reason: string, paths: string[] = []): FlushOutcome {
+  const state = readState(process.cwd());
+  return {
+    status: "skipped",
+    reason,
+    docsPath: null,
+    docsUpdated: false,
+    memorySlot: null,
+    paths,
+    pending: state.pending.length,
+    lastSync: state.lastSync
+  };
+}
+
+function flushDocs(cwd: string, paths: string[]): { path: string; updated: boolean } {
+  const docPath = join(cwd, "novahiz-docs", "ARCHITECTURE.md");
+  if (!existsSync(docPath)) return { path: ARCHITECTURE, updated: false };
+  const sample = paths.slice(0, MAX_DOC_PATHS);
+  if (sample.length === 0) return { path: ARCHITECTURE, updated: false };
+  const doc = readFileSync(docPath, "utf8");
+  const lines = sample.map((path) => `${path} (${dateStamp()})`);
+  const next = upsertChangesSection(doc, lines);
+  if (next === doc) return { path: ARCHITECTURE, updated: false };
+  writeFileSync(docPath, next, "utf8");
+  return { path: ARCHITECTURE, updated: true };
+}
+
+function flushMemory(cwd: string, paths: string[]): string | null {
+  const sample = paths.slice(0, MAX_DOC_PATHS);
+  if (sample.length === 0) return null;
+  try {
+    const result = writeEntry({
+      title: "Auto docs sync",
+      description: "Change log written by novahiz autodocs",
+      tags: ["autodocs", "sync"],
+      root: memoryRoot(cwd),
+      content: [`Sync: ${new Date().toISOString()}`, ...sample.map((path) => `- ${path}`)].join("\n")
+    });
+    return result.slot.id;
+  } catch {
+    return null;
+  }
+}
+
+export function flushAutoDocs(cwd: string): FlushOutcome {
+  if (!autoDocsEnabled(cwd)) {
+    return skipResult("autoDocs disabled (set autoDocs=true in .novahiz/config.json or unset NOVAHIZ_AUTODOCS)");
+  }
+  const state = readState(cwd);
+  if (!state.dirty && state.pending.length === 0) {
+    return skipResult("nothing dirty", state.pending);
+  }
+  try {
+    const paths = state.pending;
+    const docs = flushDocs(cwd, paths);
+    const memorySlot = flushMemory(cwd, paths);
+    const next = clearDirty(cwd);
+    return {
+      status: "flushed",
+      reason: `${paths.length} path(s) recorded`,
+      docsPath: docs.path,
+      docsUpdated: docs.updated,
+      memorySlot,
+      paths,
+      pending: next.pending.length,
+      lastSync: next.lastSync
+    };
+  } catch (error) {
+    return {
+      status: "failed",
+      reason: (error as Error).message,
+      docsPath: null,
+      docsUpdated: false,
+      memorySlot: null,
+      paths: state.pending,
+      pending: state.pending.length,
+      lastSync: state.lastSync
+    };
+  }
+}
+
+function markFromArgs(cwd: string, mark: string | boolean, positionals: string[]): FlushOutcome {
+  const raw =
+    typeof mark === "string" && mark.length > 0
+      ? mark
+      : positionals.join(",");
+  const list = raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (list.length === 0) {
+    return {
+      status: "failed",
+      reason: "--mark needs at least one path",
+      docsPath: null,
+      docsUpdated: false,
+      memorySlot: null,
+      paths: [],
+      pending: readState(cwd).pending.length,
+      lastSync: readState(cwd).lastSync
+    };
+  }
+  const accepted: string[] = [];
+  const rejected: string[] = [];
+  for (const path of list) {
+    if (isMajorPath(path)) {
+      markDirty(cwd, path);
+      accepted.push(path);
+    } else {
+      rejected.push(path);
+    }
+  }
+  const state = readState(cwd);
+  if (accepted.length === 0) {
+    return {
+      status: "skipped",
+      reason: `no major path among ${rejected.join(", ")}`,
+      docsPath: null,
+      docsUpdated: false,
+      memorySlot: null,
+      paths: rejected,
+      pending: state.pending.length,
+      lastSync: state.lastSync
+    };
+  }
+  return {
+    status: "marked",
+    reason:
+      rejected.length > 0
+        ? `marked ${accepted.length}, ignored ${rejected.length} non-major`
+        : `marked ${accepted.length}`,
+    docsPath: null,
+    docsUpdated: false,
+    memorySlot: null,
+    paths: accepted,
+    pending: state.pending.length,
+    lastSync: state.lastSync
+  };
+}
+
+function statusView(cwd: string): Record<string, unknown> {
+  const config = readProjectConfig(cwd);
+  const state = readState(cwd);
+  return {
+    cwd,
+    autoDocs: config.autoDocs === true,
+    enabled: autoDocsEnabled(cwd),
+    dirty: state.dirty,
+    pending: state.pending,
+    lastSync: state.lastSync,
+    sessions: state.sessions
+  };
+}
+
+export function commandAutodocs(parsed: Parsed): void {
+  const cwd = process.cwd();
+  const wantFlush = flagOn(parsed, "flush");
+  const markFlag = parsed.flags.mark;
+  const isMark = markFlag !== undefined && markFlag !== false;
+
+  let outcome: FlushOutcome | null = null;
+  if (isMark) {
+    outcome = markFromArgs(cwd, markFlag, parsed.positionals.slice(1));
+  } else if (wantFlush) {
+    outcome = flushAutoDocs(cwd);
+  }
+
+  const value = outcome
+    ? { ...statusView(cwd), action: isMark ? "mark" : "flush", ...outcome }
+    : { ...statusView(cwd), action: "status" };
+
+  emit(parsed, value, () => {
+    const view = statusView(cwd);
+    const lines = [
+      ui.heading("novahiz autodocs"),
+      ui.kv([
+        ["Cwd", String(view.cwd)],
+        ["autoDocs", String(view.autoDocs)],
+        ["Enabled", String(view.enabled)],
+        ["Dirty", String(view.dirty)],
+        ["Pending", String(view.pending)],
+        ["Last sync", String(view.lastSync)]
+      ])
+    ];
+    if (outcome) {
+      lines.push(
+        "",
+        ui.kv([
+          ["Action", outcome.status],
+          ["Reason", outcome.reason],
+          ["Docs", outcome.docsPath ? `${outcome.docsPath}${outcome.docsUpdated ? " updated" : " unchanged"}` : "n/a"],
+          ["Memory", outcome.memorySlot ?? "n/a"]
+        ])
+      );
+      lines.push(
+        "",
+        outcome.status === "failed" ? ui.style("red", outcome.reason) : ui.style("green", outcome.reason)
+      );
+    } else {
+      lines.push("", ui.style("dim", "Use --flush to sync, --mark <path> to record a change."));
+    }
+    return lines.join("\n");
+  });
+
+  if (outcome?.status === "failed") process.exitCode = 1;
+}