@saastemly/voidcommerce 0.4.0 → 0.6.0

package/dist/deploy/github.d.ts

@@ -0,0 +1,85 @@
+/**
+ * GitHub as the root of trust.
+ *
+ * ── Why GitHub and not Cloudflare ────────────────────────────────────────
+ *
+ * The shop's credentials have to be reachable by whatever deploys it, and
+ * whatever deploys it has to be reachable by a push. The first design
+ * derived the encryption key from a Cloudflare API token, which put the
+ * bootstrap in the wrong order: the token authorises a worker that does not
+ * exist yet, and getting one means `wrangler login` — the exact step this is
+ * supposed to remove.
+ *
+ * GitHub is already there. A person who can push is logged into `gh`, and
+ * `gh` can write repository secrets. So GitHub holds the credentials, GitHub
+ * Actions is the thing that deploys, and the local machine holds nothing.
+ *
+ * ── What this cannot do, stated plainly ──────────────────────────────────
+ *
+ * It cannot mint a Cloudflare credential. There is no OIDC or workload
+ * identity federation from GitHub Actions to the Cloudflare API — the
+ * request has been open since 2025 with no Cloudflare commitment, and the
+ * official CI guidance is still "store an API token in your CI provider's
+ * secrets". The Cloudflare GitHub App runs one way: it grants Cloudflare
+ * access to the repository, not the repository access to Cloudflare.
+ *
+ * So exactly one long-lived Cloudflare token must exist, and this module's
+ * job is to make sure it exists in ONE place — GitHub's encrypted secrets —
+ * rather than on a laptop, in a shell profile, or in `~/.wrangler`.
+ *
+ * @see https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/
+ * @see https://github.com/cloudflare/workers-sdk/discussions/11434
+ */
+export interface GhAuth {
+    /** Logged in, with a token that can write repository secrets. */
+    ok: boolean;
+    user?: string | undefined;
+    scopes?: string[] | undefined;
+    reason?: string | undefined;
+}
+export declare function findGh(): string | null;
+export declare function run(cmd: string, args: string[], cwd: string, stdin?: string): Promise<{
+    code: number;
+    out: string;
+}>;
+/** Is `gh` here, logged in, and scoped to write secrets? */
+export declare function ghAuth(cwd: string): Promise<GhAuth>;
+/** `owner/repo` for this checkout, or null when there is no GitHub remote yet. */
+export declare function repoSlug(cwd: string): Promise<string | null>;
+/**
+ * Write a repository secret, with the value on STDIN.
+ *
+ * Never as an argument: an argument is visible in `ps` to every other
+ * process on the machine for as long as the call runs, and this is called
+ * with private keys.
+ */
+export declare function setSecret(cwd: string, name: string, value: string): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/** Repository secret NAMES. GitHub never gives a value back, by design. */
+export declare function secretNames(cwd: string): Promise<Set<string>>;
+/** A repository VARIABLE — readable, for things that are configuration rather than credentials. */
+export declare function setVariable(cwd: string, name: string, value: string): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+export declare function variableNames(cwd: string): Promise<Set<string>>;
+/**
+ * Ask Cloudflare whether a token is real, before it is stored anywhere.
+ *
+ * A token that is wrong should be caught at the moment it is typed, by the
+ * person who has it, and not two minutes into a CI run by someone reading a
+ * log. This is the one Cloudflare call vc makes with the token in hand.
+ *
+ * @see https://developers.cloudflare.com/fundamentals/api/reference/verify-token/
+ */
+export declare function verifyCloudflareToken(token: string): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** The accounts a token can see, so the account id never has to be typed. */
+export declare function cloudflareAccounts(token: string): Promise<Array<{
+    id: string;
+    name: string;
+}>>;

package/dist/deploy/index.d.ts

@@ -26,3 +26,6 @@ export declare function keysHelp(): Promise<number>;
  * Exit code is the whole interface — a hook cares about nothing else.
  */
 export declare function guardCommand(): Promise<number>;
+/** `vc link` — GitHub holds the credentials; this is what puts them there. */
+export declare function linkCliCommand(args: string[]): Promise<number>;
+export declare function linkHelp(): Promise<number>;

package/dist/deploy/keys.d.ts

