shopify-tunnel-dev 0.1.0 → 0.3.0

package/README.md

@@ -1,118 +1,103 @@
 # shopify-tunnel-dev
 
-Chạy `shopify app dev` sau một Cloudflare named tunnel có **hostname cố định**. Cả team dùng chung
-một bộ credential, dev mới chỉ cần đặt `VITE_HOST` rồi chạy, không ai phải cấp tunnel hay cert.
+Run `shopify app dev` behind a Cloudflare named tunnel with a **fixed hostname**. The team shares one
+set of credentials; a new dev picks a hostname and runs. Nobody provisions tunnels or certificates.
 
-Cùng cơ chế và cùng tên biến với `@bss-sbc/shopify-dev`, nên repo đang dùng tool đó đổi sang được
-mà không phải sửa `.env` hay `account.json`. Không có dependency, cần Node >= 20.12.
+Zero dependencies. Node >= 20.12.
 
-## Cách chạy
+## How it works
 
-```
-pnpm dev
-  ├─ đọc web/.env hoặc .env, sau đó .cloudflared/account.json (account.json đè lên)
-  ├─ tìm tunnel tên = phần đầu của VITE_HOST, chưa có thì tạo bằng secret chung
-  ├─ trỏ DNS VITE_HOST về tunnel (không ghi đè record của tunnel khác)
-  ├─ chạy connector về http://localhost:$VITE_PORT, chờ edge nhận kết nối
-  └─ npx shopify app dev --tunnel-url https://$VITE_HOST:$VITE_PORT
-```
+1. Reads `DEV_HOST` / `DEV_PORT` from `.env`, shared credentials from `.cloudflared/`.
+2. Finds the tunnel named after the first label of `DEV_HOST`, creates it on first run.
+3. Points DNS for `DEV_HOST` at the tunnel.
+4. Starts the connector to `http://localhost:$DEV_PORT`.
+5. Runs `shopify app dev --tunnel-url https://$DEV_HOST:$DEV_PORT`.
+
+TLS terminates at Cloudflare, so no local certificate is needed. `cloudflared` is used from `PATH`,
+or downloaded to `~/.cache/shopify-tunnel-dev/` on first run (override with `CLOUDFLARED_BIN`).
+
+## Team setup (once)
 
