@untangle-code/cli 0.0.0-stage → 0.1.0

package/src/commands/init/report.ts

@@ -0,0 +1,204 @@
+/**
+ * The terminal report of `untangle init`.
+ *
+ * Separate from the file it writes, and deliberately shorter: the file is the
+ * record, the report is the answer to "what just happened and what do I do
+ * now". It ends in exactly one next step — never a list — because a first
+ * command that hands back five errands is a first command nobody finishes.
+ *
+ * Wall-clock time is allowed in a report (it is not result data), and is
+ * still not used here: there is nothing about `init` whose duration a user
+ * needs to be told.
+ */
+
+import { formatCount, formatShare, productContextWarnings } from "./render.js";
+import type { InitResultV1, ProjectFindingsV1 } from "./types.js";
+
+/** Human report. One line per array element, no trailing newline. */
+export function formatTextReport(result: InitResultV1): string[] {
+  const { findings } = result;
+  const lines: string[] = [];
+
+  lines.push(`untangle init — ${findings.root}`);
+  lines.push("");
+
+  const languages = findings.languages;
+  if (languages.entries.length === 0) {
+    lines.push("Languages       no analyzable files found");
+  } else {
+    const top = languages.entries
+      .slice(0, 5)
+      .map((entry) => `${entry.languageId} ${formatShare(entry.lineShare)}`)
+      .join(", ");
+    lines.push(`Languages       ${top}`);
+    lines.push(
+      `                ${formatCount(languages.totalFiles)} files, ${formatCount(languages.totalLines)} lines; ${formatShare(languages.parsedLineShare)} with a parser`,
+    );
+    const withoutParser = languages.entries.filter(
+      (entry) => !entry.hasParserAdapter && entry.lineShare >= 0.05,
+    );
+    if (withoutParser.length > 0) {
+      lines.push(
+        `                no parser (text search only): ${withoutParser.map((entry) => entry.languageId).join(", ")}`,
+      );
+    }
+  }
+
+  const topology = findings.topology;
+  lines.push(
+    `Topology        ${formatCount(topology.packages.length)} packages, ${formatCount(topology.services.length)} Container-Dienste${topology.isMonorepo ? "; monorepo" : "; single project"}`,
+  );
+  if (topology.workspaceGlobs.length > 0) {
+    lines.push(`                Globs: ${topology.workspaceGlobs.join(", ")}`);
+  }
+  if (topology.packages.length > 0) {
+    lines.push(`                ${topology.packages.map((pkg) => pkg.name).join(", ")}`);
+  }
+  if (topology.services.length > 0) {
+    lines.push(
+      `                Services: ${topology.services.map((service) => service.name).join(", ")}`,
+    );
+  }
+  for (const uncovered of topology.managers.uncoveredByTopology) {
+    lines.push(`                GAP: ${uncovered} declares packages that were not found`);
+  }
+
+  const productContext = findings.productContext;
+  if (productContext !== undefined) {
+    const readable = productContext.sources.filter(
+      (source) => source.selected && source.status === "readable",
+    ).length;
+    lines.push(
+      `Produktkontext  ${formatCount(readable)} selected sources readable; ${productContext.status}; ${formatCount(productContext.reviewDraft.questions.length)} open questions in the review draft`,
+    );
+    for (const warning of productContextWarnings(findings)) {
+      lines.push(`WARNING         ${warning}`);
+    }
+  }
+
+  const ollama = findings.ollama;
+  if (findings.featureAlignment !== undefined) {
+    const alignment = findings.featureAlignment;
+    lines.push(
+      `Feature evidence ${alignment.status}; ${formatCount(alignment.features.length)} declared features; semantic conformance ${alignment.semanticConformance}`,
+    );
+    for (const feature of alignment.features) {
+      lines.push(
+        `                ${feature.id.replace(/[\r\n]/gu, " ")}: ${feature.status}; ownership ${feature.ownership.map((owner) => `${owner.id.replace(/[\r\n]/gu, " ")}:${owner.status}`).join(", ") || "none"}; test evidence ${feature.testEvidence.status}`,
+      );
+      for (const hint of feature.agentHints) {
+        lines.push(`HINT            ${hint.code}: ${hint.message.replace(/[\r\n]/gu, " ")}`);
+      }
+    }
+    for (const limitation of alignment.limitations) {
+      lines.push(`LIMIT           ${limitation.replace(/[\r\n]/gu, " ")}`);
+    }
+  }
+  lines.push(
+    ollama.outcome === "reachable"
+      ? `Embeddings      ${ollama.url} erreichbar${ollama.chosenModel === undefined ? "; no embedding model" : ` — ${ollama.chosenModel.name} (${ollama.chosenModel.dimensions === undefined ? "?" : formatCount(ollama.chosenModel.dimensions)} dimensions)`}`
+      : `Embeddings      ${ollama.url} unreachable; this is not an error`,
+  );
+  // WP-228: Die Zeile darueber sagt nur, dass /api/tags geantwortet hat.
+  // Diese hier sagt, ob der Dienst das kann, wofuer er gebraucht wird.
+  lines.push(`                ${describeEmbedProbe(ollama)}`);
+  if (findings.storage?.backend === "lancedb") {
+    lines.push(
+      `Vector store    LanceDB at ${findings.storage.directory}; directory ${findings.storage.directoryStatus}`,
+    );
+    lines.push("                Local storage only; no database opened, Docker or Qdrant probed.");
+  } else {
+    const qdrant = findings.qdrant;
+    lines.push(
+      qdrant.outcome === "reachable"
+        ? `Vector store    ${qdrant.url ?? "?"} reachable`
+        : `Vector store    unreachable (${qdrant.probedUrls.join(", ")}); this is not an error`,
+    );
+    for (const skipped of qdrant.skippedUrls) {
+      lines.push(`                not checked: ${skipped.url}`);
+    }
+  }
+
+  const ignore = findings.ignore;
+  lines.push(
+    ignore.gitignorePresent
+      ? `Ignore rules    .gitignore with ${formatCount(ignore.gitignoreRuleCount)} rules + ${formatCount(ignore.defaultExcludes.length)} defaults${ignore.additionalExcludes.length > 0 ? `, ${formatCount(ignore.additionalExcludes.length)} imported (${ignore.additionalExcludes.join(", ")})` : ""}`
+      : `Ignore rules    no .gitignore; ${formatCount(ignore.defaultExcludes.length)} defaults`,
+  );
+
+  if (findings.skipped.entries.length > 0) {
+    lines.push(
+      `Skipped         ${formatCount(findings.skipped.entries.length)} entries with reasons (--format json shows all)`,
+    );
+  }
+
+  lines.push("");
+  lines.push(...formatOutcome(result));
+
+  for (const warning of result.configWarnings) {
+    lines.push(`WARNING         ${warning}`);
+  }
+  for (const error of result.configErrors) {
+    lines.push(`ERROR           ${error}`);
+  }
+
+  lines.push("");
+  lines.push(result.nextStep);
+  return lines;
+}
+
+/**
+ * Der Satz zum Probe-Embedding (WP-228).
+ *
+ * Er nennt IMMER, was geprueft wurde — auch im Erfolgsfall. Eine Zeile, die
+ * nur bei Problemen erscheint, liest sich in ihrer Abwesenheit wie „geprueft
+ * und in Ordnung", und genau das war der Befund.
+ */
+export function describeEmbedProbe(ollama: ProjectFindingsV1["ollama"]): string {
+  const probe = ollama.embedProbe;
+  switch (probe.outcome) {
+    case "ok":
+      return `/api/embed checked: responds${probe.dimensions === undefined ? "" : ` (${formatCount(probe.dimensions)} dimensions)`}; the service is usable`;
+    case "timeout":
+      return `/api/embed NO RESPONSE within ${formatCount(probe.timeoutMs)} ms; reachable does not mean usable here; use \`--embedder=offline\``;
+    case "failed":
+      return `/api/embed failed (${probe.detail ?? "no details"}); use \`--embedder=offline\``;
+    default:
+      return `/api/embed not checked (${probe.detail ?? "no details"})`;
+  }
+}
+
+function formatOutcome(result: InitResultV1): string[] {
+  switch (result.outcome) {
+    case "created":
+      return [`Written         ${result.configPath}`];
+    case "overwritten":
+      return [`Overwritten     ${result.configPath} (--force)`];
+    case "unchanged":
+      return [`Unchanged       ${result.configPath}; a second identical run changes nothing.`];
+    case "would-create":
+      return [`--dry-run       ${result.configPath} would be created (nothing written).`];
+    case "would-be-unchanged":
+      return [`--dry-run       ${result.configPath} is already current (nothing written).`];
+    case "would-overwrite":
+    case "differs":
+      return [
+        result.outcome === "differs"
+          ? `Difference      ${result.configPath} differs. Nothing written; use --force to overwrite.`
+          : `--dry-run       ${result.configPath} would change (nothing written).`,
+        ...formatChanges(result),
+      ];
+    default:
+      return [];
+  }
+}
+
+/** At most 40 changed lines; more than that is a rewrite, not a diff. */
+function formatChanges(result: InitResultV1): string[] {
+  const shown = result.changes.slice(0, 40);
+  const lines = shown.map((change) => `  ${change.kind === "added" ? "+" : "-"} ${change.line}`);
+  if (result.changes.length > shown.length) {
+    lines.push(`  … ${formatCount(result.changes.length - shown.length)} additional lines`);
+  }
+  return lines;
+}

