fabrica-e-commerce 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +113 -78
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,122 +1,157 @@
1
1
  # fabrica-e-commerce
2
2
 
3
- Orange themed NPX CLI for launching a Fabrica e-commerce storefront from CMD or any terminal.
3
+ Orange-themed NPX CLI for launching a Fabrica e-commerce storefront (Supabase + Vercel + Next.js) from any terminal — Windows, macOS, Linux, and Termux (no root required).
4
4
 
5
- ## Install / run
5
+ ## Quick start
6
6
 
7
7
  ```bash
8
- npx fabrica-e-commerce help
9
8
  npx fabrica-e-commerce build
10
9
  ```
11
10
 
12
- The package exposes both `fabrica` and `fabrica-e-commerce` binaries after global install.
11
+ Or install globally:
13
12
 
14
13
  ```bash
15
14
  npm install -g fabrica-e-commerce
16
15
  fabrica build
17
16
  ```
18
17
 
18
+ Both `fabrica` and `fabrica-e-commerce` binaries are available after a global install.
19
19
 
20
- ## Local NPX-style package test
20
+ ---
21
21
 
22
- Before publishing, test the package exactly like a fresh command-line install:
22
+ ## Commands
23
23
 
24
- ```bash
25
- npm run build
26
- npm pack --dry-run
27
- npm exec --yes --package . -- fabrica help
28
- npm exec --yes --package . -- fabrica info
29
- ```
24
+ | Command | Description |
25
+ |---------|-------------|
26
+ | `build` | Full deploy wizard — Supabase → secrets → admin password → clone → Vercel or local |
27
+ | `list` | Show all projects and view details |
28
+ | `env` | Update environment variables for any project |
29
+ | `rerun` | Re-open or restart an existing project |
30
+ | `vins` | Verify and auto-install CLI dependencies (git, gh, vercel) |
31
+ | `clean` | Remove local data, env files, or logout from Vercel / GitHub |
32
+ | `info` | Package, bridge, repo, and storage info |
33
+ | `help` | Show the command guide |
30
34
 
31
- You can also run the bundled pack test, which creates a real `.tgz` tarball and executes the installed binary from that tarball:
35
+ ---
32
36
 
33
- ```bash
34
- npm run test:pack
35
- ```
37
+ ## Build flow (6 steps)
36
38
 
37
- On Windows CMD, these commands do not require Unix tools such as `find` or `xargs`; the build script uses a Node.js checker instead.
39
+ ### Step 1 — Dependency check
40
+ Verifies `git` is installed. Auto-installs it if missing.
38
41
 
39
- ## Commands
42
+ ### Step 2 — Supabase connect
43
+ Posts your schema/seed SQL to the Fabrica bridge (`sparrow-supabase-connect.lovable.app`), opens the OAuth connect URL in your browser, and polls until the Supabase project is provisioned and returns `{ url, anonKey }`.
44
+
45
+ ### Step 3 — Environment variables
46
+ Prompts for your API keys:
47
+
48
+ | Variable | Purpose |
49
+ |----------|---------|
50
+ | `RAZORPAY_KEY_ID` | Razorpay payment key ID |
51
+ | `RAZORPAY_KEY_SECRET` | Razorpay payment secret |
52
+ | `OPENROUTER_API_KEY` | OpenRouter AI API key |
53
+ | `UMAMI_WEBSITE_ID` | Umami analytics website ID |
54
+ | `UMAMI_API_KEY` | Umami analytics API key |
55
+ | `SHIPPO_API_KEY` | Shippo shipping API key |
56
+
57
+ `SUPABASE_URL` and `SUPABASE_ANON_KEY` are filled automatically from the bridge response.
58
+
59
+ ### Step 4 — Admin password
60
+ Prompts for a password to protect your store's admin and edit panel. Stored as the `PASS` environment variable.
61
+
62
+ ### Step 5 — Clone storefront
63
+ Clones `https://github.com/trucount/fabrica-final-e-c.git` into a local builds directory. Asks for a project name (used as the Vercel project name).
64
+
65
+ ### Step 6 — Deploy target
66
+ Choose how to run your store:
67
+
68
+ **Local mode**
69
+ - Writes all collected variables to `.env.local` inside the cloned app.
70
+ - Runs `pnpm install` (or `npm install`) and starts the Next.js dev server at `http://localhost:3000`.
40
71
 
