@varde-flyt/vfac 0.3.2 → 0.5.0

package/README.md

@@ -26,8 +26,18 @@ vfac guide
 vfac whoami
 ```
 
-`doctor` checks the endpoint, the API, your credential and what that credential
-reaches, in that order, and reports the first thing that is actually wrong.
+`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` 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.
+That request is anonymous — no credential, no session, no endpoint, nothing
+identifying you — and it can never change the exit code, so an unreachable or
+blocked registry is reported and otherwise ignored. Set `VFAC_NO_UPDATE_CHECK` to
+any value to skip it entirely; nothing else in this tool makes that request.
 
 `vfac guide` is the documentation. It is served by the platform you are pointed
 at rather than bundled here, so it always describes the deployment in front of
@@ -91,6 +101,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

@@ -7670,7 +7670,9 @@ async function probeMachineApi(args) {
   }
   const authentication = payload["authentication"];
   const contextGate = typeof authentication === "object" && authentication !== null && typeof authentication["contextGate"] === "string" ? authentication["contextGate"] : null;
-  return { ok: true, service, apiVersion, contextGate };
+  const cli = payload["cli"];
+  const minimumCliVersion = typeof cli === "object" && cli !== null && typeof cli["minimumVersion"] === "string" ? cli["minimumVersion"] : null;
+  return { ok: true, service, apiVersion, contextGate, minimumCliVersion };
 }
 
 // src/manifest.ts
@@ -12678,6 +12680,15 @@ var RESOURCE_API_VERSION = "resources.vardeflyt.no/v1";
 var PRODUCT_INSTANCE_KIND = "ProductInstance";
 
 // ../product-configuration/dist/product-instance-example.js
+function resolveExampleChoice(options, selected, declaredDefault) {
+  if (selected !== void 0)
+    return options.includes(selected) ? { value: selected, issue: null } : { value: null, issue: "invalid" };
+  if (declaredDefault !== void 0 && options.includes(declaredDefault))
+    return { value: declaredDefault, issue: null };
+  if (options.length === 1)
+    return { value: options[0], issue: null };
+  return { value: null, issue: options.length === 0 ? "unavailable" : "required" };
+}
 function isSecret(declaration) {
   return declaration.writeOnly === true || declaration["x-secret"] === true;
 }
@@ -15430,18 +15441,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 +15538,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 +15567,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 +15693,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:");
@@ -15676,9 +15747,9 @@ async function runApply(verb, parsed, deps = {}) {
     process.stderr.write("Which manifest? Use -f <file>.\n");
     return 2;
   }
-  const manifest = readManifest(file);
-  if (!manifest.ok) {
-    process.stderr.write(`${manifest.message}
+  const manifest2 = readManifest(file);
+  if (!manifest2.ok) {
+    process.stderr.write(`${manifest2.message}
 `);
     return 2;
   }
