@farthershore/product 0.0.0 → 0.1.0

package/dist/bin.js

@@ -27,6 +27,97 @@ var ManifestBuilderError = class extends Error {
   }
 };
 
+// src/resource-graph.ts
+var ManifestResourceGraph = class {
+  nodes = /* @__PURE__ */ new Map();
+  declarationOrder = 0;
+  register(kind, key, value, dependsOn = []) {
+    const id = nodeId(kind, key);
+    if (this.nodes.has(id)) {
+      throw new Error(`duplicate resource node ${id}`);
+    }
+    const node = {
+      urn: resourceUrn(kind, key),
+      kind,
+      key,
+      value,
+      dependsOn: [...new Set(dependsOn)],
+      declarationOrder: this.declarationOrder
+    };
+    this.declarationOrder += 1;
+    this.nodes.set(id, node);
+    return node;
+  }
+  upsert(kind, key, value, dependsOn = []) {
+    const id = nodeId(kind, key);
+    const existing = this.nodes.get(id);
+    if (!existing) {
+      return this.register(kind, key, value, dependsOn);
+    }
+    const node = {
+      urn: existing.urn,
+      kind,
+      key,
+      value,
+      dependsOn: [...new Set(dependsOn)],
+      declarationOrder: existing.declarationOrder
+    };
+    this.nodes.set(id, node);
+    return node;
+  }
+  clearKind(kind) {
+    for (const [id, node] of this.nodes.entries()) {
+      if (node.kind === kind) this.nodes.delete(id);
+    }
+  }
+  has(kind, key) {
+    return this.nodes.has(nodeId(kind, key));
+  }
+  get(kind, key) {
+    return this.nodes.get(nodeId(kind, key)) ?? null;
+  }
+  values(kind) {
+    return [...this.nodes.values()].filter((node) => node.kind === kind).map((node) => node.value);
+  }
+  sortedValues(kind, key) {
+    return sortBy(this.values(kind), key);
+  }
+  snapshot() {
+    return {
+      nodes: sortBy([...this.nodes.values()], (node) => node.urn).map(
+        ({ value: _value, ...node }) => node
+      )
+    };
+  }
+  missingDependencies() {
+    const known = new Set([...this.nodes.values()].map((node) => node.urn));
+    return [...this.nodes.values()].flatMap(
+      (node) => node.dependsOn.filter((dependency) => !known.has(dependency)).map((dependency) => ({
+        from: node.urn,
+        missing: dependency
+      }))
+    );
+  }
+};
+function resourceUrn(kind, key) {
+  return `urn:farthershore:product:${kind}:${encodeURIComponent(
+    key
+  )}`;
+}
+function resourceDependency(kind, key) {
+  return resourceUrn(kind, key);
+}
+function nodeId(kind, key) {
+  return `${kind}:${key}`;
+}
+function sortBy(items, key) {
+  return [...items].sort((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+}
+
 // ../contracts/dist/plans/limits-schema.js
 import { z } from "zod";
 var limitDimensionSchema = z.string().min(1);
@@ -1251,6 +1342,77 @@ var featureCatalogEntrySchema = z13.object({
   plans: z13.array(z13.string().min(1)).min(1).max(20)
 });
 var featureCatalogSchema = z13.record(z13.string().min(1).max(100).regex(/^[a-z0-9_.:-]+$/), featureCatalogEntrySchema);
+var productCleanupPolicyModeSchema = z13.enum([
+  "report",
+  "pull_request"
+]);
+var productChangeApprovalRiskSchema = z13.enum([
+  "safe",
+  "non_blocking",
+  "economic_risk",
+  "blocking"
+]);
+var productOperatorPoliciesSchema = z13.object({
+  /**
+   * Route cleanup operator. Disabled by default; report-mode is the safe
+   * default so a product can surface zero-traffic runtime-route candidates
+   * before it opts into draft PR mutation.
+   */
+  cleanup: z13.object({
+    enabled: z13.boolean().default(false),
+    mode: productCleanupPolicyModeSchema.default("report")
+  }).default({ enabled: false, mode: "report" }),
+  /**
+   * PR approval thresholds for manifest impact reports. This schema makes
+   * the policy a first-class product-as-code field even while enforcement is
+   * still report/label-only.
+   */
+  change_approval: z13.object({
+    auto_merge_max_risk: z13.enum(["none", "safe", "non_blocking"]).default("none"),
+    require_human_for: z13.array(productChangeApprovalRiskSchema).default(["economic_risk", "blocking"])
+  }).default({
+    auto_merge_max_risk: "none",
+    require_human_for: ["economic_risk", "blocking"]
+  })
+}).default({
+  cleanup: { enabled: false, mode: "report" },
+  change_approval: {
+    auto_merge_max_risk: "none",
+    require_human_for: ["economic_risk", "blocking"]
+  }
+});
+var customerIdentityRequirementSchema = z13.enum([
+  "org_only",
+  "org_and_user"
+]);
+var customerPortalAuthStrategySchema = z13.enum([
+  "clerk",
+  "test-personas"
+]);
+var productCustomerContextSchema = z13.object({
+  /**
+   * Edge credential identity policy. This is intentionally Product-scoped:
+   * B7 keeps Product as the business boundary and avoids customer-side
+   * Workspace/subject models until per-subject entitlements need them.
+   */
+  identity_requirement: customerIdentityRequirementSchema.optional(),
+  /**
+   * Enables signed customer-context tokens (`fsc_*`) without putting the
+   * runtime signing secret in product.config.ts. Core generates/preserves the
+   * secret when this is true and clears it when explicitly false.
+   */
+  context_tokens: z13.object({
+    enabled: z13.boolean().default(true)
+  }).optional(),
+  /**
+   * Portal auth strategy for environment-scoped product applies. Production
+   * portal auth is provisioner-owned; preview/test environments can opt into
+   * test personas through Product-as-Code.
+   */
+  portal_auth: z13.object({
+    strategy: customerPortalAuthStrategySchema
+  }).optional()
+});
 var productSpecSchema = z13.object({
   product: z13.object({
     name: z13.string().min(1).max(100),
@@ -1282,6 +1444,8 @@ var productSpecSchema = z13.object({
   }).optional(),
   features: featureCatalogSchema.optional(),
   resources: countedResourcesSchema,
+  policies: productOperatorPoliciesSchema,
+  customer_context: productCustomerContextSchema.optional(),
   /**
    * Track B4 — Declarative frontend surface. Product code can declare
    * template-owned nav/pages composed from known portal components. The
@@ -1997,6 +2161,8 @@ var productSpecV2Schema = z20.object({
   frontend: frontendManifestSchema.optional(),
   migrations: migrationDeclsSchema.optional(),
   resources: countedResourcesSchema,
+  policies: productOperatorPoliciesSchema,
+  customer_context: productCustomerContextSchema.optional(),
   billing: z20.object({
     gracePeriodDays: z20.number().int().nonnegative().default(3),
     // When true (default), a plan limit INCREASE re-projects onto active
@@ -2194,7 +2360,7 @@ function hashIr(ir) {
 }
 
 // src/version.ts
-var SDK_VERSION = true ? "0.0.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "0.1.0" : "0.0.0-dev";
 
 // src/business.ts
 var BUSINESS_BRAND = Symbol.for("farthershore.product.business");
@@ -2243,13 +2409,7 @@ var Business = class {
   [BUSINESS_BRAND] = true;
   name;
   options;
-  meters = /* @__PURE__ */ new Map();
-  resources = /* @__PURE__ */ new Map();
-  plans = /* @__PURE__ */ new Map();
-  features = /* @__PURE__ */ new Map();
-  policies = /* @__PURE__ */ new Map();
-  capabilities = /* @__PURE__ */ new Map();
-  migrations = [];
+  graph = new ManifestResourceGraph();
   frontendManifest;
   productPatch = {};
   /** Sugar for binding API routes to features. */
@@ -2269,16 +2429,21 @@ var Business = class {
     }
     this.name = name;
     this.options = options;
+    this.graph.register("product", name, {
+      name,
+      options
+    });
     this.api = {
       route: (match, options2) => {
         const featureKey = keyOf(options2.feature);
-        const file = this.features.get(featureKey);
+        const file = this.getFeatureFile(featureKey);
         if (!file) {
           throw new ManifestBuilderError(
             `api.route("${match}"): feature "${featureKey}" is not declared \u2014 call business.feature("${featureKey}", \u2026) first`
           );
         }
         file.routes.push(this.buildRoute(match, options2));
+        this.syncFeatureGraphNode(file);
         return this;
       }
     };
@@ -2290,6 +2455,7 @@ var Business = class {
           path: item.path,
           ...item.capability !== void 0 ? { capability: keyOf(item.capability) } : {}
         }));
+        this.syncFrontendGraphNode(manifest);
         return this;
       },
       page: (path, options2) => {
@@ -2314,17 +2480,19 @@ var Business = class {
             }))
           } : {}
         });