41
- - `build` — checks Git, creates a Fabrica Connect Supabase job, opens the OAuth bridge, asks for required secrets, clones `https://github.com/trucount/fabrica-final-e-c.git`, then asks whether to run locally or deploy on Vercel. Local mode writes `.env.local`, installs dependencies, and starts the Next.js dev server. Vercel mode checks GitHub/Vercel dependencies, verifies/logs in to Vercel, creates a user-owned repo from the hardcoded storefront source (fork/template, not `git push`), connects Vercel to that repo, writes every environment variable to production/preview/development, and deploys with `vercel --prod`.
42
- - `list` — shows locally saved deployments and lets you replace a saved project's Vercel environment variable (across production, preview, and development), then redeploys.
43
- - `vins` — verifies the CLI's external dependencies (`git`, GitHub CLI `gh`, and the Vercel CLI via `npx`) and automatically installs anything missing using your system's package manager (`apt-get`/`dnf`/`pacman` on Linux, `brew` on macOS, `winget`/`choco` on Windows). Prints manual install links for anything it can't install automatically.
44
- - `info` / `.info` — prints package, bridge, repository, and local data paths.
45
- - `help` — prints the command guide.
46
-
47
- ## Build flow
48
-
49
- 1. Posts the hidden schema/seed SQL to `https://sparrow-supabase-connect.lovable.app/api/public/jobs` using the configured bridge API key.
50
- 2. Opens the returned `connectUrl` in the browser and polls until `{ status: "done", url, anonKey }` is returned.
51
- 3. Prompts for user-owned secrets:
52
- - `RAZORPAY_KEY_ID`
53
- - `RAZORPAY_KEY_SECRET`
54
- - `OPENROUTER_API_KEY`
55
- - `UMAMI_WEBSITE_ID`
56
- - `UMAMI_API_KEY`
57
- - `SHIPPO_API_KEY`
58
- 4. Adds hardcoded values requested by the project:
59
- - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=0000`
60
- - `UMAMI_API_CLIENT_ENDPOINT=https://api.umami.is/v1`
61
- - `SUPABASE_SERVICE_ROLE_KEY=0000`
62
- 5. Adds `SUPABASE_URL` and `SUPABASE_ANON_KEY` from the bridge response.
63
- 6. **Step 3 — run target:**
64
- - Asks whether to run the storefront **locally** or deploy on **Vercel cloud**.
65
- - Local mode writes every collected variable to `.env.local` inside the cloned Next.js app, installs dependencies (`pnpm install` when available, otherwise `npm install`), and starts `pnpm run dev`/`npm run dev` at `http://localhost:3000`.
66
- - Vercel mode verifies you're logged in to Vercel (`vercel whoami`); if not, runs an interactive `vercel login` and waits for it to finish.
67
- - Vercel mode logs in to the GitHub CLI if needed (`gh auth login`) and creates a user-owned repo from the hardcoded storefront source with a fork/template flow, avoiding local `git push` credentials.
68
- - Vercel mode links a new Vercel project with `vercel link --yes --project <name>` and connects it to the new GitHub repo with `vercel git connect` so future pushes auto-deploy.
69
- - Vercel mode writes every collected environment variable (including the Supabase URL/anon key) to the **production, preview, and development** environments with `vercel env add`, so the values are permanent for the project, not just the first deploy.
70
- - Vercel mode creates the production deployment with `vercel --prod --yes`.
71
-
72
- ## Dependency check (`vins`)
73
-
74
- Run `npx fabrica-e-commerce vins` any time to verify the tools the CLI depends on:
72
+ **Vercel cloud mode**
73
+ - Checks and installs `gh` (GitHub CLI) and `vercel` CLI if missing.
74
+ - Logs in to Vercel interactively if needed.
75
+ - Logs in to GitHub CLI if needed and forks the storefront to a new user-owned repo.
76
+ - Links a new Vercel project and connects it to the GitHub repo for auto-deploys.
77
+ - Writes every environment variable to **production, preview, and development** environments with `vercel env add`.
78
+ - Deploys with `vercel --prod`.
79
+
80
+ ---
81
+
82
+ ## Dependency installer (`vins`)
83
+
84
+ `vins` checks for `git`, `gh`, and the Vercel CLI and auto-installs anything missing — **no root or admin required** on any platform.
75
85
 
