@shortlink-org/portolan 0.3.0 → 0.4.0

package/scripts/host-plugins/fetch-argocd.mjs

@@ -0,0 +1,338 @@
+// fetch-argocd, run by the host: an Argo CD API on one side, a snapshot of
+// where the estate's services run committed to this repository on the other.
+//
+// portolan.0011 reads the names a service answers on and dials, from the
+// manifests and from the cluster, and nothing else; neither says which
+// revision of which repository stands in which cluster and namespace, under
+// which name. Only the thing that deploys knows that (portolan.0012). It is
+// not in any tree, so it cannot be an extractor's, and it is read over a
+// socket with a credential, so it is the host's (portolan.0008).
+//
+// The contract is the plugin's all the same: the snapshot is named, never
+// written, so the host writes it, it gets a manifest entry, is compared by
+// `gen:check` like any other generated file, and is removed when the step
+// stops naming it. Two files land in the step's out. `argocd.apps.json` is
+// a catalog fragment - the deployments, one per Application, nothing else.
+// `argocd.lock.json` is for the next run of this step: the server, the
+// applications and the fragment's digest, which is what lets an offline run
+// replay the committed snapshot and refuse one edited by hand.
+//
+// There is no pin. An Application has no immutable commit the way a module
+// or a repository has; the snapshot IS the fact, and it moves when a deploy
+// moves it. So an online run after a deploy changes the committed snapshot,
+// and that diff is the review worth having: what went where, in one pull
+// request. What is kept is what a deploy changes - the revision, the images,
+// the destination. What is not kept is what changes without one: health,
+// sync state, the time of the last operation. A page that said "healthy"
+// yesterday and was not regenerated since is a page that lies, and a build
+// that reads a clock is not reproducible (portolan.0010).
+//
+// In CI, or with PORTOLAN_OFFLINE=1, the step replays the committed
+// snapshot, checks it against its lock and emits an identical file list, so
+// a fork's pull request needs no token and Argo CD being down cannot turn
+// the tree red.
+//
+// No token in the manifest, ever: portolan.json is committed. The credential
+// comes from ARGOCD_AUTH_TOKEN, the variable the argocd CLI reads, and it
+// changes whether the fetch succeeds, never what the fetch says.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import optionsSchema from "./fetch-argocd.options.json" with { type: "json" };
+import { webRepo } from "./fetch-git.mjs";
+
+export const LOCK_NAME = "argocd.lock.json";
+export const FRAGMENT_NAME = "argocd.apps.json";
+export const TOKEN_ENV = "ARGOCD_AUTH_TOKEN";
+export const OFFLINE_ENV = "PORTOLAN_OFFLINE";
+
+/** The one call: every Application the token can list, narrowed by query. */
+export const LIST_PATH = "/api/v1/applications";
+
+/** The label that names an environment when the manifest does not say. */
+export const DEFAULT_ENVIRONMENT_LABEL = "env";
+
+/**
+ * The labels that name the service an Application deploys, when the
+ * manifest does not say: the Kubernetes recommended ones, the same
+ * fetch-k8s reads off a workload. An ApplicationSet that stamps them on
+ * every Application it makes is what lets a GitOps repository - where the
+ * path points at an overlay, not at the service - still place each
+ * Application on its service.
+ */
+export const DEFAULT_LABELS = { context: "app.kubernetes.io/part-of", service: "app.kubernetes.io/name" };
+
+/** How Argo CD names the cluster it runs in, and how the catalog does. */
+const IN_CLUSTER_SERVER = "https://kubernetes.default.svc";
+const IN_CLUSTER_NAME = "in-cluster";
+
+export function describe() {
+  return {
+    name: "fetch-argocd",
+    summary: "Reads the applications an Argo CD server manages into a snapshot of where each service runs - cluster, namespace, revision, images - with a lock beside it.",
+    category: "sources",
+    phases: ["extract"],
+    options: optionsSchema,
+  };
+}
+
+/**
+ * The step. Reads nothing out of the tree being described; its `cache` is
+ * repo-relative and everything else is in the options.
+ *
+ * The rules are fetch-bsr's: a failed fetch falls back to the committed
+ * snapshot with a warning, and a failed fetch with no snapshot is an ERROR,
+ * never a short file list, because the host deletes files a step stops
+ * naming.
+ *
+ * @param {{options?: object}} request
+ * @param {{env?: NodeJS.ProcessEnv, fetch?: typeof fetch}} [io]
+ */
+export async function run(request, { env = process.env, fetch: fetchFn = globalThis.fetch } = {}) {
+  const options = request.options ?? {};
+  const server = String(options.server ?? "").trim();
+  if (!server) throw new Error("no server: name the Argo CD API server in the manifest");
+  if (!options.cache) {
+    throw new Error("no cache directory: set `cache` to the same path as the step's `out`, so an offline run can replay what the last online one wrote");
+  }
+
+  const out = new Builder();
+  if (offline(env)) {
+    emitCached(out, options.cache, "offline");
+    return out.response();
+  }
+
+  let deployments;
+  try {
+    deployments = await live(server, options, env, fetchFn);
+  } catch (cause) {
+    try {
+      emitCached(out, options.cache, cause.message);
+    } catch (cacheCause) {
+      throw new Error(`${server} could not be read (${cause.message}) and there is no usable snapshot in the tree (${cacheCause.message})`);
+    }
+    return out.response();
+  }
+  emitFetched(out, server, deployments);
+  return out.response();
+}
+
+export function offline(env = process.env) {
+  if (String(env[OFFLINE_ENV] ?? "").trim()) return true;
+  return !["", "0", "false"].includes(String(env.CI ?? "").trim().toLowerCase());
+}
+
+/** A credential, or "". The argocd CLI reads the same variable. */
+export function token(env = process.env) {
+  return String(env[TOKEN_ENV] ?? "").trim();
+}
+
+/** The server as a base URL: https unless the manifest says otherwise. */
+export function baseUrl(server) {
+  const value = String(server ?? "").trim().replace(/\/+$/, "");
+  return /^https?:\/\//.test(value) ? value : `https://${value}`;
+}
+
+/**
+ * One Application, reduced to what a deploy changes.
+ *
+ * Everything the wire knows is looked at here and nowhere else. What comes
+ * out is names and revisions: no parameter, no value, no status that moves
+ * without a commit. A Helm parameter or a plugin env is a value and stays
+ * behind for the reason portolan.0011 gives.
+ *
+ * @param {object} app an item of the list answer
+ * @param {string} base the server's base URL, for the link
+ * @param {string} environmentLabel
+ * @param {{context?: string, service?: string}} serviceLabels
+ */
+export function deploymentOf(app, base, environmentLabel = DEFAULT_ENVIRONMENT_LABEL, serviceLabels = DEFAULT_LABELS) {
+  const metadata = app?.metadata ?? {};
+  const spec = app?.spec ?? {};
+  const status = app?.status ?? {};
+  const name = String(metadata.name ?? "").trim();
+  if (!name) throw new Error("an application has no name");
+  const appNamespace = String(metadata.namespace ?? "argocd").trim() || "argocd";
+
+  // A multi-source application deploys the source that carries a path (its
+  // manifests) and reads values out of the others; the path is the one
+  // whose revision a reader wants to follow.
+  const sources = Array.isArray(spec.sources) && spec.sources.length ? spec.sources : spec.source ? [spec.source] : [];
+  const sourceIndex = Math.max(0, sources.findIndex((source) => String(source?.path ?? "").trim()));
+  const source = sources[sourceIndex] ?? {};
+  const revisions = Array.isArray(status.sync?.revisions) ? status.sync.revisions : [];
+  const revision = String(revisions[sourceIndex] ?? status.sync?.revision ?? "").trim();
+
+  const destination = spec.destination ?? {};
+  const server = String(destination.server ?? "").trim();
+  const cluster = String(destination.name ?? "").trim() || (server === IN_CLUSTER_SERVER ? IN_CLUSTER_NAME : server);
+  const labels = metadata.labels ?? {};
+  const environment = String(labels[environmentLabel] ?? "").trim() || cluster;
+
+  const record = {
+    id: `${appNamespace}/${name}`,
+    name,
+    project: String(spec.project ?? "default").trim() || "default",
+    environment,
+    cluster,
+    namespace: String(destination.namespace ?? "").trim(),
+    repo: webRepo(source.repoURL ?? ""),
+    path: String(source.path ?? "").trim().replace(/^\.?\/+|\/+$/g, ""),
+    targetRevision: String(source.targetRevision ?? "").trim(),
+    revision,
+    tool: toolOf(status.sourceType ?? status.sourceTypes?.[sourceIndex], ...sources),
+    url: `${base}/applications/${encodeURIComponent(appNamespace)}/${encodeURIComponent(name)}`,
+    // Who said so: the deployer. A row extract-argocd reads out of the
+    // GitOps tree says "manifest", and the merge lays the two over each
+    // other (portolan.0013).
+    basis: "api",
+  };
+  // The service, when the labels say: `<context>.<service>`, the id a
+  // service carries in the catalog. Both labels or nothing - a name without
+  // a context is a word, and the catalog does not place words.
+  const contextSlug = String(labels[serviceLabels.context ?? DEFAULT_LABELS.context] ?? "").trim();
+  const serviceSlug = String(labels[serviceLabels.service ?? DEFAULT_LABELS.service] ?? "").trim();
+  if (contextSlug && serviceSlug) record.service = `${contextSlug}.${serviceSlug}`;
+  const chart = String(source.chart ?? "").trim();
+  if (chart) record.chart = chart;
+  const images = [...new Set((status.summary?.images ?? []).map((image) => String(image).trim()).filter(Boolean))].sort();
+  if (images.length) record.images = images;
+  return record;
+}
+
+/**
+ * `Helm`, `Kustomize`, `Directory`, `Plugin` as Argo CD says it, lowercased;
+ * inferred from the sources when the status has not said yet. A multi-source
+ * application says it on the chart, not on the values it reads beside it.
+ */
+export function toolOf(sourceType, ...sources) {
+  const said = String(sourceType ?? "").trim().toLowerCase();
+  if (said) return said;
+  for (const source of sources) {
+    if (source?.chart || source?.helm) return "helm";
+    if (source?.kustomize) return "kustomize";
+    if (source?.plugin) return "plugin";
+    if (source?.directory) return "directory";
+  }
+  return "";
+}
+
+/** The fragment: a catalog holding deployments and nothing else. */
+export function fragment(deployments) {
+  const sorted = [...deployments].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return `${JSON.stringify({ contexts: [], defs: {}, flows: [], adrs: [], deployments: sorted }, null, 2)}\n`;
+}
+
+/** The lock, written the way every generated file here is written. */
+export function encodeLock(entry) {
+  return `${JSON.stringify({ server: entry.server, applications: [...entry.applications].sort(), sha256: entry.sha256 }, null, 2)}\n`;
+}
+
+function digestOf(contents) {
+  return createHash("sha256").update(contents).digest("hex");
+}
+
+async function live(server, options, env, fetchFn) {
+  const base = baseUrl(server);
+  const query = new URLSearchParams();
+  for (const project of Array.isArray(options.projects) ? options.projects : []) query.append("projects", String(project));
+  if (options.selector) query.set("selector", String(options.selector));
+  const url = `${base}${LIST_PATH}${query.size ? `?${query}` : ""}`;
+
+  const headers = { Accept: "application/json" };
+  const credential = token(env);
+  if (credential) headers.Authorization = `Bearer ${credential}`;
+  let response;
+  try {
+    // A timeout rather than none: a step that hangs holds up the whole run.
+    response = await fetchFn(url, { method: "GET", headers, signal: AbortSignal.timeout(60_000) });
+  } catch (cause) {
+    throw new Error(`${LIST_PATH}: ${cause.cause?.message ?? cause.message}`);
+  }
+  const raw = await response.text();
+  if (!response.ok) throw new Error(`${LIST_PATH}: ${apiError(response.status, raw)}`);
+  let answer;
+  try {
+    answer = JSON.parse(raw);
+  } catch {
+    throw new Error(`${LIST_PATH}: the answer is not JSON`);
+  }
+  const items = Array.isArray(answer?.items) ? answer.items : [];
+  if (items.length === 0) throw new Error(`${server} lists no applications; check the projects and selector in the manifest, and what the token may see`);
+  const label = String(options.environmentLabel ?? "").trim() || DEFAULT_ENVIRONMENT_LABEL;
+  const serviceLabels = { ...DEFAULT_LABELS, ...(options.labels ?? {}) };
+  return items.map((item) => deploymentOf(item, base, label, serviceLabels));
+}
+
+/** The error body Argo CD sends, or the status when the body is not one. */
+function apiError(status, raw) {
+  try {
+    const wire = JSON.parse(raw);
+    if (wire?.message) return wire.message;
+    if (wire?.error) return wire.error;
+  } catch {
+    // Not an error body.
+  }
+  return `http ${status}`;
+}
+
+function emitFetched(out, server, deployments) {
+  const contents = fragment(deployments);
+  out.file(FRAGMENT_NAME, contents);
+  out.file(LOCK_NAME, encodeLock({ server, applications: deployments.map((d) => d.id), sha256: digestOf(contents) }));
+}
+
+function emitCached(out, cache, why) {
+  const held = replay(cache);
+  out.file(FRAGMENT_NAME, held.contents);
+  out.file(LOCK_NAME, encodeLock(held.lock));
+  out.warn(held.lock.server, `not fetched (${why}); the snapshot committed in this repository is used unchanged`);
+}
+
+function replay(dir) {
+  const lockPath = join(dir, LOCK_NAME);
+  let raw;
+  try {
+    raw = readFileSync(lockPath, "utf8");
+  } catch (cause) {
+    if (cause.code === "ENOENT") throw new Error(`no ${LOCK_NAME} in ${dir.split("\\").join("/")}`);
+    throw cause;
+  }
+  let lock;
+  try {
+    lock = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`${lockPath}: ${cause.message}`);
+  }
+  let contents;
+  try {
+    contents = readFileSync(join(dir, FRAGMENT_NAME), "utf8");
+  } catch (cause) {
+    if (cause.code === "ENOENT") throw new Error(`${FRAGMENT_NAME} is in the lock but not on disk`);
+    throw cause;
+  }
+  if (digestOf(contents) !== lock.sha256) throw new Error(`${FRAGMENT_NAME} does not match its digest; the snapshot was edited by hand`);
+  return {
+    lock: { server: String(lock.server ?? ""), applications: Array.isArray(lock.applications) ? lock.applications : [], sha256: String(lock.sha256 ?? "") },
+    contents,
+  };
+}
+
+class Builder {
+  files = [];
+  warnings = [];
+
+  file(name, contents) {
+    this.files.push({ name, contents });
+  }
+
+  warn(ref, message) {
+    this.warnings.push({ severity: "warning", message, ref });
+  }
+
+  response() {
+    return { files: this.files, warnings: this.warnings };
+  }
+}

