@varde-flyt/vfac 0.15.0 → 0.15.2

package/README.md

@@ -26,10 +26,10 @@ vfac guide
 vfac whoami
 ```
 
-`doctor` checks the endpoint, which Project this terminal has selected, the API,
-whether this client is new enough for the platform it is pointed at, how this
-terminal is signed in and what that credential reaches, in that order, and reports
-the first thing that is actually wrong. Both ways of signing in count: a Context
+`doctor` checks the endpoint, which Project this terminal has selected and which
+one this command will act in, the API, whether this client is new enough for the
+platform it is pointed at, how this terminal is signed in and what that credential
+reaches, in that order, and reports the first thing that is actually wrong. Both ways of signing in count: a Context
 Gate exchanged from `VFAC_CREDENTIAL_ID` and `VFAC_CREDENTIAL_SECRET`, or a
 sign-in from `vfac login` that is still valid. A platform declares the oldest client it supports;
 below that, `doctor` fails and says so before sending your credential anywhere.
@@ -37,7 +37,10 @@ below that, `doctor` fails and says so before sending your credential anywhere.
 The selected Project and the Projects your credential reaches are two different
 lines, and reading the second as the first is the mistake worth naming: a command
 with no `--project` uses the SELECTED one, and having access to a Project is not
-the same as being in it. `doctor` also says so when it has just started a fresh
+the same as being in it. `--project` overrides the selection for one command and
+writes nothing, so `vfac doctor --project prj_…` reports the Project it would act
+in, says the flag is where that came from, and still names what your context has
+selected. `doctor` also says so when it has just started a fresh
 config because the old one could not be read — the endpoint and Project you had
 set are gone in that case, and the unreadable file is kept beside it rather than
 discarded.
@@ -68,7 +71,7 @@ vfac context set --project <projectId>
 
 ```sh
 vfac product list
-vfac product show <productId>
+vfac product show <productId>          # every setting, and when you must answer it
 vfac manifest init --product <productId> --name "My resource" > resource.yaml
 ```
 
@@ -97,9 +100,12 @@ the plan describes a different request.
 
 `--secret` names a root setting by its name, and a setting inside a group by its
 path — `--secret /upstreamAuth/clientSecret=env:UPSTREAM_CLIENT_SECRET` for the
-`clientSecret` under `upstreamAuth`. `vfac product show` and `vfac manifest init`
-print each required secret in that form. A path never names an item of a list:
-no secret is declared there.
+`clientSecret` under `upstreamAuth`. `vfac product show` prints that form beside
+EVERY credential the Product declares, with a line saying whether it is required
+of everyone, required when another setting holds a particular value, or required
+because another setting was answered — `dependentRequired` is directional, and
+the line says which way it runs; `vfac manifest init` names the ones required
+outright. A path never names an item of a list: no secret is declared there.
 
 `requiredSecrets` in a plan is what the Product requires for the configuration in
 your document — not a list of what the platform is missing. It names a credential
@@ -109,7 +115,9 @@ act on. `secretsToWrite` is the field that says what this apply would write.
 A credential the Product requires for your document — outright, or because of
 what a setting is set to — that the run neither supplies nor the resource already
 holds is refused by `plan` and `apply` alike, before anything is written: the
-error names every one, by the path `--secret` takes, and the command exits 1.
+error names every one, by the path `--secret` takes, and the command exits 1. So
+is a credential the run DOES supply whose value the Product's own declaration
+refuses: the error names the setting and the bound it missed, never the value.
 `vfac validate` carries no secrets and refuses none; it lists them.
 
 ### `metadata.key` is the name you choose
@@ -229,9 +237,11 @@ it.
 ## For an agent or a pipeline
 
 Every command takes `--output json`, and it is the same data rather than a
-prettier subset — the human format of `vfac product show` prints a readable
-selection on purpose and says so at the foot of its output, and the JSON carries
-the whole Product contract.
+prettier subset. The human format of `vfac product show` lists every setting the
+Product declares and says when each must be answered; what it leaves to the JSON
+form is the prose and the value constraints — descriptions, patterns, bounds —
+and it says so at the foot of its output. The JSON carries the whole Product
+contract.
 
 ```sh
 vfac product show <productId> --output json

package/dist/vfac.mjs

