@varde-flyt/vfac 0.10.0 → 0.11.0

package/README.md

@@ -91,13 +91,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
 
@@ -193,6 +194,43 @@ 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 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:

package/dist/vfac.mjs

@@ -16804,9 +16804,16 @@ var MANIFEST_ACTIONS = [
   /** 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. */
   "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
@@ -18437,8 +18444,9 @@ Run \`vfac get product-instance pri_\u2026\` to see which ones this credential m
   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\`.
 `
@@ -18597,7 +18605,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.11.0",
   "description": "Deploy and manage Varde Flyt Products from a manifest.",
   "repository": {
     "type": "git",