@saastemly/voidcommerce 0.1.0

package/README.md

@@ -0,0 +1,271 @@
+# voidcommerce
+
+Void, with a shop in it.
+
+```sh
+vc init          # void init, then a form for the shop
+vc --help        # void's help, with vc's commands merged in
+vc dev           # everything else is void's, verbatim
+```
+
+## vc extends void; it replaces nothing
+
+Every command vc does not name goes to `void` untouched — same arguments,
+same terminal, same exit code. The named ones run void's version and add vc's
+part after it:
+
+| | void's part | then vc's |
+|---|---|---|
+| `vc init` | `void init`, when there is no Void app here yet | the shop form |
+| `vc --help` | `void --help` | a `shop` group merged into the Commands box |
+| `vc init --help` | `void init --help` | a second box, `vc init` |
+| `vc --version` | void's version | vc's |
+| `vc dev`, `vc build`, `vc preview` | — void has no such commands | the app's own script, where the app is |
+
+`vc init --github` and void's other partial modes are void's alone. `vc help
+db execute` is void's. When void is not installed, vc says so and stops —
+except for help, which it prints alone and says why. `dev`, `build` and
+`preview` are the scripts `void init` writes into the app's package.json;
+vc only decides where they run — `api/` from a monorepo root, `.vc/app` at
+a strict root.
+
+## The first question: one app, or api + frontend
+
+| | where it runs | what `vc init` does |
+|---|---|---|
+| **One app** | one Void app on Cloudflare Workers at `<domain>` and `www` — the API and the generated storefront and panel together | `void init` here, then the form |
+| **Monorepo** | `api/` on Workers at `api.<domain>` with the panel; `frontend/` a static Void site on GitHub Pages at `<domain>` | `void init` in `api/` (the D1 starter), `void init` in `frontend/` (Static Pages), then the form |
+| **Strict** *(experimental)* | `api.<domain>` on Workers; the storefront on `<domain>` | no `void init` at all: the repository root IS the storefront, and the worker is generated under `.vc/app` |
+
+The layout decides what the domain means, so it is asked before anything
+else, and it cannot change after init — moving files is not a regeneration.
+`vc init --layout app|monorepo|strict` skips the question for scripts.
+
+The domain need not be a registrable apex. `shop.example.com` is a shop inside
+the zone `example.com`, and the two are different questions: the domain is
+where the shop answers, the zone is where records go and which zone Cloudflare
+needs for the worker's custom domain. The wizard asks for the zone only when
+the domain is not one. A subdomain has no `www`, so it does not get a route
+nobody would type.
+
+Every layout puts the worker on a Cloudflare custom domain, which Cloudflare
+creates in its own zone — so the zone must be on Cloudflare, and DNS at
+Simply is refused with that reason rather than generating a shop with no
+hostname. Where Cloudflare also does the mail, there are no records left for
+the DNS plugin to write and the shop needs no DNS token at all.
+
+In a monorepo the Pages host (`<owner>.github.io`) is required, the frontend
+gets the custom storefront kit, and a workflow publishes it: every push builds
+`frontend/`, prerenders it, and force-pushes the tree to a `static` branch with
+the shop's domain in `CNAME`. Pages serves that branch from `/`.
+
+### Strict: a monorepo turned inside out
+
+A monorepo has `api/` and `frontend/` side by side. Strict has the same two
+halves and the same hosting, but only one of them is a directory you can see:
+
+```
+voidcommerce.json   the answers — the worker is generated from this
+package.json        ONE package.json, shared by the storefront and the worker
+pages/  lib/        the STOREFRONT. Yours, and what the repository looks like
+vite.config.ts      its Vite config; void.json sets output: "static"
+data/               the catalogue, pushed by vc import
+content/            faqs.json and posts.json — launch content, snapshotted in
+branding/           static assets, copied to public/branding/
+migrations/         what production has already applied — see below
+patches/            a void fix that has not shipped upstream
+.env                local values, shared by both halves
+.vc/app/            the WORKER. Generated, gitignored, nobody's to edit
+```
+
+So the repository is, in technicality, a frontend app that builds a backend
+app — and in practice a monorepo without the ceremony of being one. What you
+edit is the shop front; the API, the panel, the cron, the queue and the live
+stream are generated underneath it from the manifest and rewritten by
+`vc generate`. A hand edit to a generated app drifts from the thing it exists
+to describe, and strict is the mode that refuses to let it. If you need a file
+the manifest cannot produce, that is the signal to use the one-app layout.
+
+Two branches come out of one push:
+
+| branch | what is on it | who serves it |
+|---|---|---|
+| `void-dist` | the worker, as a self-contained Void app | Cloudflare Workers Builds |
+| `frontend-static` | the prerendered storefront | GitHub Pages, or Cloudflare Pages |
+
+Locally, `bun run dev` is the shop — the worker with its panel — and
+`bun run dev:storefront` is the shop front, which calls it at
+`http://localhost:5173`. Start the worker first; the storefront takes the next
+free port.
+
+At a strict root every Void command runs in the artifact: `vc dev` is
+`void dev` in `.vc/app`, generated first if it is not there. `vc generate`
+also runs `void prepare` and `void db generate`, so the app typechecks and
+carries its migrations. Migrations are the one artifact that must be
+committed: regenerated on a fresh clone they would get new names, and a deploy
+would try to apply them twice — so they live in `migrations/` at the root and
+the app reaches them through a symlink.
+
+Strict pins `void` to the version its vendored patch applies to. A strict
+project has been generated, typechecked and production-built against real
+packages; it has not yet been served or deployed end to end.
+
+## Push, and it is live
+
+With everything on Cloudflare, a shop can reach production without a single
+credential in CI:
+
+```
+main ──push──▶ GitHub Actions: vc dist ──▶ void-dist branch ──▶ Cloudflare Workers Builds ──▶ live
+```
+
+`main` is the manifest and the data. The workflow regenerates the app and
+force-pushes a self-contained Void app to `void-dist`; Cloudflare builds *that*
+branch and deploys it, so it never needs to know voidcommerce exists. The
+generated `DEPLOY.md` lists the one-time setup, including the one genuinely
+non-obvious part: the API token Cloudflare generates for a build has no D1
+permission, so a build that applies migrations needs a token you make.
+
+Email is the same story. Cloudflare Email Service is reached through a Worker
+binding rather than an API key, and onboarding the sending domain writes its
+own SPF, DKIM and DMARC records — so mail costs no secret and no DNS work.
+Sending to real customers needs a Workers Paid plan.
+
+## Deploying
+
+```sh
+vc preflight                          # is the shop ready to advertise on?
+vc deploy                             # preflight, then void deploy — the Void platform
+vc deploy --cloudflare --provision    # first time: your own Cloudflare account, with wrangler
+vc deploy --cloudflare                # every time after
+```
+
+`vc deploy` extends `void deploy`: vc's preflight runs first, then void's
+deploy exactly as you typed it, with void's login. The Void platform is in
+private beta; the pass-through is there for when it is not.
+
+`--cloudflare` is the other road, and needs no Void account at all. It is
+Void's documented manual path, automated with wrangler:
+
+1. **wrangler is installed and logged in** (`wrangler login`, or
+   `CLOUDFLARE_API_TOKEN`). When wrangler sees exactly one account, vc pins it
+   in `wrangler.jsonc` for you; with several, it asks you to choose.
+2. **Preflight.** Every required key is either a worker secret
+   (`wrangler secret put`) or a committed plaintext value; the worker's
+   hostnames are the shop's. Not ready means no deploy, unless `--force`.
+   On a first deploy the worker does not exist yet, so its secrets cannot be
+   listed: preflight prints the `wrangler secret put` lines, and running them
+   creates the draft worker.
+3. **`--provision`** creates the D1 database and the queue, and records them
+   in `wrangler.jsonc` and `voidcommerce.json` — so a regenerated strict
+   artifact carries the real ids.
+4. **Build**, then **scrub**. Void's build bakes every `.env*` value into the
+   worker's `vars` as plaintext — a dev cron secret, `unset` for each
+   credential — and a var shadows the secret of the same name. Every
+   secret-class key and every `unset` is removed from the emitted config
+   before it is uploaded; the worker reads those from its secrets.
+5. **Migrate** the remote D1 from the committed migrations, then
+   **`wrangler deploy`** exactly the config that was scrubbed.
+
+At a monorepo root `vc deploy` deploys `api/`; the frontend deploys itself
+from GitHub Actions on push. At a strict root it deploys the artifact.
+
+The Cloudflare road has been exercised against a fake wrangler that answers
+like the real one, and its `wrangler deploy` invocation dry-run against a real
+build; it has not yet put a shop on a real account.
+
+## What `vc init` asks
+
+`void init` asks three questions, which is right for Void — a Void app can be
+anything. A shop cannot be anything: it has a payment rail or it does not
+trade, it has email or nobody can sign in, it has a tax rate or it sells
+unlawfully. So `vc init` asks about all of it, in the order a person thinks
+about it:
+
+| | you choose |
+|---|---|
+| **Who signs in** | magic link, email code, passkeys, Google/Apple/GitHub, password, username, phone, guest |
+| **Account features** | every official Better Auth plugin — 2FA, organizations, API keys, JWT, multi-session, … |
+| **Catalogue** | custom fields, personalization, inventory, bundles, price lists, translations, search |
+| **Selling** | channels, discounts, gift cards, loyalty, subscriptions, draft orders, returns, wishlists, reviews, customer groups, agentic commerce |
+| **Operations** | webhooks, workflows, files, marketplace |
+| **Payment rail** | Adyen *or* Stripe — one, never both |
+| **Tax** | declared rates, TaxJar, Avalara |
+| **Carriers** | Shippo, EasyPost, UPS, FedEx, DHL, USPS, Royal Mail, Aramex, DoorDash, Stuart |
+| **ERP** | Business Central |
+| **Email** | Cloudflare Email Service (a Worker binding, no API key) or Resend |
+| **DNS, content** | Cloudflare or Simply; blog and FAQ |
+| **Interfaces** | the generated storefront and panel (better-admin-ui, standard theming, one line to turn off), or the custom storefront kit (better-auth-ui + better-commerce-ui, hosted in your own app) |
+
+Every choice carries a one-line hint written for the person choosing — *"teams
+that share a shop account — a club ordering trophies as one buyer"* — not a
+plugin name. Required choices are shown so you know what you are getting;
+recommended ones are ticked, because a shop that starts with reviews off has
+to remember to turn them on and never does.
+
+## The manifest
+
+Answers are written to **`voidcommerce.json`**, and everything else is
+generated from it. Run `vc init` again to change your mind: the answers are
+pre-filled, regenerated files are rewritten, and files you own are kept.
+
+That is the difference between a scaffolder and a generator. A wizard that
+writes `auth.ts` once and forgets what it asked is useless on day thirty when
+you want subscriptions and cannot remember which of forty checkboxes you
+ticked.
+
+## What gets generated
+
+```
+voidcommerce.json          the answers
+auth.ts                    the plugin ring — every choice, with the hint as a comment
+env.ts                     every key REQUIRED, none optional, none defaulted
+.env.example               with `unset` for each secret
+.env.production            plaintext values only
+lib/deploy/requirements.ts what breaks without each key — read by `vc preflight`
+wrangler.jsonc             the worker's custom domain, api.<domain>
+```
+
+And, written once then **yours**: `.env`, `lib/domain.ts`, `lib/payment.ts`,
+`lib/notifications.ts`, `lib/erp.ts`. They are what a shop edits when it
+grows past the wizard, so they are never overwritten.
+
+A monorepo puts all of that under `api/`, and adds:
+
+```
+package.json                          workspaces: api, frontend; dev:api, dev:frontend, deploy …
+.github/workflows/frontend-pages.yml  build frontend/, publish to the static branch, CNAME
+frontend/lib/api.ts                   the one client: better-auth/react + commerceClient  (yours)
+frontend/.env                         VITE_API_ORIGIN=http://localhost:5173                (yours)
+frontend/.env.production              VITE_API_ORIGIN=https://api.<domain>
+frontend/void.json                    target: node, output: static — merged into void's
+```
+
+## Why the files are plain
+
+Void's `gen` has no extensibility and its directory set is closed — it will
+not scan a `plugins/` folder. So `vc` writes ordinary Void files a reader can
+see, the way `rails generate` writes into files you own, rather than hiding
+registrations in a virtual module. A `vc` project is a valid Void project with
+nothing magic in it, which is what would let Void absorb these generators one
+day as a copy rather than a negotiation.
+
+## The rules the wizard enforces
+
+- **Nothing is optional.** If a shop supports an integration, the deployment
+  sets it up. `env.ts` has no `.optional()` and no defaults — a default is
+  compiled into the worker's vars and shadows the real secret.
+- **One integration per job.** Adyen *or* Stripe, Cloudflare *or* Simply.
+  Carrying both means every reader works out which half is live.
+- **DNS at Simply is refused when the API is on `api.<domain>`.** A Worker
+  custom domain needs the zone on Cloudflare; the wizard says so rather than
+  generating a configuration that resolves and then errors for every visitor.
+- **The country's VAT is declared** so a fresh deploy is never tax-free. For a
+  country the wizard does not know, it writes `TODO VERIFY` rather than a
+  guess.
+- **The worker carries no catalogue.** `catalogImport` is registered with no
+  source; `vc import` pushes from `data/catalog.json`.
+- **Passwords are explicitly off** unless chosen, because Better Auth's
+  default is off and a version bump could flip it.
+
+The generated shop typechecks clean against the real packages.

