@micropage-sh/cli 2.0.0

package/README.md

@@ -0,0 +1,183 @@
+# micropage CLI
+
+Command-line interface for [micropage.sh](https://app.micropage.sh) — create, edit, publish, and manage microsites from your terminal.
+
+## Requirements
+
+- Node.js ≥ 18
+- A micropage.sh account
+
+## Installation
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap micropage-sh/tap
+brew install micropage
+```
+
+### npm
+
+```bash
+npm install -g micropage
+```
+
+## Authentication
+
+Authenticate with your browser (GitHub or magic link):
+
+```bash
+micropage login        # opens browser for authentication
+micropage whoami       # show the currently logged-in user and subscription
+micropage logout       # clear the stored session
+```
+
+## Project workflow
+
+```bash
+# Create a new project and initialise a local folder
+micropage projects create my-site
+
+cd my-site
+
+# Edit landing.page (or any *.page file) with your content
+nano landing.page
+
+# Push local content as a draft build
+micropage push
+
+# Publish the current draft (deploys to Cloudflare Pages)
+micropage publish
+
+# Pull the latest remote build content to landing.page
+micropage projects pull
+
+# Open the live site in the browser
+micropage preview
+
+# Copy the live URL to clipboard
+micropage copy-link
+```
+
+### Project domains
+
+When you create a project without `-d`, the API assigns `projects.domain` as the initial host for your site (for example `my-site.micropage.sh`). You can optionally attach a custom domain (such as `www.example.com`) in the web editor; when present, the CLI shows that custom domain as the site URL (otherwise the default host).
+
+## Commands reference
+
+### Auth
+
+| Command | Description |
+|---|---|
+| `micropage login [--force]` | Authenticate via browser |
+| `micropage logout` | Clear stored session |
+| `micropage whoami` | Show logged-in user and subscription/plan |
+
+### Projects
+
+| Command | Description |
+|---|---|
+| `micropage projects list [--json]` | List your projects |
+| `micropage projects show [id] [--json]` | Show project + latest build details |
+| `micropage projects create <name> [-d domain]` | Create a project and init local folder. Omit `-d` to let the API assign `{slugified-name}-{6 hex}` (unique Pages/DNS label, max 58 chars). Use `-d` only to override the slug. |
+| `micropage projects fetch <uuid\|domain>` | Fetch an existing project and init local folder (includes storage → `./assets` sync) |
+| `micropage projects pull` | Pull latest build raw content → `landing.page`, then sync `./assets` with project storage (1:1) |
+| `micropage projects delete [-y]` | Delete project (remote + local `.micropage/`) |
+| `micropage projects deploy <uuid> <token> [-w]` | CI: read `.page` files, create build, and publish with a deploy token (Pro+). No login. |
+
+When you create a new project, the CLI also scaffolds:
+
+- an `examples/` directory with multiple starter `.page` files (full sites and component-only patterns),
+- default `logo.svg` and `favicon.svg` under `assets/` (referenced by the examples as `logo: <- logo.svg` / `favicon: <- favicon.svg`),
+- a `PROJECT_AGENT.md` file that explains the layout for local tools and agents, and links to the docs at `https://docs.micropage.sh`.
+
+### Builds
+
+| Command | Description |
+|---|---|
+| `micropage push` | Merge local `.page` files and save as a draft build |
+| `micropage publish` | Push then deploy to Cloudflare Pages |
+| `micropage builds list [--json]` | List builds for the current project |
+| `micropage builds redeploy [version]` | Re-publish an older build as a new deploy |
+| `micropage builds download [version] [-o file]` | Download a deployed build archive as a `.zip` file |
+
+**Notes:**
+
+- Archives are only available for **deployed** builds.
+- If you omit `version`, the CLI downloads the latest deployed build.
+- The first time you request an archive for a build, the server may need a short time to prepare it; the CLI will wait and then download once ready.
+- By default the archive is saved as `build-v<version>.zip` in the current directory; use `-o` to change the output path.
+
+### Links
+
+| Command | Description |
+|---|---|
+| `micropage preview` | Open the live site in the browser |
+| `micropage copy-link` | Copy the live URL to clipboard |
+| `micropage open-pricing` | Open the pricing page in the browser |
+
+### Files
+
+| Command | Description |
+|---|---|
+| `micropage files list [--json]` | List uploaded project files |
+| `micropage files url <filename> [--copy]` | Get (and optionally copy) a file URL |
+| `micropage files sync [-q]` | Download every file from project storage into `./assets` (matches remote list; removes extra local files) |
+
+### Form submissions
+
+| Command | Description |
+|---|---|
+| `micropage submissions list [--json]` | List form submissions for the project |
+| `micropage submissions show <id> [--json]` | Show a single submission in detail |
+| `micropage submissions export [--format csv|json] [-o file]` | Export all form submissions for the current project |
+
+**Examples:**
+
+- Export to CSV in the current directory:
+
+  ```bash
+  micropage submissions export
+  ```
+
+- Export to a custom CSV path:
+
+  ```bash
+  micropage submissions export --output exports/contact-form.csv
+  ```
+
+- Export as JSON:
+
+  ```bash
+  micropage submissions export --format json --output submissions.json
+  ```
+
+## Local content model
+
+The CLI uses one or more `*.page` files in the working directory as the source of truth for project content.
+
+**Merge order when pushing:**
+1. `landing.page` (canonical primary file)
+2. Any additional `*.page` files, sorted alphabetically
+3. Files are joined with a single blank line between them
+
+**Pulling** always writes to `landing.page` only.
+
+## Project configuration
+
+Each project folder has a `.micropage/project.json` file that stores:
+- `projectId` — the Supabase project ID
+- `buildId` — the ID of the last draft/deployed build (auto-updated by push/pull)
+- `domain` — the Cloudflare Pages domain
+- `name` — the project name
+
+Add `.micropage/` to your `.gitignore` if you share the content folder.
+
+## Machine-readable output
+
+Most list and detail commands accept a `--json` flag to output raw JSON, which is useful for scripting.
+
+```bash
+micropage projects list --json | jq '.[].name'
+micropage builds list --json | jq '.[] | select(.status == "deployed") | .number'
+```

package/bin/micropage.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../src/index.js');

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@micropage-sh/cli",
+  "version": "2.0.0",
+  "description": "CLI for micropage.sh - create, sync, and publish microsites",
+  "main": "src/index.js",
+  "bin": {
+    "micropage": "bin/micropage.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node -e \"require('./src/index.js')\"",
+    "build:bin": "pkg . --targets node18-linux-x64,node18-macos-x64,node18-macos-arm64 --output dist/micropage",
+    "build:linux": "pkg . --target node18-linux-x64 --output dist/micropage-linux-amd64",
+    "build:macos-amd64": "pkg . --target node18-macos-x64 --output dist/micropage-darwin-amd64",
+    "build:macos-arm64": "pkg . --target node18-macos-arm64 --output dist/micropage-darwin-arm64"
+  },
+  "pkg": {
+    "scripts": [
+      "src/**/*.js",
+      "bin/**/*.js"
+    ],
+    "assets": [
+      "templates/**/*"
+    ],
+    "targets": [
+      "node18-linux-x64",
+      "node18-macos-x64",
+      "node18-macos-arm64"
+    ],
+    "outputPath": "dist"
+  },
+  "keywords": [
+    "micropage",
+    "cli",
+    "microsite",
+    "static-site"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/micropage-sh/cli.git"
+  },
+  "homepage": "https://github.com/micropage-sh/cli#readme",
+  "bugs": {
+    "url": "https://github.com/micropage-sh/cli/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@yao-pkg/pkg": "^5.11.5"
+  }
+}