@@ -1,34 +1,77 @@
-import type { Manifest } from "../manifest";
-/** Where the token comes from, in the order wrangler itself reads them. */
-export declare function apiToken(): string | null;
+import type { Project } from "../project";
 /**
- * The private key this token and account derive.
+ * The key that encrypts this repository's secrets.
  *
- * The account id is the salt rather than a constant, so the same token used
- * against two accounts does not produce one key — tokens are often scoped to
- * several accounts, and a shared key across them would be a wider blast
- * radius than anyone asked for.
+ * ── The realisation that shaped this ─────────────────────────────────────
+ *
+ * dotenvx is ASYMMETRIC. Encryption takes the public key; only decryption
+ * takes the private one. The public key is committed at the top of
+ * `.env.secrets`, so ADDING OR CHANGING A SECRET NEEDS NO CREDENTIAL AT
+ * ALL — not a Cloudflare token, not a wrangler login, not even this file.
+ * Anyone who can clone the repository can set a secret in it; nobody who
+ * can clone it can read one.
+ *
+ * That collapses the problem. The private key is needed in exactly one
+ * place — wherever the deploy runs — and nowhere else, ever.
+ *
+ * ── Why the key lives in GitHub ──────────────────────────────────────────
+ *
+ * The first design derived it from a Cloudflare API token, which put the
+ * bootstrap in the wrong order: the token authorises a worker that does not
+ * exist yet, and obtaining one means `wrangler login`. It also made every
+ * secret unreadable the day the token rotated, and gave two admins two
+ * different keys.
+ *
+ * So the key is generated at random and handed to GitHub, which is where
+ * the deploy runs and the one place a person who can push is already
+ * authenticated. It is never written to disk. `gh secret set` takes it on
+ * stdin, GitHub encrypts it, and no API can read it back — which is the
+ * property that makes it a good home and, unavoidably, the property that
+ * makes rotation a re-key rather than a re-encrypt.
+ *
+ * ── Rotation, and why losing the key is survivable ───────────────────────
+ *
+ * Nothing can read a GitHub secret back, so re-encrypting the existing
+ * ciphertext needs a local copy of the old key. Usually there is none, and
+ * that is fine: the only reason to rotate an encryption key is that it may
+ * have leaked, and a key that may have leaked means the VALUES may have
+ * leaked. Those must be replaced at Stripe and everywhere else regardless.
+ * Re-entering them is not extra work — it is the work.
  */
-export declare function derivePrivateKey(token: string, accountId: string): string;
-/** The public key for a private one, via dotenvx's own primitive. */
-export declare function publicKeyFor(privateKey: string): Promise<string | null>;
-/** The public key the repository was actually encrypted under. */
+/** The public key the repository was encrypted under, from the committed file. */
 export declare function committedPublicKey(root: string): string | null;
-export type KeyState = {
-    ok: true;
+/** A fresh secp256k1 pair. The private half must reach GitHub and then be forgotten. */
+export declare function generateKeypair(): Promise<{
+    publicKey: string;
     privateKey: string;
+} | null>;
+export declare function publicKeyFor(privateKey: string): Promise<string | null>;
+export interface KeyState {
+    /** The public key in `.env.secrets`, if the file exists. */
+    publicKey: string | null;
+    /** Does GitHub hold a private key for this repository? Names only — values never come back. */
+    inGitHub: boolean;
+    /** `owner/repo`, or null when there is no GitHub remote yet. */
+    slug: string | null;
+    /** A local override, for deploying by hand without CI. */
+    localKey: string | null;
+    /** Set when the local override does not match the committed public key. */
+    mismatch?: string | undefined;
+}
+export declare function keyState(project: Project): Promise<KeyState>;
+/**
+ * Make a key and give it to GitHub.
+ *
+ * Returns the PUBLIC key for the caller to write into `.env.secrets`. The
+ * private key is deliberately not returned and not logged: it exists as a
+ * local variable for the length of one `gh` call and then goes out of scope.
+ */
+export declare function provisionKey(project: Project): Promise<{
+    ok: true;
     publicKey: string;
-    fresh: boolean;
 } | {
     ok: false;
     reason: string;
-};
-/**
- * The key for this repository, or a refusal that says exactly what is wrong.
- *
- * `fresh` means the repository has no secrets yet, so there is nothing to
- * check the derivation against and any token is as good as another.
- */
-export declare function keyFor(manifest: Manifest, root: string): Promise<KeyState>;
-/** `vc keys` — what the derivation says, without printing anything secret. */
-export declare function keysCommand(manifest: Manifest, root: string, args: string[]): Promise<number>;
+}>;
+/** `vc keys` — where the key is, and what is missing. */
+export declare function keysCommand(project: Project, args: string[]): Promise<number>;

