@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/commands/extensions/list.ts

@@ -0,0 +1,158 @@
+/**
+ * `untangle extensions list`
+ *
+ * Shows what is installed for THIS user: name, license, status, last run.
+ *
+ * The listing is also where the two silences E4 forbids are broken. A
+ * manifest that was found but rejected, and a manifest that was found but
+ * deliberately not loaded — a project-local one above all — both appear with
+ * their reason. So do the roots that were searched, including the ones that
+ * do not exist: "no extensions" must be a statement about a place, not an
+ * unexplained blank.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import { boolFlag, stringFlag, type ParsedArgs } from "../../cli/args.js";
+import { EXIT } from "../../cli/exit.js";
+import { line, note, type Io } from "../../cli/io.js";
+
+import { gateFor, loadExtensionContext } from "./context.js";
+import type { ExtensionEnvironmentV1 } from "./environment.js";
+import { emitJson, renderTable } from "./render.js";
+import type { LastRunRecordV1 } from "./state.js";
+
+interface ListRowV1 {
+  id: string;
+  displayName: string;
+  category: string;
+  invocation: string[];
+  outputFormat: string;
+  license: { spdxId: string; usageRestriction: string; gateStatus: string; gateReason: string };
+  enabled: boolean;
+  status: string;
+  networkAccess: string;
+  /** The manifest pin (X6); null when the extension is not container-invoked. */
+  pin: { image: string; digest: string } | null;
+  manifestPath: string;
+  origin: string;
+  lastRun?: LastRunRecordV1;
+}
+
+export async function runList(
+  environment: ExtensionEnvironmentV1,
+  args: ParsedArgs,
+  io: Io,
+  format: "text" | "json",
+): Promise<number> {
+  const context = await loadExtensionContext(environment);
+  const categoryFilter = stringFlag(args, "category")
+    ?.split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "");
+  const enabledOnly = boolFlag(args, "enabled-only");
+
+  const rows: ListRowV1[] = [];
+  for (const extension of context.discovery.extensions) {
+    const manifest = extension.manifest;
+    if (categoryFilter !== undefined && !categoryFilter.includes(manifest.category)) {
+      continue;
+    }
+    const enabled = context.state.enabled.includes(manifest.id);
+    if (enabledOnly && !enabled) {
+      continue;
+    }
+    const gate = gateFor(context, extension);
+    const lastRun = context.state.lastRuns[manifest.id];
+    rows.push({
+      id: manifest.id,
+      displayName: manifest.displayName,
+      category: manifest.category,
+      invocation: manifest.invocation,
+      outputFormat: manifest.outputFormat,
+      license: {
+        spdxId: manifest.license.spdxId,
+        usageRestriction: manifest.license.usageRestriction,
+        gateStatus: gate.tool.status,
+        gateReason: gate.tool.reason,
+      },
+      enabled,
+      status: statusOf(enabled, gate.allowed, gate.tool.status),
+      networkAccess: manifest.networkAccess,
+      pin:
+        manifest.container === undefined
+          ? null
+          : { image: manifest.container.image, digest: manifest.container.digest },
+      manifestPath: extension.manifestPath,
+      origin: extension.origin,
+      ...(lastRun === undefined ? {} : { lastRun }),
+    });
+  }
+  rows.sort((left, right) => compareCodepoints(left.id, right.id));
+
+  if (format === "json") {
+    emitJson(io, {
+      command: "extensions list",
+      rootsScanned: context.discovery.rootsScanned,
+      projectRootsExcluded: environment.projectRoots,
+      extensions: rows,
+      rejected: context.discovery.rejected,
+      ignored: context.discovery.ignored,
+      warnings: context.warnings,
+    });
+  } else {
+    if (rows.length === 0) {
+      line(io, "no extensions installed.");
+    } else {
+      for (const rendered of renderTable(
+        ["ID", "LICENSE", "RESTRICTION", "STATUS", "LAST RUN"],
+        rows.map((row) => [
+          row.id,
+          row.license.spdxId,
+          row.license.usageRestriction,
+          row.status,
+          describeLastRun(row.lastRun),
+        ]),
+      )) {
+        line(io, rendered);
+      }
+    }
+    line(io, "");
+    line(io, "roots searched (project directories are never searched):");
+    for (const root of context.discovery.rootsScanned) {
+      line(io, `  ${root.root}${root.exists ? "" : "  (does not exist)"}`);
+    }
+    if (environment.projectRoots.length > 0) {
+      line(io, `  excluded as project directories: ${environment.projectRoots.join(", ")}`);
+    }
+  }
+
+  for (const rejected of context.discovery.rejected) {
+    note(io, `rejected ${rejected.manifestPath}:`);
+    for (const issue of rejected.issues) {
+      note(io, `  ${issue.field}: ${issue.message}`);
+    }
+  }
+  for (const ignored of context.discovery.ignored) {
+    note(io, `ignored ${ignored.manifestPath} (${ignored.reason}): ${ignored.detail}`);
+  }
+  for (const warning of context.warnings) {
+    note(io, `warning: ${warning}`);
+  }
+  return EXIT.ok;
+}
+
+function statusOf(enabled: boolean, gateAllowed: boolean, gateStatus: string): string {
+  if (!gateAllowed) {
+    return `blocked (license ${gateStatus})`;
+  }
+  return enabled ? "enabled" : "installed, not enabled";
+}
+
+function describeLastRun(lastRun: LastRunRecordV1 | undefined): string {
+  if (lastRun === undefined) {
+    return "never";
+  }
+  const when = lastRun.finishedAt ?? lastRun.startedAt;
+  const suffix = lastRun.errorCode === undefined ? "" : ` ${lastRun.errorCode}`;
+  return `${when} ${lastRun.exitStatus}${suffix} (${String(lastRun.findingsTotal)} findings)`;
+}