package/scripts/host-plugins/fetch-argocd.options.json

@@ -0,0 +1,49 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["server", "cache"],
+  "properties": {
+    "server": {
+      "type": "string",
+      "description": "The Argo CD API server: a host, or a URL when it is not https. The token comes from ARGOCD_AUTH_TOKEN, never from here.",
+      "examples": ["argocd.example.com"]
+    },
+    "projects": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Argo CD projects to read applications from. Left out, every application the token can list.",
+      "examples": [["shop", "platform"]]
+    },
+    "selector": {
+      "type": "string",
+      "description": "A label selector narrowing the applications, as `argocd app list -l` takes one.",
+      "examples": ["team=shop"]
+    },
+    "environmentLabel": {
+      "type": "string",
+      "default": "env",
+      "description": "The application label that names the environment. An application without it is placed by the cluster it deploys to."
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Which application labels name the service it deploys. The defaults are the Kubernetes recommended labels, the same ones fetch-k8s reads off a workload; an estate that labels differently names its own keys here. An application without them is placed by the repository and directory it deploys from.",
+      "properties": {
+        "context": {
+          "type": "string",
+          "description": "The label whose value is the bounded context's slug.",
+          "default": "app.kubernetes.io/part-of"
+        },
+        "service": {
+          "type": "string",
+          "description": "The label whose value is the service's slug.",
+          "default": "app.kubernetes.io/name"
+        }
+      }
+    },
+    "cache": {
+      "type": "string",
+      "description": "Where the last run's snapshot was written, repo-relative: the same path as the step's out. An offline run replays what is there and checks it against the lock beside it."
+    }
+  }
+}