package/bin/vc

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli.ts";

package/dist/catalog.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Everything `vc init` can offer, and what choosing it means.
+ *
+ * ── Why a registry ───────────────────────────────────────────────────────
+ *
+ * The wizard is only as good as its descriptions. A checkbox that says
+ * "organization" tells nobody anything; one that says "teams that share a
+ * shop — a club ordering trophies as one account" is a decision somebody can
+ * make. So every entry carries a one-line `hint` written for the person
+ * choosing, not for the person who wrote the plugin.
+ *
+ * Each entry also carries what choosing it COSTS: the packages to install,
+ * the env keys it needs, and whether those keys are secrets. That is how the
+ * generator knows what to write into `env.ts`, `.env.example` and the
+ * deploy requirements without a second hand-kept list.
+ */
+export interface EnvKey {
+    key: string;
+    /** What breaks without it — the sentence an operator reads at preflight. */
+    breaks: string;
+    /** Safe to commit in `.env.production`. Everything else is a secret. */
+    plaintext?: boolean | undefined;
+    /** A working value for local development. */
+    dev?: string | undefined;
+    /** Where the real value comes from. */
+    where?: string | undefined;
+}
+export interface Choice {
+    id: string;
+    label: string;
+    hint: string;
+    /** npm packages the choice pulls in. */
+    packages?: string[] | undefined;
+    env?: EnvKey[] | undefined;
+    /** Chosen unless the person unticks it. */
+    recommended?: boolean | undefined;
+    /** Cannot be unticked; shown so the person knows it is there. */
+    required?: boolean | undefined;
+    /** Ids this choice needs; the wizard adds them. */
+    requires?: string[] | undefined;
+    /** Ids this choice cannot coexist with. */
+    conflicts?: string[] | undefined;
+}
+export interface Group {
+    id: string;
+    title: string;
+    /** One line under the title. */
+    intro?: string | undefined;
+    choices: Choice[];
+    /** `select` picks exactly one; `multiselect` any number. */
+    kind: "select" | "multiselect";
+}
+export declare const SIGN_IN: Group;
+export declare const AUTH_PLUGINS: Group;
+export declare const COMMERCE_CATALOG: Group;
+export declare const COMMERCE_SALES: Group;
+export declare const COMMERCE_OPERATIONS: Group;
+export declare const PAYMENT: Group;
+export declare const TAX: Group;
+export declare const CARRIERS: Group;
+export declare const ERP: Group;
+export declare const EMAIL: Group;
+export declare const DNS: Group;
+export declare const CONTENT: Group;
+export declare const UI: Group;
+/** The order the wizard walks them in. */
+export declare const GROUPS: Group[];
+/** Every choice, by id, for lookups the generator makes. */
+export declare const CHOICES: Map<string, Choice>;