76
86
  ```bash
77
87
  npx fabrica-e-commerce vins
78
88
  ```
79
89
 
80
- It checks for `git`, the GitHub CLI (`gh`), and the Vercel CLI (via `npx`), and tries to install anything missing using the right package manager for your OS. If a tool can't be installed automatically (for example, no package manager is available), it prints a manual install link and exits with a non-zero status so scripts can detect the failure.
90
+ | Platform | Install strategy |
91
+ |----------|-----------------|
92
+ | **Termux** | `pkg install` — no root needed |
93
+ | **Linux (no root)** | Homebrew/Linuxbrew → system pkg manager (tries without sudo first) → conda/mamba → binary download from GitHub releases |
94
+ | **Linux (with sudo)** | apt-get / dnf / yum / pacman / zypper / apk |
95
+ | **macOS** | `brew install` → auto-installs Homebrew if missing → binary download |
96
+ | **Windows (no admin)** | `winget --scope user` → auto-installs Scoop → `scoop install` → Chocolatey |
81
97
 
98
+ If a tool still can't be installed automatically, `vins` prints the correct manual install command for your platform and exits with a non-zero status.
82
99
 
100
+ ---
83
101
 
84
- ## Windows Vercel command note
102
+ ## Managing projects
85
103
 
86
- The CLI runs npm-launched commands through `npx.cmd` on Windows, so `npx vercel@latest ...` works from CMD and PowerShell instead of failing with `'vercel@latest' is not recognized`. If you still see Vercel login prompts, complete them in the browser and rerun the command.
104
+ ### `list`
105
+ Shows all projects saved locally with their type (local/cloud), creation date, GitHub repo, Supabase URL, and live URL.
87
106
 
88
- ## Automatic npm publishing from GitHub
107
+ ### `env`
108
+ Lets you update any environment variable for a saved project. For local projects it rewrites `.env.local`. For cloud projects it updates Vercel (production, preview, development) and triggers a redeploy.
89
109
 
90
- The repository includes a GitHub Actions workflow at `.github/workflows/npm-publish.yml` that verifies the CLI and publishes it to npm on pushes to `main`, `master`, or `work`, and can also be started manually from the Actions tab.
110
+ ### `rerun`
111
+ - **Local projects** — restarts the dev server at `http://localhost:3000`.
112
+ - **Cloud projects** — opens the production URL in your browser.
91
113
 
92
- Before the workflow can publish, add an npm automation token to your GitHub repository secrets:
114
+ ### `clean`
115
+ Offers four modes: delete local project records, wipe env files, logout from Vercel, logout from GitHub, or a full reset of all of the above.
93
116
 
94
- 1. Create an npm token with publish permissions from your npm account.
95
- 2. In GitHub, open **Settings → Secrets and variables → Actions**.
96
- 3. Add a repository secret named `NPM_TOKEN` with that npm token.
117
+ ---
97
118
 
98
- On every publish run, the workflow:
119
+ ## Local project records
99
120
 
