@cervio/cli 1.0.0 → 1.0.2

package/README.md

@@ -1,7 +1,8 @@
 # @cervio/cli
 
-Developer CLI for Cervio route plugins - login, validate, pack, push, and manage releases,
-built on top of `@cervio/plugin-core`.
+Developer CLI for Cervio plugins: login, validate, pack, push and manage releases, built
+on [`@cervio/plugin-core`](https://www.npmjs.com/package/@cervio/plugin-core), the same
+validation the Cervio host applies to uploads.
 
 The binary is `cervio`. This document is the **command reference** (source of truth for flags
 and behaviour). Partner-facing install and multi-instance auth also live on
@@ -9,12 +10,11 @@ and behaviour). Partner-facing install and multi-instance auth also live on
 
 ## Install
 
-Inside this monorepo it's already a workspace package. To use it as a standalone tool once published:
+Requires Node.js 26 or later.
 
 ```bash
-npm install -g @cervio/cli
-# or as a project dependency
-pnpm add -D @cervio/cli
+npm install --save-dev @cervio/cli   # per project (the templates already include it)
+npm install -g @cervio/cli           # or globally
 ```
 
 ## Typical workflow
@@ -31,8 +31,8 @@ cervio push --changelog "…" --expect-host https://your-instance.cervio.app
 ```
 
 **First stable push before `--dev`.** The first upload must be a release-channel push
-(`cervio push` without `--dev`) so the host creates the `installed_plugins` row. Only then
-can `cervio push --dev` upsert a scratch artifact on that plugin.
+(`cervio push` without `--dev`) so the host creates the plugin. Only then can
+`cervio push --dev` upload a scratch build of it.
 
 ## Configuration
 
@@ -56,8 +56,7 @@ Do not duplicate multi-instance guidance here - use the auth-instances docs (or
 
 ## PAT scopes
 
-The plugin admin API is scope-gated (`lib/auth/api-scope-guard.ts`). A personal access token
-used with this CLI needs:
+The plugin admin API is scope-gated. A personal access token used with this CLI needs:
 
 | Scope | Commands |
 |---|---|
@@ -148,7 +147,7 @@ Flow:
 5. Packs the plugin (or validates `--file`) and `POST`s it to `/api/v1/admin/plugins/upload` as
    `multipart/form-data` - see "Upload request format" below. **`--dev` requires the plugin
    to already exist on the host** (i.e. at least one prior non-dev push) - the dev channel
-   upserts a scratch artifact for an existing `installed_plugins` row and cannot create one.
+   updates a scratch build of an existing plugin and cannot create one.
 6. On success, updates `lastHost` in `~/.cervio/state.json`.
 
 Together with `cervio download`, `--file` lets you round-trip a host artifact
@@ -159,7 +158,7 @@ Together with `cervio download`, `--file` lets you round-trip a host artifact
 |---|---|
 | `--host <url>` | Override resolved host |
 | `--release <semver>` | Download that release label (default: current active release) |
-| `--dev` | Download the scratch `plugin_dev_channel` ZIP instead |
+| `--dev` | Download the dev-channel ZIP instead |
 | `-o, --output <path>` | Destination file (default: `.cervio/out/<plugin_key>-vX.zip` or `…-dev.zip`) |
 | `--json` | Machine-readable output |
 
@@ -193,8 +192,8 @@ scaffolder as `npm create @cervio/plugin`. The optional positional `name` is pas
 | `--dev` | With `--push`, push to the dev channel |
 | `--host <url>` | Override host for the push |
 
-Watches `src/` with `chokidar`; on any change, rebuilds and validates. Without `--push`,
-only build + validate run.
+Watches `src/` (Node's recursive `fs.watch`, changes coalesced); on any change, rebuilds
+and validates. Without `--push`, only build + validate run.
 
 ### `cervio doctor [--host <url>] [--json]`
 
@@ -269,6 +268,11 @@ Response shape depends on `channel`:
 - `dev`: `{ channel: "dev", plugin, dev_channel: { content_sha256, artifact_sha256, artifact_size_bytes, updated_at } }`.
   Fails with `plugin_not_found` if the plugin doesn't exist yet (see `push` flow above).
 
+## Requests
+
+Every request sends `User-Agent: cervio-cli/<version> node/<version>`, so a Cervio host can
+see which CLI versions are still in use.
+
 ## Known gaps
 
 - `GET /api/v1/me` does not return an organization display name (only `organization_id`), so
@@ -284,3 +288,17 @@ pnpm --filter @cervio/cli build     # tsup → dist/cli.js
 pnpm --filter @cervio/cli typecheck
 node packages/cli/dist/cli.js --help
 ```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+**Trademark.** "Cervio" and the Cervio logo are trademarks of Cervio S.r.l. This license
+does not grant permission to use them. You may say that a plugin "works with Cervio"; you
+may not imply endorsement or ship a product named Cervio.
+
+**Platform.** Using a Cervio organization is governed by your partner or customer
+agreement, not by this license.
+
+**Your plugins.** Plugins you write are yours: using this package gives Cervio no rights
+over your plugin, and does not require you to open-source it.

package/dist/cli.js

@@ -297,6 +297,10 @@ async function readProjectConfig(cwd = process.cwd()) {
     throw err;
   }
 }
+async function writeProjectConfig(config, cwd = process.cwd()) {
+  await promises.writeFile(projectConfigPath(cwd), `${JSON.stringify(config, null, 2)}
+`);
+}
 function resolveHost(opts) {
   const host = opts.cliHost || process.env.CERVIO_URL || opts.projectConfig?.host;
   return host ? normalizeHost(host) : void 0;
@@ -525,10 +529,14 @@ async function loginCommand(opts) {
   const client = createApiClient({ host, token });
   const me = await client.getMe();
   await saveToken(host, token);
+  const project = await readProjectConfig().catch(() => null);
+  const projectHostSet = !!project?.host?.trim();
+  if (project && !projectHostSet) await writeProjectConfig({ ...project, host });
   log.success(`Logged in to ${host}`);
   log.info(`  user:  ${me.email ?? me.user_id}`);
   log.info(`  org:   ${me.organization_name ?? me.organization_id}`);
   log.info(`  auth:  ${me.auth_method}`);
+  if (project && !projectHostSet) log.dim(`  cervio.json host set to ${host}`);
 }
 
 // src/commands/open.ts
@@ -731,6 +739,16 @@ async function pushCommand(opts) {
     log.info(`  content_sha256: ${upload.version.content_sha256 ?? "(n/a)"}`);
     if (upload.reason) log.dim(`  ${upload.reason}`);
   }
+  if (upload.plugin.plugin_type === "route") await hintMissingRouteConfig(client, upload.plugin.id);
+}
+async function hintMissingRouteConfig(client, pluginId) {
+  try {
+    const { route_config } = await client.getRouteConfig(pluginId);
+    if (route_config) return;
+  } catch {
+    return;
+  }
+  log.step('Not reachable yet: run "cervio route set" to publish it at /r/<route_slug> (or set it in Admin \u2192 Plugins).');
 }
 async function safeMe(client) {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cervio/cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Developer CLI for Cervio plugins: login, validate, pack, push and manage releases.",
   "keywords": [
     "cervio",
@@ -30,8 +30,8 @@
   "dependencies": {
     "commander": "^15.0.0",
     "prompts": "^2.4.2",
-    "@cervio/create-plugin": "^1.0.0",
-    "@cervio/plugin-core": "^1.0.0"
+    "@cervio/create-plugin": "^1.1.1",
+    "@cervio/plugin-core": "^1.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",