package/dist/deploy/link.d.ts

@@ -0,0 +1,2 @@
+import type { Project } from "../project";
+export declare function linkCommand(project: Project, args: string[]): Promise<number>;

package/dist/deploy/secrets.d.ts

@@ -12,10 +12,11 @@ import type { Project } from "../project";
  *
  * dotenvx closes it. `.env.secrets` holds ciphertext and a public key, and
  * it is COMMITTED: the key names are readable, the values are not, and a
- * diff shows when a secret changed without showing what it changed to. The
- * private key is not stored at all — it is derived from the Cloudflare API
- * token, so whoever can deploy the worker can read its secrets and nobody
- * else can. See `./keys.ts`, which also spells out what that costs.
+ * diff shows when a secret changed without showing what it changed to.
+ *
+ * Because dotenvx is asymmetric, SETTING a secret needs only the committed
+ * public key — no credential, no login, no key file. The private key lives
+ * in one place, GitHub Actions, and only the deploy uses it. See `./keys.ts`.
  *
  * ── Why the values still become worker SECRETS ───────────────────────────
  *
@@ -34,10 +35,9 @@ import type { Project } from "../project";
  * in the history, including ones that were rotated — which is not true of
  * `wrangler secret put`, where a rotation genuinely retires the old value.
  *
- * And because the key is derived, rotating the API token orphans the lot.
- * `keys.ts` guards that with a public-key check, so the failure is a clear
- * refusal rather than a decryption error nobody can place — but the guard
- * cannot recover values, only explain them.
+ * And GitHub will not hand a secret back once set, so re-keying means
+ * entering the values again. That is the right trade: a key worth rotating
+ * is a key that may have leaked, and the values then need replacing anyway.
  *
  * Both are the price of a shop that rebuilds from a checkout, and both
  * should be decisions rather than surprises.
@@ -46,6 +46,19 @@ export declare const SECRETS_FILE = ".env.secrets";
 export declare const PRIVATE_KEY_VAR = "DOTENV_PRIVATE_KEY_SECRETS";
 /** dotenvx, from the project's own install rather than a global one. */
 export declare function findDotenvx(from: string): string | null;
+export declare function run(cmd: string, args: string[], cwd: string, env?: Record<string, string>): Promise<{
+    code: number;
+    out: string;
+}>;
+/**
+ * Put a public key at the top of `.env.secrets`, creating the file if it is
+ * not there yet.
+ *
+ * Only the public half is ever written to disk, and it is meant to be
+ * committed: it is what lets anyone with a clone SET a secret without
+ * holding a credential.
+ */
+export declare function committedPublicKeyInto(root: string, publicKey: string): void;
 /**
  * The names a `.env.secrets` declares, read WITHOUT decrypting.
  *
@@ -72,3 +85,33 @@ export declare function decryptSecrets(project: Project): Promise<DecryptedSecre
 }>;
 /** `vc secrets` — what the repository declares, and whether it is readable here. */
 export declare function secretsCommand(project: Project, args: string[]): Promise<number>;
