@untangle-code/cli 0.0.0-stage → 0.1.0

package/src/commands/extensions/feature-scan.ts

@@ -0,0 +1,232 @@
+/** Declared feature context for a scan; external evidence never becomes a feature metric. */
+import { analyzeProductAlignment } from "@untangle-code/core";
+import type { ProductAlignmentReportV1 } from "@untangle-code/domain";
+
+import type { Io } from "../../cli/io.js";
+import { line } from "../../cli/io.js";
+import { formatProductReport } from "../product.js";
+
+import type { ExtensionRanV1 } from "./invoke.js";
+
+export type ScanProductAnalyzer = typeof analyzeProductAlignment;
+export type ScanFeatureOptions = Parameters<ScanProductAnalyzer>[0] & { featureId: string };
+
+export interface ScanFeatureContext {
+  requestedFeatureId: string;
+  nextSteps: string[];
+  /** Full-file own metrics, declared ownership, acceptance and test evidence. */
+  report: ProductAlignmentReportV1;
+  sourceBinding: {
+    status: "unchanged" | "changed" | "unverified";
+    beforeDigest: string;
+    afterDigest?: string;
+    beforeManifestHash?: string;
+    afterManifestHash?: string;
+    afterStatus?: ProductAlignmentReportV1["status"];
+    afterIssues?: string[];
+    beforeInventory: ProductAlignmentReportV1["inventory"];
+    afterInventory?: ProductAlignmentReportV1["inventory"];
+    detail: string;
+    nextStep: string;
+  };
+  externalEvidence: {
+    extensionId: string;
+    runId: string;
+    status:
+      "available" | "not_measured" | "source_changed" | "source_unverified" | "no_feature_boundary";
+    /** Request time is not proof of the analyzer's underlying source snapshot. */
+    analyzerSourceIdentity: "not_independently_proven";
+    bindings: {
+      kind: "measurement" | "finding";
+      index: number;
+      relation: "declared_feature_file" | "other_file" | "repository_context" | "unscoped";
+      filePath?: string;
+      sharedWithFeatures?: string[];
+    }[];
+    nextStep: string;
+  }[];
+  limitations: string[];
+}
+
+/** Re-analyze after the external calls, preserving both source identities and missing evidence. */
+export async function finishScanFeature(
+  options: ScanFeatureOptions,
+  before: ProductAlignmentReportV1,
+  outcomes: readonly ExtensionRanV1[],
+  analyze: ScanProductAnalyzer = analyzeProductAlignment,
+): Promise<ScanFeatureContext> {
+  let after: ProductAlignmentReportV1 | undefined;
+  let failure: string | undefined;
+  try {
+    after = await analyze(options);
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    failure = error instanceof Error ? error.message : String(error);
+  }
+  options.signal?.throwIfAborted();
+  const changed =
+    after !== undefined &&
+    (before.sourceTreeDigest !== after.sourceTreeDigest ||
+      before.manifest.contentHash !== after.manifest.contentHash);
+  const verified = after !== undefined && !unstableInventory(before) && !unstableInventory(after);
+  const status = changed ? "changed" : verified ? "unchanged" : "unverified";
+  const feature = before.features.find((entry) => entry.id === options.featureId);
+  const selected = new Set(
+    [...(feature?.code.files ?? []), ...(feature?.tests.files ?? [])].map((file) => file.path),
+  );
+  const shared = new Map(before.coverage.sharedFiles.map((file) => [file.path, file.featureIds]));
+  const sharedContext = (filePath: string | undefined): { sharedWithFeatures?: string[] } => {
+    const featureIds = filePath === undefined ? undefined : shared.get(filePath);
+    return featureIds === undefined ? {} : { sharedWithFeatures: featureIds };
+  };
+  const nextStep =
+    "Repeat scan on a stable working tree; inspect product evidence and analyzer source provenance separately.";
+  return {
+    requestedFeatureId: options.featureId,
+    nextSteps: [
+      ...(feature === undefined
+        ? [
+            "Review the manifest path and declared feature ID with untangle product; a missing boundary has no feature metrics.",
+          ]
+        : []),
+      ...(feature?.code.complete === false
+        ? [
+            "Resolve missing, unsupported or partial declared files before treating feature complexity as complete.",
+          ]
+        : []),
+      ...(outcomes.length === 0
+        ? [
+            "External feature evidence is not measured. Inspect untangle extensions list/status; add and enable an analyzer explicitly if needed.",
+          ]
+        : []),
+      ...(status === "unchanged" ? [] : [nextStep]),
+    ],
+    report: before,
+    sourceBinding: {
+      status,
+      beforeDigest: before.sourceTreeDigest,
+      beforeInventory: before.inventory,
+      ...(after === undefined
+        ? {}
+        : {
+            afterDigest: after.sourceTreeDigest,
+            afterStatus: after.status,
+            afterIssues: after.issues,
+            afterInventory: after.inventory,
+          }),
+      ...(before.manifest.contentHash === undefined
+        ? {}
+        : { beforeManifestHash: before.manifest.contentHash }),
+      ...(after?.manifest.contentHash === undefined
+        ? {}
+        : { afterManifestHash: after.manifest.contentHash }),
+      detail:
+        failure === undefined
+          ? "Compared accepted local inventories and feature-manifest hashes before own analysis and after external calls. This is not an atomic snapshot or proof of a remote analysis revision."
+          : `The final local source check failed: ${failure}`,
+      nextStep,
+    },
+    externalEvidence: outcomes.map(({ extensionId, result }) => {
+      const bindings: ScanFeatureContext["externalEvidence"][number]["bindings"] = [
+        ...result.measurements.map((measurement, index) => ({
+          kind: "measurement" as const,
+          index,
+          relation:
+            measurement.signal?.scope === "repository"
+              ? ("repository_context" as const)
+              : measurement.signal === undefined || measurement.filePath === undefined
+                ? ("unscoped" as const)
+                : selected.has(measurement.filePath)
+                  ? ("declared_feature_file" as const)
+                  : ("other_file" as const),
+          ...(measurement.filePath === undefined ? {} : { filePath: measurement.filePath }),
+          ...sharedContext(measurement.filePath),
+        })),
+        ...result.findings.map((finding, index) => ({
+          kind: "finding" as const,
+          index,
+          relation: selected.has(finding.filePath)
+            ? ("declared_feature_file" as const)
+            : ("other_file" as const),
+          filePath: finding.filePath,
+          ...sharedContext(finding.filePath),
+        })),
+      ];
+      return {
+        extensionId,
+        runId: result.run.runId,
+        status:
+          feature === undefined
+            ? "no_feature_boundary"
+            : status === "changed"
+              ? "source_changed"
+              : status === "unverified"
+                ? "source_unverified"
+                : result.run.exitStatus !== "completed" || bindings.length === 0
+                  ? "not_measured"
+                  : "available",
+        analyzerSourceIdentity: "not_independently_proven",
+        bindings,
+        nextStep:
+          bindings.length === 0
+            ? "Inspect run errors, skips, output mapping and configured analyzer target; empty output is not a passed feature check."
+            : "Use file bindings as declared context only; verify the analyzer project/revision, corpus and metric definition before drawing conclusions.",
+      };
+    }),
+    limitations: [
+      "No external measurement is added, compared or attributed as a feature total. Repository measurements remain repository context.",
+      "A file binding follows the declared feature map and can belong to several features; it does not prove feature ownership or semantic conformance.",
+      "The local digest covers the accepted product inventory, not excluded files or an external server's source revision. Equal request-time inventories do not prove fresh remote measures.",
+      "No enabled analyzer or no evidence means not measured, never zero complexity or a passed quality gate.",
+    ],
+  };
+}
+
+function unstableInventory(report: ProductAlignmentReportV1): boolean {
+  return (
+    report.inventory.truncated ||
+    report.issues.some(
+      (issue) => issue.startsWith("Accepted source") || issue.startsWith("Accepted inventory"),
+    )
+  );
+}
+
+export function renderScanFeature(io: Io, context: ScanFeatureContext): void {
+  line(io, "\n# Declared feature — own analysis, responsibility and evidence");
+  line(io, formatProductReport(context.report));
+  if (context.report.features.length === 0) {
+    line(
+      io,
+      `Feature ${context.requestedFeatureId} was not resolved. Review untangle.features.json and run untangle product.`,
+    );
+  }
+  line(io, `Local source binding: ${context.sourceBinding.status}`);
+  line(io, `  ${context.sourceBinding.detail}`);
+  if (context.sourceBinding.status !== "unchanged")
+    line(io, `  Action: ${context.sourceBinding.nextStep}`);
+  if (context.externalEvidence.length === 0)
+    line(
+      io,
+      "External feature evidence: not measured; inspect untangle extensions list/status and explicitly configure the desired analyzer.",
+    );
+  for (const evidence of context.externalEvidence) {
+    line(
+      io,
+      `  ${evidence.extensionId}: ${evidence.status}; analyzer source identity: ${evidence.analyzerSourceIdentity}`,
+    );
+    for (const binding of evidence.bindings)
+      line(
+        io,
+        `    ${binding.kind}[${binding.index}]: ${binding.relation}${binding.filePath === undefined ? "" : ` — ${binding.filePath}`}`,
+      );
+    for (const binding of evidence.bindings)
+      if (binding.sharedWithFeatures !== undefined)
+        line(
+          io,
+          `    Shared file: ${binding.filePath}; features ${binding.sharedWithFeatures.join(", ")}`,
+        );
+    line(io, `    Action: ${evidence.nextStep}`);
+  }
+  for (const limitation of context.limitations) line(io, `Limit: ${limitation}`);
+  for (const nextStep of context.nextSteps) line(io, `Action: ${nextStep}`);
+}