package/scripts/host-plugins/fetch-argocd.test.mjs

@@ -0,0 +1,274 @@
+// The fetcher, against a recorded Argo CD. NEVER against a live one: the
+// whole point of this plugin's design is that the build does not depend on
+// a control plane being up, or on anyone holding a token.
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { runPlugin } from "../plugin-host.mjs";
+import { FRAGMENT_NAME, LIST_PATH, LOCK_NAME, OFFLINE_ENV, TOKEN_ENV, baseUrl, deploymentOf, run, toolOf } from "./fetch-argocd.mjs";
+
+const REVISION = "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678";
+
+/** Two applications the way the API lists them, with everything a page must not keep. */
+const CART = {
+  metadata: { name: "shop-cart", namespace: "argocd", labels: { env: "prod", team: "shop", "app.kubernetes.io/part-of": "shop", "app.kubernetes.io/name": "cart" } },
+  spec: {
+    project: "shop",
+    source: { repoURL: "https://github.com/shortlink-org/portolan.git", path: "./examples/shop/cart/deploy/k8s/", targetRevision: "main", kustomize: { namePrefix: "prod-" } },
+    destination: { server: "https://kubernetes.default.svc", namespace: "shop" },
+  },
+  status: {
+    sync: { status: "Synced", revision: REVISION },
+    health: { status: "Healthy" },
+    summary: { images: ["ghcr.io/shortlink-org/cart:1.4.2", "ghcr.io/shortlink-org/cart:1.4.2", "redis:7"] },
+    sourceType: "Kustomize",
+    operationState: { finishedAt: "2026-09-11T10:00:00Z" },
+  },
+};
+const PRICING = {
+  metadata: { name: "shop-pricing", namespace: "argocd" },
+  spec: {
+    project: "shop",
+    sources: [
+      { repoURL: "https://charts.example.com", chart: "service", targetRevision: "2.1.0", helm: { valueFiles: ["$values/pricing.yaml"], parameters: [{ name: "db.password", value: "hunter2" }] } },
+      { repoURL: "git@github.com:shortlink-org/portolan.git", path: "examples/shop/pricing/deploy", targetRevision: "HEAD", ref: "values" },
+    ],
+    destination: { name: "eu-west-1", namespace: "shop" },
+  },
+  status: { sync: { revisions: ["2.1.0", REVISION] }, summary: { images: ["ghcr.io/shortlink-org/pricing:0.9.0"] } },
+};
+
+const cleanups = [];
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) await cleanup();
+});
+
+/** Serves the one call the plugin makes, from recorded shapes. */
+async function argocd(handle = null) {
+  const seen = [];
+  const urls = [];
+  const server = createServer((request, response) => {
+    seen.push(request.headers.authorization ?? "");
+    urls.push(request.url);
+    if (handle) return handle(request, response);
+    response.setHeader("Content-Type", "application/json");
+    if (request.url.startsWith(LIST_PATH)) {
+      response.end(JSON.stringify({ metadata: { resourceVersion: "12345" }, items: [PRICING, CART] }));
+    } else {
+      response.statusCode = 404;
+      response.end(JSON.stringify({ error: "not found", code: 5, message: "no such route" }));
+    }
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  cleanups.push(() => new Promise((resolve) => server.close(resolve)));
+  return { url: `http://127.0.0.1:${server.address().port}`, seen, urls };
+}
+
+function cache() {
+  const dir = mkdtempSync(join(tmpdir(), "portolan-fetch-argocd-"));
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+// A test must never inherit a real credential or a real offline setting.
+const isolated = { [TOKEN_ENV]: "", [OFFLINE_ENV]: "", CI: "" };
+const options = (server, cacheDir, extra = {}) => ({ server, cache: cacheDir, ...extra });
+const fetch = (opts, env = {}) => run({ options: opts }, { env: { ...isolated, ...env } });
+const names = (response) => response.files.map((file) => file.name).sort();
+const contentsOf = (response, name) => response.files.find((file) => file.name === name)?.contents ?? "";
+const write = (dir, response) => {
+  for (const file of response.files) {
+    mkdirSync(dirname(join(dir, file.name)), { recursive: true });
+    writeFileSync(join(dir, file.name), file.contents);
+  }
+};
+
+describe("fetch-argocd", () => {
+  it("writes the snapshot and a lock beside it, sorted, keeping what a deploy changes and nothing else", async () => {
+    const server = await argocd();
+    const response = await fetch(options(server.url, cache(), { projects: ["shop"] }));
+    expect(names(response)).toEqual([FRAGMENT_NAME, LOCK_NAME]);
+    expect(server.urls).toEqual([`${LIST_PATH}?projects=shop`]);
+
+    const catalog = JSON.parse(contentsOf(response, FRAGMENT_NAME));
+    expect(catalog).toMatchObject({ contexts: [], defs: {}, flows: [], adrs: [] });
+    expect(catalog.deployments.map((d) => d.id)).toEqual(["argocd/shop-cart", "argocd/shop-pricing"]);
+    expect(catalog.deployments[0]).toEqual({
+      id: "argocd/shop-cart",
+      name: "shop-cart",
+      project: "shop",
+      environment: "prod",
+      cluster: "in-cluster",
+      namespace: "shop",
+      repo: "github.com/shortlink-org/portolan",
+      path: "examples/shop/cart/deploy/k8s",
+      targetRevision: "main",
+      revision: REVISION,
+      tool: "kustomize",
+      url: `${server.url}/applications/argocd/shop-cart`,
+      basis: "api",
+      service: "shop.cart",
+      images: ["ghcr.io/shortlink-org/cart:1.4.2", "redis:7"],
+    });
+    // No labels, no service: the catalog places it by repository and path.
+    expect(catalog.deployments[1].service).toBeUndefined();
+    // A multi-source application follows the source that carries the
+    // manifests, and its cluster names the environment when no label does.
+    expect(catalog.deployments[1]).toMatchObject({
+      environment: "eu-west-1",
+      cluster: "eu-west-1",
+      repo: "github.com/shortlink-org/portolan",
+      path: "examples/shop/pricing/deploy",
+      targetRevision: "HEAD",
+      revision: REVISION,
+      tool: "helm",
+    });
+    expect(catalog.deployments[1].chart).toBeUndefined();
+    // Nothing that moves without a commit, and no value, reaches the tree.
+    const text = contentsOf(response, FRAGMENT_NAME);
+    for (const leaked of ["Synced", "Healthy", "finishedAt", "hunter2", "namePrefix", "resourceVersion"]) expect(text).not.toContain(leaked);
+
+    const lock = JSON.parse(contentsOf(response, LOCK_NAME));
+    expect(lock).toEqual({
+      server: server.url,
+      applications: ["argocd/shop-cart", "argocd/shop-pricing"],
+      sha256: createHash("sha256").update(text).digest("hex"),
+    });
+    expect(response.warnings).toEqual([]);
+  });
+
+  it("asks with the projects, the selector and the token, and lets none of them reach the output", async () => {
+    const server = await argocd();
+    const anonymous = await fetch(options(server.url, cache()));
+    const authorised = await fetch(options(server.url, cache(), { projects: ["shop", "platform"], selector: "team=shop" }), { [TOKEN_ENV]: "a-real-looking-secret" });
+    expect(server.urls).toEqual([LIST_PATH, `${LIST_PATH}?projects=shop&projects=platform&selector=team%3Dshop`]);
+    expect(server.seen).toEqual(["", "Bearer a-real-looking-secret"]);
+    for (const file of anonymous.files) {
+      expect(contentsOf(authorised, file.name)).toBe(file.contents);
+      expect(contentsOf(authorised, file.name)).not.toContain("a-real-looking-secret");
+    }
+  });
+
+  it("replays the committed snapshot offline, byte for byte, and in CI", async () => {
+    const server = await argocd();
+    const cacheDir = cache();
+    const online = await fetch(options(server.url, cacheDir));
+    write(cacheDir, online);
+
+    const replayed = await fetch(options(server.url, cacheDir), { [OFFLINE_ENV]: "1" });
+    expect(names(replayed)).toEqual(names(online));
+    for (const file of online.files) expect(contentsOf(replayed, file.name)).toBe(file.contents);
+    expect(replayed.warnings).toHaveLength(1);
+    expect(replayed.warnings[0].message).toContain("not fetched (offline)");
+
+    const inCi = await fetch(options(server.url, cacheDir), { CI: "true" });
+    expect(names(inCi)).toEqual(names(online));
+    expect(server.urls).toHaveLength(1);
+  });
+
+  it("names a snapshot edited by hand", async () => {
+    const server = await argocd();
+    const cacheDir = cache();
+    write(cacheDir, await fetch(options(server.url, cacheDir)));
+    writeFileSync(join(cacheDir, FRAGMENT_NAME), '{ "deployments": [] }\n');
+    await expect(fetch(options(server.url, cacheDir), { [OFFLINE_ENV]: "1" })).rejects.toThrow(/edited by hand/);
+  });
+
+  it("fails rather than emitting nothing when there is no snapshot to fall back to", async () => {
+    await expect(fetch(options("http://127.0.0.1:1", cache()), { [OFFLINE_ENV]: "1" })).rejects.toThrow(/no argocd\.lock\.json/);
+
+    const broken = await argocd((request, response) => {
+      response.statusCode = 500;
+      response.end(JSON.stringify({ error: "the control plane is having a day", code: 13 }));
+    });
+    await expect(fetch(options(broken.url, cache()))).rejects.toThrow(/the control plane is having a day.*no usable snapshot/);
+
+    const empty = await argocd((request, response) => {
+      response.end(JSON.stringify({ items: null }));
+    });
+    await expect(fetch(options(empty.url, cache()))).rejects.toThrow(/lists no applications/);
+  });
+
+  it("falls back to the committed snapshot when the server fails", async () => {
+    const server = await argocd();
+    const cacheDir = cache();
+    const online = await fetch(options(server.url, cacheDir));
+    write(cacheDir, online);
+
+    const broken = await argocd((request, response) => {
+      response.statusCode = 502;
+      response.end();
+    });
+    const fallback = await fetch(options(broken.url, cacheDir));
+    expect(names(fallback)).toEqual(names(online));
+    expect(fallback.warnings[0].message).toMatch(/not fetched \(.*http 502\)/);
+  });
+
+  it("refuses a missing server and a missing cache", async () => {
+    await expect(fetch(options("", cache()))).rejects.toThrow(/server/);
+    await expect(fetch(options("argocd.example.com", ""))).rejects.toThrow(/cache/);
+  });
+
+  it("runs through the host like any plugin", async () => {
+    const server = await argocd();
+    const cacheDir = cache();
+    write(cacheDir, await fetch(options(server.url, cacheDir)));
+    const saved = { CI: process.env.CI, [OFFLINE_ENV]: process.env[OFFLINE_ENV] };
+    process.env.CI = "";
+    process.env[OFFLINE_ENV] = "1";
+    try {
+      const result = await runPlugin({ name: "argocd", host: "fetch-argocd" }, { portolanVersion: "0.1.0", options: options(server.url, cacheDir) });
+      expect(result.files).toHaveLength(2);
+      expect(result.warnings).toEqual([`${server.url}: not fetched (offline); the snapshot committed in this repository is used unchanged`]);
+      const described = await runPlugin({ name: "argocd", host: "fetch-argocd" }, { portolanVersion: "0.1.0", kind: "describe" });
+      expect(described.describe).toMatchObject({ name: "fetch-argocd", phases: ["extract"] });
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+});
+
+describe("one application", () => {
+  it("spells the server as a URL, https unless told otherwise", () => {
+    expect(baseUrl("argocd.example.com")).toBe("https://argocd.example.com");
+    expect(baseUrl("https://argocd.example.com/")).toBe("https://argocd.example.com");
+    expect(baseUrl("http://127.0.0.1:8080")).toBe("http://127.0.0.1:8080");
+  });
+
+  it("reads the environment off the label the manifest names, else off the cluster", () => {
+    const base = "https://argocd.example.com";
+    expect(deploymentOf(CART, base, "env").environment).toBe("prod");
+    expect(deploymentOf(CART, base, "tier").environment).toBe("in-cluster");
+    expect(deploymentOf({ ...CART, spec: { ...CART.spec, destination: { server: "https://1.2.3.4", namespace: "x" } } }, base, "tier").environment).toBe("https://1.2.3.4");
+  });
+
+  it("infers the tool from the source until the status has said", () => {
+    expect(toolOf("Kustomize", {})).toBe("kustomize");
+    expect(toolOf("", { chart: "x" })).toBe("helm");
+    expect(toolOf("", { helm: {} })).toBe("helm");
+    expect(toolOf("", { kustomize: {} })).toBe("kustomize");
+    expect(toolOf("", { plugin: {} })).toBe("plugin");
+    expect(toolOf("", { directory: {} })).toBe("directory");
+    expect(toolOf("", {})).toBe("");
+  });
+
+  it("places by the labels the manifest names, and by nothing when only one of the two is there", () => {
+    const base = "https://argocd.example.com";
+    const labelled = (labels) => ({ ...CART, metadata: { ...CART.metadata, labels } });
+    expect(deploymentOf(labelled({ team: "shop", component: "cart" }), base, "env", { context: "team", service: "component" }).service).toBe("shop.cart");
+    expect(deploymentOf(labelled({ "app.kubernetes.io/name": "cart" }), base).service).toBeUndefined();
+    expect(deploymentOf(labelled({}), base).service).toBeUndefined();
+  });
+
+  it("refuses an application without a name, and defaults the namespace and project", () => {
+    expect(() => deploymentOf({ metadata: {} }, "https://a")).toThrow(/no name/);
+    expect(deploymentOf({ metadata: { name: "x" } }, "https://a")).toMatchObject({ id: "argocd/x", project: "default", tool: "", url: "https://a/applications/argocd/x" });
+  });
+});

package/scripts/host-plugins/fetch-bsr.mjs

@@ -46,6 +46,7 @@ export function describe() {
   return {
     name: "fetch-bsr",
     summary: "Fetches pinned modules from a Buf Schema Registry into the tree, with a lock beside each, so the proto extractor can read a published contract.",
+    category: "sources",
     phases: ["extract"],
     options: optionsSchema,
   };