@webflow/webflow-cli 2.3.0-next.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @webflow/webflow-cli
 
+## 2.3.0
+
+### Minor Changes
+
+- 18a2d43: Site ID resolution in `webflow cloud` and `webflow auth` now follows flag > `WEBFLOW_SITE_ID` env var > `webflow.json` order. Previously, `webflow.json` `siteId` took priority over the `WEBFLOW_SITE_ID` environment variable. This makes behavior consistent with the resolver used by all new CLI commands and allows CI/CD env vars to override the checked-in manifest as expected.
+
+  Note: `WEBFLOW_SITE_ID` now also takes precedence over `cloud.workspace_id` in `webflow.json`. A project configured for standalone/workspace deploys that has `WEBFLOW_SITE_ID` set in the environment will route to site-attached instead.
+
+  `webflow cloud deploy` now also respects `WEBFLOW_APP_ID` as an environment variable override for the app ID, and `WEBFLOW_WORKSPACE_ID` when resolving the workspace for a standalone-first deploy.
+
+- 2875d7d: Two behavior changes for CI and agent callers, plus new internal path/archive safety utilities.
+
+  - **`--json` failures now go to stdout as a JSON document.** Previously a failure printed prose to stderr; it is now a single `{ "error": { "message", "context", "missingFlag" } }` document on stdout, written synchronously so a long message is not truncated when stdout is a pipe. `context` carries the operation the command was performing. The failure is also recorded, with its stack, in the session debug log. **Scripts that grep stderr for the failure message need updating.**
+  - **Non-interactive mode is auto-detected in more environments.** In addition to `CI=true` and a missing stdout TTY, `--no-input` is now enabled when stdin has no TTY or when a coding agent's execution environment is detected, so prompts no longer hang agent and CI invocations. A new `--input` flag forces interactive mode, for the case where the detection misreads a human environment.
+
+- 2d85a3e: Add the `webflow skills` namespace — install, update, list, and remove Webflow's first-party agent skills into your coding agents' skill directories.
+
+  - `webflow skills install [names...]` — fetches the skill catalog, writes each skill once into a shared canonical store, and links it into every selected agent's directory. Symlinks by default with an automatic per-target fallback to copying (`--copy` forces copies). Records what it wrote in a lockfile — `webflow-skills-lock.json` for a project, `skills-lock.json` under the CLI config directory for a `--global` install — so `install` with no names restores an existing set reproducibly. `--ref <branch|sha>` pins to a branch or commit.
+  - `webflow skills update [names...]` — re-resolves the pinned ref and updates installed skills, reporting each one as unchanged, updated, moved, reinstalled, or blocked. `--check` reports what would change and writes nothing.
+  - `webflow skills list` — shows what is installed in both scopes with a per-skill status (`up-to-date`, `modified`, `missing`, `unmanaged`) computed by re-hashing what is on disk against the lockfile. Never touches the network. Supports `--fields`, `--sort-by`, and `--order`.
+  - `webflow skills remove [names...]` — unlinks a skill from every agent and deletes its store directory once nothing references it any more.
+
+  Every command supports `--json`, every write command supports `--dry-run`, and `-a, --agent` selects specific coding agents (repeatable, comma-separated, or `all`). `-g, --global` and `-p, --project` select the scope. A skill directory is only ever replaced without `--force` when the CLI itself wrote it and it has not been edited since — and `remove` applies the same rule to deletion, so a skill directory another tool installed (or one you wrote yourself) is left alone unless you pass `--force`.
+
+  Because `--global` installs write into agent directories under your home directory, a skill directory is never replaced or deleted unless the CLI itself wrote it and it has not been edited since — anything else needs `--force`. Archives are extracted through hardened path-containment checks, and `--dry-run` prints every path before any write happens.
+
+  Also fixes a pre-existing issue affecting every command: the "New versions of the following @webflow packages are available" notice was written to stdout even under `--json`, so on any machine with a pending CLI update it appeared ahead of the JSON document and broke `JSON.parse` on the output. The update check is now skipped when `--json` is in effect.
+
+### Patch Changes
+
+- 12bcf3b: Deprecate `webflow cloud list` ahead of removal. The command still works but prints a warning — it lists scaffold templates for `init`, not the user's Cloud apps. Help text is tagged `[Deprecated]`; use `cloud`/`apps` `init --framework` / `--help` for templates (and `webflow apps list` for apps on `@next`).
+- 2dbf0ae: Update `tar` to a patched version that prevents decompression denial-of-service attacks.
+- 84dc26e: Fix the message shown when `webflow devlink sync` fails with a 404. It previously told users to apply for DevLink beta access; it now points to `webflow devlink export` and the migration guide.
+- 0f8a85f: Explain how to recover when a deploy cannot create an app. Hitting an app name that is already taken on the site, or a site that has reached its Cloud app limit, previously reported only "An unknown error occurred". Both now say what happened and how to proceed. The usual cause is `app_id` missing from `webflow.json`, for example on a fresh CI checkout.
+- f7efc3d: Pin the transitive `adm-zip` dependency (pulled in via `@module-federation/enhanced` → `dts-plugin`) to `^0.6.0` via an npm override, fixing a high-severity denial-of-service vulnerability (CVE-2026-39244) where a crafted ZIP file could trigger an unbounded ~4GB memory allocation.
+- b4e08db: Internal refactor: added a `resolveOptionalResourceId` helper to collapse repeated try/catch blocks around `resolveResourceId` in the cloud deploy/preflight code paths. No user-facing behavior change.
+- 903c4a4: Bump transitive `undici` dependency (pulled in via `@module-federation/enhanced`) to 7.28.0 to fix a WebSocket client denial-of-service vulnerability (CVE-2026-12151).
+  - @webflow/data-types@2.1.0
+
 ## 2.2.0
 
 ### Minor Changes

