@varde-flyt/vfac 0.5.0 → 0.7.0

package/README.md

@@ -101,6 +101,37 @@ service, exactly as it resolves the service's own credentials. So there is no
 second copy to rotate, and no value for you to read — `vfac get product-instance`
 shows one as `[secret]`. `vfac guide` is authoritative.
 
+## Settings that go together
+
+A Product may declare that a group of settings is all-or-nothing: leave every one
+of them alone, or supply all of them. A provider connection is the usual shape —
+an address without its credential is worse than neither, because the service
+starts and then fails on its first call.
+
+```yaml
+spec:
+  configuration:
+    upstreamUrl: https://upstream.example.com
+    upstreamAccount: acct-9
+    # and the credential, beside the apply rather than in the file:
+    #   vfac apply -f resource.yaml --secret upstreamToken=env:UPSTREAM_TOKEN
+```
+
+Supply the whole group or none of it. A partial answer is refused, and the
+refusal names the setting that is missing and the one that made it necessary.
+
+`vfac manifest init` lists each group and seeds nothing for it — half a group is
+exactly the state that gets refused, so a placeholder would only produce a file
+that fails `vfac validate`.
+
+**`validate` and `plan` answer different questions here, and the difference is
+not a bug.** A manifest may never carry a secret, so `vfac validate` — which
+reads a file with no Project and no credential — cannot tell whether the
+credential in a group is configured, and does not refuse a document over it.
+`vfac plan` knows what the apply would carry and what the resource already holds,
+so it is where a missing member is reported. A credential the resource already
+holds does not have to be sent again to change one of its siblings.
+
 ## Connecting to another resource
 
 A Product may declare a **service dependency** — a connection to another service

package/dist/vfac.mjs

@@ -7880,14 +7880,26 @@ function renderOperation(operationId, data) {
     lines.push(`  Failed${typeof stage === "string" ? ` at ${stage}` : ""}`);
     const summary = failure["summary"];
     if (typeof summary === "string") lines.push(`    ${summary}`);
-    const detail = failure["detail"];
-    if (typeof detail === "string" && detail !== "") lines.push(`    ${detail}`);
     const cause = failure["cause"];
     if (typeof cause === "string") lines.push(`    cause: ${cause}`);
+    const services = failure["services"];
+    if (Array.isArray(services)) {
+      for (const entry of services) {
+        const one = asRecord(entry);
+        if (one === null) continue;
+        const dependency = one["dependency"];
+        if (typeof dependency !== "string" || dependency === "") continue;
+        const code = one["code"];
+        lines.push(
+          typeof code === "string" && code !== "" ? `    ${dependency} \u2014 the service reported: ${code}` : `    ${dependency} \u2014 the service reported nothing usable`
+        );
+      }
+    }
     const retryable = failure["retryable"];
     if (typeof retryable === "boolean") {
+      const again = data["type"] === "PRODUCT_INSTANCE_UPGRADE" ? "`vfac lifecycle upgrade <pri_\u2026>`" : "`vfac lifecycle reconcile <pri_\u2026>`";
       lines.push(
-        retryable ? "    Another attempt can succeed: `vfac lifecycle reconcile <pri_\u2026>`." : "    Another attempt will fail the same way. Change something first."
+        retryable ? `    Another attempt can succeed: ${again}.` : `    Repeating this unchanged fails again \u2014 fix what the lines above name, then ${again}.`
       );
     }
   }
