@farthershore/product 0.1.0 → 0.2.1

package/README.md

@@ -1,9 +1,12 @@
 # @farthershore/product
 
-Product-as-Code SDK for Farther Shore. Builder repos use this package in
-`product.config.ts` to declare product contracts in TypeScript. Builders author
-and export a `Business`; the Farther Shore GitHub bot checks and publishes those
-declarations when repo changes land.
+Product-as-Code SDK for Farther Shore. Builder repos use this package from
+`product/product.config.ts` to declare product contracts in TypeScript. Builders
+author and export a `Business`; Farther Shore compiles that program to
+backend-owned IR, validates it, and applies it through Core. Every product is
+created with a GitHub repo that contains the editable `frontend/` starter and
+the Product SDK entrypoint; connecting GitHub is a product-creation
+precondition.
 
 ## Install
 
@@ -12,12 +15,37 @@ pnpm add @farthershore/product
 ```
 
 Builder repos generated by Farther Shore already pin this dependency in
-`package.json`.
+`product/package.json`.
+
+## Repo Layout
+
+```text
+product/
+  package.json
+  product.config.ts
+  meters.ts
+  plans/
+    free.ts
+    pro.ts
+  routes/
+    api.ts
+frontend/
+  ...
+```
+
+`product/` is authored Product SDK code and may be split into any imported files
+the builder wants. `frontend/` is the generated editable starter app and is built
+by the frontend pipeline only. Runtime state, accepted specs, compilation
+records, deployment runs, and compiled IR are not checked into the builder repo;
+Farther Shore stores them in Core.
 
 ## Example
 
 ```ts
 import { fs } from "@farthershore/product";
