@varde-flyt/vfac 0.11.0 → 0.12.0

package/README.md

@@ -74,14 +74,21 @@ vfac manifest init --product <productId> --name "My resource" > resource.yaml
 
 ```sh
 vfac validate -f resource.yaml
-vfac plan     -f resource.yaml
+vfac plan     -f resource.yaml --secret SETTING=env:VARIABLE
 vfac apply    -f resource.yaml --secret SETTING=env:VARIABLE
 vfac get operation <operationId>
 vfac get product-instance <productInstanceId>
 ```
 
 Secrets are supplied per apply and never belong in the manifest — a manifest is a
-file you commit. `vfac plan` lists the ones an apply will still need.
+file you commit. **Plan the run that sets one with the same `--secret` inputs the
+apply will carry**: `plan` takes the flag exactly as `apply` does, and without it
+the plan describes a different request.
+
+`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
+whether or not this resource already holds one, so it is not a shopping list to
+act on. `secretsToWrite` is the field that says what this apply would write.
 
 ### `metadata.key` is the name you choose
 
@@ -176,7 +183,8 @@ spec:
 `vfac manifest init` names the exact property for every dependency you have to
 choose, and `vfac plan` prints the connections an apply would establish before
 you approve it. The dependency key comes from the Product, not from you —
-`vfac product show <productId>` lists them.
+`vfac product show <productId>` lists every dependency with its key, its
+capability, and whether a setting is what turns it on.
 
 This is not the same thing as the section above, and the difference is worth
 holding on to:
@@ -198,7 +206,8 @@ it.
 
 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 the JSON carries the whole Product contract.
+selection on purpose and says so at the foot of its output, and the JSON carries
+the whole Product contract.
 
 ```sh
 vfac product show <productId> --output json
@@ -261,12 +270,15 @@ so this answers `UPDATE` and redeploys, even when the value is the value already
 stored:
 
 ```sh
+vfac plan  -f resource.yaml --secret SETTING=env:VARIABLE
 vfac apply -f resource.yaml --secret SETTING=env:VARIABLE
 ```
 
-Send secrets on the apply that creates the resource and on the run that rotates
-one, and on no other run. A pipeline that passes its secrets every run restarts
-your service every time somebody pushes a README.
+Three runs carry a secret: the apply that creates the resource, the first time a
+setting needs a credential on a resource that already exists, and a rotation. Send
+none on any other run — a pipeline that passes its secrets every run restarts your
+service every time somebody pushes a README. Plan each of those three with the
+same `--secret` inputs: with no secret to write, a rotation plans as `NO_CHANGE`.
 
 ## Where the Gate Secret goes
 

package/dist/vfac.mjs

@@ -7932,8 +7932,9 @@ function renderOperation(operationId, data) {
     if (typeof retryable === "boolean") {
       const again = data["type"] === "PRODUCT_INSTANCE_UPGRADE" ? "`vfac lifecycle upgrade <pri_\u2026>`" : "`vfac lifecycle reconcile <pri_\u2026>`";
       const changeIt = data["type"] === "PRODUCT_INSTANCE_UPGRADE" ? "" : ", or `vfac apply` a corrected manifest";
+      const cause2 = failure["cause"];
       lines.push(
-        retryable ? `    Another attempt can succeed: ${again}.` : `    Repeating this unchanged fails again \u2014 fix what the lines above name, then ${again}${changeIt}.`
+        retryable ? `    Another attempt can succeed: ${again}.` : cause2 === "unknown" ? `    The platform could not classify this, so there is nothing here to correct. Read the whole record with \`vfac get operation ${operationId} --output json\`, and quote that id if you ask for help. Repeating it unchanged fails the same way.` : `    Repeating this unchanged fails again \u2014 fix what the lines above name, then ${again}${changeIt}.`
       );
     }
   }
