@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/commands/scan.ts

@@ -0,0 +1,360 @@
+/** One report with separate own metrics, external evidence and explained gaps. */
+import { analyzeProductAlignment } from "@untangle-code/core";
+import { METRICS_VERSION, compareCodepoints, formatExternalNumber } from "@untangle-code/domain";
+import { createLineOffsetResolver, defaultProcessLimits } from "@untangle-code/extension-runtime";
+
+import { boolFlag, enumFlag, 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 { line, note, type Io } from "../cli/io.js";
+
+import { analyze, type AnalysisResult } from "./complexity.js";
+import { explainMissing, loadExtensionContext } from "./extensions/context.js";
+import {
+  canonicalize,
+  createExtensionEnvironment,
+  resolveUserPath,
+} from "./extensions/environment.js";
+import {
+  finishScanFeature,
+  renderScanFeature,
+  type ScanFeatureContext,
+  type ScanProductAnalyzer,
+} from "./extensions/feature-scan.js";
+import { invokeExtension, type ExtensionRanV1 } from "./extensions/invoke.js";
+import { emitJson, renderTable } from "./extensions/render.js";
+import { workspaceFileResolver, lazyWorkspaceContents } from "./extensions/run.js";
+import { saveCliState, summarizeRun } from "./extensions/state.js";
+
+const FLAGS: FlagSpecs = {
+  root: {
+    kind: "string",
+    placeholder: "PATH",
+    describe: "Measurement root directory.",
+    defaultLabel: "current directory",
+  },
+  yes: {
+    kind: "boolean",
+    describe:
+      "Allow container provisioning and missing-credential setup for enabled extensions; costs are shown on stderr first.",
+  },
+  format: {
+    kind: "string",
+    placeholder: "text|json",
+    describe: "Output format.",
+    defaultLabel: "text",
+  },
+  feature: {
+    kind: "string",
+    placeholder: "ID",
+    describe:
+      "Declared feature: own full-file analysis, responsibility and separately scoped external evidence.",
+  },
+  manifest: {
+    kind: "string",
+    placeholder: "PATH",
+    describe: "Feature manifest inside --root; requires --feature.",
+  },
+  "test-evidence": {
+    kind: "string",
+    placeholder: "PATH",
+    describe:
+      "Supplied source-bound test evidence inside --root; requires --feature. Does not execute tests.",
+  },
+};
+
+interface NotMeasured {
+  extensionId: string;
+  reason: string;
+  detail: string;
+  nextStep?: string;
+}
+
+interface ScanData {
+  root: string;
+  own: AnalysisResult;
+  outcomes: ExtensionRanV1[];
+  notMeasured: NotMeasured[];
+  warnings: string[];
+  featureAlignment?: ScanFeatureContext;
+}
+
+export const scanCommand: Command = {
+  spec: {
+    name: "scan",
+    implementedBy: "commands/scan.js",
+    summary: "Own metrics and enabled extensions in one report",
+    usage:
+      "untangle scan [--root=PATH] [--feature=ID] [--manifest=PATH] [--test-evidence=PATH] [--yes] [--format=text|json]",
+    details: [
+      "Measure local complexity without an index and run all enabled extensions through Untangle. License gates, digest pins and provenance still apply.",
+      "Three separate sections: own metrics, external evidence and unmeasured extensions with reasons. comparableTo supports test cross-checks, never differences, ratios or a combined report score (X3, X8).",
+      "Without --yes, no container is provisioned. With --yes, consent applies to the whole scan; resources and image are shown on stderr before each provisioning action. License gates remain independent.",
+      "Individual extension failures do not stop the report. Exit code 0 means the report was created, not that every extension succeeded. JSON includes run status, provenance and skip reasons.",
+      "--feature links declared intent, ownership, complete code/test measurements and external file evidence. Repository analyzer values stay repository context; remote source freshness is not inferred. Local sources are checked before and after. No feature flag preserves the existing report.",
+    ],
+    flags: FLAGS,
+    examples: [
+      "untangle scan",
+      "untangle scan --format=json",
+      "untangle scan --feature=search.local --format=json",
+      "untangle scan --yes",
+    ],
+    exitCodes: [
+      [EXIT.ok, "Report created, including explained extension failures."],
+      [EXIT.operational, "The own-code analysis could not run."],
+      [EXIT.usage, "Invalid arguments."],
+      [EXIT.cancelled, "Cancelled."],
+    ],
+  },
+  run: runScan,
+};
+
+/** Injectable HTTP boundary; analysis, discovery and execution remain real in tests. */
+export async function runScan(
+  ctx: CommandContext,
+  args: ParsedArgs,
+  deps: { fetchImpl?: typeof fetch; analyzeProduct?: ScanProductAnalyzer } = {},
+): Promise<number> {
+  const format = enumFlag(args, "format", ["text", "json"] as const, "text");
+  if (args.positionals.length > 0) {
+    throw new UsageError("scan does not accept positional arguments.", "Use --root=PATH.");
+  }
+  const featureId = stringFlag(args, "feature");
+  const manifestPath = stringFlag(args, "manifest");
+  const testEvidencePath = stringFlag(args, "test-evidence");
+  for (const [name, value] of [
+    ["feature", featureId],
+    ["manifest", manifestPath],
+    ["test-evidence", testEvidencePath],
+  ] as const) {
+    if (value !== undefined && value.trim().length === 0)
+      throw new UsageError(`--${name} requires a non-empty value.`);
+  }
+  if (featureId === undefined && (manifestPath !== undefined || testEvidencePath !== undefined))
+    throw new UsageError("--manifest and --test-evidence require --feature.");
+  ctx.signal.throwIfAborted();
+  const requestedRoot = resolveUserPath(ctx.cwd, stringFlag(args, "root") ?? ".");
+  // The analyzed project, including --root outside cwd, is the discovery boundary.
+  const environment = await createExtensionEnvironment({ cwd: requestedRoot, env: ctx.env });
+  const root = await canonicalize(environment.fs, requestedRoot);
+  const productAnalyzer = deps.analyzeProduct ?? analyzeProductAlignment;
+  const featureOptions =
+    featureId === undefined
+      ? undefined
+      : {
+          root,
+          featureId,
+          signal: ctx.signal,
+          ...(manifestPath === undefined
+            ? {}
+            : { manifestPath: resolveUserPath(root, manifestPath) }),
+          ...(testEvidencePath === undefined
+            ? {}
+            : { testEvidencePath: resolveUserPath(root, testEvidencePath) }),
+        };
+  const productBefore =
+    featureOptions === undefined ? undefined : await productAnalyzer(featureOptions);
+  const own = await analyze(root, ctx.signal);
+  const context = await loadExtensionContext(environment);
+  const notMeasured: NotMeasured[] = [];
+  const outcomes: ExtensionRanV1[] = [];
+  const warnings = [...context.warnings];
+
+  for (const rejected of context.discovery.rejected) {
+    notMeasured.push({
+      extensionId: rejected.directoryName ?? rejected.manifestPath,
+      reason: "manifest_rejected",
+      detail: `${rejected.manifestPath}: ${rejected.issues.map((issue) => `${issue.field}: ${issue.message}`).join("; ")}`,
+      nextStep: "untangle extensions list",
+    });
+  }
+  for (const ignored of context.discovery.ignored) {
+    notMeasured.push({
+      extensionId: ignored.manifestPath,
+      reason: "manifest_ignored",
+      detail: `${ignored.reason}: ${ignored.detail}`,
+      nextStep: "untangle extensions list",
+    });
+  }
+  const installed = new Set(context.discovery.extensions.map((entry) => entry.manifest.id));
+  for (const id of context.state.enabled) {
+    if (!installed.has(id) && !notMeasured.some((entry) => entry.extensionId === id)) {
+      notMeasured.push({
+        extensionId: id,
+        reason: "extension_missing",
+        detail: explainMissing(context, id),
+        nextStep: "untangle extensions list",
+      });
+    }
+  }
+
+  const resolveFile = workspaceFileResolver(root);
+  const resolvePosition = createLineOffsetResolver(lazyWorkspaceContents(root));
+  const extensions = [...context.discovery.extensions].sort((a, b) =>
+    compareCodepoints(a.manifest.id, b.manifest.id),
+  );
+  for (const extension of extensions) {
+    ctx.signal.throwIfAborted();
+    const outcome = await invokeExtension({
+      environment,
+      context,
+      extension,
+      workspacePath: root,
+      target: root,
+      limits: defaultProcessLimits(),
+      provisionConsent: boolFlag(args, "yes"),
+      requireEnabled: true,
+      ...(deps.fetchImpl === undefined ? {} : { fetchImpl: deps.fetchImpl }),
+      onProvisionPlanned: (detail) => {
+        note(ctx.io, `Provisioning: ${detail}`);
+      },
+      onProvisionStep: (step) => {
+        note(ctx.io, `  ${step}`);
+      },
+      signal: ctx.signal,
+      resolveFile,
+      resolvePosition,
+    });
+    if (outcome.status === "not_run") {
+      notMeasured.push(outcome);
+      continue;
+    }
+    outcomes.push(outcome);
+    if (outcome.result.run.exitStatus !== "completed") {
+      notMeasured.push({
+        extensionId: outcome.extensionId,
+        reason: "run_failed",
+        detail: [
+          outcome.result.run.exitStatus,
+          outcome.result.run.errorCode,
+          outcome.result.error?.message,
+        ]
+          .filter(Boolean)
+          .join(": "),
+        nextStep: `untangle extensions run ${outcome.extensionId}${extension.manifest.container === undefined ? "" : " --yes"}`,
+      });
+    }
+  }
+  ctx.signal.throwIfAborted();
+  if (outcomes.length > 0) {
+    try {
+      await saveCliState(environment.fs, environment.userDataDir, {
+        ...context.state,
+        lastRuns: {
+          ...context.state.lastRuns,
+          ...Object.fromEntries(
+            outcomes.map((outcome) => [outcome.extensionId, summarizeRun(outcome.result.run)]),
+          ),
+        },
+      });
+    } catch {
+      warnings.push(
+        "The report was created, but the last extension run could not be saved in the user profile.",
+      );
+    }
+  }
+  notMeasured.sort(
+    (a, b) =>
+      compareCodepoints(a.extensionId, b.extensionId) || compareCodepoints(a.reason, b.reason),
+  );
+  ctx.signal.throwIfAborted();
+  const featureAlignment =
+    featureOptions === undefined || productBefore === undefined
+      ? undefined
+      : await finishScanFeature(featureOptions, productBefore, outcomes, productAnalyzer);
+  ctx.signal.throwIfAborted();
+  render(ctx.io, format, {
+    root,
+    own,
+    outcomes,
+    notMeasured,
+    warnings,
+    ...(featureAlignment === undefined ? {} : { featureAlignment }),
+  });
+  return EXIT.ok;
+}
+
+function render(io: Io, format: "text" | "json", data: ScanData): void {
+  if (format === "json") {
+    emitJson(io, {
+      command: "scan",
+      root: data.root,
+      ownMetrics: {
+        metricsVersion: METRICS_VERSION,
+        filesDiscovered: data.own.filesDiscovered,
+        filesAnalyzed: data.own.filesAnalyzed,
+        totals: data.own.totals,
+        totalsReading: data.own.totalsReading,
+        proseAnalyzed: data.own.proseAnalyzed,
+        prose: data.own.prose,
+        skipped: data.own.skipped,
+      },
+      externalSignals: data.outcomes.map((outcome) => ({
+        extensionId: outcome.extensionId,
+        evidenceOnly: true,
+        health: outcome.health,
+        run: outcome.result.run,
+        measurements: outcome.result.measurements,
+        findings: outcome.result.findings,
+        skipped: outcome.result.skipped,
+        error: outcome.result.error?.message,
+      })),
+      notMeasured: data.notMeasured,
+      warnings: data.warnings,
+      ...(data.featureAlignment === undefined ? {} : { featureAlignment: data.featureAlignment }),
+    });
+    return;
+  }
+  line(io, `# Own metrics (${METRICS_VERSION}) — ${data.root}`);
+  for (const row of renderTable(
+    ["KENNZAHL", "VALUE"],
+    [
+      ["files analyzed", String(data.own.filesAnalyzed)],
+      ["Ausfuehrungseinheiten", String(data.own.totals.executionUnits)],
+      ["including outermost units", String(data.own.totals.executionUnitRoots)],
+      ["Cognitive total", String(data.own.totals.cognitive)],
+      ["Cyclomatic total", String(data.own.totals.cyclomatic)],
+      ["Prose analyzed separately", String(data.own.proseAnalyzed)],
+      ["skipped with a reason", String(data.own.skipped.length)],
+    ],
+  ))
+    line(io, `  ${row}`);
+  line(io, "  Totals: execution_unit (nested functions are not counted twice).");
+  for (const skip of data.own.skipped)
+    note(io, `skip ${skip.path ?? ""}: ${skip.reason} — ${skip.detail}`);
+
+  line(io, "\n# External signals — evidence, never Untangle metrics (X3)");
+  if (data.outcomes.length === 0) line(io, "  no extension was executed.");
+  for (const { extensionId, result } of data.outcomes) {
+    line(io, `  ${extensionId} (${result.run.toolVersion}): ${result.run.exitStatus}`);
+    line(
+      io,
+      `    Lauf ${result.run.runId}; ${result.run.findingsTotal} findings; ${result.run.formatParserVersion}`,
+    );
+    for (const measurement of result.measurements) {
+      const signal = measurement.signal;
+      line(
+        io,
+        `    ${measurement.key}: ${formatExternalNumber(measurement.value)} — ${signal === undefined ? "without a declared meaning" : `${signal.kind}/${signal.scope}`}`,
+      );
+    }
+    for (const finding of result.findings)
+      line(
+        io,
+        `    ${finding.severity.normalized} ${finding.filePath}:${finding.sourceRange.startLine ?? 0} ${finding.ruleId}: ${finding.message}`,
+      );
+    for (const skip of result.skipped) note(io, `${extensionId}: ${skip.reason} — ${skip.detail}`);
+    for (const warning of result.run.warnings) note(io, `${extensionId}: ${warning}`);
+    for (const error of result.run.errors)
+      note(io, `${extensionId}: ${error.code} — ${error.message}`);
+  }
+  line(io, "\n# Not measured, with reasons (E4)");
+  if (data.notMeasured.length === 0) line(io, "  no omitted or failed extensions.");
+  for (const entry of data.notMeasured) {
+    line(io, `  ${entry.extensionId}: ${entry.reason}\n    ${entry.detail}`);
+    if (entry.nextStep !== undefined) line(io, `    -> ${entry.nextStep}`);
+  }
+  for (const warning of data.warnings) note(io, `warning: ${warning}`);
+  if (data.featureAlignment !== undefined) renderScanFeature(io, data.featureAlignment);
+}

package/src/commands/sdd.ts

@@ -0,0 +1,243 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, unlink } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  discoverSddArtifacts,
+  type SddConnectionReportV1,
+  type SddFrameworkV1,
+} from "@untangle-code/core";
+import { canonicalJson, sha256Hex } from "@untangle-code/domain";
+
+import { boolFlag, enumFlag, stringFlag, type FlagSpecs, type ParsedArgs } from "../cli/args.js";
+import type { CommandContext } from "../cli/command.js";
+import { OperationalError, UsageError } from "../cli/exit.js";
+import { line, note } from "../cli/io.js";
+
+export const SDD_CONNECT_FLAGS: FlagSpecs = {
+  "dry-run": {
+    kind: "boolean",
+    describe: "Inspect the SDD connector draft without writing its local report or manifest.",
+  },
+};
+
+export interface SddConnectionArtifactV1 {
+  schemaVersion: 1;
+  kind: "sdd_connection_artifact";
+  report: SddConnectionReportV1;
+  reportPath: string | null;
+  manifestPath: string | null;
+  sha256: { report: string; manifest: string } | null;
+}
+
+/** Exclusive, versioned project metadata; the upstream workspace is never modified. */
+export async function writeSddConnection(
+  report: SddConnectionReportV1,
+  options: { signal?: AbortSignal } = {},
+): Promise<SddConnectionArtifactV1> {
+  const { signal } = options;
+  signal?.throwIfAborted();
+  if (report.status === "stale")
+    throw new OperationalError("SDD sources changed during inspection; run the connector again.");
+  if (report.features.length === 0)
+    return {
+      schemaVersion: 1,
+      kind: "sdd_connection_artifact",
+      report,
+      reportPath: null,
+      manifestPath: null,
+      sha256: null,
+    };
+  const root = await realpath(report.root);
+  if (root !== report.root)
+    throw new OperationalError("The selected SDD project root changed physical identity.");
+  const current = await discoverSddArtifacts({
+    root,
+    framework: report.requestedFramework,
+    ...(signal ? { signal } : {}),
+  });
+  if (
+    current.status === "stale" ||
+    current.sourceDigest !== report.sourceDigest ||
+    canonicalJson(current) !== canonicalJson(report)
+  )
+    throw new OperationalError(
+      "SDD source evidence changed after the preview; inspect a fresh connector plan before writing.",
+    );
+  const reportText = JSON.stringify(report, null, 2) + "\n";
+  const manifestText = JSON.stringify(report.draft, null, 2) + "\n";
+  const sha256 = { report: sha256Hex(reportText), manifest: sha256Hex(manifestText) };
+  const artifactKey = sha256Hex(
+    canonicalJson({ report: sha256.report, manifest: sha256.manifest }),
+  );
+  let directory = root;
+  for (const component of [
+    ".untangle",
+    "sdd",
+    `${report.requestedFramework}-${artifactKey.slice(0, 24)}`,
+  ]) {
+    signal?.throwIfAborted();
+    directory = path.join(directory, component);
+    try {
+      await mkdir(directory, { mode: 0o700 });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink() || (await realpath(directory)) !== directory)
+      throw new OperationalError(
+        "SDD metadata directories must be physical in-project directories, without symlinks.",
+      );
+  }
+  const created: { file: string; ino: number; dev: number; expected: Buffer; complete: boolean }[] =
+    [];
+  try {
+    for (const [name, text] of [
+      ["report.json", reportText],
+      ["untangle.features.json", manifestText],
+    ] as const) {
+      signal?.throwIfAborted();
+      const file = path.join(directory, name);
+      let handle;
+      try {
+        handle = await open(
+          file,
+          constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+          0o600,
+        );
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        const existing = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+          const info = await existing.stat();
+          if (
+            !info.isFile() ||
+            info.size !== Buffer.byteLength(text) ||
+            (await realpath(file)) !== file ||
+            (await existing.readFile()).toString("utf8") !== text
+          )
+            throw new OperationalError("Existing SDD artifacts differ; no file was overwritten.");
+        } finally {
+          await existing.close();
+        }
+        continue;
+      }
+      try {
+        const info = await handle.stat();
+        const own = {
+          file,
+          ino: info.ino,
+          dev: info.dev,
+          expected: Buffer.from(text),
+          complete: false,
+        };
+        created.push(own);
+        await handle.writeFile(text, { signal });
+        own.complete = true;
+        signal?.throwIfAborted();
+      } finally {
+        await handle.close();
+      }
+    }
+  } catch (error) {
+    for (const own of created) {
+      const info = await lstat(own.file).catch(() => null);
+      if (!info?.isFile() || info.ino !== own.ino || info.dev !== own.dev) continue;
+      const handle = await open(own.file, constants.O_RDONLY | constants.O_NOFOLLOW).catch(
+        () => null,
+      );
+      if (!handle) continue;
+      try {
+        const opened = await handle.stat();
+        if (opened.ino !== own.ino || opened.dev !== own.dev || opened.size > own.expected.length)
+          continue;
+        const bytes = await handle.readFile();
+        // A failed write may leave only a prefix. Preserve replacements and unexpected edits.
+        const matches = own.complete
+          ? bytes.equals(own.expected)
+          : bytes.equals(own.expected.subarray(0, bytes.length));
+        const current = await lstat(own.file).catch(() => null);
+        const unchanged =
+          current?.ino === opened.ino &&
+          current.dev === opened.dev &&
+          current.size === opened.size &&
+          current.mtimeMs === opened.mtimeMs;
+        if (matches && unchanged) await unlink(own.file);
+      } finally {
+        await handle.close();
+      }
+    }
+    throw error;
+  }
+  return {
+    schemaVersion: 1,
+    kind: "sdd_connection_artifact",
+    report,
+    reportPath: path.join(directory, "report.json"),
+    manifestPath: path.join(directory, "untangle.features.json"),
+    sha256,
+  };
+}
+
+export async function runSddConnection(
+  ctx: CommandContext,
+  args: ParsedArgs,
+  deps: { discover?: typeof discoverSddArtifacts; write?: typeof writeSddConnection } = {},
+): Promise<number> {
+  const positionals =
+    args.positionals[0] === "connect" ? args.positionals.slice(1) : args.positionals;
+  if (
+    positionals.length > 1 ||
+    !["auto", "spec-kit", "openspec"].includes(positionals[0] ?? "auto")
+  )
+    throw new UsageError(
+      "Use `untangle product connect [auto|spec-kit|openspec] [--root=PATH] [--dry-run] [--format=json]`.",
+    );
+  for (const [name, value] of Object.entries(args.flags))
+    if (!["root", "dry-run", "format", "help"].includes(name) && value !== undefined)
+      throw new UsageError(`--${name} is not supported by product connect.`);
+  const framework = (positionals[0] ?? "auto") as SddFrameworkV1 | "auto";
+  const format = enumFlag(args, "format", ["text", "json"] as const, "text");
+  const report = await (deps.discover ?? discoverSddArtifacts)({
+    root: path.resolve(ctx.cwd, stringFlag(args, "root") ?? "."),
+    framework,
+    signal: ctx.signal,
+  });
+  ctx.signal.throwIfAborted();
+  const result: SddConnectionArtifactV1 = boolFlag(args, "dry-run")
+    ? {
+        schemaVersion: 1,
+        kind: "sdd_connection_artifact",
+        report,
+        reportPath: null,
+        manifestPath: null,
+        sha256: null,
+      }
+    : await (deps.write ?? writeSddConnection)(report, { signal: ctx.signal });
+  if (format === "json") line(ctx.io, JSON.stringify(result, null, 2));
+  else {
+    line(
+      ctx.io,
+      `SDD connection: ${report.status}; ${String(report.features.length)} proposed features from ${report.frameworks.join(", ") || "no detected framework"}.`,
+    );
+    if (result.manifestPath) {
+      line(ctx.io, `Review manifest: ${result.manifestPath}`);
+      line(ctx.io, `Evidence report: ${result.reportPath!}`);
+      line(
+        ctx.io,
+        `Next argv (data, not a shell command): ${JSON.stringify(["untangle", "product", `--root=${report.root}`, `--manifest=${result.manifestPath}`])}`,
+      );
+      line(
+        ctx.io,
+        `Map argv (data, not a shell command): ${JSON.stringify(["untangle", "graph", "features", `--root=${report.root}`, `--feature-map=${result.manifestPath}`])}`,
+      );
+    }
+    for (const issue of report.issues)
+      note(ctx.io, `${issue.code}: ${issue.path}: ${issue.message}`);
+    note(
+      ctx.io,
+      "Imported declarations require review. No framework commands or tests ran; no implementation or ownership was confirmed.",
+    );
+  }
+  return report.status === "stale" ? 1 : 0;
+}