100
- 1. Runs `npm run build`.
101
- 2. Runs `npm run test:cli`.
102
- 3. Runs `npm run test:pack`.
103
- 4. Checks the current latest version on npm and bumps `package.json` to the next patch version when needed.
104
- 5. Runs `npm publish --access public --provenance`.
105
- 6. Commits the published version back to GitHub with `[skip npm-publish]` to avoid an infinite publish loop.
121
+ Deployment metadata is saved to `~/.fabrica-ecommerce/projects.json`. Secret values are **not** stored — only variable names, project path, repo URL, creation date, and Supabase URL are recorded.
106
122
 
107
- The workflow publishes `fabrica-e-commerce` as an unscoped public npm package. The package name must be available on npm, and your `NPM_TOKEN` account must have permission to publish it.
123
+ ---
108
124
 
125
+ ## Requirements
109
126
 
110
- For npm provenance publishing, `package.json` includes a `repository.url` that matches the GitHub repository used by the workflow. Keep that URL in sync if you move the repository, otherwise npm will reject the provenance bundle.
127
+ - **Node.js 18.17+**
128
+ - **Git** — run `npx fabrica-e-commerce vins` to auto-install
129
+ - **GitHub CLI (`gh`)** — run `vins` to auto-install; interactive login handled by `build`
130
+ - **Vercel account** — login is handled interactively by `build` if needed
131
+ - A **Supabase** account connected via the Fabrica bridge
111
132
 
112
- ## Local project records
133
+ ---
113
134
 
114
- Deployment metadata is saved to `~/.fabrica-ecommerce/projects.json`. Secret values are not stored; only the variable names, project path, repo URL, created date, and Supabase URL are saved.
135
+ ## Automatic npm publishing (GitHub Actions)
115
136
 
116
- ## Requirements
137
+ The workflow at `.github/workflows/npm-publish.yml` verifies and publishes to npm on every push to `main`, `master`, or `work`, and can be triggered manually from the Actions tab.
138
+
139
+ **Setup — add your npm token once:**
140
+ 1. Create an npm token with publish permissions.
141
+ 2. In GitHub go to **Settings → Secrets and variables → Actions**.
142
+ 3. Add a secret named `NPM_TOKEN`.
143
+
144
+ **What the workflow does on each run:**
145
+ 1. Upgrades npm to the latest version (avoids bundled-npm bugs on GitHub runners).
146
+ 2. Runs `npm install`, `npm run build`, `npm run test:cli`, `npm run test:pack`.
147
+ 3. Bumps `package.json` to the next patch version if the current version is already published.
148
+ 4. Publishes with `npm publish --access public --provenance`.
149
+ 5. Commits the bumped version back to GitHub with `[skip npm-publish]` to prevent an infinite loop.
150
+
151
+ > The `repository.url` in `package.json` must match the GitHub repo used by the workflow — npm uses it to verify the provenance bundle.
152
+
153
+ ---
154
+
155
+ ## Windows notes
117
156
 
118
- - Node.js 18.17+
119
- - Git installed and available in PATH
120
- - [GitHub CLI](https://github.com/cli/cli) (`gh`) installed and available in PATH — used to create the new repository and push the storefront code. Logging in (`gh auth login`) is handled interactively by `build` if needed.
121
- - A Vercel account. The Vercel CLI will prompt/login when required (`build` also runs this check up front).
122
- - Run `npx fabrica-e-commerce vins` to check for and auto-install `git`/`gh` if either is missing.
157
+ The CLI spawns npm commands through `npx.cmd` on Windows so `npx vercel@latest ...` works correctly from CMD and PowerShell. If you see a Vercel login prompt, complete it in your browser and the CLI will continue automatically.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fabrica-e-commerce",
3
- "version": "0.2.3",
3
+ "version": "0.2.4",
4
4
  "description": "CLI launcher for deploying Fabrica e-commerce stores — Supabase + Vercel, works on Windows, macOS, Linux & Termux.",
5
5
  "type": "module",
6
6
  "bin": {