@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/commands/extensions/add.ts

@@ -0,0 +1,312 @@
+/**
+ * `untangle extensions add --from <url|path>`
+ *
+ * Installs ONE manifest into the user's extension root
+ * (`~/.untangle/extensions/<id>/manifest.toml`). Four gates stand between the
+ * argument and the file on disk, and none of them is optional:
+ *
+ * 1. **Transport.** A URL must be https and must carry `--digest`
+ *    (`source.ts` explains why).
+ * 2. **Project boundary.** A path inside a project directory is refused
+ *    unless the user types `--allow-project-local` in the same invocation.
+ *    Automatic loading from a project directory does not exist at all: a
+ *    cloned repository must not be able to hand a tool definition to the
+ *    runtime (extensions.md §17).
+ * 3. **Manifest validity.** Structure and semantics both, X6 included: a
+ *    container manifest without a fully pinned sha256 digest is rejected.
+ * 4. **License gate (X5).** Installing never acknowledges anything. A
+ *    restricted tool is installed in state `unacknowledged`, and the exact
+ *    command that would grant the acknowledgment is printed.
+ *
+ * `add` starts nothing — no process, no pull, no container (X1).
+ */
+import { join } from "node:path";
+
+import {
+  MANIFEST_FILE_NAME,
+  buildAcknowledgment,
+  extensionDirectory,
+  extensionManifestPath,
+  isProjectLocalManifest,
+  loadExtensionManifestFile,
+  parseExtensionManifest,
+} from "@untangle-code/extension-runtime";
+
+import { boolFlag, listFlag, stringFlag, type ParsedArgs } from "../../cli/args.js";
+import { EXIT, OperationalError, UsageError } from "../../cli/exit.js";
+import { line, note, type Io } from "../../cli/io.js";
+
+import { gateFor, loadExtensionContext } from "./context.js";
+import { canonicalize, resolveUserPath, type ExtensionEnvironmentV1 } from "./environment.js";
+import { emitJson } from "./render.js";
+import {
+  DIGEST_PATTERN,
+  ManifestSourceError,
+  fetchManifestFromUrl,
+  isUrlSource,
+  readManifestFromPath,
+  type FetchManifestOptions,
+  type ManifestSourceV1,
+} from "./source.js";
+import { saveAcknowledgments, upsertAcknowledgment } from "./state.js";
+
+export interface AddDeps {
+  /** Injected in tests so no unit test opens a socket. */
+  fetchOptions?: FetchManifestOptions;
+}
+
+export async function runAdd(
+  environment: ExtensionEnvironmentV1,
+  args: ParsedArgs,
+  io: Io,
+  format: "text" | "json",
+  deps: AddDeps = {},
+): Promise<number> {
+  const from = stringFlag(args, "from");
+  if (from === undefined) {
+    throw new UsageError(
+      "`untangle extensions add` needs a source.",
+      "Write --from=<path to a manifest.toml> or --from=<https URL> --digest=sha256:<64 hex>.",
+    );
+  }
+  const expectedDigest = stringFlag(args, "digest");
+  if (expectedDigest !== undefined && !DIGEST_PATTERN.test(expectedDigest)) {
+    throw new UsageError(
+      `--digest must look like "sha256:<64 lowercase hex>", got "${expectedDigest}".`,
+      "Compute it with: shasum -a 256 manifest.toml",
+    );
+  }
+
+  const source = await readSource(environment, from, expectedDigest, args, deps);
+
+  if (expectedDigest !== undefined && source.digest !== expectedDigest) {
+    throw new OperationalError(
+      `Digest mismatch for ${source.resolved}: expected ${expectedDigest}, got ${source.digest}. ` +
+        "Nothing was installed.",
+      "Verify the digest with the publisher before installing this manifest.",
+    );
+  }
+
+  // --- manifest validity (structure + semantics, X6 included) -------------
+  const parsed = parseExtensionManifest(source.text);
+  if (parsed.manifest === null) {
+    note(io, `The manifest at ${source.resolved} is not valid; nothing was installed:`);
+    for (const issue of parsed.issues) {
+      note(io, `  ${issue.field}: ${issue.message}`);
+    }
+    throw new OperationalError(
+      `${String(parsed.issues.length)} problem(s) in the manifest at ${source.resolved}.`,
+      "Fix the fields listed above; the manifest schema is documented in extensions.md §5.2.",
+    );
+  }
+  const manifest = parsed.manifest;
+
+  // --- write --------------------------------------------------------------
+  const root = environment.roots[0];
+  if (root === undefined) {
+    throw new OperationalError(
+      "No extension root could be resolved for this user profile.",
+      "Set UNTANGLE_EXTENSIONS_HOME to a writable directory outside any project.",
+    );
+  }
+  const targetDirectory = extensionDirectory(root, manifest.id);
+  const targetPath = extensionManifestPath(root, manifest.id);
+  const existing = await environment.fs.stat(targetPath);
+  if (existing !== null && !boolFlag(args, "force")) {
+    throw new OperationalError(
+      `"${manifest.id}" is already installed at ${targetPath}.`,
+      `Repeat with --force to replace it, or remove it first: untangle extensions remove ${manifest.id}`,
+    );
+  }
+
+  await environment.fs.mkdir(targetDirectory, { recursive: true });
+  const temporary = join(targetDirectory, `${MANIFEST_FILE_NAME}.tmp`);
+  await environment.fs.writeFile(temporary, source.bytes);
+  await environment.fs.rename(temporary, targetPath);
+
+  // Re-read through the loader, so what is reported is what the runtime will
+  // see — not what this command believed it wrote.
+  const loaded = await loadExtensionManifestFile(environment.fs, targetPath, "user-data-dir", {
+    expectedId: manifest.id,
+  });
+  if (loaded.extension === null) {
+    for (const issue of loaded.issues) {
+      note(io, `  ${issue.field}: ${issue.message}`);
+    }
+    throw new OperationalError(
+      `The installed manifest at ${targetPath} does not load back.`,
+      "Remove the directory and install the manifest again.",
+    );
+  }
+  const installed = loaded.extension;
+
+  // --- license gate (X5) --------------------------------------------------
+  const context = await loadExtensionContext(environment);
+  let acknowledgments = context.acknowledgments;
+  const acknowledgedNow: string[] = [];
+  if (boolFlag(args, "acknowledge-license")) {
+    acknowledgments = upsertAcknowledgment(
+      acknowledgments,
+      buildAcknowledgment({
+        manifest,
+        acknowledgedAt: environment.clock.nowIso(),
+        acknowledgedBy: environment.userName,
+      }),
+    );
+    acknowledgedNow.push(`tool:${manifest.id}`);
+  }
+  for (const ruleset of listFlag(args, "acknowledge-ruleset")) {
+    acknowledgments = upsertAcknowledgment(
+      acknowledgments,
+      buildAcknowledgment({
+        manifest,
+        ruleset,
+        acknowledgedAt: environment.clock.nowIso(),
+        acknowledgedBy: environment.userName,
+      }),
+    );
+    acknowledgedNow.push(`ruleset:${ruleset}`);
+  }
+  let acknowledgmentFile: string | undefined;
+  if (acknowledgedNow.length > 0) {
+    acknowledgmentFile = await saveAcknowledgments(
+      environment.fs,
+      environment.userDataDir,
+      acknowledgments,
+    );
+  }
+
+  const gate = gateFor({ ...context, acknowledgments }, installed);
+
+  if (format === "json") {
+    emitJson(io, {
+      command: "extensions add",
+      extensionId: manifest.id,
+      displayName: manifest.displayName,
+      category: manifest.category,
+      invocation: manifest.invocation,
+      outputFormat: manifest.outputFormat,
+      source: { kind: source.kind, requested: source.requested, resolved: source.resolved },
+      manifestDigest: source.digest,
+      manifestSha256: installed.manifestSha256,
+      installedTo: targetPath,
+      replacedExisting: existing !== null,
+      containerDigest: manifest.container?.digest,
+      license: {
+        spdxId: manifest.license.spdxId,
+        usageRestriction: manifest.license.usageRestriction,
+        requiresAcknowledgment: manifest.requiresLicenseAcknowledgment,
+        gateStatus: gate.tool.status,
+        gateReason: gate.tool.reason,
+        rulesets: gate.rulesets.map((entry) => ({
+          ruleset: entry.ruleset,
+          status: entry.status,
+          reason: entry.reason,
+        })),
+        acknowledgedNow,
+        acknowledgmentFile,
+      },
+      networkAccess: manifest.networkAccess,
+      telemetry: manifest.telemetry,
+      enabled: false,
+      started: false,
+      nextSteps: gate.allowed
+        ? [`untangle extensions enable ${manifest.id}`]
+        : gate.acknowledgeCommands,
+      warnings: context.warnings,
+    });
+  } else {
+    line(io, `installed "${manifest.id}" (${manifest.displayName})`);
+    line(io, `  from        ${source.resolved}`);
+    line(io, `  manifest    ${targetPath}`);
+    line(io, `  digest      ${source.digest}`);
+    if (manifest.container !== undefined) {
+      line(io, `  image       ${manifest.container.image}@${manifest.container.digest}`);
+    }
+    line(io, `  invocation  ${manifest.invocation.join(", ")}`);
+    line(io, `  format      ${manifest.outputFormat}`);
+    line(
+      io,
+      `  license     ${manifest.license.spdxId} (${manifest.license.usageRestriction}) — gate: ${gate.tool.status}`,
+    );
+    for (const entry of gate.rulesets) {
+      line(io, `  ruleset     ${entry.ruleset} — gate: ${entry.status}`);
+    }
+    line(io, `  network     ${manifest.networkAccess}`);
+    line(
+      io,
+      "  enabled     no — installing starts nothing (X1); enable it with " +
+        `untangle extensions enable ${manifest.id}`,
+    );
+  }
+
+  for (const warning of context.warnings) {
+    note(io, `warning: ${warning}`);
+  }
+  if (!gate.allowed) {
+    note(io, `The license gate is not satisfied: ${gate.tool.reason}`);
+    note(io, "Nothing will run until you acknowledge it:");
+    for (const command of gate.acknowledgeCommands) {
+      note(io, `  ${command}`);
+    }
+  }
+
+  // Installing succeeded even when the gate is still open: the manifest is on
+  // disk and `list` will show it. The gate is enforced where it matters — at
+  // `run` — so a successful install is not reported as a failure.
+  return EXIT.ok;
+}
+
+async function readSource(
+  environment: ExtensionEnvironmentV1,
+  from: string,
+  expectedDigest: string | undefined,
+  args: ParsedArgs,
+  deps: AddDeps,
+): Promise<ManifestSourceV1> {
+  if (isUrlSource(from)) {
+    if (expectedDigest === undefined) {
+      throw new UsageError(
+        `Refusing to install from a URL without --digest. "${from}" is not a fixed artifact: ` +
+          "whatever the server returns today would become a program invocation on this machine.",
+        "Ask the publisher for the sha256 of the manifest and pass --digest=sha256:<64 hex>, " +
+          "or download the file and use --from=<path>.",
+      );
+    }
+    try {
+      return await fetchManifestFromUrl(from, deps.fetchOptions ?? {});
+    } catch (cause) {
+      throw new OperationalError(
+        cause instanceof ManifestSourceError ? cause.message : String(cause),
+        "Check the URL, or download the manifest and install the local copy with --from=<path>.",
+        { cause },
+      );
+    }
+  }
+
+  // The boundary check compares lexically and does not resolve symlinks — the
+  // runtime says so explicitly. Canonicalizing here is what makes the check
+  // sound: without it a symlink (or, on macOS, the /var alias alone) would
+  // carry a path out of the project it really lives in.
+  const path = await canonicalize(environment.fs, resolveUserPath(environment.cwd, from));
+  if (
+    isProjectLocalManifest(path, environment.projectRoots) &&
+    !boolFlag(args, "allow-project-local")
+  ) {
+    throw new UsageError(
+      `Refusing to read a manifest from a project directory: "${path}" lies inside ` +
+        `${environment.projectRoots.join(", ")}. A manifest describes how to start a program, so a ` +
+        "cloned repository must never be able to supply one unnoticed (extensions.md §17).",
+      "If you wrote this manifest yourself, repeat the command with --allow-project-local.",
+    );
+  }
+  try {
+    return await readManifestFromPath(environment.fs, path);
+  } catch (cause) {
+    throw new OperationalError(
+      cause instanceof ManifestSourceError ? cause.message : String(cause),
+      "Check the path; --from accepts a manifest.toml or the directory containing it.",
+      { cause },
+    );
+  }
+}

package/src/commands/extensions/configure.ts

@@ -0,0 +1,82 @@
+/** User-private credential configuration; values never appear in output or argv. */
+import { readFile } from "node:fs/promises";
+
+import { stringFlag, type ParsedArgs } from "../../cli/args.js";
+import { EXIT, OperationalError, UsageError } from "../../cli/exit.js";
+import { line, type Io } from "../../cli/io.js";
+
+import { explainMissing, findExtension, loadExtensionContext } from "./context.js";
+import { resolveUserPath, type ExtensionEnvironmentV1 } from "./environment.js";
+import { emitJson } from "./render.js";
+import {
+  parseSecretValues,
+  readStoredSecrets,
+  secretStorePath,
+  withSecretLock,
+  writeStoredSecrets,
+} from "./secret-store.js";
+
+export async function runConfigure(
+  environment: ExtensionEnvironmentV1,
+  args: ParsedArgs,
+  io: Io,
+  format: "text" | "json",
+): Promise<number> {
+  const id = args.positionals[1];
+  if (!id || args.positionals.length !== 2)
+    throw new UsageError(
+      "configure needs exactly one extension id.",
+      "untangle extensions configure <id> [--from=<private-json-file>]",
+    );
+  const context = await loadExtensionContext(environment);
+  const extension = findExtension(context, id);
+  if (!extension)
+    throw new OperationalError(explainMissing(context, id), "Install the extension first.");
+  const manifest = extension.manifest;
+  const source = stringFlag(args, "from");
+  let imported: Record<string, string> = {};
+  if (source !== undefined) {
+    let content: unknown;
+    try {
+      content = JSON.parse(await readFile(resolveUserPath(environment.cwd, source), "utf8"));
+    } catch {
+      throw new UsageError(
+        "Cannot read credential JSON; its contents were withheld.",
+        "Use a JSON object keyed by the secret names declared in the manifest.",
+      );
+    }
+    imported = parseSecretValues(content, manifest);
+  }
+  const values = await withSecretLock(environment, id, async () => {
+    const stored = await readStoredSecrets(environment, manifest);
+    const values = {
+      ...Object.fromEntries(manifest.secrets.map((secret) => [secret.name, ""])),
+      ...stored,
+      ...imported,
+    };
+    await writeStoredSecrets(environment, manifest, values);
+    return values;
+  });
+  const path = secretStorePath(environment, id);
+  const secrets = manifest.secrets.map((secret) => ({
+    name: secret.name,
+    envVar: secret.envVar,
+    configured: Boolean(values[secret.name]),
+    setupOnly: secret.setupOnly ?? false,
+  }));
+  if (format === "json")
+    emitJson(io, { command: "extensions configure", extensionId: id, path, secrets });
+  else {
+    line(io, `Private credential configuration (0600): ${path}`);
+    for (const secret of secrets)
+      line(
+        io,
+        `  ${secret.name}: ${secret.configured ? "configured" : "not set"}; environment override: ${secret.envVar}${secret.setupOnly ? " (setup only)" : ""}`,
+      );
+    line(
+      io,
+      `Edit the secrets object in that file, then run: untangle extensions setup ${id} --yes`,
+    );
+  }
+  return EXIT.ok;
+}