-HTTPS do Cloudflare xử lý, máy dev không cần cert TLS. Nếu không có `cloudflared` trên máy, lần
-chạy đầu tool tự tải bản mới nhất về `~/.cache/shopify-tunnel-dev/`. Muốn dùng binary khác thì đặt
-`CLOUDFLARED_BIN`.
+Use a Cloudflare account dedicated to dev (see [Security](#security)).
 
-## Setup một lần cho cả team
+```bash
+cloudflared tunnel login     # pick your zone, writes ~/.cloudflared/cert.pem
+openssl rand -base64 32      # tunnel secret
+```
 
-1. Dùng một Cloudflare account chỉ dành cho dev (lý do ở mục Bảo mật), thêm domain vào account đó.
-2. Chạy `cloudflared tunnel login`, chọn zone. Lệnh này sinh `~/.cloudflared/cert.pem`.
-3. Tạo secret: `openssl rand -base64 32`.
-4. Lưu cả hai lên password manager (Passbolt...), kèm `account.json`:
+Store `cert.pem` and this `account.json` in your password manager:
 
 ```json
 {
   "CF_ACCOUNT_TAG": "<account id>",
-  "CF_SECRET_KEY": "<base64 32 byte>",
-  "CF_HOST_PATTERN": "^dev-banner-[a-zA-Z0-9-]+\\.yourdomain\\.com$"
+  "CF_SECRET_KEY": "<base64 secret>",
+  "CF_HOST_PATTERN": "^dev-myapp-[a-zA-Z0-9-]+\\.example\\.com$"
 }
 ```
 
-`CF_HOST_PATTERN` là tuỳ chọn. Nên đặt để mỗi app có tiền tố riêng và không đè DNS của nhau.
+`CF_HOST_PATTERN` is optional; use it to give each app its own prefix.
 
-## Setup cho repo app
+## App repo setup
 
 ```bash
-pnpm add -D shopify-tunnel-dev       # hoặc git URL / pnpm link khi chưa publish
+pnpm add -D shopify-tunnel-dev
 ```
 
 ```json
 "scripts": { "dev": "shopify-tunnel-dev" }
 ```
 
-`.gitignore`:
-
-```
-.cloudflared/*
-!.cloudflared/*.example
+```bash
+npx shopify-tunnel-dev init
 ```
 
-`shopify.app.toml` của từng dev nên đặt `automatically_update_urls_on_dev = true` (mặc định), để
-Shopify CLI tự cập nhật URL app theo `VITE_HOST`. Mỗi dev nên có app dev riêng trên Partner, vì URL
-app nằm trên Shopify chứ không nằm ở tunnel.
+`init` creates `.cloudflared/account.json` (empty template, mode 600), adds `.cloudflared/` to
+`.gitignore`, and adds `DEV_HOST=` / `DEV_PORT=` to `.env`. It never overwrites anything, and
+`pnpm dev` runs it automatically in a fresh clone.
 
-## Dev mới
+Give each dev their own app in the Partner Dashboard; the app URL lives on Shopify, not in the tunnel.
 
-```bash
-# lấy từ password manager
-.cloudflared/cert.pem
-.cloudflared/account.json
-chmod 600 .cloudflared/*
-```
+## Per dev
 
-`.env`:
+Run `pnpm dev` once to scaffold, then fill `.cloudflared/account.json` and add `.cloudflared/cert.pem`
+from the password manager (`chmod 600 .cloudflared/*`). Set in `.env`:
 
 ```
-VITE_HOST=dev-banner-huy.yourdomain.com
-VITE_PORT=9000
+DEV_HOST=dev-myapp-alice.example.com
+DEV_PORT=9000
 ```
 
-Chạy `pnpm dev`.
-
-## Tuỳ chọn
+Run `pnpm dev`.
 
-| Flag | Tác dụng |
+| Variable | Meaning |
 |---|---|
-| `-q`, `--quick` | URL `*.trycloudflare.com` ngẫu nhiên, chỉ cần `VITE_PORT`, không cần credential |
-| `-f`, `--force` | Chiếm `VITE_HOST` dù DNS đang trỏ tunnel khác, hoặc tunnel đang có kết nối |
-| còn lại | Chuyển tiếp cho `shopify app dev` (`--reset`, `--store=...`) |
+| `DEV_HOST` | Public hostname for your dev app. Its first label is the tunnel name (3-63 chars). |
+| `DEV_PORT` | Local port Shopify CLI listens on; the tunnel forwards to it. |
 
-## Chống trùng hostname
+## Options
 
-`@bss-sbc/shopify-dev` luôn ghi đè DNS và không kiểm tra connector đang chạy, nên hai người đặt
-cùng `VITE_HOST` sẽ bị chia request ngẫu nhiên cho nhau. Tool này dừng với lỗi khi:
-
-- tunnel của `VITE_HOST` đang có kết nối sống từ máy khác;
-- DNS của `VITE_HOST` đang trỏ về tunnel khác.
+| Flag | Effect |
+|---|---|
+| `-q`, `--quick` | Random `*.trycloudflare.com` URL. Needs only `DEV_PORT`, no credentials. |
+| `-f`, `--force` | Take over `DEV_HOST` even if it is in use. |
+| anything else | Passed to `shopify app dev` (`--reset`, `--store=...`). |
 
-Nếu chính process của bạn vừa chết và tunnel còn giữ kết nối cũ, chờ vài giây hoặc chạy với `--force`.
+## Hostname collisions
 
-## Khác với `@bss-sbc/shopify-dev`
+The tool stops with an error instead of hijacking a hostname when:
 
-- Đọc `.env` bằng `util.parseEnv` của Node: dòng comment và giá trị có dấu `=` không còn làm hỏng.
-- `account.json` và `cert.pem` chỉ bắt buộc ở named mode, `--quick` không cần.
-- Credential của tunnel truyền qua env (`TUNNEL_CRED_CONTENTS`), không ghi file `<id>.json` ra đĩa.
-- Không có lệnh `start` (prod), vì prod không nên chạy qua tunnel dev.
+- the tunnel already has a live connection from another machine, or
+- the DNS record points at a different tunnel.
 
-## Bảo mật
+If your own process just died and left a stale connection, wait a few seconds or use `--force`.
 
-- `cert.pem` cho quyền tạo, xoá và trỏ DNS **mọi** tunnel trong account và zone đã chọn.
-- Ai có `CF_SECRET_KEY` thì chạy được connector cho mọi tunnel mà tool đã tạo.
+## Security
 
-Vì vậy dùng account Cloudflare riêng cho dev, và không commit hai giá trị này. Rotate: đổi secret
-trên password manager, xoá các tunnel cũ (`cloudflared tunnel delete`), lần `pnpm dev` sau sẽ tự
-tạo lại.
+- `cert.pem` can create, delete and route **every** tunnel in the account and zone.
+- `CF_SECRET_KEY` lets anyone run a connector for any tunnel this tool created.
 
-## Test
+Use a dedicated dev account and never commit either. Tunnel credentials are passed to `cloudflared`
+via environment, never written to disk.
 
-```bash
-node --test
-```
+To rotate: change the secret in the password manager, delete old tunnels
+(`cloudflared tunnel delete <name>`); the next `pnpm dev` recreates them.

package/bin/shopify-tunnel-dev.js

@@ -3,20 +3,30 @@ import { spawn } from 'node:child_process';
 import { resolveCloudflared } from '../src/cloudflared-binary.js';
 import { ConfigError, loadConfig } from '../src/load-config.js';
 import { stopCloudflared } from '../src/run-cloudflared.js';
+import { scaffoldProject } from '../src/scaffold-project.js';
 import { startNamedTunnel, startQuickTunnel } from '../src/start-tunnel.js';
 
 const USAGE = `Usage: shopify-tunnel-dev [dev] [options] [-- shopify app dev args]
+       shopify-tunnel-dev init
+
+Commands:
+  dev    Start the tunnel and shopify app dev (default)
+  init   Create .cloudflared/account.json, gitignore it, add DEV_HOST/DEV_PORT to .env
 
 Options:
   -q, --quick   Random *.trycloudflare.com URL, no Cloudflare credentials needed
-  -f, --force   Take over VITE_HOST even if its DNS record or tunnel is in use
+  -f, --force   Take over DEV_HOST even if its DNS record or tunnel is in use
   -h, --help    Show this help
 
 Any other argument (e.g. --reset, --store=foo) is passed to \`shopify app dev\`.`;
 
+const NEXT_STEPS =
+  'set DEV_HOST and DEV_PORT in .env, fill .cloudflared/account.json and add .cloudflared/cert.pem';
+
 function parseArgs(argv) {
-  const args = argv[0] === 'dev' ? argv.slice(1) : argv;
-  const opts = { quick: false, force: false, help: false, passthrough: [] };
+  const init = argv[0] === 'init';
+  const args = argv[0] === 'dev' || init ? argv.slice(1) : argv;
+  const opts = { init, quick: false, force: false, help: false, passthrough: [] };
   for (const arg of args) {
     if (arg === '-q' || arg === '--quick') opts.quick = true;
     else if (arg === '-f' || arg === '--force') opts.force = true;
@@ -29,6 +39,15 @@ function parseArgs(argv) {
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) return console.log(USAGE);
+  // `init` scaffolds explicitly; a named `dev` run in a fresh clone does the same before complaining,
+  // so the config error points at files that already exist.
+  if (opts.init || !opts.quick) {
+    const changes = scaffoldProject();
+    changes.forEach((change) => console.log(`[init] ${change}`));
+    if (changes.length) console.log(`[init] next: ${NEXT_STEPS}`);
+    else if (opts.init) console.log('[init] nothing to do');
+    if (opts.init) return;
+  }
 
   const cfg = loadConfig({ quick: opts.quick });
   const bin = await resolveCloudflared();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shopify-tunnel-dev",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Run `shopify app dev` behind a fixed-hostname Cloudflare named tunnel that the whole team shares one credential set for",
   "type": "module",
   "bin": {

package/src/load-config.js

@@ -4,9 +4,8 @@ import { parseEnv } from 'node:util';
 
 export class ConfigError extends Error {}
 
-// Same file layout and variable names as @bss-sbc/shopify-dev, so an existing repo can switch
-// without renaming anything: web/.env wins over ./.env, and .cloudflared/account.json overrides
-// keys from the env file.
+// Per-dev values come from web/.env (if present) or ./.env; team-shared values come from
+// .cloudflared/account.json, which overrides keys from the env file.
 export function loadConfig({ cwd = process.cwd(), quick = false } = {}) {
   const envPath = [path.join(cwd, 'web/.env'), path.join(cwd, '.env')].find((p) => existsSync(p));
   const cloudflaredDir = path.join(cwd, '.cloudflared');
@@ -17,28 +16,28 @@ export function loadConfig({ cwd = process.cwd(), quick = false } = {}) {
   const account = existsSync(accountPath) ? readJson(accountPath) : {};
   const vars = { ...env, ...account };
 
-  const port = Number(vars.VITE_PORT);
+  const port = Number(vars.DEV_PORT);
   if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new ConfigError(`VITE_PORT must be a port number, got "${vars.VITE_PORT ?? ''}"`);
+    throw new ConfigError(`DEV_PORT must be a port number, got "${vars.DEV_PORT ?? ''}"`);
   }
   if (quick) return { quick, port };
 
-  const missing = ['VITE_HOST', 'CF_ACCOUNT_TAG', 'CF_SECRET_KEY'].filter((key) => !vars[key]);
+  const missing = ['DEV_HOST', 'CF_ACCOUNT_TAG', 'CF_SECRET_KEY'].filter((key) => !vars[key]);
   if (missing.length) {
-    throw new ConfigError(`Missing ${missing.join(', ')}. Put VITE_HOST in .env and CF_* in ${accountPath}`);
+    throw new ConfigError(`Missing ${missing.join(', ')}. Put DEV_HOST in .env and CF_* in ${accountPath}`);
   }
   if (!existsSync(certPath)) {
     throw new ConfigError(`Missing ${certPath} (origin cert from \`cloudflared tunnel login\`)`);
   }
 
-  const host = vars.VITE_HOST.trim();
+  const host = vars.DEV_HOST.trim();
   if (vars.CF_HOST_PATTERN && !hostPattern(vars.CF_HOST_PATTERN).test(host)) {
-    throw new ConfigError(`VITE_HOST "${host}" does not match CF_HOST_PATTERN ${vars.CF_HOST_PATTERN}`);
+    throw new ConfigError(`DEV_HOST "${host}" does not match CF_HOST_PATTERN ${vars.CF_HOST_PATTERN}`);
   }
-  // Tunnel name = first DNS label, same rule as @bss-sbc/shopify-dev, so both tools reuse one tunnel.
+  // Tunnel name = first DNS label, so the same hostname always maps to the same tunnel on any machine.
   const tunnelName = host.split('.')[0];
   if (!host.includes('.') || !/^[a-zA-Z0-9-]{3,63}$/.test(tunnelName)) {
-    throw new ConfigError(`VITE_HOST "${host}" must be a full hostname whose first label is 3-63 chars of [a-zA-Z0-9-]`);
+    throw new ConfigError(`DEV_HOST "${host}" must be a full hostname whose first label is 3-63 chars of [a-zA-Z0-9-]`);
   }
   // cloudflared rejects tunnel secrets that decode to fewer than 32 bytes.
   if (Buffer.from(vars.CF_SECRET_KEY, 'base64').length < 32) {

package/src/scaffold-project.js

@@ -0,0 +1,44 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseEnv } from 'node:util';
+
+const ACCOUNT_TEMPLATE = { CF_ACCOUNT_TAG: '', CF_SECRET_KEY: '', CF_HOST_PATTERN: '' };
+
+// Idempotent: only creates what is missing, never overwrites. Returns the list of changes made.
+export function scaffoldProject(cwd = process.cwd()) {
+  const changes = [];
+  const dir = path.join(cwd, '.cloudflared');
+  const accountPath = path.join(dir, 'account.json');
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { mode: 0o700 });
+    changes.push('created .cloudflared/');
+  }
+  if (!existsSync(accountPath)) {
+    writeFileSync(accountPath, `${JSON.stringify(ACCOUNT_TEMPLATE, null, 2)}\n`, { mode: 0o600 });
+    changes.push('created .cloudflared/account.json (fill in from your password manager)');
+  }
+
+  // Keep the shared secrets out of git before anyone pastes them in.
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const gitignore = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+  if (!/^\/?\.cloudflared\/?(\*)?\s*$/m.test(gitignore)) {
+    appendLine(gitignorePath, gitignore, '.cloudflared/');
+    changes.push('added .cloudflared/ to .gitignore');
+  }
+
+  const envPath = [path.join(cwd, 'web/.env'), path.join(cwd, '.env')].find((p) => existsSync(p)) ?? path.join(cwd, '.env');
+  const envText = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+  const env = parseEnv(envText);
+  const missingKeys = ['DEV_HOST', 'DEV_PORT'].filter((key) => !(key in env));
+  if (missingKeys.length) {
+    appendLine(envPath, envText, missingKeys.map((key) => `${key}=`).join('\n'));
+    changes.push(`added ${missingKeys.join(', ')} to ${path.relative(cwd, envPath)}`);
+  }
+
+  return changes;
+}
+
+function appendLine(file, current, line) {
+  appendFileSync(file, `${current && !current.endsWith('\n') ? '\n' : ''}${line}\n`);
+}

package/src/start-tunnel.js

@@ -37,8 +37,8 @@ export async function startNamedTunnel(bin, cfg, { force = false } = {}) {
     // Two connectors on one tunnel = Cloudflare load-balances requests between two laptops.
     throw new Error(
       `Tunnel "${cfg.tunnelName}" already has ${tunnel.connections.length} live connection(s): ` +
-        `someone else is probably running with VITE_HOST=${cfg.host}. ` +
-        'Pick another VITE_HOST, or pass --force if it is your own process that just died.',
+        `someone else is probably running with DEV_HOST=${cfg.host}. ` +
+        'Pick another DEV_HOST, or pass --force if it is your own process that just died.',
     );
   }
 
@@ -84,7 +84,7 @@ async function routeDns(cf, tunnelId, host, force) {
     const detail = (err.stderr || err.message).trim();
     throw new Error(
       `Cannot point ${host} at tunnel ${tunnelId}: ${detail}\n` +
-        'If the record belongs to another tunnel, pick another VITE_HOST or pass --force to take it over.',
+        'If the record belongs to another tunnel, pick another DEV_HOST or pass --force to take it over.',
     );
   }
 }