@varde-flyt/vfac 0.10.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
 
@@ -91,13 +98,14 @@ identifier in a manifest that is yours: a resource key is 3–63 characters of
 lowercase letters, digits and hyphens, starting with a letter and ending with a
 letter or digit.
 
-**A key is claimed for good, and a delete does not release it.** The record of a
-deleted resource keeps its key, so a manifest that named it can never apply again
-— `vfac plan` answers `GONE` — and a replacement needs a different key. That is
-worth knowing before the delete rather than after it, because after it there is
-nothing to undo; `vfac lifecycle delete` says the same thing at the prompt. If
-what you want is to stop the service and keep the option of bringing it back,
-`vfac lifecycle suspend` is the reversible one.
+**A live resource holds its key, and a finished delete releases it.** The key
+stays claimed while the teardown runs, so nothing can take the name before the
+original is gone. Once the delete completes the name is free and the same
+manifest applies again — as a `CREATE`, building a NEW resource with nothing in
+it. Reuse is not a restore, which is worth knowing before the delete rather than
+after it: the apply succeeds, so nothing will stop you. `vfac lifecycle delete`
+says the same thing at the prompt. If what you want is to stop the service and
+keep its data, `vfac lifecycle suspend` is the reversible one.
 
 ## Reading a setting from another resource
 
@@ -175,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:
@@ -193,6 +202,44 @@ credential the connection delivers never appears in your manifest, in a plan, or
 in any `vfac` output — the providing service issues it and the platform stores
 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.
+
+```sh
+vfac product show <productId> --output json
+vfac plan -f resource.yaml --output json
+vfac get product-instance <productInstanceId> --output json
+vfac get product-instances --output json
+```
+
+**Decide from the action, not from the exit code.** A plan that REFUSES still
+exits 0: a plan reporting `UPGRADE_REQUIRED` did what it was asked, and the
+answer is "not like this". A job that reads only the exit code treats that as
+success and applies nothing.
+
+```sh
+ACTION="$(vfac plan -f resource.yaml --output json | jq -r .action)"
+```
+
+**And a non-zero exit is a real failure.** The code is not decoration: a
+`NO_CHANGE` against a resource that is not actually serving exits 1, with
+`--output json` as without it, because "nothing needed applying" and "it works"
+are different answers. Read the action for what the plan MEANS and the exit code
+for whether anything is WRONG — neither substitutes for the other.
+
+The envelopes are stable at the top level:
+
+| Command | Answers with |
+| --- | --- |
+| `vfac get product-instance <id> --output json` | `resource` and `lifecycle` — `status`, `outputs` and `conditions` are under `resource` |
+| `vfac get product-instances --output json` | `productInstances` and `nextCursor` |
+
+`vfac guide` is authoritative for what is inside them.
+
 ## Running it again
 
 **Send no secret.** A pipeline re-applies the same manifest on every push:
@@ -223,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,12 +16807,27 @@ 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",
-  /** The key names a resource that was DELETED. Its own verb, because both
+  /** `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
-   *  `CREATE` cannot be honoured while the tombstone holds the key. */
+   *  `CREATE` would silently ignore the `adopt` the caller asked for.
+   *
+   *  IT USED TO COVER A SECOND, COMMONER CASE: a manifest whose `metadata.key`
+   *  named a deleted resource, back when a key was claimed for ever. A completed
+   *  delete now releases the key, so that manifest is planned as a `CREATE` and
+   *  the verb narrowed to the one case a caller reaches by naming a `pri_…` by
+   *  hand. Kept in the vocabulary rather than removed: it is still produced, and
+   *  a Control Plane that still answers it must still be understood. */
   "GONE",
   /** The document pins a different release. Done through `:upgrade`, which has
    *  the Definition's own capability check, its own version resolution and its
@@ -17082,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;
 }
@@ -17886,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") {
@@ -18078,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) {
@@ -18434,11 +18484,18 @@ 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.
-If it was deployed from a manifest, its \`metadata.key\` stays claimed: a replacement
-needs a different key, and re-applying the same file will answer GONE.
+If it was deployed from a manifest, its \`metadata.key\` is held until this delete
+FINISHES, then released. Applying the same file afterwards creates a new, empty
+resource under that key. It does not bring this one back.
 Re-run with --yes to confirm:  vfac lifecycle delete ${instanceId} --yes
 Or suspend it instead, which stops it and keeps it: \`vfac lifecycle suspend\`.
 `
@@ -18539,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
@@ -18556,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
@@ -18597,7 +18657,10 @@ Authentication
 
 Exit codes
   0  done \u2014 including "no change", which is what a pipeline that changes nothing
-     should report
+     should report, AND including a plan that refuses. plan answers what would
+     happen; "it would be refused" is an answer, so it exits 0. Read the action,
+     not the code: vfac plan -f resource.yaml --output json, then branch on
+     .action
   1  refused, the request was wrong, or the resource matches your manifest and is
      NOT serving. "Nothing needed applying" is not the same as "it works", and a
      NO_CHANGE that could be a false green is the case this one exists for

package/package.json

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