@webmate-studio/cli 0.3.62 → 0.4.0

package/README.md

@@ -0,0 +1,222 @@
+# @webmate-studio/cli
+
+Command-line tool for Webmate Studio component development and synchronisation.
+
+```bash
+npm install -g @webmate-studio/cli
+```
+
+## Command overview
+
+| Command | Purpose |
+|---|---|
+| `wm init [dir]` | Bootstrap a new component project |
+| `wm generate [type] [name]` | Scaffold a new component or island |
+| `wm dev` | Run the local preview server |
+| `wm install` | Install npm deps in the project and per-component `package.json`s |
+| `wm login` / `wm logout` / `wm whoami` | CLI authentication |
+| `wm components ls` | Browse components in your org (or another, with `--org`) |
+| `wm versions [component]` | List published versions of a component |
+| `wm status [dir]` | Show local vs remote sync state of a component |
+| `wm pull [dir]` | Download a component version from the CMS |
+| `wm push [dir]` | Upload local changes as a new version |
+| `wm clone --from <uuid>[@<ver>]` | Duplicate a component into another (or the same) org |
+
+## Authentication
+
+Most sync commands require a Webmate session. The CLI looks for credentials in this order:
+
+1. `WEBMATE_TOKEN` environment variable (with optional `WEBMATE_BASE_URL`)
+2. `~/.webmate/auth.json` (created by `wm login`)
+3. `.webmate/config.json` in the current workspace (with `apiToken`)
+
+`wm login` itself resolves the target `baseUrl` in this order:
+
+1. `--base-url` flag
+2. `WEBMATE_BASE_URL` environment variable
+3. `baseUrl` field in the nearest `.webmate/config.json` (workspace default)
+4. The built-in default
+
+A workspace-level `.webmate/config.json` with just `{ "baseUrl": "https://app.webmate-studio.com" }` is enough to pin all subsequent `wm login` calls in that directory to the right environment.
+
+### Interactive login (recommended)
+
+```bash
+wm login
+```
+
+Opens your browser at the active Webmate instance, shows a verification code, and waits while you click **Authorize**. The resulting token is saved to `~/.webmate/auth.json` with `0600` permissions.
+
+```bash
+wm login --base-url https://app.webmate-studio.io   # switch environment
+wm login --force                                     # overwrite an existing session
+```
+
+### Non-interactive (CI/CD)
+
+```bash
+export WEBMATE_TOKEN="wms_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx"
+export WEBMATE_BASE_URL="https://app.webmate-studio.io"
+wm push ./my-hero
+```
+
+Create tokens under **Settings → API Tokens** in the CMS.
+
+## The sync workflow
+
+A typical component lifecycle:
+
+```bash
+# Start from an existing component
+wm components ls                          # find the UUID you want
+wm pull ./my-hero --id <uuid>             # download it
+# … edit files …
+wm status                                 # see what changed
+wm push                                   # publish a new version
+```
+
+Or from scratch:
+
+```bash
+wm init my-components
+cd my-components
+wm generate my-hero                       # scaffolds component.json with a fresh UUID
+wm dev                                    # iterate locally
+wm push --force                           # first push needs --force (no baseVersion yet)
+```
+
+### `.webmate.json` — local manifest
+
+After `wm pull`, `wm push`, or `wm clone` the CLI writes a `.webmate.json` next to your component:
+
+```json
+{
+  "componentId": "f97e376c-f8bd-42e4-9b9a-c2d62d4dcc9a",
+  "baseVersion": "cmn7b9r7p00014i013dk007hw",
+  "version": "1.0.5",
+  "pulledAt": "2026-05-20T18:31:46.791Z",
+  "fileHashes": {
+    "component.html": "c2689e…",
+    "component.json": "088e8d…"
+  }
+}
+```
+
+The CLI uses `baseVersion` for optimistic locking on push and `fileHashes` for change detection. The Workbench desktop app shares the same file format.
+
+### Conflict handling
+
+`wm push` checks the remote head before uploading. If the remote moved since your last pull, the push is refused:
+
+```
+[ERROR] Remote moved: your baseVersion is cmABC… but remote latest is cmDEF… (1.0.6).
+  Run wm pull first, then push again.
+```
+
+Resolve by pulling, merging locally, and pushing again.
+
+`wm pull` warns about uncommitted local changes and prompts before overwriting, unless `--force` is given.
+
+### Git snapshot
+
+If the component directory is a git repo, `wm pull` and `wm push` automatically `git add . && git commit` a snapshot of the synced state. This is purely a local backup — nothing is pushed to a remote. Disable with `--no-git`.
+
+## Commands
+
+### `wm login`
+
+```
+wm login [--token <wms_...>] [--base-url <url>] [-f|--force]
+```
+
+Default flow opens the browser and waits for a verification click — no copy/paste needed. With `--token` it accepts a pre-generated token directly (useful when scripting or behind firewalls).
+
+### `wm whoami`
+
+```
+wm whoami [--local]
+```
+
+Shows the active token source, base URL, user, and organisation. `--local` skips the `/api/auth/me` round-trip.
+
+### `wm components ls`
+
+```
+wm components ls [--org <slug>] [--org-id <id>]
+                 [--category <cat>] [--search <q>]
+```
+
+Lists components in your active org. With `--org` or `--org-id` you can browse another org you are a member of (gated server-side by `UserOrganizationRole`).
+
+### `wm versions [component]`
+
+```
+wm versions [<uuid> | <dir>] [--limit <n>]
+```
+
+Lists all published versions, newest first. The positional argument can be a UUID, a directory containing `component.json` or `.webmate.json`, or omitted to use the current directory.
+
+### `wm status [component]`
+
+```
+wm status [<dir>] [--offline]
+```
+
+Reports one of:
+- `in sync` — local file hashes match the manifest and the manifest points at the remote head
+- `local changes` — you have uncommitted edits
+- `behind remote` — remote has moved past your `baseVersion`
+- `diverged` — both local edits **and** a moved remote
+- `unlinked` — no `.webmate.json` yet
+
+`--offline` skips the network call and only reports the local diff.
+
+### `wm pull [component]`
+
+```
+wm pull [<dir>] [--id <uuid>] [--version <ver|cuid|latest>]
+                 [--merge] [--force] [--no-git]
+```
+
+Downloads the source bundle of the requested version and rewrites `.webmate.json`. Defaults to `latest`. With `--merge`, local files not present in the remote bundle are kept; without it the directory is brought into a 1:1 match.
+
+### `wm push [component]`
+
+```
+wm push [<dir>] [-m|--message <msg>] [--force] [--no-git]
+```
+
+Uploads the current file tree as a new patch version. The server bumps SemVer automatically (e.g. `1.0.5 → 1.0.6`). The CLI:
+
+- runs a pre-flight `GET /versions` to detect a moved remote and refuses to upload on mismatch
+- skips uploads when nothing changed since the last pull/push (override with `--force`)
+- treats HTTP 409 as a late-conflict signal and HTTP 422 as a build failure
+
+### `wm clone --from`
+
+```
+wm clone --from <component-uuid>[@<version|cuid|latest>]
+         [--target-org <slug>] [--target-org-id <id>]
+         [--name <displayName>] [--category <category>]
+         [--to <dir>] [--merge] [--force] [--no-git]
+```
+
+Duplicates an existing component into another (or the same) org. You must be a member of both the source and the target org. The server mints a fresh UUID, copies the source `source.json` into a patched file map (new id, optional new name), and creates the new component row without a published version yet. The CLI writes the files locally; the first real publish happens when you run `wm push --force`.
+
+## Where things live
+
+- Token store: `~/.webmate/auth.json` (chmod `0600`)
+- Workspace org config: `<your-apps-root>/.webmate/config.json`
+- Per-component manifest: `<component>/.webmate.json`
+
+## Troubleshooting
+
+**`Not logged in.`** → Run `wm login`, or check `WEBMATE_TOKEN` is set.
+
+**`Remote moved: your baseVersion is …`** → Someone else (or the Workbench, or another machine) pushed a new version. Run `wm pull` to re-sync, resolve any conflicts, then `wm push` again.
+
+**`Build failed (HTTP 422)`** → The build service rejected the artifact. Check the server logs in the CMS for details; common causes are island files that fail to bundle or invalid `component.json`.
+
+**`Token rejected (HTTP 401)`** → The token has been revoked or expired. Run `wm login --force` to refresh it.
+
+**`No .webmate.json found`** (`wm push`) → The directory has not been linked to a component yet. Either run `wm pull --id <uuid>` first, or push with `--force` to skip the safety check (useful right after `wm generate` or `wm clone`).