package/src/api.js

@@ -0,0 +1,51 @@
+const { getToken } = require('./auth');
+
+const BASE_URL = process.env.MICROPAGE_API_URL || 'https://api.microsite.sh';
+
+async function request(method, path, body = null) {
+  const token = getToken();
+  if (!token) {
+    const err = new Error('No token set. Run: micropage token set <token>');
+    err.code = 'NO_TOKEN';
+    throw err;
+  }
+
+  const url = path.startsWith('http') ? path : `${BASE_URL}${path.startsWith('/') ? '' : '/'}${path}`;
+  const options = {
+    method,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+  };
+  if (body !== null && body !== undefined) {
+    options.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, options);
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = null;
+  }
+
+  if (!res.ok) {
+    const err = new Error(data?.error || data?.message || res.statusText || `HTTP ${res.status}`);
+    err.status = res.status;
+    err.data = data;
+    throw err;
+  }
+
+  return data;
+}
+
+const api = {
+  get: (path) => request('GET', path),
+  post: (path, body) => request('POST', path, body),
+  put: (path, body) => request('PUT', path, body),
+  delete: (path) => request('DELETE', path),
+};
+
+module.exports = { api, BASE_URL };

package/src/auth.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || '',
+  '.micropage'
+);
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+const PROJECT_CONFIG_DIR = '.micropage';
+const PROJECT_CONFIG_FILE = path.join(PROJECT_CONFIG_DIR, 'project.json');
+
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Session storage (Supabase access_token + refresh_token)
+// ---------------------------------------------------------------------------
+
+function getSession() {
+  const config = readConfig();
+  if (config.access_token && config.refresh_token) {
+    return {
+      access_token: config.access_token,
+      refresh_token: config.refresh_token,
+      user: config.user || null,
+    };
+  }
+  return null;
+}
+
+function setSession({ access_token, refresh_token, user }) {
+  const config = readConfig();
+  config.access_token = access_token;
+  config.refresh_token = refresh_token;
+  if (user) config.user = user;
+  writeConfig(config);
+}
+
+function clearSession() {
+  const config = readConfig();
+  delete config.access_token;
+  delete config.refresh_token;
+  delete config.user;
+  writeConfig(config);
+}
+
+// ---------------------------------------------------------------------------
+// Legacy token support (deprecated – kept for backward compat messaging)
+// ---------------------------------------------------------------------------
+
+function getToken() {
+  return readConfig().token || null;
+}
+
+function setToken(token) {
+  const config = readConfig();
+  config.token = token;
+  writeConfig(config);
+}
+
+function maskToken(token) {
+  if (!token || token.length < 8) return token ? '****' : '(none)';
+  return token.slice(0, 4) + '****' + token.slice(-4);
+}
+
+// ---------------------------------------------------------------------------
+// Per-project config (.micropage/project.json)
+// ---------------------------------------------------------------------------
+
+function getProjectConfig(cwd = process.cwd()) {
+  const filePath = path.join(cwd, PROJECT_CONFIG_FILE);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function setProjectConfig(cwd, config) {
+  const filePath = path.join(cwd, PROJECT_CONFIG_FILE);
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2), 'utf8');
+}
+
+module.exports = {
+  CONFIG_DIR,
+  CONFIG_FILE,
+  PROJECT_CONFIG_DIR,
+  PROJECT_CONFIG_FILE,
+  // Session (new)
+  getSession,
+  setSession,
+  clearSession,
+  // Legacy token
+  getToken,
+  setToken,
+  maskToken,
+  // Project config
+  getProjectConfig,
+  setProjectConfig,
+};