package/src/commands/extensions/logs.ts

@@ -0,0 +1,104 @@
+/**
+ * `untangle extensions logs <id>`
+ *
+ * Liest ausschliesslich die Logs des EIGENEN Containers (extensions.md §11.1).
+ * Die Besitzprobe liegt im Container-Adapter: ohne beide Labels wird nichts
+ * gelesen, auch wenn ein Container des erwarteten Namens existiert. Der Name
+ * `untangle-ext-<id>` ist vorhersagbar, und niemand hindert einen fremden
+ * Container daran, so zu heissen.
+ */
+import {
+  defaultProcessLimits,
+  createNodeProcessRunner,
+  redactSecrets,
+} from "@untangle-code/extension-runtime";
+
+import { integerFlag, type ParsedArgs } from "../../cli/args.js";
+import { EXIT, OperationalError, UsageError } from "../../cli/exit.js";
+import { line, type Io } from "../../cli/io.js";
+
+import { createContainerCli } from "./container.js";
+import { explainMissing, findExtension, loadExtensionContext } from "./context.js";
+import type { ExtensionEnvironmentV1 } from "./environment.js";
+import { composeFilePath } from "./provision.js";
+import { emitJson } from "./render.js";
+import { readStoredSecrets } from "./secret-store.js";
+
+export async function runLogs(
+  environment: ExtensionEnvironmentV1,
+  args: ParsedArgs,
+  io: Io,
+  format: "text" | "json",
+): Promise<number> {
+  const extensionId = args.positionals[1];
+  if (extensionId === undefined) {
+    throw new UsageError(
+      "`untangle extensions logs` needs an extension id.",
+      "Run `untangle extensions list` to see the installed ids.",
+    );
+  }
+  const context = await loadExtensionContext(environment);
+  const extension = findExtension(context, extensionId);
+  if (extension === null) {
+    throw new OperationalError(
+      explainMissing(context, extensionId),
+      "Install it first: untangle extensions add --from=<path-or-url>",
+    );
+  }
+  const manifest = extension.manifest;
+  if (manifest.container === undefined) {
+    throw new OperationalError(
+      `"${extensionId}" declares no container; there are no container logs to read.`,
+      "Logs exist only for extensions Untangle provisions as a container.",
+    );
+  }
+
+  const tail = integerFlag(args, "tail", 200);
+  if (tail <= 0) {
+    throw new UsageError("--tail expects a positive number of lines.", "Example: --tail=200");
+  }
+
+  // Include bootstrap credentials and stored values even when an environment
+  // override is active: old credentials can still occur in retained logs.
+  const stored = await readStoredSecrets(environment, manifest);
+  const secrets = manifest.secrets.flatMap((secret) =>
+    [stored[secret.name], environment.env[secret.envVar]].filter((value): value is string =>
+      Boolean(value),
+    ),
+  );
+  const containerCli = createContainerCli({
+    processRunner: createNodeProcessRunner(environment.clock),
+    limits: { ...defaultProcessLimits(), timeoutMs: 60_000 },
+    ...(environment.env["UNTANGLE_CONTAINER_CLI"] === undefined
+      ? {}
+      : { command: environment.env["UNTANGLE_CONTAINER_CLI"] }),
+  });
+  const result = await containerCli.logs({
+    manifest,
+    composeFilePath: composeFilePath(environment.userDataDir, manifest.id),
+    tail,
+  });
+  result.detail = redactSecrets(result.detail, secrets);
+  result.text = redactSecrets(result.text, secrets);
+
+  if (format === "json") {
+    emitJson(io, {
+      command: "extensions logs",
+      extensionId,
+      ok: result.ok,
+      detail: result.detail,
+      lines: result.text === "" ? [] : result.text.split("\n"),
+    });
+  } else {
+    if (!result.ok) {
+      throw new OperationalError(
+        `No logs were read for "${extensionId}": ${result.detail}`,
+        `Check the container with untangle extensions status ${extensionId}`,
+      );
+    }
+    for (const entry of result.text.split("\n")) {
+      line(io, entry);
+    }
+  }
+  return result.ok ? EXIT.ok : EXIT.operational;
+}