package/bin/wm.mjs

@@ -4,6 +4,30 @@ import { Command } from 'commander';
 import { devCommand } from '../src/commands/dev.js';
 import { initCommand } from '../src/commands/init.js';
 import { generate } from '../src/commands/generate.js';
+import { installCommand } from '../src/commands/install.js';
+import { loginCommand } from '../src/commands/login.js';
+import { logoutCommand } from '../src/commands/logout.js';
+import { whoamiCommand } from '../src/commands/whoami.js';
+import { pullCommand } from '../src/commands/pull.js';
+import { pushCommand } from '../src/commands/push.js';
+import { buildCommand } from '../src/commands/build.js';
+import { statusCommand } from '../src/commands/status.js';
+import { resetCommand } from '../src/commands/reset.js';
+import { doctorCommand } from '../src/commands/doctor.js';
+import { cloneCommand } from '../src/commands/clone.js';
+import { componentsListCommand } from '../src/commands/components.js';
+import { projectsListCommand } from '../src/commands/projects.js';
+import { versionsCommand } from '../src/commands/versions.js';
+import {
+	coreListCommand,
+	coreCloneCommand,
+	coreInitCommand,
+	coreInitAllCommand,
+	coreAttachCommand,
+	corePushCommand,
+	coreStatusCommand
+} from '../src/commands/core.js';
+import { isLocallyKnownSuperAdmin } from '../src/utils/auth-storage.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -45,4 +69,188 @@ program
 	.option('-o, --open', 'Open browser automatically')
 	.action(devCommand);
 