@@ -12261,6 +12273,27 @@ var CustomerConfigurationObjectSchema = external_exports.object({
   type: external_exports.literal("object"),
   properties: external_exports.record(PropertyNameSchema, ConfigurationPropertySchema).describe("Customer-editable settings, keyed by camelCase property name."),
   required: external_exports.array(PropertyNameSchema).max(40).optional(),
+  /**
+   * Settings that must be configured TOGETHER, keyed by the one that triggers
+   * the requirement.
+   *
+   * `required` says a setting must always have a value. This says a group is
+   * either wholly absent or wholly complete — the shape a provider connection
+   * has, where an endpoint without its credential is worse than neither.
+   *
+   * JSON SCHEMA 2020-12 SEMANTICS, DELIBERATELY AND EXACTLY: if the trigger
+   * key is present in the submitted object, every name in its list must be
+   * present too. The key is published under its standard name in
+   * `schemas/product-definition.schema.json`, inside a node that already looks
+   * like JSON Schema, so a publisher running an off-the-shelf validator over
+   * that file must get the answer the platform gives. The refinement below is
+   * what keeps that promise true — see the `default` rule, which exists for
+   * this reason and no other.
+   *
+   * CYCLES ARE LEGAL. `{a: ["b"], b: ["a"]}` is how "all or none" is written,
+   * and refusing it would remove the primitive's main use.
+   */
+  dependentRequired: external_exports.record(PropertyNameSchema, external_exports.array(PropertyNameSchema).min(1).max(40)).optional().describe("Settings that must be supplied together, keyed by the triggering property."),
   /**
    * Literal `false`, not merely defaulted: docs/CONVENTIONS.md §8 requires
    * contracts to reject unknown fields, and an unknown key accepted here
@@ -12455,7 +12488,129 @@ var CustomerConfigurationSchema = CustomerConfigurationObjectSchema.superRefine(
       message: `Duplicate required entries: ${[...new Set(duplicates)].join(", ")}.`
     });
   }
+  checkDependentRequired(config, ctx);
 });
+function checkDependentRequired(config, ctx) {
+  const clauses = Object.entries(config.dependentRequired ?? {});
+  if (clauses.length === 0)
+    return;
+  if (clauses.length > MAX_CONFIGURATION_PROPERTIES) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["dependentRequired"],
+      message: `A Product may declare at most ${MAX_CONFIGURATION_PROPERTIES} dependent-required groups; found ${clauses.length}.`
+    });
+  }
+  for (const [trigger, dependents] of clauses) {
+    const path = ["dependentRequired", trigger];
+    const declaredTrigger = config.properties[trigger];
+    if (declaredTrigger === void 0) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `"${trigger}" requires other settings but is not a declared property.`
+      });
+    } else if (declaredTrigger.type !== "string") {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `"${trigger}" is a ${declaredTrigger.type} setting and cannot require others. Only a string setting can, because presence is the question this rule asks and a boolean or an empty list is an answer the customer gave rather than a setting they left alone.`
+      });
+    } else if (declaredTrigger.default !== void 0) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path,
+        message: `"${trigger}" declares a default, so it is never absent and would require the settings below of every customer unconditionally. Remove the default, or make the requirement unconditional with \`required\`.`
+      });
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const dependent of dependents) {
+      if (dependent === trigger) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${trigger}" cannot require itself.`
+        });
+        continue;
+      }
+      if (seen.has(dependent)) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${trigger}" lists "${dependent}" more than once.`
+        });
+        continue;
+      }
+      seen.add(dependent);
+      const declared = config.properties[dependent];
+      if (declared === void 0) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${trigger}" requires "${dependent}", which is not a declared property.`
+        });
+        continue;
+      }
+      if (declared.default !== void 0) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path,
+          message: `"${dependent}" declares a default, so it is never absent and this requirement could never fail. Remove the default, or drop it from this group.`
+        });
+      }
+    }
+  }
+  checkOneSecretPerGroup(config, ctx);
+}
+function checkOneSecretPerGroup(config, ctx) {
+  const clauses = Object.entries(config.dependentRequired ?? {});
+  if (clauses.length === 0)
+    return;
+  const neighbours = /* @__PURE__ */ new Map();
+  const link = (a, b) => {
+    if (!neighbours.has(a))
+      neighbours.set(a, /* @__PURE__ */ new Set());
+    neighbours.get(a).add(b);
+  };
+  for (const [trigger, dependents] of clauses) {
+    for (const dependent of dependents) {
+      link(trigger, dependent);
+      link(dependent, trigger);
+    }
+  }
+  const isSecret2 = (name) => {
+    const property = config.properties[name];
+    return property !== void 0 && property.type === "string" && property["x-secret"] === true;
+  };
+  const seen = /* @__PURE__ */ new Set();
+  for (const start of neighbours.keys()) {
+    if (seen.has(start))
+      continue;
+    const component = [];
+    const queue = [start];
+    seen.add(start);
+    while (queue.length > 0) {
+      const name = queue.pop();
+      component.push(name);
+      for (const next of neighbours.get(name) ?? []) {
+        if (seen.has(next))
+          continue;
+        seen.add(next);
+        queue.push(next);
+      }
+    }
+    const secrets = component.filter(isSecret2).sort();
+    if (secrets.length <= 1)
+      continue;
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      // The component has no single name, so the issue is reported against the
+      // map rather than against whichever member happened to be visited first.
+      path: ["dependentRequired"],
+      message: `These settings are configured together and include more than one secret (${secrets.join(", ")}). Only one secret can be supplied per change, so a group must ask for at most one \u2014 otherwise completing it on a running resource takes several, in an order the customer has to work out.`
+    });
+  }
+}
 function enumerableValues(property) {
   const out = [];
   if (property.type === "string") {
@@ -12490,8 +12645,9 @@ function isPlainObject(value) {
 function isSecretProperty(property) {
   return property.type === "string" && property["x-secret"] === true;
 }
-function validateSubmittedConfiguration(schema, submitted) {
+function validateSubmittedConfiguration(schema, submitted, presence = {}) {
   const issues = [];
+  const supplied = /* @__PURE__ */ new Set();
   if (submitted !== void 0 && submitted !== null && !isPlainObject(submitted)) {
     return {
       ok: false,
@@ -12522,6 +12678,8 @@ function validateSubmittedConfiguration(schema, submitted) {
     const blank = typeof input[name] === "string" && input[name].trim().length === 0;
     const present = Object.hasOwn(input, name) && input[name] !== void 0 && !blank;
     const secret = isSecretProperty(property);
+    if (present)
+      supplied.add(name);
     if (!present) {
       const fallback = secret ? void 0 : defaultOf(property);
       if (fallback !== void 0) {
@@ -12546,10 +12704,48 @@ function validateSubmittedConfiguration(schema, submitted) {
     }
     configuration[name] = checked;
   }
+  issues.push(...crossFieldIssues(schema, supplied, presence));
   if (issues.length > 0)
     return { ok: false, issues, partial: configuration };
   return { ok: true, configuration, secrets };
 }
+function crossFieldIssues(schema, supplied, presence) {
+  const clauses = Object.entries(schema.dependentRequired ?? {});
+  if (clauses.length === 0)
+    return [];
+  const alsoPresent = new Set(presence.present ?? []);
+  const unknown = new Set(presence.unknown ?? []);
+  const known = (name) => !unknown.has(name);
+  const held = (name) => supplied.has(name) || alsoPresent.has(name);
+  const issues = [];
+  const reported = /* @__PURE__ */ new Set();
+  for (const [trigger, dependents] of clauses) {
+    if (!known(trigger) || !held(trigger))
+      continue;
+    for (const dependent of dependents) {
+      if (!known(dependent) || held(dependent))
+        continue;
+      if (reported.has(dependent))
+        continue;
+      reported.add(dependent);
+      issues.push({
+        field: dependent,
+        message: `This setting is required when ${labelOf(schema, trigger)} is configured.`
+      });
+    }
+  }
+  return issues;
+}
+function labelOf(schema, name) {
+  const property = schema.properties[name];
+  return property === void 0 ? `"${name}"` : `"${property.title}"`;
+}
+function withoutCrossFieldRules(schema) {
+  if (schema.dependentRequired === void 0)
+    return schema;
+  const { dependentRequired: _removed, ...rest } = schema;
+  return rest;
+}
 function defaultOf(property) {
   switch (property.type) {
     case "string":
@@ -12698,6 +12894,14 @@ function seedConfiguration(configuration) {
   const values = {};
   const open = [];
   const requiredSecrets = [];
+  const groups = Object.entries(configuration?.dependentRequired ?? {}).map(([trigger, dependents]) => {
+    const members = [trigger, ...dependents];
+    return {
+      trigger,
+      settings: members.filter((name) => !isSecret(properties[name] ?? {})),
+      secrets: members.filter((name) => isSecret(properties[name] ?? {}))
+    };
+  }).sort((a, b) => a.trigger.localeCompare(b.trigger));
   for (const [name, declaration] of Object.entries(properties)) {
     if (isSecret(declaration)) {
       if (required.has(name))
@@ -12713,7 +12917,7 @@ function seedConfiguration(configuration) {
       open.push({ name, type: declaration.type ?? null });
     }
   }
-  return { values, open, requiredSecrets };
+  return { values, open, requiredSecrets, groups };
 }
 function productInstanceExample(input) {
   return {
@@ -13199,6 +13403,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.
@@ -13427,6 +13641,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.
    *
@@ -13493,6 +13717,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) {
@@ -13584,11 +13817,11 @@ var ProductDefinitionSchema = ProductDefinitionObjectSchema.superRefine((definit
       });
       return;
     }
-    const single = {
+    const single = withoutCrossFieldRules({
       ...definition.configuration,
       properties: { [condition.property]: property },
       required: [condition.property]
-    };
+    });
     const outside = condition.anyOf.filter((value) => !validateSubmittedConfiguration(single, { [condition.property]: value }).ok);
     if (outside.length > 0) {
       ctx.addIssue({
@@ -14676,6 +14909,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),
@@ -16420,6 +16680,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));
@@ -16893,6 +17174,13 @@ async function runManifestInit(parsed) {
       `spec.configuration.${setting.name}  \u2014 required${setting.type ? ` (${setting.type})` : ""}`
     );
   }
+  for (const group of seed.groups) {
+    const settings = group.settings.map((name2) => `spec.configuration.${name2}`);
+    const secrets = group.secrets.map((name2) => `--secret ${name2}=env:VAR`);
+    notes.push(
+      `${[...settings, ...secrets].join(" + ")}  \u2014 all of these together, or none of them`
+    );
+  }
   const document = productInstanceExample({
     name,
     ...key ? { key } : {},

package/package.json

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