@varde-flyt/vfac 0.3.1 → 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

@@ -12673,6 +12673,58 @@ function matches(pattern, value) {
   }
 }
 
+// ../product-configuration/dist/resource-api-version.js
+var RESOURCE_API_VERSION = "resources.vardeflyt.no/v1";
+var PRODUCT_INSTANCE_KIND = "ProductInstance";
+
+// ../product-configuration/dist/product-instance-example.js
+function isSecret(declaration) {
+  return declaration.writeOnly === true || declaration["x-secret"] === true;
+}
+function seedConfiguration(configuration) {
+  const properties = configuration?.properties ?? {};
+  const required = new Set(configuration?.required ?? []);
+  const values = {};
+  const open = [];
+  const requiredSecrets = [];
+  for (const [name, declaration] of Object.entries(properties)) {
+    if (isSecret(declaration)) {
+      if (required.has(name))
+        requiredSecrets.push(name);
+      continue;
+    }
+    if (declaration.default !== void 0) {
+      values[name] = declaration.default;
+      continue;
+    }
+    if (required.has(name)) {
+      values[name] = "";
+      open.push({ name, type: declaration.type ?? null });
+    }
+  }
+  return { values, open, requiredSecrets };
+}
+function productInstanceExample(input) {
+  return {
+    apiVersion: RESOURCE_API_VERSION,
+    kind: PRODUCT_INSTANCE_KIND,
+    // The key is spread rather than set, so an underivable one is ABSENT from
+    // the document instead of present and empty.
+    metadata: { name: input.name, ...input.key ? { key: input.key } : {} },
+    spec: {
+      productId: input.productId,
+      productVersion: input.productVersion,
+      region: input.region,
+      profile: input.profile,
+      configuration: input.configuration
+    }
+  };
+}
+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 : "";
+}
+
 // ../platform-schemas/dist/index.js
 var TENANT_KEY_REGEX = /^[a-z][a-z0-9-]{2,23}[a-z0-9]$/;
 var RESERVED_TENANT_KEYS = /* @__PURE__ */ new Set([
@@ -12763,10 +12815,8 @@ var OperationStatusSchema = external_exports.enum([
 
 // ../product-contracts/dist/api-version.js
 var PRODUCT_API_VERSION = "products.vardeflyt.no/v1";
-var RESOURCE_API_VERSION = "resources.vardeflyt.no/v1";
 var PRODUCT_DEFINITION_KIND = "ProductDefinition";
 var DEPLOYMENT_BLUEPRINT_KIND = "DeploymentBlueprint";
-var PRODUCT_INSTANCE_KIND = "ProductInstance";
 var ProductApiVersionSchema = external_exports.literal(PRODUCT_API_VERSION, {
   errorMap: () => ({
     message: `apiVersion must be "${PRODUCT_API_VERSION}". An unrecognized contract format is refused rather than ignored.`
@@ -15380,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,
@@ -15452,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),
@@ -15481,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();
 
@@ -15587,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:");
@@ -16170,13 +16280,13 @@ async function runGet(parsed) {
     const declared = Array.isArray(resource["outputDeclarations"]) ? resource["outputDeclarations"] : [];
     const declaredNames = declared.map((entry) => entry["key"]).filter((key2) => typeof key2 === "string");
     const names = [.../* @__PURE__ */ new Set([...Object.keys(outputs), ...declaredNames])].sort();
-    const isSecret = (name) => declared.find((entry) => entry["key"] === name)?.["secret"] === true;
+    const isSecret2 = (name) => declared.find((entry) => entry["key"] === name)?.["secret"] === true;
     if (names.length > 0) {
       lines.push("", "  Outputs");
       const width = Math.max(...names.map((name) => name.length));
       for (const name of names) {
         lines.push(
-          `    ${name.padEnd(width)}  ${isSecret(name) ? "[secret]" : String(outputs[name] ?? "")}`
+          `    ${name.padEnd(width)}  ${isSecret2(name) ? "[secret]" : String(outputs[name] ?? "")}`
         );
         const meaning = declared.find((entry) => entry["key"] === name);
         const description = meaning?.["description"];
@@ -16597,7 +16707,7 @@ async function runManifestInit(parsed) {
   if (!result.ok) return printError(result.error, parsed.flags["output"] === "json");
   const product = result.data;
   const notes = [];
-  const key = parsed.flags["key"] ?? keyFrom(name);
+  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"
@@ -16606,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 ?? [];
@@ -16663,43 +16760,24 @@ Product Deployment as Code v1 cannot express yet. Deploy it from the portal.
       offered.length === 0 ? `${product.productId} ${product.version} declares no service profile. Ask the publisher.` : `This Product offers several service profiles. Pass --profile <${offered.join("|")}>.`
     );
   }
-  const properties = product.configuration?.properties ?? {};
-  const required = product.configuration?.required ?? [];
-  const configuration = {};
-  for (const [property, declaration] of Object.entries(properties)) {
-    const secret = declaration.writeOnly === true || declaration["x-secret"] === true;
-    if (secret) {
-      if (required.includes(property)) {
-        notes.push(`--secret ${property}=env:VAR  \u2014 required, and never written to this file`);
-      }
-      continue;
-    }
-    if (declaration.default !== void 0) {
-      configuration[property] = declaration.default;
-      continue;
-    }
-    if (required.includes(property)) {
-      configuration[property] = "";
-      notes.push(`spec.configuration.${property}  \u2014 required${typeOf(declaration)}`);
-    }
+  const seed = seedConfiguration(product.configuration);
+  for (const property of seed.requiredSecrets) {
+    notes.push(`--secret ${property}=env:VAR  \u2014 required, and never written to this file`);
   }
-  const document = {
-    apiVersion: "resources.vardeflyt.no/v1",
-    kind: "ProductInstance",
-    // The key is spread rather than set, so an underivable one is ABSENT from
-    // the document instead of present and empty.
-    metadata: { name, ...key ? { key } : {} },
-    spec: {
-      productId: product.productId,
-      // PINNED, ALWAYS. The contract requires a version, and a document that
-      // tracked "newest" would redeploy a customer's resource because somebody
-      // else published.
-      productVersion: product.version,
-      region,
-      profile,
-      configuration
-    }
-  };
+  for (const setting of seed.open) {
+    notes.push(
+      `spec.configuration.${setting.name}  \u2014 required${setting.type ? ` (${setting.type})` : ""}`
+    );
+  }
+  const document = productInstanceExample({
+    name,
+    ...key ? { key } : {},
+    productId: product.productId,
+    productVersion: product.version,
+    region,
+    profile,
+    configuration: seed.values
+  });
   const checked = ProductInstanceTemplateSchema.safeParse(document);
   if (!checked.success) {
     const where = checked.error.issues.map((issue) => `  ${issue.path.join(".") || "(document)"}: ${issue.message}`).join("\n");
@@ -16723,13 +16801,6 @@ function refuse(message) {
 `);
   return 1;
 }
-function typeOf(declaration) {
-  return declaration.type ? ` (${declaration.type})` : "";
-}
-function keyFrom(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 : "";
-}
 
 // src/commands/guide.ts
 async function runGuide(parsed) {

package/package.json

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