@varde-flyt/vfac 0.6.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
@@ -13403,6 +13432,16 @@ var ProductOutputSchema = external_exports.object({
    */
   secret: external_exports.boolean().optional()
 }).strict();
+var ProductConditionSchema = external_exports.object({
+  key: external_exports.string().regex(/^[a-z][a-zA-Z0-9]{1,47}$/, "Condition keys are camelCase.").describe("Stable key. A running instance reports its state under this key."),
+  displayName: external_exports.string().min(2).max(60),
+  /**
+   * What the customer must understand, and — when it is ACTION_REQUIRED —
+   * enough to act on. The platform never writes this sentence: it does not
+   * know what the condition is about.
+   */
+  description: external_exports.string().min(10).max(300)
+}).strict();
 var ProductDependencySchema = external_exports.object({
   /**
    * OPTIONAL ONLY WHEN `interface` IS PRESENT, enforced below.
@@ -13631,6 +13670,16 @@ var ProductDefinitionObjectSchema = external_exports.object({
   // --- Results, relationships, operations -------------------------------
   outputs: external_exports.array(ProductOutputSchema).min(1).max(MAX_PRODUCT_OUTPUTS),
   dependencies: external_exports.array(ProductDependencySchema).max(8),
+  /**
+   * Operational conditions a running instance of this Product may report.
+   *
+   * `.optional()`, NEVER `.default([])`. A default materialises the key,
+   * `contractDigest` digests the parsed object, and a republish of unchanged
+   * bytes would then be refused as `RELEASED_CONTRACT_MUTATED`. Absent means
+   * this Product reports none, which is what every Definition published
+   * before this field already means.
+   */
+  conditions: external_exports.array(ProductConditionSchema).min(1).max(8).optional(),
   /**
    * The service interfaces this Product provides to other Products.
    *
@@ -13697,6 +13746,15 @@ var ProductDefinitionSchema = ProductDefinitionObjectSchema.superRefine((definit
       });
     }
   });
+  const conditionKeys = (definition.conditions ?? []).map((condition) => condition.key);
+  const duplicateConditions = conditionKeys.filter((key, i) => conditionKeys.indexOf(key) !== i);
+  if (duplicateConditions.length > 0) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["conditions"],
+      message: `Duplicate condition keys: ${[...new Set(duplicateConditions)].join(", ")}.`
+    });
+  }
   const dependencyIds = definition.dependencies.map((dependency) => dependency.productId).filter((id) => id !== void 0);
   const duplicateDependencies = dependencyIds.filter((id, i) => dependencyIds.indexOf(id) !== i);
   if (duplicateDependencies.length > 0) {
@@ -14880,6 +14938,33 @@ var DeploymentBlueprintObjectSchema = external_exports.object({
   serviceExports: external_exports.array(ServiceExportSchema).max(MAX_SERVICE_EXPORTS).optional(),
   /** Service interfaces this Product consumes. Absent means none. */
   serviceBindings: external_exports.array(ServiceBindingSchema).max(MAX_SERVICE_BINDINGS).optional(),
+  /**
+   * Which of your own components may report an operational condition.
+   *
+   * NOT DECORATION, and the same policy `dynamicResources[].consumers` is. The
+   * Control Plane mints the condition-reporting credential only for a named
+   * component, so a Blueprint that names none has declared conditions in its
+   * Definition that nothing can reach. Delivery is the enforcement.
+   *
+   * `.optional()`, NEVER `.default([])` — `contractDigest` digests the parsed
+   * object, and a default would materialise the key on every Blueprint
+   * published before this field existed.
+   *
+   * EXACTLY ONE, and that is a property of what a condition IS rather than a
+   * limit somebody will want raised. A condition is keyed per INSTANCE, not
+   * per component: two components reporting `sso` write the same row and
+   * decide it between them by whichever clock is ahead, which is a race with
+   * a customer-visible answer. And "is this Product usable" is a statement
+   * about the instance — CLAUDE.md's "One Product Instance is ONE runtime
+   * unit" — so a second voice is a second opinion, not more coverage.
+   *
+   * It also keeps the platform's withdrawal honest. The watermark that stops
+   * a superseded runtime's answer being served is per instance, because what
+   * replaced the container is an instance-level event; with two reporters,
+   * redeploying one would withdraw the other's still-correct answer and it
+   * would never speak again.
+   */
+  conditionReporters: external_exports.array(ComponentIdSchema).min(1).max(1).optional(),
   secrets: external_exports.array(SecretWiringSchema).max(20),
   dataStores: external_exports.array(DataStoreSchema).max(8),
   egress: external_exports.array(EgressRuleSchema).max(24),
@@ -15645,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();
@@ -16271,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({
@@ -16289,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) {
@@ -16335,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`
@@ -16365,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."
     }
   );
@@ -16624,6 +16735,27 @@ async function runGet(parsed) {
     const declaredNames = declared.map((entry) => entry["key"]).filter((key2) => typeof key2 === "string");
     const names = [.../* @__PURE__ */ new Set([...Object.keys(outputs), ...declaredNames])].sort();
     const isSecret2 = (name) => declared.find((entry) => entry["key"] === name)?.["secret"] === true;
+    const conditions = Array.isArray(resource["conditions"]) ? resource["conditions"] : [];
+    if (conditions.length > 0) {
+      lines.push("", "  Operational");
+      const width = Math.max(
+        ...conditions.map((one) => String(one["displayName"] ?? one["key"] ?? "").length)
+      );
+      for (const one of conditions) {
+        const label = String(one["displayName"] ?? one["key"] ?? "");
+        const state = String(one["state"] ?? "UNKNOWN");
+        const reason = one["reason"];
+        lines.push(
+          `    ${label.padEnd(width)}  ${state}${typeof reason === "string" && reason !== "" ? `  (${reason})` : ""}`
+        );
+        const description = one["description"];
+        if (typeof description === "string") {
+          for (const line of wrapOutput(description, 68)) {
+            lines.push(`    ${" ".repeat(width)}  ${line}`);
+          }
+        }
+      }
+    }
     if (names.length > 0) {
       lines.push("", "  Outputs");
       const width = Math.max(...names.map((name) => name.length));
@@ -17052,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"
@@ -17183,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.6.0",
+  "version": "0.7.1",
   "description": "Deploy and manage Varde Flyt Products from a manifest.",
   "repository": {
     "type": "git",