+// wm install - Install component + project dependencies
+program
+	.command('install')
+	.description('Install npm dependencies for the project and every component that ships its own package.json')
+	.option('-f, --force', 'Re-install even if node_modules already exists')
+	.option('--prune', 'Remove leftover package-lock.json + node_modules under stub package.json files (keeps the package.json itself)')
+	.action(installCommand);
+
+// wm login - Authenticate against Webmate Studio
+program
+	.command('login')
+	.description('Authenticate against Webmate Studio and store credentials in ~/.webmate/auth.json')
+	.option('--token <token>', 'API token (wms_...). If omitted, prompts interactively.')
+	.option('--base-url <url>', 'Webmate base URL (overrides WEBMATE_BASE_URL env and workspace .webmate/config.json)')
+	.option('-f, --force', 'Overwrite existing credentials without confirmation')
+	.action(loginCommand);
+
+// wm logout - Remove stored credentials
+program
+	.command('logout')
+	.description('Remove stored Webmate credentials')
+	.action(logoutCommand);
+
+// wm whoami - Show active identity
+program
+	.command('whoami')
+	.description('Show the active Webmate identity')
+	.option('--local', 'Skip server round-trip; show stored values only')
+	.action(whoamiCommand);
+
+// wm pull - Download a component version from the CMS
+program
+	.command('pull [component]')
+	.description('Download component source from the CMS into the local directory')
+	.option('--id <uuid>', 'Component UUID (overrides .webmate.json and component.json)')
+	.option('--version <ver>', 'Version to pull (SemVer like 1.0.5, CUID, or "latest")', 'latest')
+	.option('--merge', 'Keep local files that are not present in the remote version')
+	.option('--force', 'Overwrite local changes without prompting')
+	.option('--no-git', 'Do not auto-commit the pulled state (when in a git repo)')
+	.action(pullCommand);
+
+// wm push - Upload local component source as a new version
+program
+	.command('push [component]')
+	.description('Upload local component files to the CMS as a new version')
+	.option('-m, --message <msg>', 'Commit message for the new version')
+	.option('--force', 'Bypass conflict and unlinked-component checks')
+	.option('--no-git', 'Do not auto-commit the pushed state (when in a git repo)')
+	.action(pushCommand);
+
+// wm build - Local dry-run of the cloud build pipeline (no push, no upload)
+program
+	.command('build [component]')
+	.description('Run the cloud build pipeline locally to validate a component before push')
+	.option('--out <dir>', 'Write built artefacts (component.html/css, islands/*) to <dir>')
+	.option('--verbose', 'Show all islands in the summary, not just the first five')
+	.action(buildCommand);
+
+// wm status - Show local vs remote sync state
+program
+	.command('status [component]')
+	.description('Show local vs remote sync state for a component')
+	.option('--offline', 'Skip the remote round-trip')
+	.action(statusCommand);
+
+// wm reset - Drop .webmate.json sync pointers so the next push registers fresh
+program
+	.command('reset [dir]')
+	.description('Reset sync pointers in .webmate.json — use after copying components into a new workspace')
+	.action(resetCommand);
+
+// wm doctor - Run a local health check on the workspace setup
+program
+	.command('doctor [dir]')
+	.description('Scan the workspace for common setup issues (auth, bindings, stale metas)')
+	.action(doctorCommand);
+
+// wm components - Browse remote components
+const componentsCmd = program
+	.command('components')
+	.description('Browse components in the current or another organization');
+
+componentsCmd
+	.command('ls')
+	.description('List components in an organization')
+	.option('--org <slug>', 'Organization slug (defaults to your current org)')
+	.option('--org-id <id>', 'Explicit organization ID (overrides --org)')
+	.option('--category <category>', 'Filter by category')
+	.option('--search <query>', 'Free-text search across name/displayName/description')
+	.action(componentsListCommand);
+
+// wm projects - Browse remote projects (= ComponentRepositories)
+const projectsCmd = program
+	.command('projects')
+	.alias('repos')
+	.description('Browse projects (= component repositories) in the current or another organization');
+
+projectsCmd
+	.command('ls')
+	.description('List projects in an organization')
+	.option('--org <slug>', 'Organization slug (defaults to your current org)')
+	.option('--org-id <id>', 'Explicit organization ID (overrides --org)')
+	.action(projectsListCommand);
+
+// wm versions - List versions of a component
+program
+	.command('versions [component]')
+	.description('List versions of a component (UUID, directory, or current dir)')
+	.option('--limit <n>', 'Maximum number of versions to show')
+	.action(versionsCommand);
+
+// wm clone - Two modes:
+//   * `wm clone <project>` — bootstrap a workspace from a project (= ComponentRepository)
+//   * `wm clone --from <uuid>[@version]` — server-side single-component clone (legacy)
+program
+	.command('clone [project...]')
+	.description('Clone a project workspace (positional, spaces allowed), or a single component with --from')
+	.option('--from <spec>', '[Component mode] Source as <component-uuid>[@<version|cuid|latest>]')
+	.option('--to <dir>', 'Target directory (project mode: defaults to slug; component mode: current dir)')
+	.option('--target-org <slug>', '[Component mode] Slug of the target organization')
+	.option('--target-org-id <id>', '[Component mode] Explicit target organization ID')
+	.option('--name <displayName>', '[Component mode] New display name for the cloned component')
+	.option('--category <category>', '[Component mode] Override category on the clone')
+	.option('--merge', '[Component mode] Keep local files that are not in the cloned source')
+	.option('--force', 'Overwrite/continue without prompting')
+	.option('--no-git', 'Do not auto-commit the cloned files (when in a git repo)')
+	.action(cloneCommand);
+
+// wm core - SuperAdmin-only authoring of global Core components.
+// The command stays registered for everyone so that anyone whose cached
+// token is stale can still invoke it (server enforces the real check)
+// — but for normal users it's hidden from `wm --help` so the help
+// output stays focused on the everyday org-component workflow.
+const coreCmd = program
+	.command('core', { hidden: !isLocallyKnownSuperAdmin() })
+	.description('SuperAdmin authoring of global Core components (platform owners only)');
+
+coreCmd
+	.command('ls')
+	.description('List all Core components registered on the platform')
+	.action(coreListCommand);
+
+coreCmd
+	.command('clone [name]')
+	.description('No name: clone every Core component into a fresh workspace. With name: pull just that one.')
+	.option('--to <dir>', 'Target directory (workspace mode default: ./webmate-core; single mode default: current)')
+	.option('--merge', 'Keep local files that are not in the cloned source (single mode)')
+	.option('--force', 'Overwrite local content without prompting')
+	.action(coreCloneCommand);
+
+coreCmd
+	.command('init [dir]')
+	.description('Register the local component (from component.json) as a new Core component on the server')
+	.option('--display-name <name>', 'Override the displayName')
+	.option('--category <category>', 'Override the category')
+	.option('--description <description>', 'Override the description')
+	.action(coreInitCommand);
+
+coreCmd
+	.command('attach <name>')
+	.description('Bind an existing (UI-created) Core record to the current folder without pushing')
+	.option('--dir <dir>', 'Target directory (default: current)')
+	.option('--force', 'Overwrite an existing .webmate.json in this folder')
+	.action(coreAttachCommand);
+
+coreCmd
+	.command('init-all [dir]')
+	.description('Bulk: init + push every component subfolder under <dir>/components/ (or <dir> directly)')
+	.option('-y, --yes', 'Skip the confirmation prompt')
+	.action(coreInitAllCommand);
+
+coreCmd
+	.command('push [dir]')
+	.description('Build and push a new version. From a workspace root: bulk-push every changed component.')
+	.option('-m, --message <msg>', 'Commit message for the new version')
+	.option('--force', 'Push even when local hashes match the last recorded state')
+	.option('--no-git', 'Do not auto-commit the pushed state (when in a git repo)')
+	.action(corePushCommand);
+
+coreCmd
+	.command('status [name]')
+	.description('Workspace overview (in-sync / changes-local / behind-remote per component) or single-component info')
+	.action(coreStatusCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webmate-studio/cli",
-  "version": "0.3.62",
+  "version": "0.4.0",
   "type": "module",
   "description": "Webmate Studio CLI - Build and manage your Webmate components",
   "keywords": [
@@ -27,6 +27,10 @@
     ".": "./src/index.js",
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "prepublishOnly": "git diff --quiet HEAD && git fetch && git merge-base --is-ancestor HEAD origin/main",
+    "postversion": "git push --follow-tags"
+  },
   "publishConfig": {
     "access": "public"
   },