package/src/commands/init/run.ts

@@ -0,0 +1,349 @@
+/**
+ * `untangle init` — the command a user runs first.
+ *
+ * It reads a project, decides, writes one commented file, and names one next
+ * step. It asks nothing. Everything it cannot determine becomes a documented
+ * finding, never a prompt and never an abort: an absent embedding provider,
+ * an absent vector store, an unreadable manifest are all things a
+ * configuration can be written AROUND (WP-125).
+ *
+ * WRITE SAFETY: the file goes to a temporary sibling and is renamed into
+ * place, so an interrupted run can never leave half a configuration behind.
+ * An existing file is replaced only with `--force`; the run that declines to
+ * replace it says exactly which lines would have differed.
+ *
+ * This module is free of argv and of output formatting — `command.ts` binds
+ * it to the CLI shell. That split is what lets the whole command be tested
+ * against an in-memory file system and a probe that answers nothing.
+ */
+
+import path from "node:path";
+
+import { analyzeProductAlignment } from "@untangle-code/core";
+import type { FileSystemPort, ParserRegistry, SkipLedgerEntryV1 } from "@untangle-code/domain";
+import { summarizeSkipReasons } from "@untangle-code/domain";
+import { createParserRegistry } from "@untangle-code/parser-registry";
+import type { ScannedFileV1 } from "@untangle-code/scanner";
+import { NodeFileSystem } from "@untangle-code/scanner/node-fs";
+
+import { OperationalError } from "../../cli/exit.js";
+import { qdrantProbePlan } from "../../cli/vector-store-policy.js";
+
+import { buildConfigDraft, deriveProjectId, nextStepFor } from "./config-draft.js";
+import { diffLines, toLines } from "./diff.js";
+import { nodeHttpProbe, offlineProbe } from "./http-probe.js";
+import { detectIgnoreRules } from "./ignore-rules.js";
+import { buildLanguageCensus } from "./languages.js";
+import { assessProductContext } from "./product-context.js";
+import { renderUntangleToml } from "./render.js";
+import { DEFAULT_OLLAMA_URL, probeOllama, probeQdrant } from "./services.js";
+import { inspectInitStorage } from "./storage.js";
+import { detectTopology } from "./topology.js";
+import { DEFAULT_INIT_LIMITS } from "./types.js";
+import type {
+  HttpProbePort,
+  InitLimitsV1,
+  InitOutcome,
+  InitResultV1,
+  ProjectFindingsV1,
+  StorageFindingsV1,
+} from "./types.js";
+
+/** The file `init` writes. */
+export const CONFIG_FILE_NAME = "untangle.toml";
+/** Suffix of the temporary sibling used for the atomic write. */
+export const TEMP_SUFFIX = ".untangle-init-tmp";
+
+/** Ports and overrides. Every one of them has a real default; tests replace them. */
+export interface InitDepsV1 {
+  fs?: FileSystemPort;
+  http?: HttpProbePort;
+  parserRegistry?: ParserRegistry;
+  env?: Readonly<Record<string, string | undefined>>;
+  limits?: Partial<InitLimitsV1>;
+  signal?: AbortSignal;
+}
+
+export interface InitOptionsV1 {
+  /** Absolute directory to initialise. */
+  root: string;
+  force: boolean;
+  dryRun: boolean;
+  /** Skip every network probe; the infrastructure counts as absent. */
+  offline: boolean;
+  /** Explicit selection; otherwise environment and existing configuration apply. */
+  storageBackend?: "lancedb" | "qdrant";
+  preferredModel?: string;
+  /** Product intent sources, relative to the chosen project root. */
+  visionPath?: string;
+  specPath?: string;
+  featureManifestPath?: string;
+}
+
+/** The command proper. Returns a result; never writes to a terminal. */
+export async function runInit(
+  options: InitOptionsV1,
+  deps: InitDepsV1 = {},
+): Promise<InitResultV1> {
+  deps.signal?.throwIfAborted();
+  const fs = deps.fs ?? new NodeFileSystem();
+  const http = deps.http ?? (options.offline ? offlineProbe() : nodeHttpProbe());
+  const parserRegistry = deps.parserRegistry ?? createParserRegistry();
+  const env = deps.env ?? process.env;
+  const limits: InitLimitsV1 = { ...DEFAULT_INIT_LIMITS, ...deps.limits };
+
+  const root = await canonicalRoot(fs, options.root);
+  const storage = await inspectInitStorage(fs, root, options.storageBackend, env, deps.signal);
+  const findings = await collectFindings({
+    fs,
+    http,
+    parserRegistry,
+    env,
+    limits,
+    root,
+    storage,
+    ...(options.preferredModel === undefined ? {} : { preferredModel: options.preferredModel }),
+    ...(options.visionPath === undefined ? {} : { visionPath: options.visionPath }),
+    ...(options.specPath === undefined ? {} : { specPath: options.specPath }),
+    ...(options.featureManifestPath === undefined
+      ? {}
+      : { featureManifestPath: options.featureManifestPath }),
+    ...(deps.signal === undefined ? {} : { signal: deps.signal }),
+  });
+  deps.signal?.throwIfAborted();
+
+  const draft = buildConfigDraft(findings);
+  const nextStep = nextStepFor(findings);
+  const rendered = renderUntangleToml({ findings, draft, limits, nextStep });
+  const configPath = path.join(root, CONFIG_FILE_NAME);
+
+  const base = {
+    configPath,
+    findings,
+    rendered,
+    nextStep,
+    configWarnings: draft.warnings,
+    configErrors: draft.errors,
+  };
+
+  if (draft.errors.length > 0) {
+    // A configuration the rest of the product would reject is not written at
+    // all. Reporting it and stopping is the only honest outcome.
+    return { ...base, outcome: "differs", changes: [], exitCode: 1 };
+  }
+
+  const existing = await readOptionalText(fs, configPath);
+  deps.signal?.throwIfAborted();
+  const outcome = decideOutcome(existing, rendered, options);
+  const changes =
+    existing === null || existing === rendered
+      ? []
+      : diffLines(toLines(existing), toLines(rendered));
+
+  if (outcome === "created" || outcome === "overwritten") {
+    await writeAtomically(fs, configPath, rendered, deps.signal);
+  }
+
+  return { ...base, outcome, changes, exitCode: outcome === "differs" ? 1 : 0 };
+}
+
+/**
+ * The whole decision table of idempotency, in one place.
+ *
+ * `--dry-run` never writes and never fails: it reports. Without `--force` an
+ * existing, differing file is left alone — the second run "meldet, was sich
+ * geaendert hat" instead of quietly rewriting a file the user may well have
+ * edited on purpose.
+ */
+export function decideOutcome(
+  existing: string | null,
+  rendered: string,
+  options: Pick<InitOptionsV1, "force" | "dryRun">,
+): InitOutcome {
+  if (existing === null) {
+    return options.dryRun ? "would-create" : "created";
+  }
+  if (existing === rendered) {
+    return options.dryRun ? "would-be-unchanged" : "unchanged";
+  }
+  if (options.dryRun) {
+    return "would-overwrite";
+  }
+  return options.force ? "overwritten" : "differs";
+}
+
+interface CollectInput {
+  fs: FileSystemPort;
+  http: HttpProbePort;
+  parserRegistry: ParserRegistry;
+  env: Readonly<Record<string, string | undefined>>;
+  limits: InitLimitsV1;
+  root: string;
+  storage: StorageFindingsV1;
+  preferredModel?: string;
+  visionPath?: string;
+  specPath?: string;
+  featureManifestPath?: string;
+  signal?: AbortSignal;
+}
+
+async function collectFindings(input: CollectInput): Promise<ProjectFindingsV1> {
+  const { fs, http, parserRegistry, env, limits, root } = input;
+  const skipEntries: SkipLedgerEntryV1[] = [];
+  const onSkipEntry = (entry: SkipLedgerEntryV1): void => {
+    skipEntries.push(entry);
+  };
+
+  // Ignore rules first: their result narrows the scan that follows.
+  const ignore = await detectIgnoreRules({ fs, repoRoot: root });
+  const files: ScannedFileV1[] = [];
+
+  const languages = await buildLanguageCensus({
+    fs,
+    parserRegistry,
+    repoRoot: root,
+    limits,
+    additionalExcludes: ignore.additionalExcludes,
+    selfManagedPaths: [CONFIG_FILE_NAME, `${CONFIG_FILE_NAME}${TEMP_SUFFIX}`],
+    onSkipEntry,
+    onDiscoveredFile: (file) => files.push(file),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+  });
+
+  const topology = await detectTopology({ fs, repoRoot: root, limits, onSkipEntry });
+  const productContext = await assessProductContext({
+    fs,
+    root,
+    files,
+    inventoryTruncated: languages.truncated,
+    ...(input.visionPath === undefined ? {} : { visionPath: input.visionPath }),
+    ...(input.specPath === undefined ? {} : { specPath: input.specPath }),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+  });
+  const featureAlignment = await analyzeProductAlignment({
+    fs,
+    root,
+    files,
+    inventoryTruncated: languages.truncated,
+    inventoryExcluded: languages.excluded.reduce((sum, entry) => sum + entry.count, 0),
+    inventoryScope: {
+      additionalDefaultExcludes: ignore.additionalExcludes,
+      maxFileSizeBytes: limits.maxFileSizeBytes,
+      maxFilesScanned: limits.maxFilesScanned,
+      concurrency: limits.concurrency,
+    },
+    parserRegistry,
+    ...(input.featureManifestPath === undefined ? {} : { manifestPath: input.featureManifestPath }),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+  });
+
+  const probeInput = {
+    http,
+    limits,
+    ollamaUrl: env["UNTANGLE_OLLAMA_URL"] ?? env["UNTANGLE_EMBEDDINGS_URL"] ?? DEFAULT_OLLAMA_URL,
+    qdrantUrls: qdrantProbeList({
+      ...env,
+      ...(input.storage.qdrantUrl === undefined
+        ? {}
+        : { UNTANGLE_QDRANT_URL: input.storage.qdrantUrl }),
+    }),
+    ...(input.preferredModel === undefined ? {} : { preferredModel: input.preferredModel }),
+  };
+  const ollama = await probeOllama(probeInput);
+  const qdrant =
+    input.storage.backend === "qdrant"
+      ? await probeQdrant(probeInput)
+      : { outcome: "not-probed" as const, probedUrls: [], skippedUrls: [] };
+
+  return {
+    schemaVersion: 1,
+    root,
+    projectId: deriveProjectId(path.basename(root)),
+    languages,
+    topology,
+    productContext,
+    featureAlignment,
+    ignore,
+    ollama,
+    qdrant,
+    storage: input.storage,
+    skipped: {
+      schemaVersion: 1,
+      generationId: "untangle-init",
+      entries: skipEntries,
+      countsByReason: summarizeSkipReasons(skipEntries),
+    },
+  };
+}
+
+/**
+ * Which vector-store URLs get probed.
+ *
+ * WP-222: this no longer decides anything — it asks
+ * `cli/vector-store-policy.ts`, the one place that knows which store Untangle
+ * may use, and which `untangle doctor` obeys through `wireStorage`. An
+ * explicitly configured `UNTANGLE_QDRANT_URL` comes first ("this one is
+ * mine"), the managed default follows, and upstream's default port is
+ * skipped WITH ITS REASON rather than silently absent (E4).
+ */
+export function qdrantProbeList(env: Readonly<Record<string, string | undefined>>): string[] {
+  return qdrantProbePlan(env).probe;
+}
+
+async function canonicalRoot(fs: FileSystemPort, candidate: string): Promise<string> {
+  const stat = await fs.stat(candidate);
+  if (stat === null) {
+    throw new OperationalError(
+      `Directory "${candidate}" does not exist.`,
+      "Create it or select an existing directory with --root.",
+    );
+  }
+  if (stat.kind !== "directory") {
+    throw new OperationalError(
+      `"${candidate}" is not a directory.`,
+      "init requires a project's root directory.",
+    );
+  }
+  try {
+    return await fs.realPath(candidate);
+  } catch {
+    return candidate;
+  }
+}
+
+async function readOptionalText(fs: FileSystemPort, filePath: string): Promise<string | null> {
+  const stat = await fs.stat(filePath);
+  if (stat === null || stat.kind !== "file") {
+    return null;
+  }
+  return fs.readTextFile(filePath);
+}
+
+/**
+ * Temp file plus rename. `rename` is atomic within a directory on every
+ * platform Untangle supports, so a reader sees either the old file or the new
+ * one — never a truncated one.
+ */
+async function writeAtomically(
+  fs: FileSystemPort,
+  filePath: string,
+  text: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const temporary = `${filePath}${TEMP_SUFFIX}`;
+  signal?.throwIfAborted();
+  const callOptions = signal === undefined ? undefined : { signal };
+  try {
+    await fs.writeFile(temporary, new TextEncoder().encode(text), callOptions);
+    signal?.throwIfAborted();
+    await fs.rename(temporary, filePath, callOptions);
+  } catch (error) {
+    await fs.remove(temporary).catch(() => undefined);
+    signal?.throwIfAborted();
+    throw new OperationalError(
+      `Writing "${filePath}" failed: ${error instanceof Error ? error.message : String(error)}`,
+      `Check write permissions for "${path.dirname(filePath)}".`,
+      { cause: error },
+    );
+  }
+}