diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..f9384e3 --- /dev/null +++ b/README.en.md @@ -0,0 +1,391 @@ +

+ + PinMe logo +

PinMe

+ +

+ +

+ Create and deploy your web in one command. +

+ +# PinMe + +[PinMe](https://pinme.eth.limo/) is a zero-config deployment CLI focused on one-command creation and deployment for full-stack projects. + +It lets you quickly set up and launch a complete project with an integrated frontend, Worker backend, and database, without tedious configuration. PinMe is built to make full-stack delivery much simpler and significantly improve development efficiency. + +Website: [https://pinme.eth.limo/](https://pinme.eth.limo/) + +> **PinMe Skill** +> +> Install the PinMe skill before using PinMe in agent workflows: +> +> ```bash +> npx skills add glitternetwork/pinme +> ``` + +## Table of Contents + +- [Quick Start](#quick-start) +- [For AI Agents](#for-ai-agents) +- [Installation](#installation) +- [PinMe Project Workflow](#pinme-project-workflow) +- [Authentication and Account Commands](#authentication-and-account-commands) +- [Static Uploads and IPFS Utilities](#static-uploads-and-ipfs-utilities) +- [Command Reference](#command-reference) +- [Development and Testing](#development-and-testing) +- [Limits and Operational Notes](#limits-and-operational-notes) +- [Examples](#examples) +- [Support](#support) + +## Quick Start + +### Prerequisites + +- Node.js `>= 16.13.0` + +### Create a new Worker project + +```bash +npm install -g pinme +pinme login +pinme create my-app +cd my-app +pinme save +``` + +What this workflow gives you: + +- a generated PinMe project from the official template +- platform-side Worker and database provisioning +- local project config in `pinme.toml` +- frontend and Worker deployment from one CLI + +### Update only the part you changed + +```bash +pinme update-worker +pinme update-db +pinme update-web +``` + +### Upload a static build when you do not need the project workflow + +```bash +pinme login +pinme upload dist +``` + +Common build directories are `dist`, `build`, `out`, and `public`. + +## For AI Agents + +Prefer the PinMe project workflow when the user wants a frontend plus backend plus database, or when the repo already contains `pinme.toml`. + +### Project-mode protocol + +Use this flow when the user wants a Worker app, database migrations, or ongoing project updates. + +1. Check Node.js: + +```bash +node --version +``` + +2. Ensure the CLI is available: + +```bash +npm install -g pinme +``` + +3. Authenticate: + +```bash +pinme login +``` + +4. Choose the right project command: + +- create a new project: `pinme create ` +- deploy everything from a PinMe project root: `pinme save` +- update Worker only: `pinme update-worker` +- update SQL migrations only: `pinme update-db` +- update frontend only: `pinme update-web` + +5. If the repo contains `pinme.toml`, run project commands from that directory. + +6. Return the final project URL printed by the CLI for frontend deploys. For Worker-only or DB-only updates, return the relevant success result instead of fabricating a URL. + +### Static-upload fallback + +Use this only when the task is just "publish the built frontend" and there is no PinMe project workflow involved. + +1. Authenticate: + +```bash +pinme login +``` + +Or for automation: + +```bash +pinme set-appkey +``` + +2. Find the built output directory in this order: + +- `dist/` +- `build/` +- `out/` +- `public/` + +3. Verify the directory exists and contains built assets such as `index.html`. + +4. Upload it: + +```bash +pinme upload +``` + +### Guardrails + +- Do not upload source folders such as `src/`. +- Do not upload `node_modules`, `.git`, or `.env`. +- Do not claim unsupported backend hosting outside the PinMe project template flow. +- For project commands, do not run `update-*` commands outside a PinMe project root with `pinme.toml`. + +## Installation + +Install from npm: + +```bash +npm install -g pinme +``` + +Verify installation: + +```bash +pinme --version +``` + +## PinMe Project Workflow + +### What `create` sets up + +`pinme create ` does more than scaffold files. The command: + +- requires an authenticated session +- creates the platform project resources first +- downloads the official Worker project template +- writes project metadata into `pinme.toml` +- writes backend metadata and frontend config files +- installs workspace dependencies +- builds the Worker +- uploads Worker code and SQL files +- builds the frontend and attempts an initial frontend upload + +After creation, the CLI prints the project management URL and suggests `pinme save` for the next deploy. + +### Create a project + +```bash +pinme login +pinme create my-app +``` + +If the target directory already exists, the CLI asks before overwriting it unless `--force` is used. + +### Deploy the whole project + +Run this from the project root that contains `pinme.toml`: + +```bash +pinme save +pinme save --domain my-site +pinme save --domain example.com +``` + +`save` performs the full deploy path: + +- installs project dependencies +- builds the Worker with `npm run build:worker` +- uploads Worker code and SQL files from `db/` +- builds the frontend with `npm run build:frontend` +- uploads `frontend/dist` +- optionally binds a domain after the frontend deploy + +### Update only one layer + +Use targeted commands when only one part changed: + +```bash +pinme update-worker +pinme update-db +pinme update-web +``` + +What each command expects: + +- `update-worker`: builds and uploads Worker code from the current PinMe project +- `update-db`: uploads `.sql` files from `db/` +- `update-web`: builds and uploads `frontend/dist` + +### Delete a project + +```bash +pinme delete +pinme delete my-app +pinme delete my-app --force +``` + +This deletes the platform-side Worker, domain binding, and D1 database. Local files remain unchanged. + +## Authentication and Account Commands + +### Login and AppKey + +```bash +pinme login +pinme login --env test + +pinme set-appkey +pinme set-appkey + +pinme show-appkey +pinme appkey + +pinme logout +``` + +Notes: + +- `pinme login` is the recommended path for project commands. +- `set-appkey` is the alternative authentication method for CLI and automation usage. + +### Domains, wallet, and history + +```bash +pinme my-domains +pinme domain + +pinme wallet +pinme wallet-balance +pinme balance + +pinme list +pinme ls +pinme list -l 5 +pinme list -c +``` + +## Static Uploads and IPFS Utilities + +These commands are useful when you already have artifacts and do not need the full Worker project flow. + +### Upload a directory or file + +```bash +pinme upload +pinme upload ./dist +pinme upload ./dist --domain my-site +pinme upload ./dist --domain example.com +pinme upload ./dist --domain my-site --dns +``` + +Domain handling: + +- domains containing a dot are treated as DNS domains +- domains without a dot are treated as PinMe subdomains +- `--dns` forces DNS mode + +### Bind while uploading + +```bash +pinme bind ./dist --domain my-site +pinme bind ./dist --domain example.com +``` + +`bind` requires wallet balance. + +### Import or export CAR files + +```bash +pinme import +pinme import ./site.car +pinme import ./site.car --domain my-site + +pinme export +pinme export --output ./exports +``` + +### Remove uploaded content + +```bash +pinme rm +pinme rm +``` + +## Command Reference + +| Command | What it does | +| --------------------------------------------------------- | ------------------------------------------------------------ | +| `pinme create [name]` | Create a new PinMe Worker project from the official template | +| `pinme save [--domain ]` | Deploy the current PinMe project: Worker, SQL, and frontend | +| `pinme update-worker` | Build and upload Worker code only | +| `pinme update-db` | Upload SQL migrations from `db/` only | +| `pinme update-web` | Build and upload the frontend only | +| `pinme delete [name] [--force]` | Delete a platform project | +| `pinme upload [path]` | Upload a file or directory to IPFS | +| `pinme bind [path] --domain ` | Upload and bind a domain | +| `pinme import [path]` | Import a CAR file | +| `pinme export [--output ]` | Export IPFS content as a CAR file | +| `pinme rm [value]` | Remove uploaded content | +| `pinme login [--env test\|prod]` | Login via browser | +| `pinme set-appkey [AppKey]` | Set authentication with an AppKey | +| `pinme show-appkey` / `pinme appkey` | Show masked AppKey info | +| `pinme my-domains` / `pinme domain` | List domains owned by the current account | +| `pinme wallet` / `pinme wallet-balance` / `pinme balance` | Show current wallet balance | +| `pinme list` / `pinme ls` | Show upload history | +| `pinme help` | Show CLI help | + +## Development and Testing + +PinMe uses Vitest for unit/integration tests, real `dist/index.js` CLI smoke tests, npm package checks, and Stryker for slower mutation testing. + +```bash +npm run test # Unit and integration tests +npm run test:coverage # Coverage gate for core modules +npm run test:cli # Real CLI black-box tests +npm run test:pack # npm pack/package-shape checks +npm run verify # Full pull-request gate +npm run test:mutation # Slow mutation tests for manual/nightly runs +``` + +Tests must not call live PinMe/IPFS/CAR services. Use `nock`, local loopback servers, fixtures, and temporary HOME directories for API and CLI scenarios. + +For the full testing policy, layout, and mutation-testing guidance, see +[TESTING.md](TESTING.md). + +## Limits and Operational Notes + +- Default single-file upload limit: `100MB` +- Default directory upload limit: `500MB` +- These upload defaults come from the CLI and can be overridden with environment variables +- `update-db` enforces a total SQL payload limit of `10MB` per run +- `upload`, `import`, and project commands require authentication +- domain binding requires wallet balance +- `save`, `update-worker`, `update-db`, and `update-web` expect to run from a PinMe project root with `pinme.toml` + +## Examples + +This repo includes example projects and docs: + +- [example/docs](./example/docs) +- [example/pinme-blog](./example/pinme-blog) +- [example/supabase](./example/supabase) + +## Support + +- Website: [https://pinme.eth.limo/](https://pinme.eth.limo/) +- GitHub: [https://github.com/glitternetwork/pinme](https://github.com/glitternetwork/pinme)