@@ -13207,6 +13207,14 @@ function canonicalJson(value) {
 function immediateContainer(node) {
   return node.containers[node.containers.length - 1] ?? null;
 }
+function resolvedGroup(node) {
+  for (const container of node.containers) {
+    const declared = container.property.group;
+    if (declared !== void 0)
+      return declared;
+  }
+  return node.property.group;
+}
 function underList(node) {
   return node.containers.some((container) => container.kind === "array");
 }
@@ -14210,6 +14218,116 @@ function exampleResourceKey(name) {
 }
 var DEPLOYMENT_EXAMPLE_GUARANTEE = "Product-owned configuration is complete and E2E-proven; tenant-specific secrets and Resource/provider selections are supplied by the tenant.";
 
+// ../product-configuration/dist/configuration-requirements.js
+function configurationRequirements(configuration) {
+  if (configuration === void 0 || configuration === null)
+    return [];
+  const schema = configuration;
+  const rootRequired = new Set(schema.required ?? []);
+  const carriers = new Map(conditionCarriers(schema).map((carrier) => [carrier.path, carrier]));
+  const secretPaths = new Set(configurationLeaves(schema).filter((leaf) => isSecretProperty(leaf.property)).map((leaf) => String(leaf.path)));
+  return configurationLeaves(schema).map((leaf) => {
+    const parent = immediateContainer(leaf);
+    const immediatelyRequired = parent === null ? rootRequired.has(leaf.name) : parent.required.includes(leaf.name);
+    const chainRequired = containersRequiredToRoot(schema, leaf);
+    const always = requiredToRoot(schema, leaf);
+    const secret = isSecretProperty(leaf.property);
+    const condition = conditionFor(schema, leaf.path, leaf.containers, carriers);
+    const clause = clauseEdges(schema, leaf, secretPaths);
+    const requiredness = always ? "always" : condition !== null && condition.carrier === "setting" ? "when-value" : immediatelyRequired && !chainRequired ? "when-group" : clause.requiredBy.length > 0 ? "with-siblings" : "optional";
+    const containers = leaf.containers.map((container, index) => settingContainer(container, index === 0 ? rootRequired : new Set(leaf.containers[index - 1]?.required ?? [])));
+    const list = [...containers].reverse().find((container) => container.kind === "array") ?? null;
+    return {
+      path: leaf.path,
+      printablePath: printableConfigurationPath(leaf.path),
+      title: leaf.property.title,
+      description: leaf.property.description,
+      type: leaf.property.type,
+      secret,
+      requiredness,
+      // NEVER A SECRET'S, even though the declaration rules already refuse one.
+      // Being wrong in that direction prints a credential, which is the same
+      // paranoia `product-instance-example.ts` documents for its own reader.
+      defaultValue: secret ? void 0 : declaredDefault(leaf.property),
+      allowed: secret ? [] : allowedValues(leaf.property),
+      condition,
+      requires: clause.requires,
+      requiredBy: clause.requiredBy,
+      containers,
+      perRow: underList(leaf),
+      list,
+      group: resolvedGroup(leaf)
+    };
+  });
+}
+function allowedValues(property) {
+  const leaf = property;
+  return [...leaf.enum ?? leaf.items?.enum ?? []];
+}
+function conditionFor(schema, path, containers, carriers) {
+  const own = carriers.get(path);
+  const ancestor = [...containers].reverse().map((container) => carriers.get(container.path)).find((carrier2) => carrier2 !== void 0 && carrier2.kind === "container");
+  const carrier = own?.kind === "leaf" ? own : ancestor;
+  if (carrier === void 0)
+    return null;
+  const setting = parseConfigurationPath(conditionSetting(carrier.condition));
+  if (setting === null)
+    return null;
+  return {
+    carrier: carrier.kind === "leaf" ? "setting" : "container",
+    carrierPath: carrier.path,
+    setting,
+    printableSetting: printableConfigurationPath(setting),
+    settingLabel: labelOfPath(schema, setting),
+    anyOf: [...carrier.condition.anyOf],
+    anyRow: "path" in carrier.condition && carrier.condition.anyRow === true
+  };
+}
+function clauseEdges(schema, leaf, secretPaths) {
+  const parent = immediateContainer(leaf);
+  const scope = parent === null ? schema : parent.kind === "array" ? parent.property.items ?? parent.property : parent.property;
+  const requires = /* @__PURE__ */ new Set();
+  const requiredBy = /* @__PURE__ */ new Set();
+  for (const [trigger, dependents] of Object.entries(scope.dependentRequired ?? {})) {
+    if (trigger === leaf.name)
+      for (const dependent of dependents)
+        requires.add(dependent);
+    else if (dependents.includes(leaf.name))
+      requiredBy.add(trigger);
+  }
+  const order = Object.keys(scope.properties ?? {});
+  const members = (names) => [...names].sort((a, b) => order.indexOf(a) - order.indexOf(b)).flatMap((name) => {
+    const path = memberPath(leaf, name);
+    return path === null ? [] : [
+      {
+        path,
+        printablePath: printableConfigurationPath(path),
+        secret: secretPaths.has(String(path))
+      }
+    ];
+  });
+  return { requires: members(requires), requiredBy: members(requiredBy) };
+}
+function memberPath(leaf, name) {
+  const parent = immediateContainer(leaf);
+  return parent === null ? configurationPath(name) : configurationPath(...pathSegments(parent.path), name);
+}
+function settingContainer(container, requiredByParent) {
+  return {
+    path: container.path,
+    printablePath: printableConfigurationPath(container.path),
+    title: container.property.title,
+    kind: container.kind,
+    required: requiredByParent.has(container.name)
+  };
+}
+
+// ../product-configuration/dist/manifest-yaml.js
+var import_yaml = __toESM(require_dist(), 1);
+function manifestYaml(document) {
+  return (0, import_yaml.stringify)(document, { compat: "yaml-1.1" });
+}
+
 // ../platform-schemas/dist/index.js
 var TENANT_KEY_REGEX = /^[a-z][a-z0-9-]{2,23}[a-z0-9]$/;
 var RESERVED_TENANT_KEYS = /* @__PURE__ */ new Set([
@@ -17868,7 +17986,7 @@ withJsonSchemaAnnex(ProductSubmissionSchema, PUBLISH_RULE_ANNEX);
 withJsonSchemaAnnex(ProductSubmissionV2Schema, PUBLISH_RULE_ANNEX);
 
 // src/manifest.ts
-var import_yaml = __toESM(require_dist(), 1);
+var import_yaml2 = __toESM(require_dist(), 1);
 function readManifest(path) {
   let text;
   try {
@@ -17878,7 +17996,7 @@ function readManifest(path) {
   }
   let parsed;
   try {
-    parsed = (0, import_yaml.parse)(text, { prettyErrors: false });
+    parsed = (0, import_yaml2.parse)(text, { prettyErrors: false });
   } catch (error) {
     return {
       ok: false,
@@ -18041,8 +18159,14 @@ async function ensureSession(args) {
     }
   };
 }
+function resolveProjectWithSource(flag, stored) {
+  if (flag !== void 0) return { value: flag, source: "--project" };
+  const selected = stored.context?.projectId;
+  if (selected !== void 0) return { value: selected, source: "the stored context" };
+  return null;
+}
 function resolveProject(flag, stored) {
-  return flag ?? stored.context?.projectId ?? null;
+  return resolveProjectWithSource(flag, stored)?.value ?? null;
 }
 
 // src/operations.ts
@@ -18692,13 +18816,18 @@ async function runDoctor(parsed) {
     detail: `${endpoint}   (from ${resolved.source})`,
     facts: { endpoint, source: resolved.source }
   });
-  const selected = stored.context?.projectId ?? null;
+  const project = resolveProjectWithSource(parsed.flags["project"], stored);
+  const storedProjectId = stored.context?.projectId ?? null;
   checks.push({
     name: "Project",
     ok: true,
-    note: selected === null,
-    detail: selected === null ? "none selected. Commands need `--project prj_\u2026`, or run `vfac context set --project prj_\u2026` once. This is not a fault \u2014 it is what a pipeline that names the Project per command looks like \u2014 but it is NOT the same thing as which Projects your credential reaches." : `${selected}   (selected in this context; which Projects the credential reaches is a separate question)`,
-    facts: { selectedProjectId: selected }
+    note: storedProjectId === null,
+    detail: project === null ? "none selected. Commands need `--project prj_\u2026`, or run `vfac context set --project prj_\u2026` once. This is not a fault \u2014 it is what a pipeline that names the Project per command looks like \u2014 but it is NOT the same thing as which Projects your credential reaches." : project.source === "--project" ? `${project.value}   (from --project, for this command only). ` + (storedProjectId === null ? "Nothing is selected in this context, so every other command needs the flag too. " : `The stored context still selects ${storedProjectId}, which is what a command with no --project uses. `) + "Which Projects the credential reaches is a separate question." : `${project.value}   (from the stored context; a command with no --project uses it, and which Projects the credential reaches is a separate question)`,
+    facts: {
+      selectedProjectId: project?.value ?? null,
+      source: project?.source ?? null,
+      storedProjectId
+    }
   });
   const probe = await probeMachineApi({ endpoint });
   if (!probe.ok) {
@@ -18733,13 +18862,13 @@ async function runDoctor(parsed) {
     return report2(checks, json);
   }
   const access = who.data.access;
-  const projects = access.projects.map((project) => project.projectId);
+  const projects = access.projects.map((project2) => project2.projectId);
   const mutating = access.projects.filter(
-    (project) => project.permissions.some((permission) => !permission.endsWith(".read"))
+    (project2) => project2.permissions.some((permission) => !permission.endsWith(".read"))
   );
   const organizationWide = access.tenantPermissions.includes("project.read");
   const alsoOrganizationWide = access.tenantPermissions.length > 0 ? `Organization-wide it holds ${access.tenantPermissions.join(", ")}, which reaches no Project. ` : "";
-  const perProject = projects.length === 0 ? "" : `. Granted per Project: ${projects.join(", ")}` + (mutating.length > 0 ? ` \u2014 you can deploy in ${mutating.map((project) => project.projectId).join(", ")}` : " \u2014 read-only there");
+  const perProject = projects.length === 0 ? "" : `. Granted per Project: ${projects.join(", ")}` + (mutating.length > 0 ? ` \u2014 you can deploy in ${mutating.map((project2) => project2.projectId).join(", ")}` : " \u2014 read-only there");
   checks.push(
     organizationWide ? {
       name: "Access",
@@ -18898,7 +19027,6 @@ function report2(checks, json) {
 }
 
 // src/commands/export.ts
-var import_yaml2 = __toESM(require_dist(), 1);
 async function runExport(parsed) {
   if (parsed.command[1] !== "product-instance" && parsed.command[1] !== "resource") {
     process.stderr.write("Usage: vfac export product-instance pri_\u2026\n");
@@ -18926,7 +19054,7 @@ async function runExport(parsed) {
   if (!result.ok) return printError(result.error, parsed.flags["output"] === "json");
   process.stdout.write(
     parsed.flags["output"] === "json" ? `${JSON.stringify(result.data, null, 2)}
-` : (0, import_yaml2.stringify)(result.data)
+` : manifestYaml(result.data)
   );
   const metadata = result.data["metadata"];
   const hasKey = typeof metadata === "object" && metadata !== null && "key" in metadata;
@@ -19338,16 +19466,44 @@ function renderProduct(product) {
     (profile) => `${profile.id}${profile.default ? " (default)" : ""}`
   );
   lines.push(`  profile         ${profiles.join(", ") || "(none declared)"}`);
-  const seed = seedConfiguration(product.configuration);
-  if (seed.open.length > 0 || seed.requiredSecrets.length > 0) {
-    lines.push("", "  Required configuration");
-    for (const name of seed.requiredSecrets) {
-      lines.push(`    ${name}  (secret \u2014 pass --secret ${name}=env:VAR)`);
-    }
-    for (const setting of seed.open) {
-      lines.push(`    ${setting.label}  ${setting.type ?? ""}`.trimEnd());
+  const settings = configurationRequirements(product.configuration);
+  if (settings.length > 0) {
+    lines.push("", `  Settings (${settings.length})`);
+    for (const setting of settings) {
+      lines.push(
+        `    ${identityOf(setting)}  ${setting.secret ? "secret" : setting.type}  ${TOKEN[setting.requiredness]}`
+      );
+      const requirement = requirementOf(setting);
+      if (requirement !== null) lines.push(...continuation(requirement));
+      if (setting.requires.length > 0 && !mutualClause(setting)) {
+        lines.push(
+          ...continuation(
+            `answering it also requires ${listOf(
+              setting.requires.map((member) => identityOf(member)),
+              "and"
+            )}`
+          )
+        );
+      }
+      if (setting.condition?.carrier === "container") {
+        lines.push(
+          ...continuation(
+            `${printableConfigurationPath(setting.condition.carrierPath)} is required when ${setting.condition.printableSetting} is ${valueList(setting.condition.anyOf)}`
+          )
+        );
+      }
+      if (setting.secret) {
+        lines.push(...continuation(`--secret ${String(setting.path)}=env:VAR`));
+      }
+      if (setting.allowed.length > 0) {
+        lines.push(...continuation(`one of ${valueList(setting.allowed)}`));
+      }
+      if (setting.defaultValue !== void 0) {
+        lines.push(...continuation(`default ${JSON.stringify(setting.defaultValue)}`));
+      }
     }
   }
+  const seed = seedConfiguration(product.configuration);
   const together = seed.groups.filter((group) => group.within !== null);
   if (together.length > 0) {
     lines.push("", "  Settings that go together");
@@ -19397,9 +19553,66 @@ function renderProduct(product) {
       lines.push(`    ${condition.key ?? ""}  ${condition.displayName ?? ""}`.trimEnd());
     }
   }
-  lines.push("", "  `--output json` carries the whole declaration, this is a readable subset.");
+  lines.push(
+    "",
+    "  `--output json` carries the whole declaration. Every setting is listed above;",
+    "  descriptions and value constraints are in the JSON form."
+  );
+  if (settings.some((setting) => setting.secret)) {
+    lines.push("  A credential is supplied per apply and never written into a manifest.");
+  }
   return lines.join("\n");
 }
+var TOKEN = {
+  always: "required",
+  "when-value": "required-when",
+  "when-group": "required-if",
+  "with-siblings": "required-with",
+  optional: "optional"
+};
+var MAX_LISTED_VALUES = 8;
+var identityOf = (setting) => setting.secret ? String(setting.path) : setting.printablePath;
+function valueList(values) {
+  const shown = values.slice(0, MAX_LISTED_VALUES).map((value) => JSON.stringify(value));
+  const rest = values.length - shown.length;
+  const joined = shown.length === 2 ? shown.join(" or ") : shown.join(", ");
+  return rest > 0 ? `${joined} and ${rest} more` : joined;
+}
+function requirementOf(setting) {
+  const list = setting.list === null ? "" : ` ${setting.list.printablePath}`;
+  switch (setting.requiredness) {
+    case "always":
+      return setting.perRow ? `in every${list} entry` : null;
+    case "when-value": {
+      const condition = setting.condition;
+      if (condition === null) return null;
+      const rows = condition.anyRow ? " in any entry" : "";
+      return `when ${condition.printableSetting} is ${valueList(condition.anyOf)}${rows}`;
+    }
+    case "when-group": {
+      const owner = setting.containers[setting.containers.length - 1];
+      const base = `once ${owner?.printablePath ?? ""} is configured`;
+      return setting.perRow ? `${base}, in every${list} entry` : base;
+    }
+    case "with-siblings": {
+      const names = (members) => members.map((member) => identityOf(member));
+      const triggers = names(setting.requiredBy);
+      return mutualClause(setting) ? `with ${names(setting.requires).join(", ")}` : `once ${listOf(triggers, "or")} is set`;
+    }
+    case "optional":
+      return setting.perRow ? `one per${list} entry` : null;
+  }
+}
+function mutualClause(setting) {
+  const requires = setting.requires.map((member) => String(member.path)).sort();
+  const requiredBy = setting.requiredBy.map((member) => String(member.path)).sort();
+  return requires.length > 0 && requires.join("\0") === requiredBy.join("\0");
+}
+function listOf(items, conjunction) {
+  if (items.length <= 1) return items[0] ?? "";
+  return `${items.slice(0, -1).join(", ")} ${conjunction} ${items[items.length - 1]}`;
+}
+var continuation = (sentence) => wrap(sentence, 72).map((line) => `      ${line}`);
 function wrap(text, width) {
   const lines = [];
   for (const paragraph of text.split(/\n\s*\n/)) {
@@ -19582,7 +19795,6 @@ Only approve a code you are looking at right now. Waiting\u2026
 }
 
 // src/commands/manifest-init.ts
-var import_yaml3 = __toESM(require_dist(), 1);
 async function runManifestInit(parsed) {
   const verb = parsed.command[1];
   if (verb !== "init") {
@@ -19687,7 +19899,7 @@ ${where}`);
   }
   process.stdout.write(
     parsed.flags["output"] === "json" ? `${JSON.stringify(document, null, 2)}
-` : (0, import_yaml3.stringify)(document)
+` : manifestYaml(document)
   );
   if (notes.length > 0) {
     process.stderr.write("\nStill yours to fill in:\n");
@@ -19901,12 +20113,16 @@ Options
       --output    json, for a pipeline that reads the answer
 
 Diagnosing
-  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 doctor   checks the config it could read, the endpoint, which Project this
+                terminal has selected and which one the command will act in, the
+                machine API, whether this client is new enough for that platform,
+                how this terminal is signed in and what that credential can reach
+                \u2014 in that order, so the first thing that is actually wrong is the
+                thing it reports. Pass --project to ask about the Project a
+                command would name, which changes nothing on disk. 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.15.0",
+  "version": "0.15.2",
   "description": "Deploy and manage Varde Flyt Products from a manifest.",
   "repository": {
     "type": "git",