package/src/commands/extensions/invoke.ts

@@ -0,0 +1,368 @@
+/** Shared extension execution for `extensions run` and `scan`.
+ * Expected refusals and failures are data; cancellation still aborts the caller.
+ * The caller owns rendering and persistence of the returned run record.
+ */
+import { buildRefId, buildRepoId, buildWorkspaceId, sha256Hex } from "@untangle-code/domain";
+import {
+  buildHttpAuthHeaders,
+  createFetchHttpRunner,
+  createNodeProcessRunner,
+  detectExtension,
+  runExtension,
+  redactSecrets,
+  type ExtensionHealthV1,
+  type ExtensionRunResultV1,
+  type FileResolutionV1,
+  type LicenseGateDecisionV1,
+  type LoadedExtensionV1,
+  type ProcessLimitsV1,
+} from "@untangle-code/extension-runtime";
+
+import { createContainerCli } from "./container.js";
+import type { ExtensionContextV1 } from "./context.js";
+import { gateFor } from "./context.js";
+import type { ExtensionEnvironmentV1 } from "./environment.js";
+import { provisionContainer, type ProvisionResultV1 } from "./provision.js";
+import { resolveSecretEnvironment } from "./secret-store.js";
+import { missingAnalyzerSecrets, setupCredentials } from "./setup.js";
+
+/**
+ * Warum eine Extension NICHT gelaufen ist — geschlossene Menge (E4).
+ *
+ * Bewusst NICHT die `SkipReason` des Domains: die beschreibt uebersprungene
+ * GEGENSTAENDE einer Pipeline und hat fuer offenes Gate, fehlendes Secret,
+ * verweigerte Zustimmung und nicht-aktiviert kein Glied. Diese Menge beschreibt
+ * einen nicht stattgefundenen AUFRUF, und sie bleibt lokal, bis ein zweiter
+ * Konsument sie braucht.
+ */
+export const EXTENSION_NOT_RUN_REASONS = [
+  "not_enabled",
+  "license_gate_open",
+  "consent_withheld",
+  "secret_missing",
+  "setup_failed",
+  "provision_failed",
+  "invocation_failed",
+] as const;
+
+export type ExtensionNotRunReason = (typeof EXTENSION_NOT_RUN_REASONS)[number];
+
+export interface ExtensionNotRunV1 {
+  status: "not_run";
+  extensionId: string;
+  reason: ExtensionNotRunReason;
+  /** Menschenlesbare Begruendung; nie leer (E4). */
+  detail: string;
+  /** Der Befehl, der den Zustand aufloesen wuerde, sofern es einen gibt. */
+  nextStep?: string;
+}
+
+export interface ExtensionRanV1 {
+  status: "ran";
+  extensionId: string;
+  health: ExtensionHealthV1;
+  result: ExtensionRunResultV1;
+  provision?: ProvisionResultV1;
+}
+
+export type InvokeExtensionOutcome = ExtensionRanV1 | ExtensionNotRunV1;
+
+export interface InvokeExtensionInput {
+  environment: ExtensionEnvironmentV1;
+  context: ExtensionContextV1;
+  extension: LoadedExtensionV1;
+  workspacePath: string;
+  target: string;
+  ruleset?: string;
+  httpUrl?: string;
+  limits: ProcessLimitsV1;
+  /**
+   * Ob eine Container-Bereitstellung erfolgen darf (X1). Ohne sie wird nichts
+   * gestartet und nichts gezogen; der Fall erscheint als `consent_withheld`.
+   */
+  provisionConsent: boolean;
+  /** Nur fuer den Fall `not_enabled` — der Aufrufer entscheidet, ob er ihn prueft. */
+  requireEnabled?: boolean;
+  fetchImpl?: typeof fetch;
+  onProvisionStep?: (step: string) => void;
+  /** Called after the gate, before provisioning, to disclose resource costs. */
+  onProvisionPlanned?: (detail: string) => void;
+  signal?: AbortSignal;
+  /** Wie ein vom Werkzeug genannter Pfad auf das Repository abgebildet wird. */
+  resolveFile: (path: string) => FileResolutionV1;
+  /** Wie eine Werkzeugposition in einen Bytebereich uebersetzt wird. */
+  resolvePosition: Parameters<typeof runExtension>[1]["resolvePosition"];
+}
+
+export async function invokeExtension(
+  input: InvokeExtensionInput,
+): Promise<InvokeExtensionOutcome> {
+  input.signal?.throwIfAborted();
+  const secrets = input.extension.manifest.secrets
+    .map((secret) => input.environment.env[secret.envVar])
+    .filter((value): value is string => value !== undefined && value !== "");
+  try {
+    const outcome = await executeExtension(input, secrets);
+    input.signal?.throwIfAborted();
+    return outcome;
+  } catch (error) {
+    input.signal?.throwIfAborted();
+    return {
+      status: "not_run",
+      extensionId: input.extension.manifest.id,
+      reason: "invocation_failed",
+      detail: redactSecrets(error instanceof Error ? error.message : String(error), secrets),
+      nextStep: `untangle extensions status ${input.extension.manifest.id}`,
+    };
+  }
+}
+
+async function executeExtension(
+  input: InvokeExtensionInput,
+  sensitiveValues: string[],
+): Promise<InvokeExtensionOutcome> {
+  const { environment, context, extension } = input;
+  const manifest = extension.manifest;
+  const extensionId = manifest.id;
+  const ruleset = input.ruleset ?? manifest.defaultRuleset;
+
+  if (input.requireEnabled === true && !context.state.enabled.includes(extensionId)) {
+    return {
+      status: "not_run",
+      extensionId,
+      reason: "not_enabled",
+      detail: `"${extensionId}" is installed but not enabled; enabling starts nothing (X1)`,
+      nextStep: `untangle extensions enable ${extensionId}`,
+    };
+  }
+
+  // Das Lizenz-Gate steht vor allem anderen (X5): ohne Bestaetigung wird nicht
+  // einmal die Version abgefragt.
+  const gate: LicenseGateDecisionV1 = gateFor(context, extension, ruleset);
+  if (!gate.allowed) {
+    const reasons = [gate.tool, ...gate.rulesets]
+      .filter((outcome) => outcome.status !== "acknowledged" && outcome.status !== "not_required")
+      .map((outcome) => outcome.reason)
+      .join("; ");
+    return {
+      status: "not_run",
+      extensionId,
+      reason: "license_gate_open",
+      detail: `nothing was started and nothing was pulled: ${reasons}`,
+      ...(gate.acknowledgeCommands.length === 0
+        ? {}
+        : { nextStep: gate.acknowledgeCommands.join(" && ") }),
+    };
+  }
+
+  const clock = environment.clock;
+  const runtimeDeps = {
+    clock,
+    random: environment.random,
+    processRunner: createNodeProcessRunner(clock),
+    httpRunner: createFetchHttpRunner(
+      (input.fetchImpl ?? fetch) as Parameters<typeof createFetchHttpRunner>[0],
+      clock,
+    ),
+  };
+
+  let provision: ProvisionResultV1 | undefined;
+  if (manifest.container !== undefined) {
+    if (!input.provisionConsent) {
+      const resources = manifest.resources;
+      return {
+        status: "not_run",
+        extensionId,
+        reason: "consent_withheld",
+        detail:
+          `a container would have to be provisioned first: at least ` +
+          `${String(resources.minMemoryMb)} MB memory (recommended ` +
+          `${String(resources.recommendedMemoryMb)} MB), ${String(resources.recommendedCpus)} CPUs, ` +
+          `image ${manifest.container.image}@${manifest.container.digest}`,
+        nextStep: `untangle extensions run ${extensionId} --yes`,
+      };
+    }
+    const resources = manifest.resources;
+    input.onProvisionPlanned?.(
+      `${extensionId}: memory at least ${String(resources.minMemoryMb)} MB, ` +
+        `recommended ${String(resources.recommendedMemoryMb)} MB; ` +
+        `cpus recommended ${String(resources.recommendedCpus)}; ` +
+        `image ${manifest.container.image}@${manifest.container.digest}`,
+    );
+    provision = await provisionContainer(
+      {
+        fs: environment.fs,
+        container: createContainerCli({
+          processRunner: runtimeDeps.processRunner,
+          limits: { ...input.limits, timeoutMs: 300_000 },
+          ...(environment.env["UNTANGLE_CONTAINER_CLI"] === undefined
+            ? {}
+            : { command: environment.env["UNTANGLE_CONTAINER_CLI"] }),
+        }),
+        httpRunner: runtimeDeps.httpRunner,
+        limits: input.limits,
+        wait: waitForRetry,
+      },
+      {
+        manifest,
+        userDataDirectory: environment.userDataDir,
+        workspacePath: input.workspacePath,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+      },
+    );
+    for (const step of provision.steps) {
+      input.onProvisionStep?.(step);
+    }
+    if (!provision.healthy) {
+      return {
+        status: "not_run",
+        extensionId,
+        reason: "provision_failed",
+        detail: provision.detail,
+        nextStep: `untangle extensions logs ${extensionId}`,
+      };
+    }
+  }
+
+  const httpUrl = input.httpUrl ?? manifest.http?.defaultUrl;
+  let effectiveEnv = await resolveSecretEnvironment(environment, manifest, httpUrl);
+  if (manifest.setup && missingAnalyzerSecrets(manifest, effectiveEnv).length > 0) {
+    try {
+      effectiveEnv = await setupCredentials({
+        environment,
+        manifest,
+        ...(provision === undefined ? {} : { provision }),
+        consent: input.provisionConsent,
+        ...(httpUrl === undefined ? {} : { url: httpUrl }),
+        processRunner: runtimeDeps.processRunner,
+        limits: input.limits,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+      });
+      input.onProvisionStep?.(
+        "required credentials were initialized and stored in the private user profile",
+      );
+    } catch (error) {
+      input.signal?.throwIfAborted();
+      return {
+        status: "not_run",
+        extensionId,
+        reason: "setup_failed",
+        detail: error instanceof Error ? error.message : "Credential setup failed.",
+        nextStep: `untangle extensions configure ${extensionId}`,
+      };
+    }
+  }
+  for (const secret of manifest.secrets) {
+    const value = effectiveEnv[secret.envVar];
+    if (value) sensitiveValues.push(value);
+  }
+
+  // Secrets kommen aus Umgebung/privatem Store, nie aus dem Manifest (§8.5). Die
+  // Reihenfolge nach der Bereitstellung ist Absicht: ein Token kann der Dienst
+  // erst ausstellen, wenn er laeuft.
+  const secretEnv: Record<string, string> = {};
+  const secretValues: string[] = [];
+  const missingSecrets: string[] = [];
+  for (const secret of manifest.secrets) {
+    if (secret.setupOnly) continue;
+    const value = effectiveEnv[secret.envVar];
+    if (value === undefined || value === "") {
+      if (secret.required) {
+        missingSecrets.push(`${secret.name} (${secret.envVar}): ${secret.purpose}`);
+      }
+      continue;
+    }
+    secretEnv[secret.envVar] = value;
+    secretValues.push(value);
+  }
+  if (missingSecrets.length > 0) {
+    return {
+      status: "not_run",
+      extensionId,
+      reason: "secret_missing",
+      detail:
+        `required secrets are not set in the environment or private config: ${missingSecrets.join("; ")}` +
+        (provision?.healthy === true
+          ? "; the service itself is up, so a token can be created there now"
+          : ""),
+      nextStep: `untangle extensions configure ${extensionId}`,
+    };
+  }
+
+  const toolEnv: Record<string, string> = {
+    PATH: environment.env["PATH"] ?? "",
+    ...(environment.env["HOME"] === undefined ? {} : { HOME: environment.env["HOME"] }),
+    ...(environment.env["LANG"] === undefined ? {} : { LANG: environment.env["LANG"] }),
+    ...secretEnv,
+  };
+  const httpHeaders = buildHttpAuthHeaders(manifest, effectiveEnv);
+
+  const health = await detectExtension(runtimeDeps, {
+    extension,
+    licenseGate: gate.tool.status,
+    env: toolEnv,
+    secretValues,
+    limits: input.limits,
+    ...(httpUrl === undefined ? {} : { httpUrl }),
+    ...(Object.keys(httpHeaders).length === 0 ? {} : { httpHeaders }),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+  });
+
+  // X6: der Pin gilt fuer den Container, den Untangle gestartet hat — auch
+  // wenn analysiert wird, indem man ihn fragt.
+  if (provision !== undefined && manifest.container !== undefined) {
+    const digest = provision.state.imageDigest;
+    if (digest !== undefined) {
+      health.imageDigest = digest;
+      health.digestMatchesManifest = digest === manifest.container.digest;
+    }
+  }
+
+  const repoId = buildRepoId({ canonicalPath: input.workspacePath });
+  const workspaceId = buildWorkspaceId({ configHash: sha256Hex(input.workspacePath) });
+  const refId = buildRefId(repoId, "working-tree");
+
+  const result = await runExtension(runtimeDeps, {
+    extension,
+    health,
+    gate,
+    workspaceId,
+    repoId,
+    refId,
+    workspacePath: input.workspacePath,
+    target: input.target,
+    env: toolEnv,
+    secretValues,
+    limits: input.limits,
+    ...(ruleset === undefined ? {} : { ruleset }),
+    ...(httpUrl === undefined ? {} : { httpUrl }),
+    ...(Object.keys(httpHeaders).length === 0 ? {} : { httpHeaders }),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+    resolveFile: input.resolveFile,
+    resolvePosition: input.resolvePosition,
+  });
+
+  return {
+    status: "ran",
+    extensionId,
+    health,
+    result,
+    ...(provision === undefined ? {} : { provision }),
+  };
+}
+
+/** Abortable wait without leaving listeners behind after each health probe. */
+function waitForRetry(ms: number, signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}