@varde-flyt/vfac 0.3.2 → 0.4.0

package/README.md

@@ -91,6 +91,41 @@ 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.
 
+## Connecting to another resource
+
+A Product may declare a **service dependency** — a connection to another service
+that signs your people in, or that it looks a directory up in. When the platform
+says the customer chooses which resource provides it, name that resource:
+
+```yaml
+spec:
+  dependencyBindings:
+    <dependency-key>:
+      resourceKey: the-providing-resource
+      projectId: prj_…            # only if it is in another Project
+```
+
+`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.
+
+This is not the same thing as the section above, and the difference is worth
+holding on to:
+
+| | |
+| --- | --- |
+| `valueFrom.resourceOutput` | read a value another resource publishes |
+| `dependencyBindings` | use that resource as the PROVIDER for a declared dependency |
+
+A connection is established once. **A manifest can make one and cannot move
+one**: pointing an existing connection at a different resource is refused rather
+than performed, because a file you re-apply on every push must not be able to
+silently move a running service onto a different identity provider. The
+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.
+
 ## Running it again
 
 **Send no secret.** A pipeline re-applies the same manifest on every push:

package/dist/vfac.mjs

@@ -15430,18 +15430,43 @@ 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 ResourceOutputReferenceSchema = external_exports.object({
   valueFrom: external_exports.object({
     resourceOutput: external_exports.object({
       /** The producing Resource's `metadata.key`, in the same Project. */
-      resourceKey: 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."),
+      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.")
     }).strict()
   }).strict()
 }).strict();
 
+// ../product-contracts/dist/dependency-binding.js
+var DependencyBindingSelectorSchema = external_exports.object({
+  /** The providing Resource's `metadata.key`. */
+  resourceKey: ResourceKeySchema,
+  /**
+   * The Project that Resource lives in. Absent means the consumer's own.
+   *
+   * PRESENT BECAUSE A BINDING IS TENANT-SCOPED AND A PROJECT IS NOT A RUNTIME
+   * BOUNDARY: a provider anywhere in the Tenant can satisfy a consumer
+   * anywhere in it, and that has been true since bindings existed. What the
+   * field does NOT do is grant anything — the Control Plane opens that
+   * Project from the caller's own assertion, and a Project the caller holds
+   * nothing in answers exactly as a Project that does not exist.
+   *
+   * A plain bounded string, exactly as `spec.projectId` is: an id that does
+   * not name a readable Project is refused where the refusal can be phrased
+   * without leaking, which is not here.
+   */
+  projectId: external_exports.string().min(1).max(64).optional()
+}).strict();
+var DependencyBindingsSchema = external_exports.record(ServiceBindingKeySchema, DependencyBindingSelectorSchema);
+
 // ../product-contracts/dist/product-instance-template.schema.js
 var ProductInstanceTemplateSchema = external_exports.object({
   apiVersion: ResourceApiVersionSchema,
@@ -15502,7 +15527,7 @@ var ProductInstanceTemplateSchema = external_exports.object({
      * Shaped like a DNS label: it becomes a database predicate and a log
      * field, and neither wants free text.
      */
-    key: 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.").optional()
+    key: ResourceKeySchema.optional()
   }).strict(),
   spec: external_exports.object({
     productId: external_exports.string().min(1).max(64),
@@ -15531,7 +15556,27 @@ var ProductInstanceTemplateSchema = external_exports.object({
      * configuration schema by `resolveTemplate`, which is where the real
      * shape lives — it differs per Product, so it cannot be stated here.
      */
-    configuration: external_exports.record(external_exports.unknown()).optional()
+    configuration: external_exports.record(external_exports.unknown()).optional(),
+    /**
+     * Which Resource satisfies each declared service dependency.
+     *
+     * A RESOURCE RELATION, NOT A SETTING, which is why it is a sibling of
+     * `configuration` rather than a key inside it. `configuration` is the
+     * Product's own settings and is validated against the Definition's
+     * schema; this names another Resource, and the create envelope made the
+     * identical split for the identical reason.
+     *
+     * OPTIONAL, PERMANENTLY. Every manifest written before this field
+     * existed omits it, and absence has to keep meaning "leave the
+     * connections alone" — otherwise re-applying an unchanged file would
+     * release a binding somebody made in the portal.
+     *
+     * The keys the platform will ACCEPT here are narrower than the shape:
+     * only a dependency whose interface the registry calls
+     * `tenant-multiple` is one a customer chooses. `resolveTemplate` says
+     * so against the pinned Definition, so the refusal names the field.
+     */
+    dependencyBindings: DependencyBindingsSchema.optional()
   }).strict()
 }).strict();
 
@@ -15637,6 +15682,21 @@ function printPlan(plan, json) {
       `      from ${reference.resourceKey}.${reference.output}${reference.secret ? " [secret]" : ""}`
     );
   }
+  const bindings = plan.dependencyBindings ?? [];
+  if (bindings.length > 0) {
+    lines.push("  dependency bindings:");
+    for (const binding of bindings) {
+      lines.push(`    ${binding.dependencyKey}`);
+      lines.push(
+        `      resource:  ${binding.resourceKey}${binding.projectId ? ` (in ${binding.projectId})` : ""}`
+      );
+      if (binding.interfaceId !== void 0) {
+        lines.push(
+          `      interface: ${binding.interfaceId}${binding.interfaceVersion ? `/${binding.interfaceVersion}` : ""}`
+        );
+      }
+    }
+  }
   const required = plan.requiredSecrets ?? [];
   if (required.length > 0) {
     lines.push("  required secrets:");
@@ -16656,23 +16716,10 @@ async function runManifestInit(parsed) {
   const chooseable = (product.dependencies ?? []).filter(
     (dependency) => dependency.interface?.cardinality === "tenant-multiple"
   );
-  const mustChoose = chooseable.filter((dependency) => dependency.required === true);
-  if (mustChoose.length > 0) {
-    process.stderr.write(
-      `${product.productId} requires a customer-selected service dependency that
-Product Deployment as Code v1 cannot express yet. Deploy it from the portal.
-`
-    );
-    for (const dependency of mustChoose) {
-      process.stderr.write(`  ${dependency.interface?.id ?? "a service"}`);
-      process.stderr.write(dependency.reason ? `  \u2014 ${dependency.reason}
-` : "\n");
-    }
-    return 1;
-  }
   for (const dependency of chooseable) {
+    const property = dependency.key === void 0 ? "spec.dependencyBindings.<key>.resourceKey" : `spec.dependencyBindings.${dependency.key}.resourceKey`;
     notes.push(
-      `${dependency.interface?.id ?? "a service connection"}  \u2014 optional here, but this Product may require it depending on your settings. A manifest cannot supply one yet`
+      `${property}  \u2014 ${dependency.required === true ? "required" : "optional, unless your settings make it required"}${dependency.interface?.id ? `. Provides ${dependency.interface.id}` : ""}. Name an existing resource: vfac get product-instances`
     );
   }
   const regions = product.supportedRegions ?? [];

package/package.json

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