@farthershore/product 0.0.0 → 0.2.0

package/README.md

@@ -0,0 +1,153 @@
+# @farthershore/product
+
+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`; the Farther Shore GitHub bot compiles that
+program to backend-owned IR, validates it, and publishes through Core when repo
+changes land.
+
+## Install
+
+```bash
+pnpm add @farthershore/product
+```
+
+Builder repos generated by Farther Shore already pin this dependency in
+`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. `frontend/` is the generated editable
+frontend app and is built by the frontend pipeline only. Runtime state 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",
+  displayName: "CronCloud",
+  description: "Managed cron jobs",
+});
+
+business.use(configureMeters, configureCronRoutes, configurePlans);
+
+export default business;
+```
+
+Modules are plain synchronous functions:
+
+```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
+
+Normal product repos do not call platform release or IR APIs. The GitHub bot
+owns that workflow:
+
+1. Loads `product/product.config.ts`.
+2. Requires the default export to be the `Business` returned by
+   `fs.business(...)` or `fs.product(...)`.
+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.
+
+## 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.
+- `business.capability(...)` — declare capability bundles and plan grants.
+- `business.feature(...)` / `business.api.route(...)` — declare gateway routes,
+  meters, and action metadata.
+- `business.policy(...)` — declare policy files in code.
+- `business.plan(...)` — declare plan pricing, limits, grants, and lifecycle
+  behavior.
+- `business.lifecycle.*` — declare migrations.
+- `business.raw.*` — escape hatches for platform-schema JSON when the typed SDK
+  does not yet have sugar.
+
+## Determinism
+
+`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.
+
+## Release
+
+`@farthershore/product` publishes to public npm through the GitHub workflow
+`.github/workflows/publish-product-sdk.yml`.
+
+Release sequence:
+
+1. Bump `packages/product/package.json` version.
+2. Run the package checks:
+   ```bash
+   pnpm --filter @farthershore/product run lint
+   pnpm --filter @farthershore/product run test
+   pnpm --filter @farthershore/product run build
+   pnpm --filter @farthershore/product run pack:check
+   ```
+3. Commit, push, and merge through the normal PR flow.
+4. Tag from `main` with the exact package version:
+   ```bash
+   git tag product-v<version>
+   git push origin product-v<version>
+   ```
+
+The publish workflow verifies that the tag equals
+`product-v<packages/product/package.json version>`, builds/tests the package and
+its dependencies, runs `pack:check`, then publishes with `NPM_PUBLISH_TOKEN`.