package/README.md

@@ -19,6 +19,7 @@ npm install -g @webflow/webflow-cli
 - [DevLink Export](#devlink-export)
 - [Designer Extensions](#designer-extensions)
 - [Apps (Webflow Cloud)](#apps-webflow-cloud)
+- [Skills (agent skills)](#skills-agent-skills)
 - [Global Options](#global-options)
 
 ---
@@ -286,6 +287,124 @@ created/updated/skipped/errors breakdown and exits non-zero if any key fails
 
 ---
 
+## Skills (agent skills)
+
+Install Webflow's first-party agent skills into your coding agents, so an agent
+working in your repo knows how to use Webflow without being told each time.
+
+> **These commands write outside the current project.** A `--global` install
+> writes into your coding agents' skill directories under your home directory. Two
+> rules bound that: nothing is replaced or deleted unless the CLI wrote it and it
+> has not been edited since (anything else needs `--force`), and `--dry-run` prints
+> every path before a single byte is written. Run it first if you are unsure.
+
+```shell
+webflow skills install                          # Restore from a lockfile, or pick interactively
+webflow skills install webflow-cms --dry-run    # Preview every path that would be written
+webflow skills install webflow-cms --agent claude-code,cursor
+webflow skills install --all-skills --all-agents --global
+webflow skills list                             # What is installed, and where
+webflow skills update --check                   # Report what would change; write nothing
+webflow skills update
+webflow skills remove webflow-cms --dry-run     # Preview exactly what is deleted
+```
+
+### Scope: project or global
+
+| Scope               | Where skills go                             | Lockfile                                 |
+| ------------------- | ------------------------------------------- | ---------------------------------------- |
+| Project (default)   | Agent directories under the current project | `webflow-skills-lock.json` (commit this) |
+| Global (`--global`) | Agent directories under your home directory | `skills-lock.json` in the CLI config dir |
+
+The project lockfile is meant to be committed: a teammate (or CI) runs
+`webflow skills install` with no arguments and gets the same skills at the same
+commit. `list` shows **both** scopes by default so a global install is never
+invisible.
+
+Each skill's files are written once into a shared canonical store and linked into
+every selected agent's directory, so installing for twenty agents costs one copy.
+Symlinks are used by default, with an automatic per-target fallback to copying
+when the filesystem or platform refuses them; `--copy` forces copies everywhere.
+
+### Safety
+
+`install` and `update` refuse to overwrite a skill directory unless the CLI
+wrote it and it has not been edited since — anything locally modified, or
+anything that exists without a matching lockfile entry, is reported as blocked
+and needs `--force`. `--dry-run` prints the exact absolute paths that would be
+written or deleted and makes no changes, which is the flag to reach for first
+when an agent chose the arguments.
+
+### `skills install` options
+
+| Flag                  | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| `-a, --agent <ids>`   | Target agent; repeatable, comma-separated, or `all`                    |
+| `--all-agents`        | Install for every supported agent                                      |
+| `--all-skills`        | Install every skill in the catalog                                     |
+| `-g, --global`        | Install into your home directory instead of the current project        |
+| `-p, --project`       | Install into the current project (the default)                         |
+| `--copy`              | Copy files instead of symlinking from the shared store                 |
+| `--ref <branch\|sha>` | Pin to a branch or 40-character commit SHA (default: `main`)           |
+| `--force`             | Replace destinations that were modified locally or installed elsewhere |
+| `-y, --yes`           | Skip the confirmation prompt                                           |
+| `--dry-run`           | Print every path that would be written; change nothing                 |
+| `--json`              | Output as JSON                                                         |
+
+### `skills update` options
+
+| Flag                  | Description                                       |
+| --------------------- | ------------------------------------------------- |
+| `--check`             | Report what would change without writing anything |
+| `-g, --global`        | Update the home-directory install                 |
+| `-p, --project`       | Update the current project's install              |
+| `--ref <branch\|sha>` | Re-pin to a different branch or commit SHA        |
+| `--force`             | Overwrite skills that were modified locally       |
+| `-y, --yes`           | Skip the confirmation prompt                      |
+| `--dry-run`           | Preview without writing                           |
+| `--json`              | Output as JSON                                    |
+
+### `skills list` options
+
+| Flag                | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `-g, --global`      | Only the home-directory install                                               |
+| `-p, --project`     | Only the current project's install                                            |
+| `-a, --agent <ids>` | Only skills linked into these agents; repeatable and comma-separated          |
+| `--fields <fields>` | Comma-separated columns (name, dir, description, status, mode, agents, scope) |
+| `--sort-by <field>` | Sort by name, dir, status, or scope (default: name)                           |
+| `--order <dir>`     | `asc` or `desc` (default: `asc`)                                              |
+| `--json`            | Output as JSON                                                                |
+
+`status` is computed offline by re-hashing what is on disk against what the
+lockfile recorded: `up-to-date`, `modified` (edited since install), `missing`
+(recorded but gone), or `unmanaged` (present with no lockfile entry). Checking
+for _upstream_ changes needs the network and is `skills update --check`'s job.
+
+### `skills remove` options
+
+| Flag                | Description                                                   |
+| ------------------- | ------------------------------------------------------------- |
+| `-a, --agent <ids>` | Only unlink from these agents; repeatable and comma-separated |
+| `--all`             | Remove every installed skill for the scope                    |
+| `-g, --global`      | Remove from the home-directory install                        |
+| `-p, --project`     | Remove from the current project's install                     |
+| `--force`           | Also remove skill directories that have no lockfile entry     |
+| `-y, --yes`         | Skip the confirmation prompt                                  |
+| `--dry-run`         | Print exactly what would be deleted; change nothing           |
+| `--json`            | Output as JSON                                                |
+
+Removing a skill from one agent unlinks it there and keeps the shared store as
+long as another agent still references it; the store directory is deleted once
+nothing does.
+
+`remove` only deletes what the lockfile records. A skill directory with no
+lockfile entry was not installed by this CLI — it may belong to another tool, or
+be hand-written — so `--all` leaves it alone and names it in a warning, and
+naming it directly is refused. `--force` opts in to removing those too.
+
+---
+
 ## Global Options
 
 Available on all commands: