@untangle-code/cli 0.0.0-stage → 0.1.0

package/src/commands/extensions/context.ts

@@ -0,0 +1,109 @@
+/**
+ * The shared read path of the extension commands.
+ *
+ * Every command starts from the same picture: which manifests were found in
+ * the user roots, which were rejected and why, which were deliberately
+ * ignored and why, which acknowledgments exist, and what the CLI recorded
+ * about earlier runs. Building that once keeps `list`, `run` and `enable`
+ * from drifting apart in what they consider "installed".
+ */
+import {
+  discoverExtensions,
+  evaluateLicenseGate,
+  loadLicenseAcknowledgments,
+  type ExtensionDiscoveryResultV1,
+  type LicenseAcknowledgmentV1,
+  type LicenseGateDecisionV1,
+  type LoadedExtensionV1,
+} from "@untangle-code/extension-runtime";
+
+import type { ExtensionEnvironmentV1 } from "./environment.js";
+import { loadCliState, type CliStateV1 } from "./state.js";
+
+export interface ExtensionContextV1 {
+  discovery: ExtensionDiscoveryResultV1;
+  acknowledgments: LicenseAcknowledgmentV1[];
+  state: CliStateV1;
+  /** Everything that was skipped, unreadable or ignored, with its reason (E4). */
+  warnings: string[];
+}
+
+/** Reads discovery, acknowledgments and CLI state in one go. */
+export async function loadExtensionContext(
+  environment: ExtensionEnvironmentV1,
+): Promise<ExtensionContextV1> {
+  const discovery = await discoverExtensions(environment.fs, {
+    roots: environment.roots,
+    projectRoots: environment.projectRoots,
+  });
+  const acknowledgments = await loadLicenseAcknowledgments(environment.fs, {
+    userDataDirectory: environment.userDataDir,
+    projectRoots: environment.projectRoots,
+  });
+  const state = await loadCliState(environment.fs, environment.userDataDir);
+  return {
+    discovery,
+    acknowledgments: acknowledgments.acknowledgments,
+    state: state.state,
+    warnings: [...acknowledgments.warnings, ...state.warnings],
+  };
+}
+
+/** Finds a loaded extension by id, or null. */
+export function findExtension(
+  context: ExtensionContextV1,
+  extensionId: string,
+): LoadedExtensionV1 | null {
+  return context.discovery.extensions.find((entry) => entry.manifest.id === extensionId) ?? null;
+}
+
+/**
+ * Evaluates both gates for one extension against the stored acknowledgments.
+ *
+ * `ruleset` is the effective ruleset of the intended run; without one the
+ * manifest's `defaultRuleset` applies, which is what the runtime would use.
+ */
+export function gateFor(
+  context: ExtensionContextV1,
+  extension: LoadedExtensionV1,
+  ruleset?: string,
+): LicenseGateDecisionV1 {
+  const effective = ruleset ?? extension.manifest.defaultRuleset;
+  return evaluateLicenseGate({
+    extension,
+    acknowledgments: context.acknowledgments,
+    ...(effective === undefined ? {} : { ruleset: effective }),
+  });
+}
+
+/**
+ * Explains why an id is not installed, naming the manifests that were
+ * rejected or ignored for it. "Not found" without a reason is exactly the
+ * silent skip E4 forbids.
+ */
+export function explainMissing(context: ExtensionContextV1, extensionId: string): string {
+  const rejected = context.discovery.rejected.filter(
+    (entry) =>
+      entry.directoryName === extensionId || entry.manifestPath.includes(`/${extensionId}/`),
+  );
+  if (rejected.length > 0) {
+    const reasons = rejected
+      .flatMap((entry) => entry.issues.map((issue) => `${issue.field}: ${issue.message}`))
+      .join("; ");
+    return `extension "${extensionId}" has a manifest but it was rejected — ${reasons}`;
+  }
+  const ignored = context.discovery.ignored.filter((entry) =>
+    entry.manifestPath.includes(`/${extensionId}/`),
+  );
+  if (ignored.length > 0) {
+    const reasons = ignored.map((entry) => `${entry.reason}: ${entry.detail}`).join("; ");
+    return `extension "${extensionId}" was found but not loaded — ${reasons}`;
+  }
+  const roots = context.discovery.rootsScanned
+    .map((entry) => `${entry.root}${entry.exists ? "" : " (does not exist)"}`)
+    .join(", ");
+  return (
+    `no extension "${extensionId}" is installed; searched: ${roots}. ` +
+    `Install one with: untangle extensions add --from <path-or-url>`
+  );
+}

package/src/commands/extensions/enable.ts

@@ -0,0 +1,237 @@
+/**
+ * `untangle extensions enable <id>` / `disable <id>`
+ *
+ * These exist because the runtime's license gate prints them. When a gate is
+ * unacknowledged the runtime hands back the exact command that would grant
+ * the acknowledgment (extensions.md §9.5), and a printed command that does
+ * not exist is worse than no hint at all.
+ *
+ * `enable` records the opt-in and, with the acknowledgment flags, the
+ * personal license declaration. It starts nothing: no process, no pull, no
+ * container (X1). `disable` reverses the opt-in and, with `--revoke-license`,
+ * the declaration (§9.3).
+ *
+ * The tool gate and the ruleset gate are separate. `--acknowledge-license`
+ * covers the tool ONLY; a restricted ruleset still needs its own
+ * `--acknowledge-ruleset=<id>`, which is repeatable.
+ */
+import {
+  buildAcknowledgment,
+  createNodeProcessRunner,
+  defaultProcessLimits,
+} from "@untangle-code/extension-runtime";
+
+import { boolFlag, listFlag, type ParsedArgs } from "../../cli/args.js";
+import { EXIT, OperationalError, UsageError } from "../../cli/exit.js";
+import { line, note, type Io } from "../../cli/io.js";
+
+import { createContainerCli } from "./container.js";
+import { explainMissing, findExtension, gateFor, loadExtensionContext } from "./context.js";
+import type { ExtensionEnvironmentV1 } from "./environment.js";
+import { composeFilePath } from "./provision.js";
+import { emitJson } from "./render.js";
+import {
+  revokeAcknowledgments,
+  saveAcknowledgments,
+  saveCliState,
+  upsertAcknowledgment,
+} from "./state.js";
+
+export async function runEnable(
+  environment: ExtensionEnvironmentV1,
+  args: ParsedArgs,
+  io: Io,
+  format: "text" | "json",
+): Promise<number> {
+  const extensionId = args.positionals[1];
+  if (extensionId === undefined) {
+    throw new UsageError(
+      "`untangle extensions enable` 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>",
+    );
+  }
+
+  let acknowledgments = context.acknowledgments;
+  const acknowledgedNow: string[] = [];
+  if (boolFlag(args, "acknowledge-license")) {
+    acknowledgments = upsertAcknowledgment(
+      acknowledgments,
+      buildAcknowledgment({
+        manifest: extension.manifest,
+        acknowledgedAt: environment.clock.nowIso(),
+        acknowledgedBy: environment.userName,
+      }),
+    );
+    acknowledgedNow.push(`tool:${extensionId}`);
+  }
+  for (const ruleset of listFlag(args, "acknowledge-ruleset")) {
+    acknowledgments = upsertAcknowledgment(
+      acknowledgments,
+      buildAcknowledgment({
+        manifest: extension.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 enabled = context.state.enabled.includes(extensionId)
+    ? context.state.enabled
+    : [...context.state.enabled, extensionId];
+  const statePath = await saveCliState(environment.fs, environment.userDataDir, {
+    ...context.state,
+    enabled,
+  });
+
+  const gate = gateFor({ ...context, acknowledgments }, extension);
+
+  if (format === "json") {
+    emitJson(io, {
+      command: "extensions enable",
+      extensionId,
+      enabled: true,
+      started: false,
+      stateFile: statePath,
+      acknowledgedNow,
+      acknowledgmentFile,
+      licenseGate: {
+        allowed: gate.allowed,
+        tool: { status: gate.tool.status, reason: gate.tool.reason },
+        rulesets: gate.rulesets.map((entry) => ({
+          ruleset: entry.ruleset,
+          status: entry.status,
+          reason: entry.reason,
+        })),
+        acknowledgeCommands: gate.acknowledgeCommands,
+      },
+    });
+  } else {
+    line(io, `enabled "${extensionId}" — nothing was started (X1).`);
+    line(io, `  state       ${statePath}`);
+    line(io, `  license     ${gate.tool.status} — ${gate.tool.reason}`);
+    for (const entry of gate.rulesets) {
+      line(io, `  ruleset     ${entry.ruleset}: ${entry.status} — ${entry.reason}`);
+    }
+  }
+
+  if (!gate.allowed) {
+    note(io, "The license gate is still open; run:");
+    for (const command of gate.acknowledgeCommands) {
+      note(io, `  ${command}`);
+    }
+    return EXIT.environment;
+  }
+  return EXIT.ok;
+}
+
+export async function runDisable(
+  environment: ExtensionEnvironmentV1,
+  args: ParsedArgs,
+  io: Io,
+  format: "text" | "json",
+): Promise<number> {
+  const extensionId = args.positionals[1];
+  if (extensionId === undefined) {
+    throw new UsageError(
+      "`untangle extensions disable` needs an extension id.",
+      "Run `untangle extensions list` to see the installed ids.",
+    );
+  }
+  // Die Flag-Pruefung steht VOR jeder Zustandsaenderung. Zuvor lag sie danach:
+  // ein Aufruf, den die CLI im selben Atemzug als Aufruffehler zurueckwies,
+  // hatte die Extension bereits deaktiviert. Ein abgelehnter Befehl darf nichts
+  // getan haben.
+  const removeContainer = boolFlag(args, "remove-container");
+  const removeVolumes = boolFlag(args, "remove-volumes");
+  if (removeVolumes && !removeContainer) {
+    throw new UsageError(
+      "--remove-volumes only applies together with --remove-container.",
+      `Run untangle extensions disable ${extensionId} --remove-container --remove-volumes`,
+    );
+  }
+
+  const context = await loadExtensionContext(environment);
+  const statePath = await saveCliState(environment.fs, environment.userDataDir, {
+    ...context.state,
+    enabled: context.state.enabled.filter((id) => id !== extensionId),
+  });
+  // `--remove-container` fasst NUR den eigenen Container an; die Besitzprobe
+  // liegt im Adapter und laesst einen fremden gleichen Namens unberuehrt.
+  // Volumes bleiben ohne die zweite, ausdrueckliche Anweisung erhalten: ein
+  // geloeschtes Volume ist die einzige hier moegliche Handlung, die Arbeit
+  // vernichtet, die niemand wiederherstellen kann.
+  let containerDetail: string | undefined;
+  if (removeContainer) {
+    const installed = findExtension(context, extensionId);
+    const manifest = installed?.manifest;
+    if (manifest?.container === undefined) {
+      containerDetail = `"${extensionId}" declares no container; nothing to remove`;
+    } else {
+      const containerCli = createContainerCli({
+        processRunner: createNodeProcessRunner(environment.clock),
+        limits: { ...defaultProcessLimits(), timeoutMs: 120_000 },
+        ...(environment.env["UNTANGLE_CONTAINER_CLI"] === undefined
+          ? {}
+          : { command: environment.env["UNTANGLE_CONTAINER_CLI"] }),
+      });
+      const down = await containerCli.down({
+        manifest,
+        composeFilePath: composeFilePath(environment.userDataDir, manifest.id),
+        removeVolumes,
+      });
+      containerDetail = down.detail;
+    }
+  }
+
+  let acknowledgmentFile: string | undefined;
+  const revoked = boolFlag(args, "revoke-license");
+  if (revoked) {
+    acknowledgmentFile = await saveAcknowledgments(
+      environment.fs,
+      environment.userDataDir,
+      revokeAcknowledgments(context.acknowledgments, extensionId, environment.clock.nowIso()),
+    );
+  }
+
+  if (format === "json") {
+    emitJson(io, {
+      command: "extensions disable",
+      extensionId,
+      enabled: false,
+      stateFile: statePath,
+      licenseAcknowledgment: revoked ? "revoked" : "kept",
+      acknowledgmentFile,
+      ...(containerDetail === undefined ? {} : { container: containerDetail }),
+    });
+  } else {
+    line(io, `disabled "${extensionId}".`);
+    line(
+      io,
+      revoked
+        ? `  license     acknowledgment revoked in ${String(acknowledgmentFile)}`
+        : "  license     acknowledgment kept (use --revoke-license to drop it)",
+    );
+    if (containerDetail !== undefined) {
+      line(io, `  container   ${containerDetail}`);
+    }
+  }
+  return EXIT.ok;
+}

package/src/commands/extensions/environment.ts

@@ -0,0 +1,218 @@
+/**
+ * Ports and locations the extension commands run against.
+ *
+ * Everything the commands touch arrives here as data or as a port: the file
+ * system, the clock, randomness, the search roots, the user data directory
+ * and — the load-bearing one — the PROJECT roots.
+ *
+ * ## Why project roots exist at all
+ *
+ * A manifest describes how to start a program. If Untangle read manifests
+ * from the working directory, `git clone` of a stranger's repository would be
+ * enough to put a tool definition in front of the runtime, and one
+ * `untangle extensions run` away from executing it. So project directories
+ * are a boundary, not a search path: `discoverExtensions` never scans them,
+ * and `loadExtensionFrom` refuses a path inside one unless the user types
+ * `--allow-project-local` in that very invocation.
+ *
+ * The same reasoning puts license acknowledgments in the user data directory
+ * (extensions.md §9.2): a `.untangle/` file can be committed, and a committed
+ * acknowledgment would inherit one person's declaration to a whole team.
+ */
+import { homedir, userInfo } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+
+import type { Clock, FileSystemPort, Random } from "@untangle-code/domain";
+import {
+  isInsideDirectory,
+  resolveExtensionRoots,
+  userDataDirectory,
+  type ExtensionPathEnvironmentV1,
+} from "@untangle-code/extension-runtime";
+import { NodeFileSystem } from "@untangle-code/scanner/node-fs";
+
+import { systemClock, systemRandom } from "../../cli/system.js";
+
+export interface ExtensionEnvironmentV1 {
+  fs: FileSystemPort;
+  clock: Clock;
+  random: Random;
+  /** Directory the user invoked the CLI from, canonicalized where possible. */
+  cwd: string;
+  /** Search roots for user-installed extensions; `roots[0]` is the install target. */
+  roots: string[];
+  /** OS-specific user data directory (holds the acknowledgment file). */
+  userDataDir: string;
+  /** Directories that MUST NOT be scanned for manifests. */
+  projectRoots: string[];
+  /** OS user name — an acknowledgment is a personal declaration. */
+  userName: string;
+  env: Readonly<Record<string, string | undefined>>;
+}
+
+export interface CreateExtensionEnvironmentOptions {
+  cwd: string;
+  env: Readonly<Record<string, string | undefined>>;
+  fs?: FileSystemPort;
+  clock?: Clock;
+  random?: Random;
+  homeDir?: string;
+  platform?: string;
+  userName?: string;
+}
+
+export async function createExtensionEnvironment(
+  options: CreateExtensionEnvironmentOptions,
+): Promise<ExtensionEnvironmentV1> {
+  const fs = options.fs ?? new NodeFileSystem();
+  const cwd = await canonicalize(fs, resolve(options.cwd));
+  const platform = options.platform ?? process.platform;
+  const pathEnvironment: ExtensionPathEnvironmentV1 = {
+    homeDir: options.homeDir ?? homeDirFrom(options.env, platform),
+    platform,
+    env: options.env,
+  };
+  return {
+    fs,
+    clock: options.clock ?? systemClock,
+    random: options.random ?? systemRandom,
+    cwd,
+    roots: await Promise.all(
+      resolveExtensionRoots(pathEnvironment).map((root) => canonicalize(fs, root)),
+    ),
+    userDataDir: userDataDirectory(pathEnvironment),
+    projectRoots: await discoverProjectRoots(fs, cwd, pathEnvironment.homeDir),
+    userName: options.userName ?? safeUserName(),
+    env: options.env,
+  };
+}
+
+/**
+ * Marker files that identify a directory as somebody's PROJECT rather than
+ * part of the user profile. `.git` is the decisive one — the threat this
+ * boundary exists for is a cloned repository — and the two Untangle markers
+ * cover a project that was shipped as an archive rather than a clone.
+ */
+const PROJECT_MARKERS = [".git", ".untangle.json", ".untangle"] as const;
+
+/**
+ * Determines which directories must be treated as project directories.
+ *
+ * Walks from `start` up to the filesystem root and collects every directory
+ * carrying a project marker; if at least one is found, `start` itself joins
+ * the list, because the working directory inside a project is part of that
+ * project.
+ *
+ * Two deliberate exclusions:
+ *
+ * - **The home directory is never a project root.** A dotfiles repository in
+ *   `$HOME` is ordinary, and treating `$HOME` as a project would put
+ *   `~/.untangle/extensions` inside a project directory — which would make the
+ *   user's own extension root unscannable the moment they ran the CLI from
+ *   their home directory. The boundary is meant to keep a stranger's
+ *   repository out, not to lock people out of their own profile.
+ * - **A directory with no marker anywhere above it yields no project roots at
+ *   all.** Without a marker there is no project to protect, and a bare
+ *   directory the user made themselves is theirs. The consequence is stated
+ *   openly: `add --from ./manifest.toml` in such a directory is NOT refused.
+ *   A cloned repository always carries `.git`, so the case the boundary exists
+ *   for is still covered.
+ */
+export async function discoverProjectRoots(
+  fs: FileSystemPort,
+  start: string,
+  homeDir?: string,
+): Promise<string[]> {
+  const home = homeDir === undefined ? undefined : resolve(homeDir);
+  const found: string[] = [];
+  let current = start;
+  for (;;) {
+    if (current !== home && (await hasProjectMarker(fs, current))) {
+      found.push(current);
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  if (found.length === 0) {
+    return [];
+  }
+  return found.includes(start) ? found : [start, ...found];
+}
+
+async function hasProjectMarker(fs: FileSystemPort, directory: string): Promise<boolean> {
+  for (const marker of PROJECT_MARKERS) {
+    if ((await fs.stat(join(directory, marker))) !== null) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** True when `candidate` lies inside any of `roots`. */
+export function isInsideAnyRoot(candidate: string, roots: readonly string[]): boolean {
+  return roots.some((root) => isInsideDirectory(candidate, root));
+}
+
+/** Resolves a user-supplied path against the working directory. */
+export function resolveUserPath(cwd: string, path: string): string {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+/**
+ * Canonical form of a path, with symlinks resolved.
+ *
+ * This is not cosmetic. `isProjectLocalManifest` and `isInsideDirectory`
+ * compare LEXICALLY and say so: they never resolve symlinks, and the caller is
+ * expected to hand them canonical paths. Skipping this step would leave the
+ * project boundary trivially escapable — a symlink, or on macOS merely the
+ * `/var` → `/private/var` alias, is enough to make a path inside a project
+ * compare as if it were outside one.
+ *
+ * A path that does not exist yet still gets canonicalized as far as it does
+ * exist: the deepest existing ancestor is resolved and the remaining segments
+ * are re-appended. Failing the whole command over a not-yet-created file would
+ * be worse than a partially canonical answer, and the ancestor is the part
+ * that decides containment.
+ */
+export async function canonicalize(fs: FileSystemPort, path: string): Promise<string> {
+  const tail: string[] = [];
+  let current = resolve(path);
+  for (;;) {
+    try {
+      const real = await fs.realPath(current);
+      return tail.length === 0 ? real : join(real, ...tail.reverse());
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) {
+        return resolve(path);
+      }
+      tail.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * The home directory as the COMMAND CONTEXT sees it.
+ *
+ * `os.homedir()` reads the process environment, not the environment handed to
+ * this command. Preferring the context keeps the extension root, the
+ * acknowledgment file and the state file inside whatever profile the caller
+ * declared — which is what makes these commands testable without writing into
+ * the real user profile.
+ */
+function homeDirFrom(env: Readonly<Record<string, string | undefined>>, platform: string): string {
+  const fromEnv = platform === "win32" ? env["USERPROFILE"] : env["HOME"];
+  return fromEnv !== undefined && fromEnv.trim() !== "" ? fromEnv : homedir();
+}
+
+function safeUserName(): string {
+  try {
+    return userInfo().username;
+  } catch {
+    return "unknown";
+  }
+}