package/src/commands/extensions/provision.ts

@@ -0,0 +1,206 @@
+/**
+ * Bereitstellung eines Container-Dienstes aus dem Manifest (extensions.md §6.2).
+ *
+ * Der Ablauf ist bewusst kurz und ohne Werkzeugwissen:
+ *
+ *   Manifest  →  Compose-Datei rendern  →  up  →  Healthcheck des Manifests
+ *
+ * Die Compose-Datei entsteht bei jedem Lauf neu aus dem validierten Manifest.
+ * Damit gilt der gepinnte Digest wirklich, die Ports binden wirklich an
+ * Loopback und die Labels sind wirklich gesetzt — statt in einer mitgebrachten
+ * YAML behauptet zu werden, die Untangle nicht geprueft hat.
+ *
+ * Auf die Gesundheit wartet Untangle SELBST, ueber den Healthcheck aus dem
+ * Manifest, statt einen in den Container zu rendern. Ein Healthcheck im
+ * Container muesste voraussetzen, welches Programm darin liegt, um eine URL
+ * abzufragen — genau das Werkzeugwissen, das X9 aus dem Quelltext heraushaelt.
+ */
+import { dirname, join } from "node:path";
+
+import type { ExtensionManifestV1, FileSystemPort } from "@untangle-code/domain";
+import {
+  renderComposeFile,
+  type ContainerRuntimePort,
+  type ContainerStateV1,
+  type HttpRunnerPort,
+  type ProcessLimitsV1,
+} from "@untangle-code/extension-runtime";
+
+/** Ort der gerenderten Datei: im Nutzer-Datenverzeichnis, nie im Projekt. */
+export function composeFilePath(userDataDirectory: string, extensionId: string): string {
+  return join(userDataDirectory, "extensions", extensionId, "compose.yaml");
+}
+
+/** Der erste Hostport des Manifests, mit optionaler Ueberschreibung. */
+export function primaryHostPort(
+  manifest: ExtensionManifestV1,
+  overrides: Readonly<Record<string, number>> = {},
+): number | undefined {
+  const port = manifest.container?.ports[0];
+  if (port === undefined) {
+    return undefined;
+  }
+  return overrides[port.name] ?? port.hostPortDefault;
+}
+
+export interface ProvisionDeps {
+  fs: FileSystemPort;
+  container: ContainerRuntimePort;
+  httpRunner: HttpRunnerPort;
+  limits: ProcessLimitsV1;
+  /** Wartepause zwischen zwei Gesundheitsproben; injiziert, damit Tests nicht schlafen. */
+  wait: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+export interface ProvisionResultV1 {
+  /** True, wenn der Dienst am Ende gesund erreichbar ist. */
+  healthy: boolean;
+  /** Was getan wurde — auch wenn nichts getan wurde (E4). */
+  steps: string[];
+  state: ContainerStateV1;
+  detail: string;
+}
+
+/**
+ * Startet den Dienst, falls noetig, und wartet auf seine Gesundheit.
+ *
+ * Ein bereits laufender, Untangle gehoerender Container wird NICHT neu
+ * gestartet: der Lauf soll den Dienst benutzen, nicht bewirtschaften.
+ */
+export async function provisionContainer(
+  deps: ProvisionDeps,
+  input: {
+    manifest: ExtensionManifestV1;
+    userDataDirectory: string;
+    hostPorts?: Readonly<Record<string, number>>;
+    workspacePath?: string;
+    signal?: AbortSignal;
+  },
+): Promise<ProvisionResultV1> {
+  const steps: string[] = [];
+  const manifest = input.manifest;
+  const container = manifest.container;
+  if (container === undefined) {
+    const state: ContainerStateV1 = {
+      exists: false,
+      running: false,
+      ownedByUntangle: false,
+      detail: "the manifest declares no container block",
+    };
+    return { healthy: false, steps, state, detail: state.detail };
+  }
+
+  const runtime = await deps.container.available(
+    input.signal === undefined ? {} : { signal: input.signal },
+  );
+  steps.push(runtime.detail);
+  if (!runtime.available) {
+    return {
+      healthy: false,
+      steps,
+      state: {
+        exists: false,
+        running: false,
+        ownedByUntangle: false,
+        detail: runtime.detail,
+      },
+      detail: runtime.detail,
+    };
+  }
+
+  const path = composeFilePath(input.userDataDirectory, manifest.id);
+  const yaml = renderComposeFile({
+    manifest,
+    ...(input.hostPorts === undefined ? {} : { hostPorts: input.hostPorts }),
+    ...(input.workspacePath === undefined ? {} : { workspacePath: input.workspacePath }),
+  });
+  await deps.fs.mkdir(dirname(path), { recursive: true });
+  await deps.fs.writeFile(path, new TextEncoder().encode(yaml));
+  steps.push(`rendered ${path} from the manifest (image pinned to ${container.digest})`);
+
+  let state = await deps.container.inspect(
+    manifest,
+    input.signal === undefined ? {} : { signal: input.signal },
+  );
+  if (state.exists && !state.ownedByUntangle) {
+    steps.push(state.detail);
+    return { healthy: false, steps, state, detail: state.detail };
+  }
+  if (state.running) {
+    steps.push("the container was already running; Untangle did not restart it");
+  } else {
+    const up = await deps.container.up(
+      { manifest, composeFilePath: path },
+      input.signal === undefined ? {} : { signal: input.signal },
+    );
+    steps.push(up.detail);
+    if (!up.ok) {
+      return { healthy: false, steps, state, detail: up.detail };
+    }
+    state = await deps.container.inspect(
+      manifest,
+      input.signal === undefined ? {} : { signal: input.signal },
+    );
+  }
+
+  const health = await waitForHealth(deps, {
+    manifest,
+    ...(input.hostPorts === undefined ? {} : { hostPorts: input.hostPorts }),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+  });
+  steps.push(health.detail);
+  return { healthy: health.healthy, steps, state, detail: health.detail };
+}
+
+/**
+ * Fragt den Healthcheck des Manifests ab, bis er antwortet oder die erklaerten
+ * Versuche erschoepft sind. Ein Dienst, der lange startet, ist kein Fehler —
+ * ein Dienst, der nie antwortet, schon, und dann steht der Grund da.
+ */
+async function waitForHealth(
+  deps: ProvisionDeps,
+  input: {
+    manifest: ExtensionManifestV1;
+    hostPorts?: Readonly<Record<string, number>>;
+    signal?: AbortSignal;
+  },
+): Promise<{ healthy: boolean; detail: string }> {
+  const check = input.manifest.container?.healthcheck;
+  if (check === undefined || check.kind !== "http" || check.httpPath === undefined) {
+    return {
+      healthy: true,
+      detail:
+        "the manifest declares no http healthcheck; Untangle treats the container as ready " +
+        "without probing and says so rather than implying it checked",
+    };
+  }
+  const port = primaryHostPort(input.manifest, input.hostPorts ?? {});
+  if (port === undefined) {
+    return { healthy: false, detail: "the manifest declares a healthcheck but no port" };
+  }
+  const url = `http://127.0.0.1:${String(port)}${check.httpPath}`;
+  let lastDetail = "no probe was made";
+  for (let attempt = 1; attempt <= check.retries; attempt += 1) {
+    const response = await deps.httpRunner.request(
+      { url, method: "GET" },
+      { ...deps.limits, timeoutMs: check.timeoutMs },
+      input.signal === undefined ? {} : { signal: input.signal },
+    );
+    if (response.outcome === "completed" && (response.status ?? 500) < 400) {
+      return {
+        healthy: true,
+        detail: `healthcheck ${url} answered ${String(response.status)} after ${String(attempt)} attempt(s)`,
+      };
+    }
+    lastDetail = `attempt ${String(attempt)}: ${response.outcome}${
+      response.status === undefined ? "" : ` (status ${String(response.status)})`
+    }`;
+    if (attempt < check.retries) {
+      await deps.wait(check.intervalMs, input.signal);
+    }
+  }
+  return {
+    healthy: false,
+    detail: `healthcheck ${url} did not answer within ${String(check.retries)} attempts — ${lastDetail}`,
+  };
+}

package/src/commands/extensions/remove.ts

@@ -0,0 +1,110 @@
+/**
+ * `untangle extensions remove <id>`
+ *
+ * Deletes one installed extension directory from the user's extension root.
+ *
+ * Two guards. The directory must lie inside a resolved extension root — the
+ * command deletes recursively, and a recursive delete driven by an id from
+ * the command line has to prove where it is pointing. And it must not lie
+ * inside a project directory, which would mean the boundary was crossed
+ * earlier and deleting is not the right repair.
+ *
+ * The license acknowledgment is kept by default. It is a personal declaration
+ * about a tool's terms, not a property of the installed file, and
+ * re-installing the same tool should not quietly need a fresh one. Dropping
+ * it is `--revoke-license`, what extensions.md §9.3 calls revocation.
+ */
+import { dirname } from "node:path";
+
+import { boolFlag, type ParsedArgs } from "../../cli/args.js";
+import { EXIT, OperationalError, UsageError } from "../../cli/exit.js";
+import { line, note, type Io } from "../../cli/io.js";
+
+import { explainMissing, findExtension, loadExtensionContext } from "./context.js";
+import { isInsideAnyRoot, type ExtensionEnvironmentV1 } from "./environment.js";
+import { emitJson } from "./render.js";
+import { removeAcknowledgments, saveAcknowledgments, saveCliState } from "./state.js";
+
+export async function runRemove(
+  environment: ExtensionEnvironmentV1,
+  args: ParsedArgs,
+  io: Io,
+  format: "text" | "json",
+): Promise<number> {
+  const extensionId = args.positionals[1];
+  if (extensionId === undefined) {
+    throw new UsageError(
+      "`untangle extensions remove` needs an extension id.",
+      "Run `untangle extensions list` to see the installed ids.",
+    );
+  }
+
+  const context = await loadExtensionContext(environment);
+  const extension = findExtension(context, extensionId);
+  if (extension === null) {
+    throw new OperationalError(
+      explainMissing(context, extensionId),
+      "Run `untangle extensions list` to see what is installed and why something was rejected.",
+    );
+  }
+
+  const directory = dirname(extension.manifestPath);
+  if (!isInsideAnyRoot(directory, environment.roots)) {
+    throw new OperationalError(
+      `Refusing to delete "${directory}": it is not inside a resolved extension root ` +
+        `(${environment.roots.join(", ")}).`,
+      "Delete the directory yourself if that is really what you want.",
+    );
+  }
+  if (isInsideAnyRoot(directory, environment.projectRoots)) {
+    throw new OperationalError(
+      `Refusing to delete "${directory}": it lies inside a project directory.`,
+      "Extensions are user-profile artifacts; remove this one with your own tools.",
+    );
+  }
+
+  await environment.fs.remove(directory, { recursive: true });
+
+  const statePath = await saveCliState(environment.fs, environment.userDataDir, {
+    ...context.state,
+    enabled: context.state.enabled.filter((id) => id !== extensionId),
+    lastRuns: Object.fromEntries(
+      Object.entries(context.state.lastRuns).filter(([id]) => id !== extensionId),
+    ),
+  });
+
+  let acknowledgmentFile: string | undefined;
+  const revoked = boolFlag(args, "revoke-license");
+  if (revoked) {
+    acknowledgmentFile = await saveAcknowledgments(
+      environment.fs,
+      environment.userDataDir,
+      removeAcknowledgments(context.acknowledgments, extensionId),
+    );
+  }
+
+  if (format === "json") {
+    emitJson(io, {
+      command: "extensions remove",
+      extensionId,
+      removedDirectory: directory,
+      stateFile: statePath,
+      licenseAcknowledgment: revoked ? "revoked" : "kept",
+      acknowledgmentFile,
+      warnings: context.warnings,
+    });
+  } else {
+    line(io, `removed "${extensionId}"`);
+    line(io, `  directory   ${directory}`);
+    line(
+      io,
+      revoked
+        ? `  license     acknowledgment revoked in ${String(acknowledgmentFile)}`
+        : "  license     acknowledgment kept (use --revoke-license to drop it)",
+    );
+  }
+  for (const warning of context.warnings) {
+    note(io, `warning: ${warning}`);
+  }
+  return EXIT.ok;
+}

package/src/commands/extensions/render.ts

@@ -0,0 +1,32 @@
+/**
+ * The two output shapes the extension commands share.
+ *
+ * Payload goes to stdout, everything else to stderr (see `cli/io.ts`), so
+ * `--format=json | jq` stays usable while warnings remain visible.
+ */
+import { line, type Io } from "../../cli/io.js";
+
+/** Writes one JSON document to stdout. */
+export function emitJson(io: Io, value: unknown): void {
+  line(io, JSON.stringify(value, null, 2));
+}
+
+/**
+ * Renders a table padded to the widest cell per column. Padding counts code
+ * units, which is what a fixed-width terminal measures for the ASCII
+ * identifiers, SPDX ids and paths shown here.
+ */
+export function renderTable(
+  header: readonly string[],
+  rows: readonly (readonly string[])[],
+): string[] {
+  const widths = header.map((cell, column) =>
+    rows.reduce((widest, row) => Math.max(widest, (row[column] ?? "").length), cell.length),
+  );
+  const render = (cells: readonly string[]): string =>
+    cells
+      .map((cell, column) => cell.padEnd(widths[column] ?? 0))
+      .join("  ")
+      .trimEnd();
+  return [render(header), render(widths.map((width) => "-".repeat(width))), ...rows.map(render)];
+}