@@ -13255,6 +13256,7 @@ function conditionHolds(condition, configuration) {
 // ../product-configuration/dist/customer-configuration-input.js
 var ABSOLUTE_MAX_STRING = MAX_DECLARABLE_STRING_LENGTH;
 var MAX_REPORTED_UNDECLARED_KEYS = 10;
+var UNDECLARED_SETTING_MESSAGE = "This Product does not declare a setting with that name.";
 function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -13338,7 +13340,7 @@ function validateObject(declaration, input, container, walk, root) {
   };
   const undeclared = Object.keys(input).filter((name) => !Object.hasOwn(declaration.properties, name));
   for (const name of undeclared.slice(0, MAX_REPORTED_UNDECLARED_KEYS)) {
-    report(walk, fieldFor(name), "This Product does not declare a setting with that name.");
+    report(walk, fieldFor(name), UNDECLARED_SETTING_MESSAGE);
   }
   if (undeclared.length > MAX_REPORTED_UNDECLARED_KEYS) {
     report(walk, container === null ? "" : container, `${undeclared.length - MAX_REPORTED_UNDECLARED_KEYS} further settings are not declared by this Product.`);
@@ -13604,7 +13606,11 @@ function checkString(field, property, value, issues) {
     return void 0;
   }
   if (property.pattern !== void 0 && !matches(property.pattern, value)) {
-    issues.push({ field, message: "Value is not in the required format." });
+    const expectation = property.description;
+    issues.push({
+      field,
+      message: expectation === void 0 ? "Value is not in the required format." : `Value is not in the required format. ${expectation.replace(/\s+$/, "")}`
+    });
     return void 0;
   }
   return value;
@@ -16801,8 +16807,16 @@ var MANIFEST_ACTIONS = [
   "ADOPT",
   /** The key names a resource and something in the document differs. */
   "UPDATE",
-  /** The key names a resource and the document matches it. A pipeline that runs
-   *  on every push and changes nothing reports this, and it is SUCCESS. */
+  /** The key names a resource and this REQUEST asks for nothing: no field
+   *  differs and no secret would be written.
+   *
+   *  NOT "the document matches it", which is how it read and is a stronger claim
+   *  than the planner makes. What a document OMITS is left alone rather than
+   *  compared — a manifest naming no connections answers this beside a resource
+   *  that holds several — so this never means the file mirrors stored state.
+   *
+   *  A pipeline that runs on every push and changes nothing reports it, and it
+   *  is SUCCESS. */
   "NO_CHANGE",
   /** `adopt` points at a resource that was DELETED. Its own verb, because both
    *  alternatives are wrong: `NO_CHANGE` would call a missing resource fine, and
@@ -17089,7 +17103,9 @@ function secretWriteConsequence(plan) {
   const lines = ["the value you send REPLACES the stored one, and the resource redeploys."];
   if (plan.action === "UPDATE" && (plan.changes ?? []).length === 0) {
     lines.push("Nothing else changed \u2014 sending a secret is itself the change.");
-    lines.push("Omit --secret on runs that are not rotating one to get NO_CHANGE.");
+    lines.push(
+      "Omit --secret on a run that is not setting or changing one; that is what answers NO_CHANGE."
+    );
   }
   return lines;
 }
@@ -17893,9 +17909,9 @@ async function runGet(parsed) {
       lines.push("", "  Outputs");
       const width = Math.max(...names.map((name) => name.length));
       for (const name of names) {
-        lines.push(
-          `    ${name.padEnd(width)}  ${isSecret2(name) ? "[secret]" : String(outputs[name] ?? "")}`
-        );
+        const value = outputs[name];
+        const shown = isSecret2(name) ? "[secret]" : value === void 0 || value === null ? "[not available]" : String(value);
+        lines.push(`    ${name.padEnd(width)}  ${shown}`);
         const meaning = declared.find((entry) => entry["key"] === name);
         const description = meaning?.["description"];
         if (typeof description === "string") {
@@ -18085,14 +18101,41 @@ function renderProduct(product) {
       lines.push(`    ${setting.label}  ${setting.type ?? ""}`.trimEnd());
     }
   }
-  const needed = (product.dependencies ?? []).filter((dependency) => dependency.required);
-  if (needed.length > 0) {
-    lines.push("", "  Requires a connection to another resource:");
-    for (const dependency of needed) {
-      lines.push(`    ${dependency.productId ?? "(a Product providing a service)"}`);
+  const dependencies = product.dependencies ?? [];
+  if (dependencies.length > 0) {
+    lines.push("", "  Connections to another resource");
+    for (const dependency of dependencies) {
+      const when = dependency.requiredWhen?.property;
+      const need = dependency.required ? "required" : when === void 0 ? "optional" : `required when ${when} is ${(dependency.requiredWhen?.anyOf ?? []).join(" or ")}`;
+      lines.push(`    ${dependency.key ?? "(no key)"}  ${need}`);
+      const capability = dependency.interface?.id;
+      if (capability !== void 0) {
+        lines.push(
+          `      ${capability}${dependency.interface?.version ? `/${dependency.interface.version}` : ""}`
+        );
+      } else if (dependency.productId !== void 0) {
+        lines.push(`      ${dependency.productId}`);
+      }
       if (dependency.reason) lines.push(`      ${dependency.reason}`);
     }
   }
+  const outputs = product.outputs ?? [];
+  if (outputs.length > 0) {
+    lines.push("", "  Publishes");
+    for (const output of outputs) {
+      lines.push(
+        `    ${output.key ?? ""}  ${output.secret === true ? "secret" : output.type ?? ""}`.trimEnd()
+      );
+    }
+  }
+  const conditions = product.conditions ?? [];
+  if (conditions.length > 0) {
+    lines.push("", "  Needs setting up outside the platform");
+    for (const condition of conditions) {
+      lines.push(`    ${condition.key ?? ""}  ${condition.displayName ?? ""}`.trimEnd());
+    }
+  }
+  lines.push("", "  `--output json` carries the whole declaration, this is a readable subset.");
   return lines.join("\n");
 }
 function wrap(text, width) {
@@ -18441,6 +18484,12 @@ Run \`vfac get product-instance pri_\u2026\` to see which ones this credential m
 `);
     return 2;
   }
+  if (parsed.booleans.has("wait")) {
+    process.stderr.write(
+      "`--wait` belongs to `vfac apply`; `vfac lifecycle` does not support it.\nThis command answers with an operation id. Follow it with:\n  vfac get operation op_\u2026\nand branch on the status it reports: SUCCEEDED, FAILED or CANCELLED. That\ncommand's exit code says whether the READ worked, never whether the operation\ndid \u2014 so a script that only checks the exit code reports a failed deploy as a\nsuccess.\n"
+    );
+    return 2;
+  }
   if (command === "delete" && !parsed.booleans.has("yes")) {
     process.stderr.write(
       `delete removes ${instanceId} and everything it is serving. This cannot be undone.
@@ -18547,7 +18596,7 @@ var USAGE = `vfac \u2014 deploy Varde Flyt resources from a manifest
   vfac manifest init --product <productId> --name <name> [--key <key>]
                      [--region <region>] [--profile <profile>]
   vfac validate -f resource.yaml
-  vfac plan     -f resource.yaml
+  vfac plan     -f resource.yaml [--secret NAME=env:VAR]
   vfac apply    -f resource.yaml [--secret NAME=env:VAR] [--adopt pri_\u2026] [--wait]
   vfac get product-instances
   vfac get product-instance pri_\u2026        what it is, and its outputs
@@ -18564,9 +18613,12 @@ Options
       --project   the Project to act in. Defaults to the stored context
       --endpoint  your organization's portal. Defaults to VFAC_ENDPOINT, then the
                   stored context
-      --secret    NAME=env:VARIABLE \u2014 the value is read from the environment.
-                  A value on the command line is in your shell history and in the
-                  process table, so it is refused
+      --secret    plan and apply: NAME=env:VARIABLE \u2014 the value is read from the
+                  environment. Plan a run that sets a secret with the same
+                  --secret inputs the apply will carry; without them the plan
+                  answers about a different request. A value on the command line
+                  is in your shell history and in the process table, so it is
+                  refused
       --product   which Product to write a starting manifest for
       --name      what a person will call the resource
       --key       its stable identity. Derived from --name when omitted

package/package.json

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