+        this.syncFrontendGraphNode(manifest);
         return this;
       },
       manifest: (manifest) => {
         this.frontendManifest = manifest;
+        this.syncFrontendGraphNode(manifest);
         return this;
       }
     };
     this.lifecycle = {
       migration: (id, options2) => {
-        this.assertUniqueMigrationId(id);
-        this.migrations.push({
+        this.assertNewKey("lifecycle_migration", id, "migration");
+        const migration = {
           id,
           from: this.normalizeMigrationPlanRef(options2.from),
           to: this.normalizeMigrationTargetRef(options2.to),
@@ -2341,12 +2509,26 @@ var Business = class {
               ...pin.notes !== void 0 ? { notes: pin.notes } : {}
             }))
           } : {}
-        });
+        };
+        this.graph.register(
+          "lifecycle_migration",
+          id,
+          migration,
+          this.migrationDependsOn(migration)
+        );
         return this;
       },
       migrations: (migrations) => {
         this.assertUniqueMigrationIds(migrations);
-        this.migrations = migrations;
+        this.graph.clearKind("lifecycle_migration");
+        for (const migration of migrations) {
+          this.graph.register(
+            "lifecycle_migration",
+            migration.id,
+            migration,
+            this.migrationDependsOn(migration)
+          );
+        }
         return this;
       }
     };