package/src/commands/extensions/container.ts

@@ -0,0 +1,209 @@
+/**
+ * Die Container-Grenze, bedient ueber ein Compose-fähiges Kommandozeilen-
+ * werkzeug des Nutzers.
+ *
+ * Untangle liefert keine Container-Runtime mit. Es ruft die auf, die auf dem
+ * Rechner steht — ueber dieselbe Prozessgrenze wie jedes andere fremde Programm
+ * (X4). Welches Kommando das ist, sagt `UNTANGLE_CONTAINER_CLI`; die Vorgabe
+ * ist das gebraeuchlichste.
+ *
+ * Zwei Dinge tragen hier die Sicherheit:
+ *
+ * 1. **Die Besitzprobe.** Auf einer Entwicklermaschine laufen fremde Container.
+ *    `down` und `logs` greifen deshalb nie nach dem Namen allein, sondern
+ *    verlangen BEIDE Labels aus §8.2. Findet sich ein Container des erwarteten
+ *    Namens ohne sie, wird nichts angefasst und der Grund gemeldet — nicht
+ *    „schon gut, ist ja unserer".
+ *
+ * 2. **Die Compose-Datei kommt von uns.** Sie wird bei jedem Lauf aus dem
+ *    validierten Manifest gerendert (siehe `renderComposeFile`), damit der
+ *    gepinnte Digest, die Loopback-Bindung und die Labels tatsaechlich gelten
+ *    und nicht nur in einer mitgebrachten YAML behauptet werden.
+ */
+import type { ExtensionManifestV1 } from "@untangle-code/domain";
+import {
+  composeProjectName,
+  EXTENSION_LABEL,
+  MANAGED_LABEL,
+  type ContainerActionResultV1,
+  type ContainerDownInputV1,
+  type ContainerLogsResultV1,
+  type ContainerRuntimeAvailabilityV1,
+  type ContainerRuntimePort,
+  type ContainerStateV1,
+  type ContainerUpInputV1,
+} from "@untangle-code/extension-runtime";
+import type { ProcessLimitsV1, ProcessRunnerPort } from "@untangle-code/extension-runtime";
+
+/** Vorgabe des Kommandos; ueberschreibbar mit `UNTANGLE_CONTAINER_CLI`. */
+export const DEFAULT_CONTAINER_CLI = "docker";
+
+/** Name des Containers einer Extension — bewusst vorhersagbar, nie geraten. */
+export function containerNameFor(extensionId: string): string {
+  return `untangle-ext-${extensionId}`;
+}
+
+const INSPECT_FORMAT =
+  `{{index .Config.Labels "${MANAGED_LABEL}"}}\t` +
+  `{{index .Config.Labels "${EXTENSION_LABEL}"}}\t` +
+  `{{.State.Running}}\t{{.Config.Image}}`;
+
+export interface ContainerCliOptions {
+  processRunner: ProcessRunnerPort;
+  limits: ProcessLimitsV1;
+  /** Kommando der Container-Runtime; kommt aus der Umgebung, nicht aus dem Quelltext. */
+  command?: string;
+  env?: Readonly<Record<string, string>>;
+}
+
+export function createContainerCli(options: ContainerCliOptions): ContainerRuntimePort {
+  const command = options.command ?? DEFAULT_CONTAINER_CLI;
+
+  const run = async (
+    args: readonly string[],
+    signal?: AbortSignal,
+  ): Promise<{ ok: boolean; stdout: string; stderr: string; detail: string }> => {
+    const result = await options.processRunner.run(
+      {
+        command,
+        args: [...args],
+        ...(options.env === undefined ? {} : { env: options.env }),
+      },
+      options.limits,
+      signal === undefined ? {} : { signal },
+    );
+    const ok = result.outcome === "completed" && (result.exitCode ?? 1) === 0;
+    return {
+      ok,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      detail: ok
+        ? `${command} ${args[0] ?? ""} succeeded`
+        : `${command} ${args.join(" ")} failed (${result.outcome}, exit ${String(result.exitCode)})` +
+          `${result.stderr.trim() === "" ? "" : `: ${result.stderr.trim().slice(0, 300)}`}`,
+    };
+  };
+
+  return {
+    async available(opts = {}): Promise<ContainerRuntimeAvailabilityV1> {
+      const result = await run(["version", "--format", "{{.Server.Version}}"], opts.signal);
+      if (!result.ok) {
+        return {
+          available: false,
+          detail:
+            `no container runtime answered: ${result.detail}. Untangle neither ships nor starts ` +
+            `one; set UNTANGLE_CONTAINER_CLI if the command is named differently.`,
+        };
+      }
+      const version = result.stdout.trim();
+      return {
+        available: true,
+        detail: `container runtime ${version} answered on "${command}"`,
+        ...(version === "" ? {} : { version }),
+      };
+    },
+
+    async inspect(manifest: ExtensionManifestV1, opts = {}): Promise<ContainerStateV1> {
+      const name = containerNameFor(manifest.id);
+      const result = await run(["inspect", name, "--format", INSPECT_FORMAT], opts.signal);
+      if (!result.ok) {
+        return {
+          exists: false,
+          running: false,
+          ownedByUntangle: false,
+          detail: `no container named "${name}" exists`,
+        };
+      }
+      const [managed, extensionId, running, image] = result.stdout.trim().split("\t");
+      const owned = managed === "true" && extensionId === manifest.id;
+      if (!owned) {
+        // Der Name allein beweist nichts. Ohne beide Labels ist der Container
+        // fremd, und fremde Container fasst Untangle nicht an (spec.md §3.2).
+        return {
+          exists: true,
+          running: running === "true",
+          ownedByUntangle: false,
+          detail:
+            `a container named "${name}" exists but does not carry ${MANAGED_LABEL}=true and ` +
+            `${EXTENSION_LABEL}=${manifest.id}; Untangle does not touch containers it did not create`,
+        };
+      }
+      const digest = /@(sha256:[0-9a-f]{64})$/.exec(image ?? "")?.[1];
+      return {
+        exists: true,
+        running: running === "true",
+        ownedByUntangle: true,
+        ...(digest === undefined ? {} : { imageDigest: digest }),
+        detail: `container "${name}" is ${running === "true" ? "running" : "stopped"}`,
+      };
+    },
+
+    async up(input: ContainerUpInputV1, opts = {}): Promise<ContainerActionResultV1> {
+      const state = await this.inspect(input.manifest, opts);
+      if (state.exists && !state.ownedByUntangle) {
+        return { ok: false, detail: state.detail };
+      }
+      const result = await run(
+        [
+          "compose",
+          "--project-name",
+          composeProjectName(input.manifest.id),
+          "--file",
+          input.composeFilePath,
+          "up",
+          "--detach",
+        ],
+        opts.signal,
+      );
+      return { ok: result.ok, detail: result.detail };
+    },
+
+    async down(input: ContainerDownInputV1, opts = {}): Promise<ContainerActionResultV1> {
+      const state = await this.inspect(input.manifest, opts);
+      if (state.exists && !state.ownedByUntangle) {
+        return { ok: false, detail: state.detail };
+      }
+      const result = await run(
+        [
+          "compose",
+          "--project-name",
+          composeProjectName(input.manifest.id),
+          "--file",
+          input.composeFilePath,
+          "down",
+          ...(input.removeVolumes ? ["--volumes"] : []),
+        ],
+        opts.signal,
+      );
+      return { ok: result.ok, detail: result.detail };
+    },
+
+    async logs(
+      input: { manifest: ExtensionManifestV1; composeFilePath: string; tail: number },
+      opts = {},
+    ): Promise<ContainerLogsResultV1> {
+      const state = await this.inspect(input.manifest, opts);
+      if (state.exists && !state.ownedByUntangle) {
+        return { ok: false, text: "", detail: state.detail };
+      }
+      if (!state.exists) {
+        return { ok: false, text: "", detail: state.detail };
+      }
+      const result = await run(
+        [
+          "compose",
+          "--project-name",
+          composeProjectName(input.manifest.id),
+          "--file",
+          input.composeFilePath,
+          "logs",
+          "--no-color",
+          "--tail",
+          String(input.tail),
+        ],
+        opts.signal,
+      );
+      return { ok: result.ok, text: result.stdout, detail: result.detail };
+    },
+  };
+}