package/src/commands/unavailable.ts

@@ -0,0 +1,92 @@
+/**
+ * DER BAUPLAN fuer Befehle, deren Faehigkeit es NOCH NICHT GIBT.
+ *
+ * STAND: DIESE DATEI FUEHRT DERZEIT KEINEN BEFEHL MEHR. `watch` ist mit
+ * WP-128 hier ausgezogen, `graph` und `flow` mit WP-229 — beide lesen den
+ * Graphen jetzt wirklich zurueck (`commands/graph/`, `commands/flow/`).
+ * Geblieben ist {@link createUnavailableCommand}: der Bauplan fuer den
+ * naechsten Befehl, der angelegt, aber noch nicht gebaut ist. Er wird
+ * absichtlich NICHT geloescht — die Alternative zu einem ehrlichen
+ * Platzhalter ist erfahrungsgemaess kein fertiger Befehl, sondern ein
+ * stiller.
+ *
+ * Sie stehen in der Oberflaeche, weil ihre Abwesenheit sonst unsichtbar waere
+ * — ein Nutzer wuesste nicht, ob `untangle index` fehlt, falsch geschrieben
+ * ist oder heimlich nichts tut. BUILD_PLAN E4 verlangt genau das Gegenteil:
+ * jedes Ueberspringen bekommt einen Grund.
+ *
+ * Deshalb tut jeder dieser Befehle drei Dinge und nichts sonst:
+ *   1. er sagt, WAS fehlt — pruefbar, mit Paket- und Typnamen;
+ *   2. er sagt, was HEUTE schon geht, wenn es etwas gibt;
+ *   3. er nennt GENAU EINEN naechsten Schritt.
+ * Und er endet mit Exit-Code 3, nie mit 0 und nie mit 1.
+ */
+
+import type { FlagSpecs } from "../cli/args.js";
+import type { Command, CommandContext, CommandSpec } from "../cli/command.js";
+import { wrap } from "../cli/command.js";
+import { EXIT, UnavailableError } from "../cli/exit.js";
+import { note } from "../cli/io.js";
+
+const COMMON_FLAGS: FlagSpecs = {
+  root: {
+    kind: "string",
+    placeholder: "PATH",
+    describe: "Project directory; configuration is discovered from here.",
+    defaultLabel: "current directory",
+  },
+};
+
+interface UnavailableDefinition {
+  readonly name: string;
+  readonly summary: string;
+  readonly usage: string;
+  /** Was fehlt — die pruefbare Aussage, nicht „nicht implementiert". */
+  readonly missing: readonly string[];
+  /** Was heute schon geht; leer, wenn es nichts gibt. */
+  readonly worksToday?: readonly string[];
+  /** GENAU EIN naechster Schritt. */
+  readonly nextStep: string;
+  readonly extraFlags?: FlagSpecs;
+}
+
+export function createUnavailableCommand(definition: UnavailableDefinition): Command {
+  const spec: CommandSpec = {
+    name: definition.name,
+    // Alle drei Platzhalter kommen aus DIESEM Modul. Das ist die Kehrseite
+    // von `implementedBy`: ein Befehl, der hierher zeigt, gibt zu, dass
+    // seine Faehigkeit noch fehlt (`notYetBuilt`) — und ein Befehl, der
+    // NICHT hierher zeigt, behauptet das Gegenteil und wird daran gemessen.
+    implementedBy: "commands/unavailable.js",
+    summary: `${definition.summary}; not available yet`,
+    usage: definition.usage,
+    details: [
+      `This command is registered, but its capability is not implemented. It performs no action and exits with code ${String(EXIT.unavailable)}; it neither reports success nor invents an operational error.`,
+      ...definition.missing,
+      ...(definition.worksToday ?? []),
+    ],
+    flags: { ...COMMON_FLAGS, ...(definition.extraFlags ?? {}) },
+    exitCodes: [[EXIT.unavailable, "This capability is not implemented."]],
+    notYetBuilt: true,
+  };
+
+  return {
+    spec,
+    run(ctx: CommandContext): Promise<number> {
+      note(ctx.io, `untangle ${definition.name}: not available yet.`);
+      note(ctx.io, "");
+      for (const paragraph of definition.missing) {
+        for (const wrapped of wrap(paragraph, 76)) note(ctx.io, `  ${wrapped}`);
+        note(ctx.io, "");
+      }
+      for (const paragraph of definition.worksToday ?? []) {
+        for (const wrapped of wrap(paragraph, 76)) note(ctx.io, `  ${wrapped}`);
+        note(ctx.io, "");
+      }
+      throw new UnavailableError(
+        `The capability behind "untangle ${definition.name}" is not implemented.`,
+        definition.nextStep,
+      );
+    },
+  };
+}