@farthershore/product 0.0.0 → 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# @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.
+
+## Install
+
+```bash
+pnpm add @farthershore/product
+```
+
+Builder repos generated by Farther Shore already pin this dependency in
+`package.json`.
+
+## Example
+
+```ts
+import { fs } from "@farthershore/product";
+
+const business = fs.business("croncloud", {
+  baseUrl: "https://api.example.com",
+  displayName: "CronCloud",
+  description: "Managed cron jobs",
+});
+
+business.meter("requests", { display: "Requests" });
+
+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,
+});
+
+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",
+    },
+  ],
+});
+
+export default business;
+```
+
+## Bot build
+
+Normal product repos do not call platform release or IR APIs. The GitHub bot
+owns that workflow:
+
+1. Loads `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.
+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.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.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.
+
+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`.