@@ -2356,43 +2538,44 @@ var Business = class {
         return this;
       },
       plan: (spec) => {
-        this.assertNewKey(this.plans, spec.key, "plan");
-        this.plans.set(spec.key, spec);
+        this.assertNewKey("plan", spec.key, "plan");
+        this.graph.register("plan", spec.key, spec, this.planDependsOn(spec));
         return this;
       },
       routesFile: (file) => {
-        this.assertNewKey(this.features, file.feature, "feature");
-        this.features.set(file.feature, file);
+        this.assertNewKey("feature", file.feature, "feature");
+        this.registerFeatureFile(file);
         return this;
       },
       policyFile: (file) => {
-        this.assertNewKey(this.policies, file.name, "policy");
-        this.policies.set(file.name, file);
+        this.assertNewKey("policy", file.name, "policy");
+        this.graph.register("policy", file.name, file);
         return this;
       },
       capabilityFile: (file) => {
-        this.assertNewKey(this.capabilities, file.capability, "capability");
-        this.capabilities.set(file.capability, file);
+        this.assertNewKey("capability", file.capability, "capability");
+        this.graph.register("capability", file.capability, file);
         return this;
       },
       frontend: (manifest) => {
         this.frontendManifest = manifest;
+        this.syncFrontendGraphNode(manifest);
         return this;
       }
     };
   }
   meter(key, options) {
-    this.assertNewKey(this.meters, key, "meter");
-    this.meters.set(key, { key, ...options });
+    this.assertNewKey("meter", key, "meter");
+    this.graph.register("meter", key, { key, ...options });
     return { kind: "meter", key };
   }
   resource(name, options = {}) {
-    this.assertNewKey(this.resources, name, "resource");
-    this.resources.set(name, { name, ...options });
+    this.assertNewKey("counted_resource", name, "resource");
+    this.graph.register("counted_resource", name, { name, ...options });
     return { kind: "resource", key: name };
   }
   capability(key, options = {}) {
-    this.assertNewKey(this.capabilities, key, "capability");
+    this.assertNewKey("capability", key, "capability");
     const file = {
       capability: key,
       ...options.description !== void 0 || options.title !== void 0 ? { description: options.description ?? options.title } : {},
@@ -2401,7 +2584,12 @@ var Business = class {
       ...options.includesPolicies?.length ? { includes_policies: options.includesPolicies.map(keyOf) } : {},
       ...options.includesCapabilities?.length ? { includes_capabilities: options.includesCapabilities.map(keyOf) } : {}
     };
-    this.capabilities.set(key, file);
+    this.graph.register(
+      "capability",
+      key,
+      file,
+      this.capabilityDependsOn(file)
+    );
     return {
       kind: "capability",
       key,
@@ -2413,7 +2601,7 @@ var Business = class {
     };
   }
   feature(key, options = {}) {
-    this.assertNewKey(this.features, key, "feature");
+    this.assertNewKey("feature", key, "feature");
     const file = {
       feature: key,
       routes: [],
@@ -2440,30 +2628,34 @@ var Business = class {
     for (const route of options.routes ?? []) {
       file.routes.push(this.buildRoute(route.match, route));
     }
-    this.features.set(key, file);
+    this.registerFeatureFile(file);
     const ref = {
       kind: "feature",
       key,
       action: (id, actionOptions) => {
         file.actions ??= [];
-        if (file.actions.some((action) => action.id === id)) {
+        if (file.actions.some((action2) => action2.id === id) || this.graph.has("action", id)) {
           throw new ManifestBuilderError(
             `duplicate action "${id}" \u2014 each action id must be declared once`
           );
         }
-        file.actions.push({ id, ...actionOptions });
+        const action = { id, ...actionOptions };
+        file.actions.push(action);
+        this.registerAction(key, action);
+        this.syncFeatureGraphNode(file);
         return { kind: "action", key: id };
       },
       route: (match, routeOptions) => {
         file.routes.push(this.buildRoute(match, routeOptions ?? {}));
+        this.syncFeatureGraphNode(file);
         return ref;
       }
     };
     return ref;
   }
   policy(name, options) {
-    this.assertNewKey(this.policies, name, "policy");
-    this.policies.set(name, {
+    this.assertNewKey("policy", name, "policy");
+    const file = {
       name,
       type: options.type,
       config: options.config,
@@ -2477,11 +2669,12 @@ var Business = class {
           ...options.compatibleWith.authModes ? { auth_modes: options.compatibleWith.authModes } : {}
         }
       } : {}
-    });
+    };
+    this.graph.register("policy", name, file, this.policyDependsOn(file));
     return { kind: "policy", key: name };
   }
   plan(key, options) {
-    this.assertNewKey(this.plans, key, "plan");
+    this.assertNewKey("plan", key, "plan");
     const capabilityKeys = (options.capabilities ?? []).map(keyOf);
     const capabilityLimits = {
       ...options.capabilityLimits ?? {}
@@ -2530,20 +2723,31 @@ var Business = class {
     if (mergedCaps.length) {
       spec.capabilities = mergedCaps;
     }
-    this.plans.set(key, spec);
+    this.graph.register("plan", key, spec, this.planDependsOn(spec));
     return { kind: "plan", key };
   }
+  /** Inspect the SDK-local declaration graph used to emit the Manifest IR. */
+  resourceGraph() {
+    return this.graph.snapshot();
+  }
   /** Assemble + validate the Manifest IR. Throws ManifestValidationError
    *  with structured issues when the declared state is invalid. */
   toIR() {
+    this.assertGraphDependenciesSatisfied();
     const candidate = {
       irVersion: 1,
       sdkVersion: SDK_VERSION,
       product: this.buildProductSpec(),
-      routes: sortBy([...this.features.values()], (file) => file.feature),
-      policies: sortBy([...this.policies.values()], (file) => file.name),
-      capabilities: sortBy(
-        [...this.capabilities.values()],
+      routes: this.graph.sortedValues(
+        "feature",
+        (file) => file.feature
+      ),
+      policies: this.graph.sortedValues(
+        "policy",
+        (file) => file.name
+      ),
+      capabilities: this.graph.sortedValues(
+        "capability",
         (file) => file.capability
       ),
       runtime: { rollout: null, flags: null, migrations: null }
@@ -2571,19 +2775,34 @@ var Business = class {
         ...options.upstreamAuth !== void 0 ? { upstreamAuth: options.upstreamAuth } : {}
       },
       metering: {
-        meters: sortBy([...this.meters.values()], (meter) => meter.key),
+        meters: this.graph.sortedValues(
+          "meter",
+          (meter) => meter.key
+        ),
         ...options.billOn4xx !== void 0 ? { billOn4xx: options.billOn4xx } : {}
       },
       ...options.billing !== void 0 ? { billing: options.billing } : {},
-      ...this.frontendManifest !== void 0 ? { frontend: this.frontendManifest } : {},
-      ...this.migrations.length ? { migrations: this.migrations } : {},
-      ...this.resources.size ? {
-        resources: sortBy(
-          [...this.resources.values()],
+      ...options.operatorPolicies !== void 0 ? { policies: options.operatorPolicies } : {},
+      ...options.customerContext !== void 0 ? { customer_context: buildCustomerContext(options.customerContext) } : {},
+      ...this.graph.has("frontend", "manifest") ? {
+        frontend: this.graph.get(
+          "frontend",
+          "manifest"
+        )?.value
+      } : {},
+      ...this.graph.values("lifecycle_migration").length ? {
+        migrations: this.graph.sortedValues(
+          "lifecycle_migration",
+          (migration) => migration.id
+        )
+      } : {},
+      ...this.graph.values("counted_resource").length ? {
+        resources: this.graph.sortedValues(
+          "counted_resource",
           (resource) => resource.name
         )
       } : {},
-      plans: sortBy([...this.plans.values()], (plan) => plan.key)
+      plans: this.graph.sortedValues("plan", (plan) => plan.key)
     };
     return deepMerge(
       base,
@@ -2601,6 +2820,7 @@ var Business = class {
   }
   ensureFrontendManifest() {
     this.frontendManifest ??= { version: 1, nav: [], pages: [] };
+    this.syncFrontendGraphNode(this.frontendManifest);
     return this.frontendManifest;
   }
   normalizeMigrationPlanRef(ref) {
@@ -2615,13 +2835,6 @@ var Business = class {
       version: ref.version ?? "head"
     };
   }
-  assertUniqueMigrationId(id) {
-    if (this.migrations.some((migration) => migration.id === id)) {
-      throw new ManifestBuilderError(
-        `duplicate migration "${id}" \u2014 each migration id must be declared once`
-      );
-    }
-  }
   assertUniqueMigrationIds(migrations) {
     const seen = /* @__PURE__ */ new Set();
     for (const migration of migrations) {
@@ -2633,27 +2846,149 @@ var Business = class {
       seen.add(migration.id);
     }
   }
-  assertNewKey(map, key, label) {
-    if (map.has(key)) {
+  assertNewKey(kind, key, label) {
+    if (this.graph.has(kind, key)) {
       throw new ManifestBuilderError(
         `duplicate ${label} "${key}" \u2014 each ${label} key must be declared once`
       );
     }
   }
+  assertGraphDependenciesSatisfied() {
+    const missing = this.graph.missingDependencies();
+    if (missing.length === 0) return;
+    const details = missing.slice(0, 8).map(
+      ({ from, missing: dependency }) => `${describeResourceUrn(from)} depends on missing ${describeResourceUrn(
+        dependency
+      )}`
+    ).join("; ");
+    const suffix = missing.length > 8 ? `; plus ${missing.length - 8} more` : "";
+    throw new ManifestBuilderError(
+      `manifest has unresolved resource reference(s): ${details}${suffix}`
+    );
+  }
+  getFeatureFile(key) {
+    return this.graph.get("feature", key)?.value ?? null;
+  }
+  registerFeatureFile(file) {
+    this.graph.register(
+      "feature",
+      file.feature,
+      file,
+      this.featureDependsOn(file)
+    );
+    for (const action of file.actions ?? []) {
+      this.registerAction(file.feature, action);
+    }
+  }
+  syncFeatureGraphNode(file) {
+    this.graph.upsert(
+      "feature",
+      file.feature,
+      file,
+      this.featureDependsOn(file)
+    );
+  }
+  registerAction(featureKey, action) {
+    this.assertNewKey("action", action.id, "action");
+    this.graph.register(
+      "action",
+      action.id,
+      action,
+      this.actionDependsOn(featureKey, action)
+    );
+  }
+  syncFrontendGraphNode(manifest) {
+    this.graph.upsert(
+      "frontend",
+      "manifest",
+      manifest,
+      this.frontendDependsOn(manifest)
+    );
+  }
+  capabilityDependsOn(file) {
+    return [
+      ...this.dependenciesFor("feature", file.includes_features),
+      ...this.dependenciesFor("policy", file.includes_policies),
+      ...this.dependenciesFor("capability", file.includes_capabilities)
+    ];
+  }
+  policyDependsOn(file) {
+    return this.dependenciesFor("meter", file.compatible_with?.meters);
+  }
+  featureDependsOn(file) {
+    const meterKeys = file.routes.flatMap((route) => route.meters ?? []);
+    return [
+      ...this.dependenciesFor("policy", file.policies),
+      ...this.dependenciesFor("capability", file.capabilities),
+      ...this.dependenciesFor("plan", file.plans),
+      ...this.dependenciesFor("meter", meterKeys)
+    ];
+  }
+  actionDependsOn(featureKey, action) {
+    return [
+      resourceDependency("feature", featureKey),
+      ...action.resource ? [resourceDependency("counted_resource", action.resource.resource)] : []
+    ];
+  }
+  planDependsOn(plan) {
+    const caps = Array.isArray(plan.capabilities) ? plan.capabilities.map(String) : [];
+    const limitDimensions = (plan.limits ?? []).map((limit) => limit.dimension);
+    const pricedMeterDimensions = (plan.meters ?? []).map(
+      (meter) => meter.dimension
+    );
+    const capacityKeys = Object.keys(plan.capability_limits ?? {});
+    return [
+      ...this.dependenciesFor("capability", caps),
+      ...this.existingDependenciesFor("meter", [
+        ...limitDimensions,
+        ...pricedMeterDimensions
+      ]),
+      ...this.existingDependenciesFor("counted_resource", capacityKeys)
+    ];
+  }
+  migrationDependsOn(migration) {
+    return [
+      resourceDependency("plan", migration.from.plan),
+      resourceDependency("plan", migration.to.plan),
+      ...this.dependenciesFor(
+        "plan",
+        migration.pins?.map((pin) => pin.pinTo.plan)
+      )
+    ];
+  }
+  frontendDependsOn(manifest) {
+    return this.dependenciesFor("capability", [
+      ...(manifest.nav ?? []).flatMap(
+        (item) => item.capability ? [item.capability] : []
+      ),
+      ...(manifest.pages ?? []).flatMap((page) => [
+        ...page.capability ? [page.capability] : [],
+        ...(page.components ?? []).flatMap(
+          (component) => component.capability ? [component.capability] : []
+        )
+      ])
+    ]);
+  }
+  dependenciesFor(kind, keys) {
+    return [...new Set(keys ?? [])].map((key) => resourceDependency(kind, key));
+  }
+  existingDependenciesFor(kind, keys) {
+    return [...new Set(keys)].filter((key) => this.graph.has(kind, key)).map((key) => resourceDependency(kind, key));
+  }
 };
 function isBusiness(value) {
   return typeof value === "object" && value !== null && value[BUSINESS_BRAND] === true;
 }
-function sortBy(items, key) {
-  return [...items].sort((a, b) => {
-    const ka = key(a);
-    const kb = key(b);
-    return ka < kb ? -1 : ka > kb ? 1 : 0;
-  });
-}
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function buildCustomerContext(options) {
+  return {
+    ...options.identityRequirement !== void 0 ? { identity_requirement: options.identityRequirement } : {},
+    ...options.contextTokens !== void 0 ? { context_tokens: options.contextTokens } : {},
+    ...options.portalAuth !== void 0 ? { portal_auth: options.portalAuth } : {}
+  };
+}
 function deepMerge(base, patch) {
   const out = { ...base };
   for (const [key, value] of Object.entries(patch)) {
@@ -2666,6 +3001,12 @@ function deepMerge(base, patch) {
   }
   return out;
 }
+function describeResourceUrn(urn) {
+  const parts = urn.split(":");
+  const kind = parts[3] ?? "resource";
+  const key = parts.slice(4).join(":");
+  return `${kind} "${decodeURIComponent(key)}"`;
+}
 
 // src/bin.ts
 function parseArgs(argv) {