+/** Write a `.env.secrets` with every required key as the `unset` sentinel. */
+export declare function initSecrets(project: Project): Promise<number>;
+/**
+ * `vc secrets set KEY` — change one value, with no credential of any kind.
+ *
+ * This is the command the whole design exists to make possible. dotenvx
+ * encrypts with the public key sitting in the committed file, so a
+ * contributor with a clone and nothing else can rotate the Stripe key. They
+ * cannot read the one that is there, which is exactly right.
+ *
+ * The value is read from the terminal or from stdin, never from argv: an
+ * argument is visible in `ps` to every process on the machine while the
+ * command runs, and shells keep it in history besides.
+ */
+export declare function setSecretValue(project: Project, args: string[]): Promise<number>;
+/**
+ * Encrypt one value into `.env.secrets`, in process.
+ *
+ * Deliberately NOT `dotenvx set NAME value -f …`: that takes the value as an
+ * argument, and an argument is visible in `ps` to every other process on the
+ * machine for as long as the call runs. This uses the same secp256k1 the CLI
+ * uses — it is the CLI's own library — so what it writes is byte-compatible
+ * with what `dotenvx decrypt` expects.
+ */
+export declare function encryptInto(root: string, publicKey: string, name: string, value: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/generate/ci.d.ts

@@ -1,23 +1,38 @@
 import type { Manifest } from "../manifest";
 /**
- * The workflow that turns a push into a deploy.
- *
- * ── Why a branch and not a build ─────────────────────────────────────────
- *
- * Cloudflare's Workers Builds watches a repository and builds what it finds.
- * A strict repository has no app in it — `.vc/app` is generated and
- * gitignored — and Cloudflare documents nothing about a build command that
- * writes the source it then builds. The install step's ordering against a
- * generated `package.json` is undocumented, which is not a thing to guess at
- * in the path that puts a shop on the internet.
- *
- * So the generator runs in GitHub Actions, where it is ordinary, and pushes
- * the result to its own branch. `main` stays the manifest and the data;
- * `void-dist` is a plain Void app with a committed `package.json`, lockfile
- * and `wrangler.jsonc` that anything can build from a cold checkout.
- * Cloudflare is pointed at that branch and needs to know nothing about
- * voidcommerce — which also means the deploy path is one a person can run by
- * hand when CI is not the answer.
+ * The workflow that turns a push into a live shop.
+ *
+ * ── Why GitHub Actions deploys, and not Cloudflare's own build ───────────
+ *
+ * Cloudflare's Workers Builds can watch a repository, and for a while that
+ * was the plan. Three things make it the wrong end to drive from.
+ *
+ * The build secret. `.env.secrets` is ciphertext, so something must hold
+ * the key that opens it. Workers Builds takes build variables ONLY from the
+ * dashboard — there is no repository file for them — so the one credential
+ * that makes push-to-deploy work would have to be pasted into a web page.
+ *
+ * The token. The API token Cloudflare generates for its own builds has no
+ * D1 and no Queues permission, so it cannot create this shop's database.
+ * Replacing it is another dashboard visit.
+ *
+ * The bootstrap. Connecting the repository is itself a dashboard step, on a
+ * Worker that has to exist first.
+ *
+ * GitHub already has what is needed. A person who can push is logged into
+ * `gh`, and `gh` can write repository secrets from the terminal — so
+ * `vc link` puts the key and the token there in one command, and this
+ * workflow spends them. Nothing is typed into a web page except the token
+ * itself, once, because Cloudflare will not issue one any other way.
+ *
+ * ── The `void-dist` branch is still built ────────────────────────────────
+ *
+ * It is no longer the deploy path, but it stays: a plain Void app with a
+ * committed lockfile and `wrangler.jsonc` that anything can build from a
+ * cold checkout. It is what makes the deploy reproducible by hand, and it
+ * is the escape hatch for anyone who does want Cloudflare's build after all.
+ *
+ * @see https://developers.cloudflare.com/workers/ci-cd/builds/configuration/#api-token
  */
 export declare function renderDistWorkflow(manifest: Manifest): string;
 /** What a person still has to do once, and why each thing cannot be done for them. */

package/dist/generate/frontend.d.ts

@@ -1,4 +1,4 @@
-import type { Manifest } from "../manifest";
+import { type Manifest } from "../manifest";
 /**
  * The storefront: a static Void site that talks to the worker over HTTP.
  *

package/dist/generate/index.d.ts

@@ -22,6 +22,8 @@ import { envSummary } from "./env";
 export interface GenerateResult {
     written: string[];
     kept: string[];
+    /** Generated files that no longer belong, and were deleted. */
+    retired: string[];
     packages: string[];
 }
 export declare function generate(root: string, manifest: Manifest): Promise<GenerateResult>;