+import { configureMeters } from "./meters.js";
+import { configureCronRoutes } from "./routes/cron.js";
+import { configurePlans } from "./plans/index.js";
 
 const business = fs.business("croncloud", {
   baseUrl: "https://api.example.com",
@@ -25,71 +53,65 @@ const business = fs.business("croncloud", {
   description: "Managed cron jobs",
 });
 
-business.meter("requests", { display: "Requests" });
+business.use(configureMeters, configureCronRoutes, configurePlans);
 
-business.resource("cron_jobs", {
-  display: "Cron jobs",
-  countSource: "action_inferred",
-});
-
-const cron = business.capability("managed-cron", {
-  title: "Managed Cron Jobs",
-});
-
-const jobs = business.feature("cron-jobs", {
-  description: "Cron job CRUD",
-  capabilities: [cron],
-  routes: [{ match: "GET /v1/cron-jobs", meters: ["requests"] }],
-});
-
-const createJob = jobs.action("cron-job.create", {
-  kind: "mutation",
-  title: "Create cron job",
-  resource: { resource: "cron_jobs", effect: "create" },
-});
-
-jobs.route("POST /v1/cron-jobs", {
-  meters: ["requests"],
-  action: createJob,
-});
+export default business;
+```
 
-business.plan("starter", {
-  name: "Starter",
-  price: fs.price.monthly(29),
-  grants: [cron.enable({ limits: { cron_jobs: 10 } })],
-  limits: [
-    {
-      dimension: "requests",
-      window: { type: "named", name: "minute" },
-      capacity: 600,
-      enforcement: "enforce",
-    },
-  ],
-});
+Modules are plain synchronous functions:
 
-export default business;
+```ts
+import { fs, type ProductModule } from "@farthershore/product";
+
+export const configureMeters: ProductModule = (product) => {
+  product.meter("requests", { display: "Requests" });
+};
+
+export const configurePlans: ProductModule = (product) => {
+  product.plan("starter", {
+    name: "Starter",
+    price: fs.price.monthly(29),
+    limits: [
+      {
+        dimension: "requests",
+        window: { type: "named", name: "minute" },
+        capacity: 600,
+        enforcement: "enforce",
+      },
+    ],
+  });
+};
 ```
 
-## Bot build
+## Lifecycle apply paths
 
-Normal product repos do not call platform release or IR APIs. The GitHub bot
-owns that workflow:
+Generated product repos use GitHub as the required automation and frontend
+workspace:
 
-1. Loads `product.config.ts`.
+1. Loads `product/product.config.ts`.
 2. Requires the default export to be the `Business` returned by
    `fs.business(...)` or `fs.product(...)`.
-3. Compiles the business into deterministic Manifest IR.
+3. Executes imported modules and compiles the business into deterministic
+   Manifest IR.
 4. Validates the result against the deployed platform contract.
 5. Publishes the accepted release through Core so edge artifacts propagate.
 
-The bundled `farthershore-manifest-build` binary is bot/build-runner plumbing.
-Run it locally only when debugging the automation itself; it is not part of the
-normal builder workflow.
+The same IR can also be applied to an already repo-backed product through
+trusted Core APIs, for example `farthershore build --apply <product>`. That path
+is useful for local validation/apply loops, but it is not a replacement for the
+product repo. The repo remains the required frontend customization workspace
+because `frontend/` is where the starter UI and all custom React code live.
+
+The bundled `farthershore-manifest-build` binary is shared by the bot,
+build-runner, and CLI. It emits the deterministic Manifest IR envelope that Core
+accepts; Core, not the user repo, remains the lifecycle authority.
 
 ## Public API
 
 - `fs.business(name, options)` / `fs.product(name, options)` — create the
   product builder.
+- `business.use(...modules)` — compose Product SDK modules from any files under
+  `product/`.
 - `business.meter(...)` — declare billable or enforceable dimensions.
 - `business.resource(...)` — declare counted resources for resource-count
   constraints.
@@ -99,16 +121,16 @@ normal builder workflow.
 - `business.policy(...)` — declare policy files in code.
 - `business.plan(...)` — declare plan pricing, limits, grants, and lifecycle
   behavior.
-- `business.frontend.*` — declare generated portal navigation and gates.
 - `business.lifecycle.*` — declare migrations.
 - `business.raw.*` — escape hatches for platform-schema JSON when the typed SDK
   does not yet have sugar.
 
 ## Determinism
 
-`product.config.ts` must be deterministic: no dates, randomness, network calls,
-or process state. Sorted collections produce stable output, while route order
-remains semantic because the gateway matcher is first-match-wins.
+`product/product.config.ts` and everything it imports must be deterministic: no
+dates, randomness, network calls, or process state. Sorted collections produce
+stable output, while route order remains semantic because the gateway matcher is
+first-match-wins.
 
 The GitHub bot runs the build twice and rejects the push if the two generated
 hashes differ.

package/dist/bin.js

@@ -2,7 +2,8 @@
 import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
 
 // src/bin.ts
-import { writeFile } from "node:fs/promises";
+import { access, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { tsImport } from "tsx/esm/api";
@@ -1398,7 +1399,7 @@ var productCustomerContextSchema = z13.object({
   identity_requirement: customerIdentityRequirementSchema.optional(),
   /**
    * Enables signed customer-context tokens (`fsc_*`) without putting the
-   * runtime signing secret in product.config.ts. Core generates/preserves the
+   * runtime signing secret in product/product.config.ts. Core generates/preserves the
    * secret when this is true and clears it when explicitly false.
    */
   context_tokens: z13.object({
@@ -1447,10 +1448,9 @@ var productSpecSchema = z13.object({
   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
-   * template renders these for non-reserved paths; contractual dashboard
-   * sections remain template-owned.
+   * Legacy/internal declarative frontend surface. New product repos customize
+   * the generated `frontend/` project directly; this remains for existing IR
+   * and internal template metadata.
    */
   frontend: frontendManifestSchema.optional(),
   migrations: migrationDeclsSchema.optional(),
@@ -1574,7 +1574,7 @@ var productSpecSchema = z13.object({
    *
    * Once a product has compiled with a `webhooks` block, API mutations
    * on those endpoints fail with `409 MANAGED_BY_CODE` — see
-   * `core/src/routes/management-webhooks.ts`. Tie-breaker: product.config.ts
+   * `core/src/routes/management-webhooks.ts`. Tie-breaker: product/product.config.ts
    * wins over API state if an endpoint id appears in both.
    */
   webhooks: webhooksBlockSchema.optional(),
@@ -2360,7 +2360,7 @@ function hashIr(ir) {
 }
 
 // src/version.ts
-var SDK_VERSION = true ? "0.1.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "0.2.1" : "0.0.0-dev";
 
 // src/business.ts
 var BUSINESS_BRAND = Symbol.for("farthershore.product.business");
@@ -2726,6 +2726,12 @@ var Business = class {
     this.graph.register("plan", key, spec, this.planDependsOn(spec));
     return { kind: "plan", key };
   }
+  use(...modules) {
+    for (const module of modules) {
+      module(this);
+    }
+    return this;
+  }
   /** Inspect the SDK-local declaration graph used to emit the Manifest IR. */
   resourceGraph() {
     return this.graph.snapshot();
@@ -3009,9 +3015,13 @@ function describeResourceUrn(urn) {
 }
 
 // src/bin.ts
+var DEFAULT_ENTRY_CANDIDATES = [
+  "product/product.config.ts",
+  "product.config.ts"
+];
 function parseArgs(argv) {
   const args = {
-    entry: "product.config.ts",
+    entry: null,
     out: "manifest-ir.json",
     diagnosticsOut: "manifest-diagnostics.json"
   };
@@ -3029,13 +3039,35 @@ function parseArgs(argv) {
       i++;
     } else if (flag === "--help" || flag === "-h") {
       process.stdout.write(
-        "Usage: farthershore-manifest-build [--entry product.config.ts] [--out manifest-ir.json] [--diagnostics-out manifest-diagnostics.json]\n"
+        "Usage: farthershore-manifest-build [--entry product/product.config.ts] [--out manifest-ir.json] [--diagnostics-out manifest-diagnostics.json]\n"
       );
       process.exit(0);
     }
   }
   return args;
 }
+async function fileExists(path) {
+  try {
+    await access(path, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveEntry(args) {
+  if (args.entry) {
+    return { entry: args.entry, entryPath: resolve(process.cwd(), args.entry) };
+  }
+  for (const candidate of DEFAULT_ENTRY_CANDIDATES) {
+    const entryPath = resolve(process.cwd(), candidate);
+    if (await fileExists(entryPath)) {
+      return { entry: candidate, entryPath };
+    }
+  }
+  throw new Error(
+    `no Product SDK entry found; expected ${DEFAULT_ENTRY_CANDIDATES.join(" or ")}`
+  );
+}
 function validationIssues(error) {
   if (error instanceof ManifestValidationError) return error.issues;
   if (typeof error === "object" && error !== null && error.name === "ManifestValidationError" && Array.isArray(error.issues)) {
@@ -3048,16 +3080,25 @@ function errorMessage(error) {
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
-  const entryPath = resolve(process.cwd(), args.entry);
+  let resolvedEntry;
+  try {
+    resolvedEntry = await resolveEntry(args);
+  } catch (error) {
+    process.stderr.write(
+      `farthershore-manifest-build: ${errorMessage(error)}
+`
+    );
+    process.exit(1);
+  }
   let mod;
   try {
     mod = await tsImport(
-      pathToFileURL(entryPath).href,
+      pathToFileURL(resolvedEntry.entryPath).href,
       import.meta.url
     );
   } catch (error) {
     process.stderr.write(
-      `farthershore-manifest-build: failed to load ${args.entry}: ${error instanceof Error ? error.message : String(error)}
+      `farthershore-manifest-build: failed to load ${resolvedEntry.entry}: ${error instanceof Error ? error.message : String(error)}
 `
     );
     process.exit(1);
@@ -3067,7 +3108,7 @@ async function main() {
   const candidate = isBusiness(direct) ? direct : interop;
   if (!isBusiness(candidate)) {
     process.stderr.write(
-      `farthershore-manifest-build: ${args.entry} must \`export default\` the Business returned by fs.business(\u2026)
+      `farthershore-manifest-build: ${resolvedEntry.entry} must \`export default\` the Business returned by fs.business(\u2026)
 `
     );
     process.exit(1);

package/dist/index.js

@@ -1391,7 +1391,7 @@ var productCustomerContextSchema = z13.object({
   identity_requirement: customerIdentityRequirementSchema.optional(),
   /**
    * Enables signed customer-context tokens (`fsc_*`) without putting the
-   * runtime signing secret in product.config.ts. Core generates/preserves the
+   * runtime signing secret in product/product.config.ts. Core generates/preserves the
    * secret when this is true and clears it when explicitly false.
    */
   context_tokens: z13.object({
@@ -1440,10 +1440,9 @@ var productSpecSchema = z13.object({
   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
-   * template renders these for non-reserved paths; contractual dashboard
-   * sections remain template-owned.
+   * Legacy/internal declarative frontend surface. New product repos customize
+   * the generated `frontend/` project directly; this remains for existing IR
+   * and internal template metadata.
    */
   frontend: frontendManifestSchema.optional(),
   migrations: migrationDeclsSchema.optional(),
@@ -1567,7 +1566,7 @@ var productSpecSchema = z13.object({
    *
    * Once a product has compiled with a `webhooks` block, API mutations
    * on those endpoints fail with `409 MANAGED_BY_CODE` — see
-   * `core/src/routes/management-webhooks.ts`. Tie-breaker: product.config.ts
+   * `core/src/routes/management-webhooks.ts`. Tie-breaker: product/product.config.ts
    * wins over API state if an endpoint id appears in both.
    */
   webhooks: webhooksBlockSchema.optional(),
@@ -2356,7 +2355,7 @@ function canonicalIrJson(ir) {
 }
 
 // src/version.ts
-var SDK_VERSION = true ? "0.1.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "0.2.1" : "0.0.0-dev";
 
 // src/business.ts
 var BUSINESS_BRAND = Symbol.for("farthershore.product.business");
@@ -2722,6 +2721,12 @@ var Business = class {
     this.graph.register("plan", key, spec, this.planDependsOn(spec));
     return { kind: "plan", key };
   }
+  use(...modules) {
+    for (const module of modules) {
+      module(this);
+    }
+    return this;
+  }
   /** Inspect the SDK-local declaration graph used to emit the Manifest IR. */
   resourceGraph() {
     return this.graph.snapshot();
@@ -2975,8 +2980,10 @@ var Business = class {
 function isBusiness(value) {
   return typeof value === "object" && value !== null && value[BUSINESS_BRAND] === true;
 }
-function business(name, options) {
-  return new Business(name, options);
+function business(name, options, configure) {
+  const product2 = new Business(name, options);
+  if (configure) product2.use(configure);
+  return product2;
 }
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/types/business.d.ts

@@ -191,6 +191,11 @@ export type PlanCapabilityGrant = {
     readonly capability: string;
     readonly limits?: Record<string, number | boolean>;
 };
+/**
+ * A synchronous Product SDK module. Use this to split a product across files:
+ * `product.use(configureMeters, configureRoutes, configurePlans)`.
+ */
+export type ProductModule = (product: Business) => void;
 export declare class Business {
     readonly [BUSINESS_BRAND] = true;
     readonly name: string;
@@ -231,6 +236,7 @@ export declare class Business {
     feature(key: string, options?: FeatureOptions): FeatureRef;
     policy(name: string, options: PolicyOptions): PolicyRef;
     plan(key: string, options: PlanOptions): PlanRef;
+    use(...modules: ProductModule[]): Business;
     /** Inspect the SDK-local declaration graph used to emit the Manifest IR. */
     resourceGraph(): ManifestResourceGraphSnapshot;
     /** Assemble + validate the Manifest IR. Throws ManifestValidationError
@@ -260,4 +266,4 @@ export declare class Business {
     private existingDependenciesFor;
 }
 export declare function isBusiness(value: unknown): value is Business;
-export declare function business(name: string, options: BusinessOptions): Business;
+export declare function business(name: string, options: BusinessOptions, configure?: ProductModule): Business;

package/dist/types/index.d.ts

@@ -14,7 +14,7 @@ export { price } from "./price.js";
 export { validateManifestIr, hashIr, canonicalIrJson } from "./validate.js";
 export { ManifestValidationError, ManifestBuilderError } from "./errors.js";
 export { SDK_VERSION } from "./version.js";
-export type { BusinessOptions, MeterOptions, ResourceOptions, CapabilityOptions, ActionOptions, FrontendNavItemOptions, FrontendPageOptions, FrontendComponentOptions, MigrationOptions, FeatureOptions, RouteOptions, PolicyOptions, PlanOptions, MeterRef, ResourceRef, ActionRef, PolicyRef, PlanRef, FeatureRef, CapabilityRef, PlanCapabilityGrant, } from "./business.js";
+export type { BusinessOptions, MeterOptions, ResourceOptions, CapabilityOptions, ActionOptions, FrontendNavItemOptions, FrontendPageOptions, FrontendComponentOptions, MigrationOptions, FeatureOptions, RouteOptions, PolicyOptions, PlanOptions, MeterRef, ResourceRef, ActionRef, PolicyRef, PlanRef, FeatureRef, CapabilityRef, PlanCapabilityGrant, ProductModule, } from "./business.js";
 export type { ManifestResourceGraphSnapshot, ManifestResourceKind, ManifestResourceUrn, } from "./resource-graph.js";
 export type { PriceSpec } from "./price.js";
 export type { ManifestIssue } from "./errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/product",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Farther Shore product-as-code SDK — declare your business in TypeScript",
   "type": "module",
   "main": "./dist/index.js",