@@ -15704,7 +15775,7 @@ async function runApply(verb, parsed, deps = {}) {
   const json = parsed.flags["output"] === "json";
   const path = `/api/v1/projects/${encodeURIComponent(projectId)}/manifest`;
   const envelope = {
-    template: manifest.document,
+    template: manifest2.document,
     ...Object.keys(secrets.secrets).length > 0 ? { secrets: secrets.secrets } : {},
     ...parsed.flags["adopt"] ? { adopt: parsed.flags["adopt"] } : {}
   };
@@ -15716,7 +15787,7 @@ async function runApply(verb, parsed, deps = {}) {
       token: session.ready.token,
       // The DOCUMENT, not the envelope: `validate` asks whether a file is well
       // formed, which is a question about the file and not about a request.
-      body: { verb: "validate", payload: manifest.document }
+      body: { verb: "validate", payload: manifest2.document }
     });
     if (!result.ok) return printError(result.error, json);
     process.stdout.write(
@@ -15789,7 +15860,7 @@ Read the operation that failed: \`vfac get operation <id>\`, or \`vfac get produ
     body: { verb: "apply", action, payload: envelope }
   });
   if (!applied.ok) return printError(applied.error, json);
-  const key = manifestKeyOf(manifest.document) ?? planned.data.manifestKey ?? "(unnamed)";
+  const key = manifestKeyOf(manifest2.document) ?? planned.data.manifestKey ?? "(unnamed)";
   const rawOperationId = applied.data["operationId"];
   const operationId = typeof rawOperationId === "string" && rawOperationId !== "" ? rawOperationId : null;
   if (!parsed.booleans.has("wait")) {
@@ -15933,17 +16004,63 @@ Project   ${projectId ?? "(none)"}
 
 // src/version.ts
 import { readFileSync as readFileSync3 } from "node:fs";
-function cliVersion() {
+function manifest() {
   try {
-    const manifest = JSON.parse(
+    const parsed = JSON.parse(
       readFileSync3(new URL("../package.json", import.meta.url), "utf8")
     );
-    const version = typeof manifest === "object" && manifest !== null ? manifest["version"] : void 0;
-    return typeof version === "string" ? version : "unknown";
+    return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
-    return "unknown";
+    return null;
   }
 }
+function cliVersion() {
+  const version = manifest()?.["version"];
+  return typeof version === "string" ? version : "unknown";
+}
+function cliPackageName() {
+  const name = manifest()?.["name"];
+  return typeof name === "string" ? name : null;
+}
+function cliInstallCommand() {
+  const name = cliPackageName();
+  return name === null ? null : `npm install -g ${name}`;
+}
+
+// src/registry.ts
+var UPDATE_CHECK_TIMEOUT_MS = 3e3;
+var REGISTRY_ORIGIN = "https://registry.npmjs.org";
+var UPDATE_CHECK_OPT_OUT = "VFAC_NO_UPDATE_CHECK";
+async function latestPublishedVersion(args) {
+  const env = args?.env ?? process.env;
+  if (env[UPDATE_CHECK_OPT_OUT]) return { ok: false };
+  const name = cliPackageName();
+  if (name === null) return { ok: false };
+  const doFetch = args?.fetchImpl ?? fetch;
+  let response;
+  try {
+    response = await doFetch(`${REGISTRY_ORIGIN}/-/package/${encodeURIComponent(name)}/dist-tags`, {
+      method: "GET",
+      redirect: "manual",
+      signal: signal()
+    });
+  } catch {
+    return { ok: false };
+  }
+  if (!response.ok) return { ok: false };
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    return { ok: false };
+  }
+  if (typeof payload !== "object" || payload === null) return { ok: false };
+  const latest = payload["latest"];
+  return typeof latest === "string" && latest !== "" ? { ok: true, latest } : { ok: false };
+}
+function signal() {
+  return typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS) : void 0;
+}
 
 // src/commands/doctor.ts
 async function runDoctor(parsed) {
@@ -15976,6 +16093,9 @@ async function runDoctor(parsed) {
     return report(checks, json);
   }
   checks.push({ name: "Machine API", ok: true, detail: probe.apiVersion });
+  const compatible = compatibility(cliVersion(), probe.minimumCliVersion);
+  checks.push(compatible);
+  if (!compatible.ok) return report(checks, json);
   const signedIn = await signIn({ endpoint });
   if (!signedIn.ok) {
     checks.push({ name: "Context Gate", ok: false, detail: signedIn.message });
@@ -16050,8 +16170,87 @@ async function runDoctor(parsed) {
     note: true,
     detail: "run `vfac guide` for the platform's own instructions, written for a machine"
   });
+  checks.push(await updateAvailable(cliVersion()));
   return report(checks, json);
 }
+function compatibility(local, declared) {
+  const name = "Compatibility";
+  const facts = { version: local, minimumVersion: declared };
+  if (declared === null) {
+    return {
+      name,
+      ok: true,
+      detail: "this Tenant Portal names no minimum version, so there is nothing to check against.",
+      facts
+    };
+  }
+  if (!PLAIN_SEMVER_REGEX.test(declared)) {
+    return {
+      name,
+      ok: true,
+      note: true,
+      detail: `this Tenant Portal asks for "${declared}", which is not a version this client can read. Treated as no requirement rather than as a refusal.`,
+      facts
+    };
+  }
+  if (!PLAIN_SEMVER_REGEX.test(local)) {
+    return {
+      name,
+      ok: true,
+      note: true,
+      detail: `this build does not report its own version, so it cannot be checked against the vfac ${declared} this Tenant Portal requires.`,
+      facts
+    };
+  }
+  if (compareSemver(local, declared) >= 0) {
+    return { name, ok: true, detail: `OK \u2014 requires vfac ${declared} or newer`, facts };
+  }
+  const install = cliInstallCommand();
+  return {
+    name,
+    ok: false,
+    detail: `UPGRADE REQUIRED. This Tenant Portal supports vfac ${declared} and newer; this is ${local}. ` + (local.includes("-") ? `A prerelease sorts below the release it is named for, so ${local} does not satisfy ${declared}. ` : "") + (install === null ? "" : `Run: ${install}`),
+    facts
+  };
+}
+async function updateAvailable(local) {
+  const name = "Update";
+  const result = await latestPublishedVersion();
+  if (!result.ok) {
+    return {
+      name,
+      ok: true,
+      detail: "could not check for updates",
+      facts: { version: local, latest: null }
+    };
+  }
+  const facts = { version: local, latest: result.latest };
+  if (!PLAIN_SEMVER_REGEX.test(local) || !PLAIN_SEMVER_REGEX.test(result.latest)) {
+    return {
+      name,
+      ok: true,
+      detail: `the latest published release is vfac ${result.latest}`,
+      facts
+    };
+  }
+  const order = compareSemver(local, result.latest);
+  if (order > 0) {
+    return {
+      name,
+      ok: true,
+      detail: `vfac ${local} is ahead of the latest release (${result.latest})`,
+      facts
+    };
+  }
+  if (order === 0) return { name, ok: true, detail: `vfac ${local} is the latest release`, facts };
+  return {
+    name,
+    ok: true,
+    note: true,
+    detail: `vfac ${result.latest} is available (running ${local})`,
+    facts
+  };
+}
 function report(checks, json) {
   const failed = checks.filter((check) => !check.ok);
   if (json) {
@@ -16656,63 +16855,35 @@ 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 ?? [];
   const chosenRegion = parsed.flags["region"];
-  let region;
-  if (chosenRegion !== void 0) {
-    if (!regions.includes(chosenRegion)) {
-      return refuse(
-        `${product.productId} ${product.version} does not offer the region "${chosenRegion}".${regions.length > 0 ? ` It offers: ${regions.join(", ")}.` : ""}`
-      );
-    }
-    region = chosenRegion;
-  } else if (regions.length === 1) {
-    region = regions[0];
-  } else {
+  const regionChoice = resolveExampleChoice(regions, chosenRegion);
+  if (regionChoice.value === null) {
     return refuse(
-      regions.length === 0 ? `${product.productId} ${product.version} declares no region. Ask the publisher.` : `This Product offers several regions. Pass --region <${regions.join("|")}>.`
+      regionChoice.issue === "invalid" ? `${product.productId} ${product.version} does not offer the region "${chosenRegion}".${regions.length > 0 ? ` It offers: ${regions.join(", ")}.` : ""}` : regionChoice.issue === "unavailable" ? `${product.productId} ${product.version} declares no region. Ask the publisher.` : `This Product offers several regions. Pass --region <${regions.join("|")}>.`
     );
   }
+  const region = regionChoice.value;
   const profiles = product.profiles ?? [];
   const offered = profiles.map((entry) => entry.id);
   const chosenProfile = parsed.flags["profile"];
-  const declaredDefault = profiles.find((entry) => entry.default === true);
-  let profile;
-  if (chosenProfile !== void 0) {
-    if (!offered.includes(chosenProfile)) {
-      return refuse(
-        `${product.productId} ${product.version} does not offer the service profile "${chosenProfile}".${offered.length > 0 ? ` It offers: ${offered.join(", ")}.` : ""}`
-      );
-    }
-    profile = chosenProfile;
-  } else if (declaredDefault) {
-    profile = declaredDefault.id;
-  } else if (offered.length === 1) {
-    profile = offered[0];
-  } else {
+  const profileChoice = resolveExampleChoice(
+    offered,
+    chosenProfile,
+    profiles.find((entry) => entry.default === true)?.id
+  );
+  if (profileChoice.value === null) {
     return refuse(
-      offered.length === 0 ? `${product.productId} ${product.version} declares no service profile. Ask the publisher.` : `This Product offers several service profiles. Pass --profile <${offered.join("|")}>.`
+      profileChoice.issue === "invalid" ? `${product.productId} ${product.version} does not offer the service profile "${chosenProfile}".${offered.length > 0 ? ` It offers: ${offered.join(", ")}.` : ""}` : profileChoice.issue === "unavailable" ? `${product.productId} ${product.version} declares no service profile. Ask the publisher.` : `This Product offers several service profiles. Pass --profile <${offered.join("|")}>.`
     );
   }
+  const profile = profileChoice.value;
   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`);
@@ -16932,9 +17103,12 @@ Options
       --output    json, for a pipeline that reads the answer
 
 Diagnosing
-  vfac doctor   checks the endpoint, the machine API, the credential and what
-                that credential can reach \u2014 in that order, so the first thing
-                that is actually wrong is the thing it reports
+  vfac doctor   checks the endpoint, the machine API, whether this client is new
+                enough for that platform, the credential and what that credential
+                can reach \u2014 in that order, so the first thing that is actually
+                wrong is the thing it reports. It ends by asking npm whether a
+                newer vfac has been published, which is a note and never a
+                failure. Set VFAC_NO_UPDATE_CHECK to skip that one request
   vfac whoami   what this credential is, and which Project scopes it has been
                 GRANTED. A credential scoped to one Project deploys fine and
                 cannot make organization-wide reads \u2014 this is where that is said.

package/package.json

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