@varde-flyt/vfac 0.7.0 → 0.7.1

package/README.md

@@ -26,11 +26,19 @@ vfac guide
 vfac whoami
 ```
 
-`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` checks the endpoint, which Project this terminal has selected, 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.
+
+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
+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.
 
 `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.
@@ -73,6 +81,22 @@ 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.
 
+### `metadata.key` is the name you choose
+
+`manifest init` writes one into the file, derived from `--name`. It is what the
+platform recognises the resource by on every later apply, and it is the one
+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.
+
 ## Reading a setting from another resource
 
 A setting may take its value from an output another resource publishes, instead

package/dist/vfac.mjs

@@ -7424,22 +7424,46 @@ function parseArgs(argv) {
 }
 
 // src/config.ts
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+var salvaged = null;
+function salvagedConfigPath() {
+  return salvaged;
+}
 function configPath() {
   const base = process.env["VFAC_CONFIG_HOME"] ?? join(homedir(), ".config", "vfac");
   return join(base, "config.json");
 }
 function readStored(path = configPath()) {
+  let raw;
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof parsed !== "object" || parsed === null) return {};
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) throw new Error("not an object");
     return parsed;
   } catch {
+    salvage(path);
     return {};
   }
 }
+function salvage(path) {
+  const kept = `${path}.corrupt`;
+  try {
+    readFileSync(kept, "utf8");
+    return;
+  } catch {
+  }
+  try {
+    renameSync(path, kept);
+    salvaged = kept;
+  } catch {
+  }
+}
 function writeStored(next, path = configPath()) {
   const directory = dirname(path);
   mkdirSync(directory, { recursive: true, mode: 448 });
@@ -12875,6 +12899,11 @@ function matches(pattern, value) {
 var RESOURCE_API_VERSION = "resources.vardeflyt.no/v1";
 var PRODUCT_INSTANCE_KIND = "ProductInstance";
 
+// ../product-configuration/dist/resource-key.js
+var RESOURCE_KEY_PATTERN = /^[a-z][a-z0-9-]{1,61}[a-z0-9]$/;
+var RESOURCE_KEY_RULE = "A resource key is 3\u201363 characters of lowercase letters, digits and hyphens, starting with a letter and ending with a letter or digit.";
+var ResourceKeySchema = external_exports.string().regex(RESOURCE_KEY_PATTERN, RESOURCE_KEY_RULE).describe(RESOURCE_KEY_RULE);
+
 // ../product-configuration/dist/product-instance-example.js
 function resolveExampleChoice(options, selected, declaredDefault) {
   if (selected !== void 0)
@@ -12937,7 +12966,7 @@ function productInstanceExample(input) {
 }
 function exampleResourceKey(name) {
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^[^a-z]+/, "").replace(/-+$/, "").slice(0, 63);
-  return /^[a-z][a-z0-9-]{1,61}[a-z0-9]$/.test(slug) ? slug : "";
+  return RESOURCE_KEY_PATTERN.test(slug) ? slug : "";
 }
 
 // ../platform-schemas/dist/index.js
@@ -15701,17 +15730,15 @@ function isTerminalAction(action) {
 }
 var ManifestActionSchema = external_exports.enum(MANIFEST_ACTIONS);
 
-// ../product-contracts/dist/resource-key.js
-var ResourceKeySchema = external_exports.string().regex(/^[a-z][a-z0-9-]{1,61}[a-z0-9]$/, "A resource key is 3\u201363 characters of lowercase letters, digits and hyphens, starting with a letter and ending with a letter or digit.");
-
 // ../product-contracts/dist/resource-output-reference.js
+var OUTPUT_KEY_RULE = "Output keys are camelCase.";
 var ResourceOutputReferenceSchema = external_exports.object({
   valueFrom: external_exports.object({
     resourceOutput: external_exports.object({
       /** The producing Resource's `metadata.key`, in the same Project. */
       resourceKey: ResourceKeySchema,
       /** The key of an output that Resource's Product declares. */
-      output: external_exports.string().regex(/^[a-z][a-zA-Z0-9]{1,47}$/, "Output keys are camelCase.")
+      output: external_exports.string().regex(/^[a-z][a-zA-Z0-9]{1,47}$/, OUTPUT_KEY_RULE)
     }).strict()
   }).strict()
 }).strict();
@@ -16327,6 +16354,16 @@ async function runDoctor(parsed) {
   const json = parsed.flags["output"] === "json";
   const checks = [{ name: "CLI", ok: true, detail: `vfac ${cliVersion()}` }];
   const stored = readStored();
+  const salvaged2 = salvagedConfigPath();
+  if (salvaged2 !== null) {
+    checks.push({
+      name: "Config",
+      ok: true,
+      note: true,
+      detail: `the previous config could not be read and was kept at ${salvaged2}. What this command reports below is a fresh one \u2014 the endpoint and Project it held are gone until you set them again. Delete the kept file once you have; it may hold a stale session.`,
+      facts: { salvagedConfigPath: salvaged2 }
+    });
+  }
   const resolved = resolveEndpoint(parsed.flags["endpoint"], stored);
   if (!resolved) {
     checks.push({
@@ -16345,7 +16382,16 @@ async function runDoctor(parsed) {
   checks.push({
     name: "Endpoint",
     ok: true,
-    detail: `${endpoint}   (from ${resolved.source})`
+    detail: `${endpoint}   (from ${resolved.source})`,
+    facts: { endpoint, source: resolved.source }
+  });
+  const selected = 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 }
   });
   const probe = await probeMachineApi({ endpoint });
   if (!probe.ok) {
@@ -16391,7 +16437,8 @@ async function runDoctor(parsed) {
     access.tenantWide ? {
       name: "Access",
       ok: true,
-      detail: `the whole organization \u2014 ${access.tenantPermissions.join(", ")}`
+      detail: `the whole organization \u2014 ${access.tenantPermissions.join(", ")}`,
+      facts: { scope: "organization", grantedProjectIds: null }
     } : projects.length === 0 ? {
       // A FAILURE, NOT A NOTE. This credential authenticates and can do
       // nothing at all — and the check said so in words while `report`
@@ -16421,6 +16468,14 @@ async function runDoctor(parsed) {
       // believes it can deploy and is then refused reports a platform
       // defect, which is precisely the outcome the guide now tells it not
       // to reach for. Scope and role are two questions; this answers both.
+      facts: {
+        scope: "projects",
+        // THE GRANT, and the name says which of the two questions it
+        // answers. A reader gating on `doctor --output json` had no way
+        // to tell this list from the selected Project; now the field
+        // names are the difference.
+        grantedProjectIds: projects.join(",")
+      },
       detail: `${projects.join(", ")} \u2014 and nothing organization-wide. ` + (mutating.length > 0 ? "You can deploy in those Projects, read their catalogue, and list them. " : "Read-only there: catalogue, manifests, resources and operations. An apply or a lifecycle command is refused, and that is what was granted rather than a fault. ") + "Anything ACROSS the organization \u2014 a Project you hold nothing in, or its members \u2014 is refused."
     }
   );
@@ -17129,9 +17184,7 @@ async function runManifestInit(parsed) {
   const notes = [];
   const key = parsed.flags["key"] ?? exampleResourceKey(name);
   if (!key) {
-    notes.push(
-      "metadata.key     \u2014 a stable identity, 3 to 63 characters, lower case. Required before apply"
-    );
+    notes.push(`metadata.key     \u2014 a stable identity, required before apply. ${RESOURCE_KEY_RULE}`);
   }
   const chooseable = (product.dependencies ?? []).filter(
     (dependency) => dependency.interface?.cardinality === "tenant-multiple"
@@ -17260,6 +17313,8 @@ 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.
 Re-run with --yes to confirm:  vfac lifecycle delete ${instanceId} --yes
 Or suspend it instead, which stops it and keeps it: \`vfac lifecycle suspend\`.
 `

package/package.json

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