package/dist/catalog.js

@@ -0,0 +1,34 @@
+import {
+  AUTH_PLUGINS,
+  CARRIERS,
+  CHOICES,
+  COMMERCE_CATALOG,
+  COMMERCE_OPERATIONS,
+  COMMERCE_SALES,
+  CONTENT,
+  DNS,
+  EMAIL,
+  ERP,
+  GROUPS,
+  PAYMENT,
+  SIGN_IN,
+  TAX,
+  UI
+} from "./index-s7sq41qs.js";
+export {
+  UI,
+  TAX,
+  SIGN_IN,
+  PAYMENT,
+  GROUPS,
+  ERP,
+  EMAIL,
+  DNS,
+  CONTENT,
+  COMMERCE_SALES,
+  COMMERCE_OPERATIONS,
+  COMMERCE_CATALOG,
+  CHOICES,
+  CARRIERS,
+  AUTH_PLUGINS
+};

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `vc` — Void, with a shop in it.
+ *
+ * vc extends parts of void; it replaces none of it. Every command not named
+ * below goes to `void` verbatim — same arguments, same terminal, same exit
+ * code — so a person who knows Void already knows vc. The named ones run
+ * void's version first and add vc's part after: `vc init` is void init then
+ * the shop form; `vc --help` is void's help with a `shop` group merged in.
+ * `dev`, `build` and `preview` are not void's at all — they are the app's
+ * own scripts — so vc only decides where they run.
+ *
+ * The one thing vc changes about a pass-through is WHERE it runs: at a
+ * strict root the Void app is the artifact under .vc/app, so void's commands
+ * run there, after generating it if it is not there yet; at a monorepo root
+ * they run in api/.
+ */
+interface Extended {
+    run: (args: string[]) => Promise<number>;
+    help: () => Promise<number>;
+}
+/** The commands vc extends or adds. Add one here and it is dispatched, helped, and tested. */
+export declare const EXTENDED: Record<string, Extended>;
+export declare function main(argv: string[]): Promise<number>;
+export {};