@varde-flyt/vfac 0.4.0 → 0.6.0

package/README.md

@@ -26,8 +26,18 @@ vfac guide
 vfac whoami
 ```
 
-`doctor` checks the endpoint, the API, your credential and what that credential
-reaches, in that order, and reports the first thing that is actually wrong.
+`doctor` checks the endpoint, the API, whether this client is new enough for the
+platform it is pointed at, your credential and what that credential reaches, in
+that order, and reports the first thing that is actually wrong. A platform
+declares the oldest client it supports; below that, `doctor` fails and says so
+before sending your credential anywhere.
+
+`doctor` is also the one command that contacts a host other than your own
+platform: it asks `registry.npmjs.org` whether a newer `vfac` has been published.
+That request is anonymous — no credential, no session, no endpoint, nothing
+identifying you — and it can never change the exit code, so an unreachable or
+blocked registry is reported and otherwise ignored. Set `VFAC_NO_UPDATE_CHECK` to
+any value to skip it entirely; nothing else in this tool makes that request.
 
 `vfac guide` is the documentation. It is served by the platform you are pointed
 at rather than bundled here, so it always describes the deployment in front of
@@ -91,6 +101,37 @@ service, exactly as it resolves the service's own credentials. So there is no
 second copy to rotate, and no value for you to read — `vfac get product-instance`
 shows one as `[secret]`. `vfac guide` is authoritative.
 
+## Settings that go together
+
+A Product may declare that a group of settings is all-or-nothing: leave every one
+of them alone, or supply all of them. A provider connection is the usual shape —
+an address without its credential is worse than neither, because the service
+starts and then fails on its first call.
+
+```yaml
+spec:
+  configuration:
+    upstreamUrl: https://upstream.example.com
+    upstreamAccount: acct-9
+    # and the credential, beside the apply rather than in the file:
+    #   vfac apply -f resource.yaml --secret upstreamToken=env:UPSTREAM_TOKEN
+```
+
+Supply the whole group or none of it. A partial answer is refused, and the
+refusal names the setting that is missing and the one that made it necessary.
+
+`vfac manifest init` lists each group and seeds nothing for it — half a group is
+exactly the state that gets refused, so a placeholder would only produce a file
+that fails `vfac validate`.
+
+**`validate` and `plan` answer different questions here, and the difference is
+not a bug.** A manifest may never carry a secret, so `vfac validate` — which
+reads a file with no Project and no credential — cannot tell whether the
+credential in a group is configured, and does not refuse a document over it.
+`vfac plan` knows what the apply would carry and what the resource already holds,
+so it is where a missing member is reported. A credential the resource already
+holds does not have to be sent again to change one of its siblings.
+
 ## Connecting to another resource
 
 A Product may declare a **service dependency** — a connection to another service

package/dist/vfac.mjs

@@ -7670,7 +7670,9 @@ async function probeMachineApi(args) {
   }
   const authentication = payload["authentication"];
   const contextGate = typeof authentication === "object" && authentication !== null && typeof authentication["contextGate"] === "string" ? authentication["contextGate"] : null;
-  return { ok: true, service, apiVersion, contextGate };
+  const cli = payload["cli"];
+  const minimumCliVersion = typeof cli === "object" && cli !== null && typeof cli["minimumVersion"] === "string" ? cli["minimumVersion"] : null;
+  return { ok: true, service, apiVersion, contextGate, minimumCliVersion };
 }
 
 // src/manifest.ts
@@ -7878,14 +7880,26 @@ function renderOperation(operationId, data) {
     lines.push(`  Failed${typeof stage === "string" ? ` at ${stage}` : ""}`);
     const summary = failure["summary"];
     if (typeof summary === "string") lines.push(`    ${summary}`);
-    const detail = failure["detail"];
-    if (typeof detail === "string" && detail !== "") lines.push(`    ${detail}`);
     const cause = failure["cause"];
     if (typeof cause === "string") lines.push(`    cause: ${cause}`);
+    const services = failure["services"];
+    if (Array.isArray(services)) {
+      for (const entry of services) {
+        const one = asRecord(entry);
+        if (one === null) continue;
+        const dependency = one["dependency"];
+        if (typeof dependency !== "string" || dependency === "") continue;
+        const code = one["code"];
+        lines.push(
+          typeof code === "string" && code !== "" ? `    ${dependency} \u2014 the service reported: ${code}` : `    ${dependency} \u2014 the service reported nothing usable`
+        );
+      }
+    }
     const retryable = failure["retryable"];
     if (typeof retryable === "boolean") {
+      const again = data["type"] === "PRODUCT_INSTANCE_UPGRADE" ? "`vfac lifecycle upgrade <pri_\u2026>`" : "`vfac lifecycle reconcile <pri_\u2026>`";
       lines.push(
-        retryable ? "    Another attempt can succeed: `vfac lifecycle reconcile <pri_\u2026>`." : "    Another attempt will fail the same way. Change something first."
+        retryable ? `    Another attempt can succeed: ${again}.` : `    Repeating this unchanged fails again \u2014 fix what the lines above name, then ${again}.`
       );
     }
   }
@@ -12259,6 +12273,27 @@ var CustomerConfigurationObjectSchema = external_exports.object({
   type: external_exports.literal("object"),
   properties: external_exports.record(PropertyNameSchema, ConfigurationPropertySchema).describe("Customer-editable settings, keyed by camelCase property name."),
   required: external_exports.array(PropertyNameSchema).max(40).optional(),
+  /**
+   * Settings that must be configured TOGETHER, keyed by the one that triggers
+   * the requirement.
+   *
+   * `required` says a setting must always have a value. This says a group is
+   * either wholly absent or wholly complete — the shape a provider connection
+   * has, where an endpoint without its credential is worse than neither.
+   *
+   * JSON SCHEMA 2020-12 SEMANTICS, DELIBERATELY AND EXACTLY: if the trigger
+   * key is present in the submitted object, every name in its list must be
+   * present too. The key is published under its standard name in
+   * `schemas/product-definition.schema.json`, inside a node that already looks
+   * like JSON Schema, so a publisher running an off-the-shelf validator over
+   * that file must get the answer the platform gives. The refinement below is
+   * what keeps that promise true — see the `default` rule, which exists for
+   * this reason and no other.
+   *
+   * CYCLES ARE LEGAL. `{a: ["b"], b: ["a"]}` is how "all or none" is written,
+   * and refusing it would remove the primitive's main use.
+   */
+  dependentRequired: external_exports.record(PropertyNameSchema, external_exports.array(PropertyNameSchema).min(1).max(40)).optional().describe("Settings that must be supplied together, keyed by the triggering property."),
   /**
    * Literal `false`, not merely defaulted: docs/CONVENTIONS.md §8 requires
    * contracts to reject unknown fields, and an unknown key accepted here
@@ -12453,7 +12488,129 @@ var CustomerConfigurationSchema = CustomerConfigurationObjectSchema.superRefine(
       message: `Duplicate required entries: ${[...new Set(duplicates)].join(", ")}.`
     });
   }
+  checkDependentRequired(config, ctx);
 });
+function checkDependentRequired(config, ctx) {
+  const clauses = Object.entries(config.dependentRequired ?? {});
+  if (clauses.length === 0)
+    return;
+  if (clauses.length > MAX_CONFIGURATION_PROPERTIES) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["dependentRequired"],
+      message: `A Product may declare at most ${MAX_CONFIGURATION_PROPERTIES} dependent-required groups; found ${clauses.length}.`
+    });
+  }
+  for (const [trigger, dependents] of clauses) {
+    const path = ["dependentRequired", trigger];
+    const declaredTrigger = config.properties[trigger];
+    if (declaredTrigger === void 0) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `"${trigger}" requires other settings but is not a declared property.`
+      });
+    } else if (declaredTrigger.type !== "string") {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `"${trigger}" is a ${declaredTrigger.type} setting and cannot require others. Only a string setting can, because presence is the question this rule asks and a boolean or an empty list is an answer the customer gave rather than a setting they left alone.`
+      });
+    } else if (declaredTrigger.default !== void 0) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `"${trigger}" declares a default, so it is never absent and would require the settings below of every customer unconditionally. Remove the default, or make the requirement unconditional with \`required\`.`
+      });
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const dependent of dependents) {
+      if (dependent === trigger) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${trigger}" cannot require itself.`
+        });
+        continue;
+      }
+      if (seen.has(dependent)) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${trigger}" lists "${dependent}" more than once.`
+        });
+        continue;
+      }
+      seen.add(dependent);
+      const declared = config.properties[dependent];
+      if (declared === void 0) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${trigger}" requires "${dependent}", which is not a declared property.`
+        });
+        continue;
+      }
+      if (declared.default !== void 0) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${dependent}" declares a default, so it is never absent and this requirement could never fail. Remove the default, or drop it from this group.`
+        });
+      }
+    }
+  }
+  checkOneSecretPerGroup(config, ctx);
+}
+function checkOneSecretPerGroup(config, ctx) {
+  const clauses = Object.entries(config.dependentRequired ?? {});
+  if (clauses.length === 0)
+    return;
+  const neighbours = /* @__PURE__ */ new Map();
+  const link = (a, b) => {
+    if (!neighbours.has(a))
+      neighbours.set(a, /* @__PURE__ */ new Set());
+    neighbours.get(a).add(b);
+  };
+  for (const [trigger, dependents] of clauses) {
+    for (const dependent of dependents) {
+      link(trigger, dependent);
+      link(dependent, trigger);
+    }
+  }
+  const isSecret2 = (name) => {
+    const property = config.properties[name];
+    return property !== void 0 && property.type === "string" && property["x-secret"] === true;
+  };
+  const seen = /* @__PURE__ */ new Set();
+  for (const start of neighbours.keys()) {
+    if (seen.has(start))
+      continue;
+    const component = [];
+    const queue = [start];
+    seen.add(start);
+    while (queue.length > 0) {
+      const name = queue.pop();
+      component.push(name);
+      for (const next of neighbours.get(name) ?? []) {
+        if (seen.has(next))
+          continue;
+        seen.add(next);
+        queue.push(next);
+      }
+    }
+    const secrets = component.filter(isSecret2).sort();
+    if (secrets.length <= 1)
+      continue;
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      // The component has no single name, so the issue is reported against the
+      // map rather than against whichever member happened to be visited first.
+      path: ["dependentRequired"],
+      message: `These settings are configured together and include more than one secret (${secrets.join(", ")}). Only one secret can be supplied per change, so a group must ask for at most one \u2014 otherwise completing it on a running resource takes several, in an order the customer has to work out.`
+    });
+  }
+}
 function enumerableValues(property) {
   const out = [];
   if (property.type === "string") {
@@ -12488,8 +12645,9 @@ function isPlainObject(value) {
 function isSecretProperty(property) {
   return property.type === "string" && property["x-secret"] === true;
 }
-function validateSubmittedConfiguration(schema, submitted) {
+function validateSubmittedConfiguration(schema, submitted, presence = {}) {
   const issues = [];
+  const supplied = /* @__PURE__ */ new Set();
   if (submitted !== void 0 && submitted !== null && !isPlainObject(submitted)) {
     return {
       ok: false,
@@ -12520,6 +12678,8 @@ function validateSubmittedConfiguration(schema, submitted) {
     const blank = typeof input[name] === "string" && input[name].trim().length === 0;
     const present = Object.hasOwn(input, name) && input[name] !== void 0 && !blank;
     const secret = isSecretProperty(property);
+    if (present)
+      supplied.add(name);
     if (!present) {
       const fallback = secret ? void 0 : defaultOf(property);
       if (fallback !== void 0) {
@@ -12544,10 +12704,48 @@ function validateSubmittedConfiguration(schema, submitted) {
     }
     configuration[name] = checked;
   }
+  issues.push(...crossFieldIssues(schema, supplied, presence));
   if (issues.length > 0)
     return { ok: false, issues, partial: configuration };
   return { ok: true, configuration, secrets };
 }
+function crossFieldIssues(schema, supplied, presence) {
+  const clauses = Object.entries(schema.dependentRequired ?? {});
+  if (clauses.length === 0)
+    return [];
+  const alsoPresent = new Set(presence.present ?? []);
+  const unknown = new Set(presence.unknown ?? []);
+  const known = (name) => !unknown.has(name);
+  const held = (name) => supplied.has(name) || alsoPresent.has(name);
+  const issues = [];
+  const reported = /* @__PURE__ */ new Set();
+  for (const [trigger, dependents] of clauses) {
+    if (!known(trigger) || !held(trigger))
+      continue;
+    for (const dependent of dependents) {
+      if (!known(dependent) || held(dependent))
+        continue;
+      if (reported.has(dependent))
+        continue;
+      reported.add(dependent);
+      issues.push({
+        field: dependent,
+        message: `This setting is required when ${labelOf(schema, trigger)} is configured.`
+      });
+    }
+  }
+  return issues;
+}
+function labelOf(schema, name) {
+  const property = schema.properties[name];
+  return property === void 0 ? `"${name}"` : `"${property.title}"`;
+}
+function withoutCrossFieldRules(schema) {
+  if (schema.dependentRequired === void 0)
+    return schema;
+  const { dependentRequired: _removed, ...rest } = schema;
+  return rest;
+}
 function defaultOf(property) {
   switch (property.type) {
     case "string":
@@ -12678,6 +12876,15 @@ var RESOURCE_API_VERSION = "resources.vardeflyt.no/v1";
 var PRODUCT_INSTANCE_KIND = "ProductInstance";
 
 // ../product-configuration/dist/product-instance-example.js
+function resolveExampleChoice(options, selected, declaredDefault) {
+  if (selected !== void 0)
+    return options.includes(selected) ? { value: selected, issue: null } : { value: null, issue: "invalid" };
+  if (declaredDefault !== void 0 && options.includes(declaredDefault))
+    return { value: declaredDefault, issue: null };
+  if (options.length === 1)
+    return { value: options[0], issue: null };
+  return { value: null, issue: options.length === 0 ? "unavailable" : "required" };
+}
 function isSecret(declaration) {
   return declaration.writeOnly === true || declaration["x-secret"] === true;
 }
@@ -12687,6 +12894,14 @@ function seedConfiguration(configuration) {
   const values = {};
   const open = [];
   const requiredSecrets = [];
+  const groups = Object.entries(configuration?.dependentRequired ?? {}).map(([trigger, dependents]) => {
+    const members = [trigger, ...dependents];
+    return {
+      trigger,
+      settings: members.filter((name) => !isSecret(properties[name] ?? {})),
+      secrets: members.filter((name) => isSecret(properties[name] ?? {}))
+    };
+  }).sort((a, b) => a.trigger.localeCompare(b.trigger));
   for (const [name, declaration] of Object.entries(properties)) {
     if (isSecret(declaration)) {
       if (required.has(name))
@@ -12702,7 +12917,7 @@ function seedConfiguration(configuration) {
       open.push({ name, type: declaration.type ?? null });
     }
   }
-  return { values, open, requiredSecrets };
+  return { values, open, requiredSecrets, groups };
 }
 function productInstanceExample(input) {
   return {
@@ -13573,11 +13788,11 @@ var ProductDefinitionSchema = ProductDefinitionObjectSchema.superRefine((definit
       });
       return;
     }
-    const single = {
+    const single = withoutCrossFieldRules({
       ...definition.configuration,
       properties: { [condition.property]: property },
       required: [condition.property]
-    };
+    });
     const outside = condition.anyOf.filter((value) => !validateSubmittedConfiguration(single, { [condition.property]: value }).ok);
     if (outside.length > 0) {
       ctx.addIssue({
@@ -15736,9 +15951,9 @@ async function runApply(verb, parsed, deps = {}) {
     process.stderr.write("Which manifest? Use -f <file>.\n");
     return 2;
   }
-  const manifest = readManifest(file);
-  if (!manifest.ok) {
-    process.stderr.write(`${manifest.message}
+  const manifest2 = readManifest(file);
+  if (!manifest2.ok) {
+    process.stderr.write(`${manifest2.message}
 `);
     return 2;
   }
@@ -15764,7 +15979,7 @@ async function runApply(verb, parsed, deps = {}) {
   const json = parsed.flags["output"] === "json";
   const path = `/api/v1/projects/${encodeURIComponent(projectId)}/manifest`;
   const envelope = {
-    template: manifest.document,
+    template: manifest2.document,
     ...Object.keys(secrets.secrets).length > 0 ? { secrets: secrets.secrets } : {},
     ...parsed.flags["adopt"] ? { adopt: parsed.flags["adopt"] } : {}
   };
@@ -15776,7 +15991,7 @@ async function runApply(verb, parsed, deps = {}) {
       token: session.ready.token,
       // The DOCUMENT, not the envelope: `validate` asks whether a file is well
       // formed, which is a question about the file and not about a request.
-      body: { verb: "validate", payload: manifest.document }
+      body: { verb: "validate", payload: manifest2.document }
     });
     if (!result.ok) return printError(result.error, json);
     process.stdout.write(
@@ -15849,7 +16064,7 @@ Read the operation that failed: \`vfac get operation <id>\`, or \`vfac get produ
     body: { verb: "apply", action, payload: envelope }
   });
   if (!applied.ok) return printError(applied.error, json);
-  const key = manifestKeyOf(manifest.document) ?? planned.data.manifestKey ?? "(unnamed)";
+  const key = manifestKeyOf(manifest2.document) ?? planned.data.manifestKey ?? "(unnamed)";
   const rawOperationId = applied.data["operationId"];
   const operationId = typeof rawOperationId === "string" && rawOperationId !== "" ? rawOperationId : null;
   if (!parsed.booleans.has("wait")) {
@@ -15993,17 +16208,63 @@ Project   ${projectId ?? "(none)"}
 
 // src/version.ts
 import { readFileSync as readFileSync3 } from "node:fs";
-function cliVersion() {
+function manifest() {
   try {
-    const manifest = JSON.parse(
+    const parsed = JSON.parse(
       readFileSync3(new URL("../package.json", import.meta.url), "utf8")
     );
-    const version = typeof manifest === "object" && manifest !== null ? manifest["version"] : void 0;
-    return typeof version === "string" ? version : "unknown";
+    return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
-    return "unknown";
+    return null;
   }
 }
+function cliVersion() {
+  const version = manifest()?.["version"];
+  return typeof version === "string" ? version : "unknown";
+}
+function cliPackageName() {
+  const name = manifest()?.["name"];
+  return typeof name === "string" ? name : null;
+}
+function cliInstallCommand() {
+  const name = cliPackageName();
+  return name === null ? null : `npm install -g ${name}`;
+}
+
+// src/registry.ts
+var UPDATE_CHECK_TIMEOUT_MS = 3e3;
+var REGISTRY_ORIGIN = "https://registry.npmjs.org";
+var UPDATE_CHECK_OPT_OUT = "VFAC_NO_UPDATE_CHECK";
+async function latestPublishedVersion(args) {
+  const env = args?.env ?? process.env;
+  if (env[UPDATE_CHECK_OPT_OUT]) return { ok: false };
+  const name = cliPackageName();
+  if (name === null) return { ok: false };
+  const doFetch = args?.fetchImpl ?? fetch;
+  let response;
+  try {
+    response = await doFetch(`${REGISTRY_ORIGIN}/-/package/${encodeURIComponent(name)}/dist-tags`, {
+      method: "GET",
+      redirect: "manual",
+      signal: signal()
+    });
+  } catch {
+    return { ok: false };
+  }
+  if (!response.ok) return { ok: false };
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    return { ok: false };
+  }
+  if (typeof payload !== "object" || payload === null) return { ok: false };
+  const latest = payload["latest"];
+  return typeof latest === "string" && latest !== "" ? { ok: true, latest } : { ok: false };
+}
+function signal() {
+  return typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS) : void 0;
+}
 
 // src/commands/doctor.ts
 async function runDoctor(parsed) {
@@ -16036,6 +16297,9 @@ async function runDoctor(parsed) {
     return report(checks, json);
   }
   checks.push({ name: "Machine API", ok: true, detail: probe.apiVersion });
+  const compatible = compatibility(cliVersion(), probe.minimumCliVersion);
+  checks.push(compatible);
+  if (!compatible.ok) return report(checks, json);
   const signedIn = await signIn({ endpoint });
   if (!signedIn.ok) {
     checks.push({ name: "Context Gate", ok: false, detail: signedIn.message });
@@ -16110,8 +16374,87 @@ async function runDoctor(parsed) {
     note: true,
     detail: "run `vfac guide` for the platform's own instructions, written for a machine"
   });
+  checks.push(await updateAvailable(cliVersion()));
   return report(checks, json);
 }
+function compatibility(local, declared) {
+  const name = "Compatibility";
+  const facts = { version: local, minimumVersion: declared };
+  if (declared === null) {
+    return {
+      name,
+      ok: true,
+      detail: "this Tenant Portal names no minimum version, so there is nothing to check against.",
+      facts
+    };
+  }
+  if (!PLAIN_SEMVER_REGEX.test(declared)) {
+    return {
+      name,
+      ok: true,
+      note: true,
+      detail: `this Tenant Portal asks for "${declared}", which is not a version this client can read. Treated as no requirement rather than as a refusal.`,
+      facts
+    };
+  }
+  if (!PLAIN_SEMVER_REGEX.test(local)) {
+    return {
+      name,
+      ok: true,
+      note: true,
+      detail: `this build does not report its own version, so it cannot be checked against the vfac ${declared} this Tenant Portal requires.`,
+      facts
+    };
+  }
+  if (compareSemver(local, declared) >= 0) {
+    return { name, ok: true, detail: `OK \u2014 requires vfac ${declared} or newer`, facts };
+  }
+  const install = cliInstallCommand();
+  return {
+    name,
+    ok: false,
+    detail: `UPGRADE REQUIRED. This Tenant Portal supports vfac ${declared} and newer; this is ${local}. ` + (local.includes("-") ? `A prerelease sorts below the release it is named for, so ${local} does not satisfy ${declared}. ` : "") + (install === null ? "" : `Run: ${install}`),
+    facts
+  };
+}
+async function updateAvailable(local) {
+  const name = "Update";
+  const result = await latestPublishedVersion();
+  if (!result.ok) {
+    return {
+      name,
+      ok: true,
+      detail: "could not check for updates",
+      facts: { version: local, latest: null }
+    };
+  }
+  const facts = { version: local, latest: result.latest };
+  if (!PLAIN_SEMVER_REGEX.test(local) || !PLAIN_SEMVER_REGEX.test(result.latest)) {
+    return {
+      name,
+      ok: true,
+      detail: `the latest published release is vfac ${result.latest}`,
+      facts
+    };
+  }
+  const order = compareSemver(local, result.latest);
+  if (order > 0) {
+    return {
+      name,
+      ok: true,
+      detail: `vfac ${local} is ahead of the latest release (${result.latest})`,
+      facts
+    };
+  }
+  if (order === 0) return { name, ok: true, detail: `vfac ${local} is the latest release`, facts };
+  return {
+    name,
+    ok: true,
+    note: true,
+    detail: `vfac ${result.latest} is available (running ${local})`,
+    facts
+  };
+}
 function report(checks, json) {
   const failed = checks.filter((check) => !check.ok);
   if (json) {
@@ -16724,42 +17067,27 @@ async function runManifestInit(parsed) {
   }
   const regions = product.supportedRegions ?? [];
   const chosenRegion = parsed.flags["region"];
-  let region;
-  if (chosenRegion !== void 0) {
-    if (!regions.includes(chosenRegion)) {
-      return refuse(
-        `${product.productId} ${product.version} does not offer the region "${chosenRegion}".${regions.length > 0 ? ` It offers: ${regions.join(", ")}.` : ""}`
-      );
-    }
-    region = chosenRegion;
-  } else if (regions.length === 1) {
-    region = regions[0];
-  } else {
+  const regionChoice = resolveExampleChoice(regions, chosenRegion);
+  if (regionChoice.value === null) {
     return refuse(
-      regions.length === 0 ? `${product.productId} ${product.version} declares no region. Ask the publisher.` : `This Product offers several regions. Pass --region <${regions.join("|")}>.`
+      regionChoice.issue === "invalid" ? `${product.productId} ${product.version} does not offer the region "${chosenRegion}".${regions.length > 0 ? ` It offers: ${regions.join(", ")}.` : ""}` : regionChoice.issue === "unavailable" ? `${product.productId} ${product.version} declares no region. Ask the publisher.` : `This Product offers several regions. Pass --region <${regions.join("|")}>.`
     );
   }
+  const region = regionChoice.value;
   const profiles = product.profiles ?? [];
   const offered = profiles.map((entry) => entry.id);
   const chosenProfile = parsed.flags["profile"];
-  const declaredDefault = profiles.find((entry) => entry.default === true);
-  let profile;
-  if (chosenProfile !== void 0) {
-    if (!offered.includes(chosenProfile)) {
-      return refuse(
-        `${product.productId} ${product.version} does not offer the service profile "${chosenProfile}".${offered.length > 0 ? ` It offers: ${offered.join(", ")}.` : ""}`
-      );
-    }
-    profile = chosenProfile;
-  } else if (declaredDefault) {
-    profile = declaredDefault.id;
-  } else if (offered.length === 1) {
-    profile = offered[0];
-  } else {
+  const profileChoice = resolveExampleChoice(
+    offered,
+    chosenProfile,
+    profiles.find((entry) => entry.default === true)?.id
+  );
+  if (profileChoice.value === null) {
     return refuse(
-      offered.length === 0 ? `${product.productId} ${product.version} declares no service profile. Ask the publisher.` : `This Product offers several service profiles. Pass --profile <${offered.join("|")}>.`
+      profileChoice.issue === "invalid" ? `${product.productId} ${product.version} does not offer the service profile "${chosenProfile}".${offered.length > 0 ? ` It offers: ${offered.join(", ")}.` : ""}` : profileChoice.issue === "unavailable" ? `${product.productId} ${product.version} declares no service profile. Ask the publisher.` : `This Product offers several service profiles. Pass --profile <${offered.join("|")}>.`
     );
   }
+  const profile = profileChoice.value;
   const seed = seedConfiguration(product.configuration);
   for (const property of seed.requiredSecrets) {
     notes.push(`--secret ${property}=env:VAR  \u2014 required, and never written to this file`);
@@ -16769,6 +17097,13 @@ async function runManifestInit(parsed) {
       `spec.configuration.${setting.name}  \u2014 required${setting.type ? ` (${setting.type})` : ""}`
     );
   }
+  for (const group of seed.groups) {
+    const settings = group.settings.map((name2) => `spec.configuration.${name2}`);
+    const secrets = group.secrets.map((name2) => `--secret ${name2}=env:VAR`);
+    notes.push(
+      `${[...settings, ...secrets].join(" + ")}  \u2014 all of these together, or none of them`
+    );
+  }
   const document = productInstanceExample({
     name,
     ...key ? { key } : {},
@@ -16979,9 +17314,12 @@ Options
       --output    json, for a pipeline that reads the answer
 
 Diagnosing
-  vfac doctor   checks the endpoint, the machine API, the credential and what
-                that credential can reach \u2014 in that order, so the first thing
-                that is actually wrong is the thing it reports
+  vfac doctor   checks the endpoint, the machine API, whether this client is new
+                enough for that platform, the credential and what that credential
+                can reach \u2014 in that order, so the first thing that is actually
+                wrong is the thing it reports. It ends by asking npm whether a
+                newer vfac has been published, which is a note and never a
+                failure. Set VFAC_NO_UPDATE_CHECK to skip that one request
   vfac whoami   what this credential is, and which Project scopes it has been
                 GRANTED. A credential scoped to one Project deploys fine and
                 cannot make organization-wide reads \u2014 this is where that is said.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@varde-flyt/vfac",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Deploy and manage Varde Flyt Products from a manifest.",
   "repository": {
     "type": "git",