@untangle-code/cli 0.0.0-stage → 0.1.0

package/src/commands/watch/runtime.ts

@@ -0,0 +1,167 @@
+/**
+ * Die Laufzeitkanten des Waechters: Uhr, Zufall, Ignorierregeln, Ausgabe.
+ *
+ * Alles hier ist bewusst DUENN. Es ist der Kompositionswurzel-Anteil des
+ * CLI — die Stelle, an der die reinen Pakete an echte Uhr, echten Zufall und
+ * echte Dateien angeschlossen werden. Kein Paket unterhalb davon liest
+ * jemals selbst die Uhr oder `node:fs` (siehe die Port-Dokumentation in
+ * `packages/domain/src/ports.ts`).
+ */
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createWriteStream, readFileSync, type WriteStream } from "node:fs";
+import path from "node:path";
+
+import type { Clock, Random } from "@untangle-code/domain";
+import { createIgnoreEngine } from "@untangle-code/scanner";
+
+/**
+ * Wanduhrzeit fuer Protokollzeitstempel und die Buchfuehrung der Lock-Lease.
+ * Ergebnisdaten (Metriken, Deltas) enthalten NIE eine Uhrzeit — dort waere
+ * sie ein Determinismusbruch; hier ist sie genau der Zweck.
+ */
+export class SystemClock implements Clock {
+  nowEpochMs(): number {
+    // Die EINZIGE echte Uhrzeitablesung des Waechters, und zwar mit Absicht
+    // an genau dieser Stelle: `SystemClock` IST die Umsetzung des
+    // `Clock`-Ports. Jede andere Datei dieses Kommandos liest die Zeit nur
+    // ueber den Port (`deps.clock`), damit ein Test sie durch eine feste Uhr
+    // ersetzen kann. Dieselbe Ausnahme, dieselbe Begruendung wie in
+    // `packages/storage-local/src/real-time.ts` und `@untangle-code/testkit`.
+    // eslint-disable-next-line no-restricted-syntax -- siehe Begruendung darueber.
+    return Date.now();
+  }
+  nowIso(): string {
+    return new Date(this.nowEpochMs()).toISOString();
+  }
+}
+
+/**
+ * Kryptografischer Zufall fuer Lock-Datensatz-Ids. Ebenfalls kein Bestandteil
+ * von Ergebnisdaten — `FileLockProvider` braucht eine eindeutige Kennung je
+ * Lease, sonst koennte ein zweiter Prozess eine fremde Lease erneuern.
+ */
+export class CryptoRandom implements Random {
+  nextFloat(): number {
+    const buffer = randomBytes(6).readUIntBE(0, 6);
+    return buffer / 2 ** 48;
+  }
+  nextInt(maxExclusive: number): number {
+    if (!Number.isInteger(maxExclusive) || maxExclusive <= 0) {
+      throw new RangeError(`nextInt requires a positive integer; received ${maxExclusive}`);
+    }
+    return Math.floor(this.nextFloat() * maxExclusive);
+  }
+  bytes(length: number): Uint8Array {
+    return new Uint8Array(randomBytes(length));
+  }
+  uuid(): string {
+    return randomUUID();
+  }
+}
+
+/**
+ * Ignorierregeln fuer den Watcher.
+ *
+ * `RepoWatcher`/`reconcileTree` kennen absichtlich keine
+ * `.gitignore`-Schichtung (siehe deren Modul-Doku: "a caller wiring a real
+ * indexing pipeline is expected to pass an `ignore` backed by scanner's own
+ * `IgnoreEngine`") — genau das passiert hier.
+ *
+ * DER EIGENE ZUSTANDSORDNER IST IMMER AUSGESCHLOSSEN. `.untangle/` steht zwar
+ * in der `.gitignore` DIESES Repositories, aber darauf darf sich der Waechter
+ * nicht verlassen: wird ein Unterverzeichnis ohne eigene `.gitignore` als
+ * `--root` beobachtet, legt der Waechter dort seinen Lock ab, sieht die
+ * Lock-Datei als Aenderung, erneuert die Lease, sieht die naechste Aenderung —
+ * eine Rueckkopplung auf sich selbst. Der Ausschluss ist deshalb fest
+ * verdrahtet und nicht ueber eine Regeldatei erschlagen.
+ *
+ * BEKANNTE GRENZE, ausdruecklich benannt statt verschwiegen: der Watcher
+ * ruft das Praedikat mit einem Pfad auf, OHNE zu sagen, ob es ein
+ * Verzeichnis ist (der `stat` folgt erst danach). Das Praedikat fragt die
+ * `IgnoreEngine` deshalb in beiden Lesarten und ignoriert, sobald eine der
+ * beiden ignoriert. Ausserdem wird nur die `.gitignore` der Baumwurzel als
+ * Schicht gelegt, keine verschachtelten — der Scanner leistet das im
+ * Indexlauf, der Waechter hier nicht.
+ */
+/** Der Zustandsordner des Waechters, relativ zum beobachteten Baum. */
+export const STATE_DIR_NAME = ".untangle";
+
+export function createIgnorePredicate(rootPath: string): (relativePath: string) => boolean {
+  const engine = createIgnoreEngine();
+  const rootGitignore = readFileIfPresent(path.join(rootPath, ".gitignore"));
+  if (rootGitignore !== null) engine.pushGitignoreLayer("", rootGitignore);
+  const rootUntangleignore = readFileIfPresent(path.join(rootPath, ".untangleignore"));
+  if (rootUntangleignore !== null) engine.pushUntangleIgnoreLayer("", rootUntangleignore);
+
+  const cache = new Map<string, boolean>();
+  return (relativePath: string): boolean => {
+    const cached = cache.get(relativePath);
+    if (cached !== undefined) return cached;
+    const decision =
+      relativePath === STATE_DIR_NAME ||
+      relativePath.startsWith(`${STATE_DIR_NAME}/`) ||
+      engine.decide(relativePath, false).ignored ||
+      engine.decide(relativePath, true).ignored;
+    cache.set(relativePath, decision);
+    return decision;
+  };
+}
+
+function readFileIfPresent(absolutePath: string): string | null {
+  try {
+    return readFileSync(absolutePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** Wohin der Strom geht: stdout und, wenn gewuenscht, zusaetzlich eine Datei. */
+export interface StreamSink {
+  write(line: string): void;
+  close(): Promise<void>;
+}
+
+export interface StreamSinkOptions {
+  stdout: (chunk: string) => void;
+  /** Absoluter Pfad der Mitschrift, oder `null`. */
+  outPath: string | null;
+}
+
+export function createStreamSink(options: StreamSinkOptions): StreamSink {
+  let file: WriteStream | null = null;
+  if (options.outPath !== null) {
+    file = createWriteStream(options.outPath, { flags: "a", encoding: "utf8" });
+  }
+  return {
+    write(line: string): void {
+      options.stdout(`${line}\n`);
+      file?.write(`${stripAnsi(line)}\n`);
+    },
+    async close(): Promise<void> {
+      const stream = file;
+      if (stream === null) return;
+      await new Promise<void>((resolve) => {
+        stream.end(() => {
+          resolve();
+        });
+      });
+    },
+  };
+}
+
+/**
+ * Entfernt ANSI-Steuerzeichen fuer die Mitschrift. Eine Logdatei voller
+ * Farbcodes ist keine Mitschrift.
+ */
+export function stripAnsi(text: string): string {
+  // Es GEHT hier um ein Steuerzeichen: die Regel warnt vor einem versehentlich
+  // in ein Muster geratenen Steuerzeichen, und genau dieses soll entfernt
+  // werden.
+  // eslint-disable-next-line no-control-regex -- siehe Begruendung darueber.
+  return text.replace(/\u001B\[[0-9;]*m/g, "");
+}
+
+/** SHA-256-Hex, fuer die kurze Kennung des gemessenen Standes. */
+export function shortDigest(input: string): string {
+  return createHash("sha256").update(input, "utf8").digest("hex").slice(0, 16);
+}

package/src/commands/watch-command.ts

@@ -0,0 +1,294 @@
+/**
+ * `watch` als Unterbefehl des CLI-Rahmens (WP-124) — die Naht zwischen dem
+ * Befehlsvertrag aus `src/cli/command.ts` und dem Komplexitaetswaechter aus
+ * `src/commands/watch/` (WP-128).
+ *
+ * WARUM DIESE DATEI HIER LIEGT UND NICHT IN `commands/watch/`: der Waechter
+ * ist bewusst frei von Abhaengigkeiten auf den Rahmen — er baut und laeuft
+ * fuer sich allein (`tsconfig.watch.json`, `dist/commands/watch/cli.js`).
+ * Die Abhaengigkeit zeigt deshalb in genau eine Richtung: dieser Adapter
+ * kennt beide Seiten, der Waechter kennt den Rahmen nicht.
+ *
+ * WAS DIESE DATEI ERSETZT: `commands/unavailable.ts` fuehrte `watch` bisher
+ * als noch nicht gebaute Faehigkeit. Das stimmt nicht mehr; einen fertigen
+ * Befehl weiter als unverfuegbar auszuweisen waere dieselbe Unwahrheit wie
+ * eine vorgetaeuschte Faehigkeit, nur in die andere Richtung.
+ */
+import { hostname } from "node:os";
+import path from "node:path";
+
+import { enumFlag, integerFlag, stringFlag, type FlagSpecs, type ParsedArgs } from "../cli/args.js";
+import type { Command, CommandContext } from "../cli/command.js";
+import { EXIT, UsageError } from "../cli/exit.js";
+
+import { runIndexWatch } from "./index-watch.js";
+import { parseWatchArgs } from "./watch/options.js";
+import { runWatch } from "./watch/run.js";
+import { CryptoRandom, SystemClock } from "./watch/runtime.js";
+
+const FLAGS: FlagSpecs = {
+  index: {
+    kind: "boolean",
+    describe: "Keep the search index current: check freshness and update changes serially",
+    defaultLabel: "off; otherwise complexity stream",
+  },
+  repo: {
+    kind: "string",
+    placeholder: "ID",
+    describe: "--index: configured repository; required when several are configured",
+  },
+  ref: {
+    kind: "string",
+    placeholder: "NAME",
+    describe: "--index: checked-out ref; otherwise the current branch",
+  },
+  embedder: {
+    kind: "string",
+    placeholder: "auto|offline",
+    describe:
+      "--index: current index profile, otherwise service; offline explicitly uses local vectors",
+    defaultLabel: "auto",
+  },
+  root: {
+    kind: "string",
+    placeholder: "PATH",
+    describe: "Tree to watch",
+    defaultLabel: "current directory",
+  },
+  "repo-id": {
+    kind: "string",
+    placeholder: "ID",
+    describe: "Repository identity for the ref lock",
+    defaultLabel: "directory name",
+  },
+  "ref-id": {
+    kind: "string",
+    placeholder: "ID",
+    describe: "Ref identity for the ref lock",
+    defaultLabel: "<repo-id>:working-tree",
+  },
+  format: {
+    kind: "string",
+    placeholder: "text|json",
+    describe: "Stream output format; json writes one JSON line per event",
+    defaultLabel: "text",
+  },
+  out: {
+    kind: "string",
+    placeholder: "FILE",
+    describe: "Also save the stream, always without control characters",
+  },
+  color: {
+    kind: "boolean",
+    describe: "Terminal colors (--no-color disables them)",
+    defaultLabel: "enabled when stdout is a terminal",
+  },
+  debounce: {
+    kind: "number",
+    placeholder: "MS",
+    describe: "Debounce quiet period",
+    defaultLabel: "200",
+  },
+  reconcile: {
+    kind: "number",
+    placeholder: "MS",
+    describe: "Reconciliation interval; --index: freshness-check interval",
+    defaultLabel: "30000",
+  },
+  "max-file-bytes": {
+    kind: "number",
+    placeholder: "N",
+    describe: "Maximum file size; larger files enter the ledger with a reason",
+    defaultLabel: "5242880",
+  },
+  scopes: {
+    kind: "number",
+    placeholder: "N",
+    describe: "Maximum contribution locations reported per change",
+    defaultLabel: "5",
+  },
+  "exit-after": {
+    kind: "number",
+    placeholder: "N",
+    describe: "Stop cleanly after N changes; --index: after N updates",
+    defaultLabel: "on signal only",
+  },
+  "baseline-only": {
+    kind: "boolean",
+    describe: "Baseline only; --index: check freshness once and update if needed",
+    defaultLabel: "off",
+  },
+};
+
+/**
+ * Setzt die zerlegten Flags in die kanonische Aufrufform des Waechters
+ * zurueck und laesst dessen EIGENEN Parser darueber laufen.
+ *
+ * Das sieht nach einem Umweg aus und ist genau deshalb richtig: Vorgaben,
+ * Wertebereiche und Fehlermeldungen des Waechters stehen damit an EINER
+ * Stelle (`watch/options.ts`) und koennen zwischen dem Rahmenaufruf
+ * (`untangle watch`) und dem Direktaufruf (`dist/commands/watch/cli.js`)
+ * nicht auseinanderlaufen. Eine zweite, hier nachgebaute Vorgabenliste waere
+ * die klassische Stelle, an der ein Werkzeug je nach Aufrufweg etwas anderes
+ * tut.
+ */
+function toWatchArgv(args: ParsedArgs): string[] {
+  const argv: string[] = [];
+  const push = (name: string, value: unknown): void => {
+    if (value === undefined) return;
+    argv.push(`--${name}`, String(value));
+  };
+  push("root", args.flags["root"]);
+  push("repo-id", args.flags["repo-id"]);
+  push("ref-id", args.flags["ref-id"]);
+  push("format", args.flags["format"]);
+  push("out", args.flags["out"]);
+  push("debounce", args.flags["debounce"]);
+  push("reconcile", args.flags["reconcile"]);
+  push("max-file-bytes", args.flags["max-file-bytes"]);
+  push("scopes", args.flags["scopes"]);
+  push("exit-after", args.flags["exit-after"]);
+  if (args.flags["color"] === false) argv.push("--no-color");
+  if (args.flags["baseline-only"] === true) argv.push("--baseline-only");
+  return argv;
+}
+
+export const watchCommand: Command = {
+  spec: {
+    name: "watch",
+    implementedBy: "commands/watch-command.js",
+    summary: "Complexity monitoring: metric deltas for every change",
+    usage: "untangle watch [--index] [--root=<PATH>] [--format=json] [--out=<FILE>]",
+    details: [
+      "--index selects search-index mode: at startup and each --reconcile interval, " +
+        "source hashes and the index contract are checked. Stale, incompatible or missing indexes are " +
+        "updated serially. --repo is required with multiple repositories; a ref that is not checked out " +
+        "is never updated. --format=json emits index status as JSONL; index reports go to stderr.",
+      "Watches a tree and reports each metric's delta for every change, " +
+        "structural, semantic, cyclomatic, cognitive, including direction: did the " +
+        'change reduce or increase complexity? "cognitive 34 -> 21 ' +
+        '(-13, reduced)" describes the change rather than only a raw number.',
+      "The three scope metrics aggregate by metrics_scope_id without " +
+        "double-counting, using execution_unit scope (spec.md §16.10). The " +
+        "semantic load sums the file's chunks and therefore uses " +
+        "file_chunks scope. Each number identifies its measurement scope.",
+      "A file that could not be analyzed appears in the same stream, " +
+        "with a reason and details. Silently omitted files could make " +
+        "a partial result appear complete; " +
+        "silence does not prove that nothing changed.",
+      "Reduced means complexity decreased. It does not prove that " +
+        "the change improved the code; vision.md §1b requires " +
+        "an unchanged symbol interface, unchanged tests and unchanged " +
+        "dependency edges, which this command does not measure.",
+      "SIGINT/SIGTERM stops cleanly: watcher stopped, stream closed, " +
+        "the ref lock released. The final event reports whether the lock was " +
+        "actually released, based on an inspection.",
+    ],
+    flags: FLAGS,
+    examples: [
+      "untangle watch",
+      "untangle watch --format=json --out=complexity.jsonl",
+      "untangle watch --root=packages/search --scopes=3",
+      "untangle watch --baseline-only",
+      "untangle watch --index --reconcile=30000",
+      "untangle watch --index --repo=backend --embedder=offline --format=json",
+    ],
+    exitCodes: [
+      [EXIT.ok, "Stopped cleanly."],
+      [EXIT.operational, "Operational error; for example, another run holds the ref lock."],
+      [EXIT.usage, "Invalid arguments."],
+      [EXIT.environment, "--index: indexing or environment is not ready."],
+      [EXIT.cancelled, "--index: cancelled cleanly by a signal."],
+    ],
+  },
+
+  async run(ctx: CommandContext, args: ParsedArgs): Promise<number> {
+    if (args.positionals.length > 0) {
+      throw new UsageError(
+        `"untangle watch" does not accept positional arguments; received "${args.positionals[0] ?? ""}".`,
+        "Specify the watched tree with --root.",
+      );
+    }
+
+    if (args.flags["index"] === true) {
+      for (const name of ["repo-id", "ref-id", "debounce", "max-file-bytes", "scopes", "color"]) {
+        if (args.flags[name] !== undefined)
+          throw new UsageError(
+            `--${name} applies to the complexity watcher, not --index.`,
+            "Use --repo/--ref to select the index and --reconcile for the check interval.",
+          );
+      }
+      const intervalMs = integerFlag(args, "reconcile", 30_000);
+      const maxRefreshes =
+        args.flags["exit-after"] === undefined ? null : integerFlag(args, "exit-after", 1);
+      if (intervalMs === 0 || intervalMs > 2_147_483_647 || maxRefreshes === 0) {
+        throw new UsageError(
+          "--reconcile and --exit-after must be positive integers; --reconcile is limited to 2147483647 ms.",
+          "Example: untangle watch --index --reconcile=30000.",
+        );
+      }
+      const repo = stringFlag(args, "repo");
+      const ref = stringFlag(args, "ref");
+      const out = stringFlag(args, "out");
+      return runIndexWatch(ctx, {
+        root: path.resolve(ctx.cwd, stringFlag(args, "root") ?? "."),
+        ...(repo === undefined ? {} : { repo }),
+        ...(ref === undefined ? {} : { ref }),
+        embedder: enumFlag(args, "embedder", ["auto", "offline"] as const, "auto"),
+        intervalMs,
+        format: enumFlag(args, "format", ["text", "json"] as const, "text"),
+        outPath: out === undefined ? null : path.resolve(ctx.cwd, out),
+        once: args.flags["baseline-only"] === true,
+        maxRefreshes,
+      });
+    }
+    if (["repo", "ref", "embedder"].some((name) => args.flags[name] !== undefined)) {
+      throw new UsageError(
+        "--repo, --ref and --embedder require --index.",
+        "The complexity watcher uses --repo-id and --ref-id.",
+      );
+    }
+
+    const parsed = parseWatchArgs(toWatchArgv(args), {
+      cwd: ctx.cwd,
+      isTty: process.stdout.isTTY === true,
+      noColorEnv: ctx.env["NO_COLOR"],
+    });
+    if (!parsed.ok) {
+      throw new UsageError(parsed.message, 'See "untangle watch --help" for supported options.');
+    }
+
+    const exitCode = await runWatch(parsed.options, {
+      clock: new SystemClock(),
+      random: new CryptoRandom(),
+      stdout: (chunk) => {
+        ctx.io.out(chunk);
+      },
+      stderr: (chunk) => {
+        ctx.io.err(chunk);
+      },
+      host: hostname(),
+      /**
+       * Der Rahmen faengt SIGINT/SIGTERM bereits ab und bricht `ctx.signal`
+       * ab; der Waechter haengt sich deshalb an DIESES Signal statt einen
+       * zweiten Griff auf denselben Prozess zu legen. Die zurueckgegebene
+       * Abmeldung loest den Zuhoerer, sobald der Abbau laeuft.
+       */
+      installSignalHandler: (handler) => {
+        if (ctx.signal.aborted) {
+          handler("SIGINT");
+          return () => undefined;
+        }
+        const onAbort = (): void => {
+          handler("SIGINT");
+        };
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        return () => {
+          ctx.signal.removeEventListener("abort", onAbort);
+        };
+      },
+    });
+
+    return exitCode === 0 ? EXIT.ok : EXIT.operational;
+  },
+};

package/src/entry-point.ts

@@ -0,0 +1,67 @@
+/**
+ * "Is this module the program, or did something import it?"
+ *
+ * The obvious answer — compare `import.meta.url` with
+ * `pathToFileURL(process.argv[1])` — is wrong in exactly the situation this
+ * package is built for. `npm install --global` does not copy the binary into
+ * the global bin directory; on POSIX it creates a SYMLINK there. Node's ESM
+ * loader resolves symlinks, so `import.meta.url` is the real path inside the
+ * package while `argv[1]` is the symlink in `…/bin`. The two never match, the
+ * guard says "imported", and the installed `untangle` prints nothing and exits
+ * 0 — a tool that silently does nothing, which is the worst possible outcome
+ * of a one-line installation.
+ *
+ * So both sides are canonicalized before they are compared. A path that
+ * cannot be resolved (deleted between spawn and check, `node --eval`, a
+ * platform quirk) falls back to the unresolved comparison rather than
+ * throwing: failing to start over a `realpath` error would trade one silent
+ * failure for a louder one.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * True when the module identified by `moduleUrl` is the entry point named by
+ * `entryPath` (normally `process.argv[1]`).
+ *
+ * BOTH sides are canonicalized, not just `entryPath`. The module URL is
+ * usually already resolved, but "usually" is not a guarantee worth betting the
+ * program's existence on — and on macOS the `/var` → `/private/var` alias
+ * makes the two differ even without a symlink in the picture.
+ */
+export function isEntryPoint(moduleUrl: string, entryPath: string | undefined): boolean {
+  if (entryPath === undefined || entryPath === "") {
+    return false;
+  }
+  if (moduleUrl === pathToFileURL(entryPath).href) {
+    return true;
+  }
+  const canonicalModule = canonical(safeFileUrlToPath(moduleUrl));
+  const canonicalEntry = canonical(entryPath);
+  return (
+    canonicalModule !== undefined &&
+    canonicalEntry !== undefined &&
+    canonicalModule === canonicalEntry
+  );
+}
+
+function safeFileUrlToPath(moduleUrl: string): string | undefined {
+  try {
+    return fileURLToPath(moduleUrl);
+  } catch {
+    // Not a file: URL at all (data:, node:, an http import). Then this module
+    // is certainly not a file on disk that argv[1] could name.
+    return undefined;
+  }
+}
+
+function canonical(path: string | undefined): string | undefined {
+  if (path === undefined) {
+    return undefined;
+  }
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}