Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
feat(cli): let agents build Dify apps with difyctl and an embedded skill (#43819)
Xiyuan Chen1fefc5272390
diff --git a/.github/workflows/cli-edge.yml b/.github/workflows/cli-edge.ymlindex 8df4bc3bac2..14d94c517e1 100644--- a/.github/workflows/cli-edge.yml+++ b/.github/workflows/cli-edge.yml@@ -57,7 +57,7 @@ jobs:run: CLI_VERSION="${{ steps.ver.outputs.version }}" scripts/release-write-checksums.sh- name: Smoke the runner-arch binary- run: ./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64 version+ run: scripts/release-smoke.sh "./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64"- name: Publish to R2env:diff --git a/.github/workflows/cli-release.yml b/.github/workflows/cli-release.ymlindex d87b21dbe6b..aba7dc3a471 100644--- a/.github/workflows/cli-release.yml+++ b/.github/workflows/cli-release.yml@@ -121,6 +121,9 @@ jobs:- name: Generate sha256 checksum filerun: scripts/release-write-checksums.sh+ - name: Smoke the runner-arch binary+ run: scripts/release-smoke.sh "./dist/bin/$(node scripts/release-naming.mjs asset "$version" linux-x64)"+- name: Attach difyctl assets to Dify releaseif: ${{ !inputs.dry_run }}env:diff --git a/cli/.bun-version b/cli/.bun-versionindex 17e63e7affd..9df886c42a1 100644--- a/cli/.bun-version+++ b/cli/.bun-version@@ -1 +1 @@-1.3.11+1.4.2diff --git a/cli/AGENTS.md b/cli/AGENTS.mdindex c40e4b8309c..cb835c0c94e 100644--- a/cli/AGENTS.md+++ b/cli/AGENTS.md@@ -8,6 +8,7 @@ This package is the ESM TypeScript implementation of `difyctl`. Use the Node.js- Plugins under `src/plugins/` (`argv global-flags env config session token catalog http ops io commands`) own state. A plugin's `build()` closes over its own cache or loaded document; nothing outside a plugin reaches into another plugin's internals. Outside a plugin folder, import only `@/plugins/<name>` and use the service from `ctx.get(...)`; the command framework (`plugins/commands/command.ts`, `cancel.ts`, `registry.ts`) and the argv parser (`plugins/argv/parse.ts`) are the only modules imported directly.- `src/protocol/` and `src/call/` are pure modules: catalog-shape logic (kinds, bind, pins, fold) and the `call` flag table, request-building and rendering, with no op-specific branching anywhere under `src/call/` — kind and bind dispatch go through the tables in `src/protocol/` and `src/call/render/`, keyed by the catalog's own `kind`/`bind` values, never by operation id.- Preserve exit codes and the JSON output contract during refactors. Do not add dependencies or compatibility shims unless the task explicitly requires them.+- Local YAML files go through `localFile` (`src/store/local-file.ts`), one schema each, no versions. Never change a key's name/type/meaning; add a new key (it may fall back to the old one).- `ARD.md` owns CLI code structure. Keep behavior aligned with the real mock-server (`test/fixtures/dify-mock/`) behavior tests.## Commandsdiff --git a/cli/ARD.md b/cli/ARD.mdindex 92ee95ca6df..2cf0896b460 100644--- a/cli/ARD.md+++ b/cli/ARD.md@@ -25,7 +25,7 @@ src/net/ fetch init and proxy dispatcher, shared by the http plugin and the pre-login device flowstore/ config/session/token file and keychain persistencesys/ the process edges — env, argv, exit, platform paths; io/ holds streams.ts, color.ts and view.ts (a JSON value paired with its text form, the mode picks one)- skills/ reads skills from a GitHub folder or a local folder, and installs them+ skills/ the one embedded difyctl skill (or a local folder) and its installer```---@@ -74,7 +74,7 @@ import { ErrorCode } from '@/errors/codes'throw new BaseError({code: ErrorCode.UsageMissingArg,message: 'workspace id required',- hint: "pass --workspace or run 'difyctl use workspace <id>'",+ hint: "pass --workspace-id or run 'difyctl use workspace <id>'",})```diff --git a/cli/README.md b/cli/README.mdindex 5abe04f0c8f..1b389e8721e 100644--- a/cli/README.md+++ b/cli/README.md@@ -2,6 +2,18 @@CLI client for the [Dify] platform. Browser device-flow sign-in, then a server-published catalog of operations you discover and call at run time, each one a command. Results are JSON; help and errors are text on a terminal, JSON in a pipe.+## Install++difyctl ships as assets on Dify releases. The installer picks the build from the latest release; set `DIFY_VERSION` to match your Dify server:++```sh+curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh | sh+```++Windows (PowerShell): `irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex`.++The binary goes to `$HOME/.local/bin` (Windows: `%LOCALAPPDATA%\difyctl\bin`). Every installer accepts `DIFYCTL_INSTALL_DIR` (the bin folder itself) and `DIFYCTL_PREFIX` (the folder above it, so the binary lands in `<prefix>/bin`); `DIFYCTL_INSTALL_DIR` wins when both are set.+## Install (edge, internal)Per-commit `edge` builds are published to Cloudflare R2. The installer script lives in this repo; binaries are fetched from R2 via `DIFYCTL_R2_BASE` (shared internally):@@ -10,15 +22,16 @@ Per-commit `edge` builds are published to Cloudflare R2. The installer script licurl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-r2.sh | DIFYCTL_R2_BASE=<BASE> sh```-| Env | Default | Purpose |-| ----------------------- | ------------------ | ------------------------------------------------------------------- |-| `DIFYCTL_R2_BASE` | — (required) | R2 public base, e.g. `https://pub-….r2.dev`. |-| `DIFYCTL_CHANNEL` | `edge` | Channel to install. |-| `DIFYCTL_INSTALL_DIR` | `$HOME/.local/bin` | Directory the binary is written to (`<dir>/difyctl`). |-| `DIFYCTL_VERSION` | latest | Pin an exact published version. |-| `DIFYCTL_COMMIT` | latest | Pin by git commit (short or full sha). |-| `DIFYCTL_R2_PREFIX` | `difyctl` | R2 key root for the pointer JSONs (`manifest.json` / `index.json`). |-| `DIFYCTL_R2_BIN_PREFIX` | `difyctl/bin` | R2 key root for binaries (the lifecycle/TTL target). |+| Env | Default | Purpose |+| ----------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |+| `DIFYCTL_R2_BASE` | — (required) | R2 public base, e.g. `https://pub-….r2.dev`. |+| `DIFYCTL_CHANNEL` | `edge` | Channel to install. |+| `DIFYCTL_INSTALL_DIR` | `$HOME/.local/bin` | Directory the binary is written to (`<dir>/difyctl`). On Windows the default is `%LOCALAPPDATA%\difyctl\bin`. |+| `DIFYCTL_PREFIX` | `$HOME/.local` | Used as `<prefix>/bin` when `DIFYCTL_INSTALL_DIR` is unset. On Windows the default is `%LOCALAPPDATA%\difyctl`. |+| `DIFYCTL_VERSION` | latest | Pin an exact published version. |+| `DIFYCTL_COMMIT` | latest | Pin by git commit (short or full sha). |+| `DIFYCTL_R2_PREFIX` | `difyctl` | R2 key root for the pointer JSONs (`manifest.json` / `index.json`). |+| `DIFYCTL_R2_BIN_PREFIX` | `difyctl/bin` | R2 key root for binaries (the lifecycle/TTL target). |By default the channel pointer (latest build) is installed. Set `DIFYCTL_COMMIT` (e.g. `ce4af86`) or `DIFYCTL_VERSION` to install a specific past build — both resolve through the channel's `index.json`:@@ -37,6 +50,7 @@ difyctl login --server https://dify.example.com # opens the browser; approve tdifyctl help # the map: every command and operation namespacedifyctl help chatbot # search commands and operations by plain wordsdifyctl get workspace # workspaces visible to this account+difyctl describe workspace # the workspace difyctl usesdifyctl get console_app --limit 5 # list appsdifyctl run console_app workflow --app-id <id> --inputs @vars.json --stream```@@ -45,21 +59,20 @@ difyctl has no built-in business commands. Every operation the server publishes## Commands-| Command | Purpose |-| -------------------------- | --------------------------------------------------------------- |-| `login` | Log in via the OAuth device flow |-| `logout` | Log out of the current session |-| `version` | Print the client and (if logged in) server versions |-| `use workspace <id>` | Pin the local session to a workspace |-| `get config [key]` | Print the local config, or one key |-| `set config <key> <value>` | Set a local config value |-| `unset config <key>` | Remove a local config value, restoring its default |-| `refresh cache` | Refetch the server catalog and replace the local cache |-| `delete cache` | Delete the local server catalog cache |-| `get skills` | List the skills in the collection |-| `install skills <dir>` | Write skills from the collection into a skills root (`--skill`) |--`login` blocks until the browser approval arrives. An agent runs it in the background, relays the `open <url>` and `code <code>` lines from its stderr to the user, and does not cancel the job. In a sandbox it adds `--no-keyring` and sets `DIFY_CONFIG_DIR` to persistent storage on every call, so the login survives the next session.+| Command | Purpose |+| -------------------------- | ------------------------------------------------------ |+| `login` | Log in via the OAuth device flow |+| `logout` | Log out of the current session |+| `version` | Print the client and (if logged in) server versions |+| `use workspace <id>` | Pin this device to a workspace you belong to |+| `get config [key]` | Print the local config, or one key |+| `set config <key> <value>` | Set a local config value |+| `unset config <key>` | Remove a local config value, restoring its default |+| `refresh cache` | Refetch the server catalog and replace the local cache |+| `delete cache` | Delete the local server catalog cache |+| `install skills <dir>` | Write the difyctl skill into a skills root (`--from`) |++`login` needs `--server`; there is no default server. It blocks until the browser approval arrives. An agent uses `--no-wait` instead: it gives the user the URL and code, then runs `login --resume` after the user approves. If it sets `DIFY_CONFIG_DIR`, it sets it on every call.`--verbose` is global: it may appear on any command, and it keeps the raw serverresponse in the error envelope instead of dropping it.@@ -68,11 +81,9 @@ response in the error envelope instead of dropping it.## Agent skills-difyctl installs agent skills from [`skills/`] at the repo root. It downloads them from GitHub at install time, from the commit the binary was built from; the binary holds no copy and needs no git. The basic skill, `difyctl`, teaches the discovery flow — `help` to see the map or search, `help <id>` to inspect one operation, then the operation's own command to run it — so it stays correct as the server's catalog grows. Scenario skills add guidance for one kind of task and open by reading the basic one.+difyctl ships one skill, `difyctl`, built into the binary. It teaches the discovery flow — `help` to see the map or search, `help <id>` to inspect one operation, then the operation's own command to run it — so it stays correct as the server's catalog grows. The skill is a tree of linked docs under [`skills/difyctl/`].-- `difyctl get skills` — the collection: each skill's name and description. Writes nothing.-- `difyctl install skills <dir>` — write every skill into `<dir>`, the agent's skills root: the folder that holds one subfolder per skill, for example `~/.claude/skills` for Claude Code or `~/.codex/skills` for Codex. Each skill's folder is replaced whole. `--skill <name>` (repeatable) writes only those skills; a scenario skill brings `difyctl` along.-- `--from` on both reads skills from elsewhere: any GitHub folder in the standard layout (`https://github.com/<owner>/<repo>/tree/<ref>/<folder>`), or a local folder when GitHub is blocked. Set `GITHUB_TOKEN` if GitHub's rate limit (60 requests an hour per IP) gets in the way.+- `difyctl install skills <dir> [--from <folder>]` — write the skill into `<dir>`, the agent's skills root: the folder that holds one subfolder per skill, for example `~/.claude/skills` for Claude Code or `~/.codex/skills` for Codex. The `difyctl` folder is replaced whole. It works offline. `--from` installs a local skill folder instead of the built-in one.difyctl does not detect agents. You name the root, and re-running the same command refreshes the copies.@@ -88,7 +99,7 @@ The same files install through the Vercel skills installer: `npx skills add lang`get config [key]` prints the whole local config or one key; `set config <key> <value>` and `unset config <key>` change it. The only config key today is `http.timeout` (request timeout in milliseconds).-Tokens use the OS keychain by default, falling back to `tokens.yml` on hosts without one; `login --no-keyring` chooses the file outright. Config and cache files are written `0600`, their directory `0700`.+Tokens use the OS keychain by default, falling back to `tokens.yml` in the config folder on hosts without one. On Linux without a DBus session (`DBUS_SESSION_BUS_ADDRESS` unset), the keychain would only hold the token until the session ends, so difyctl uses `tokens.yml` there too; `login --no-keyring` chooses the file outright. The catalog cache is kept in the config folder under `catalog/`; `DIFY_CACHE_DIR` is no longer used. Config and cache files are written `0600`, their directory `0700`.| Env var | Effect || ------------------- | ----------------------------------------------------------- |@@ -97,7 +108,6 @@ Tokens use the OS keychain by default, falling back to `tokens.yml` on hosts wit| `DIFY_WORKSPACE_ID` | Overrides the locally pinned workspace || `DIFY_OUTPUT` | `json` or `text`; overrides the terminal/pipe detection || `DIFY_CONFIG_DIR` | Overrides the config directory |-| `DIFY_CACHE_DIR` | Overrides the catalog cache directory |Resource access tokens can also be passed through `DIFY_TOKEN`. They can listtheir own workspace and discover only apps bound to that token; workspace@@ -111,7 +121,7 @@ Pass `--stream` on a streaming operation to print every event as one JSON line,difyctl run console_app chat --app-id … --query hello --inputs '{}' --stream```-`--only <event>` filters the streamed events to the named event types; repeat it to keep more than one. Without `--stream`, a streaming operation's events fold into `{status, text, outputs?, message_id?, conversation_id?, error?, hints}`.+`--only <event>` filters the streamed events to the named event types; repeat it to keep more than one. Without `--stream`, a streaming operation's events fold into `{status, text, outputs?, message_id?, conversation_id?, run_id?, error?, hints}`.## Exit codes@@ -135,4 +145,4 @@ Apache-2.0.[Agent skill]: #agent-skills[Dify]: https://dify.ai[`ARD.md`]: ARD.md-[`skills/`]: ../skills+[`skills/difyctl/`]: ../skills/difyctldiff --git a/cli/bin/dev.js b/cli/bin/dev.jsindex fb6a702ba22..5045e5e89fc 100755--- a/cli/bin/dev.js+++ b/cli/bin/dev.js@@ -9,6 +9,7 @@ globalThis.__DIFYCTL_VERSION__ = info.versionglobalThis.__DIFYCTL_COMMIT__ = info.commitglobalThis.__DIFYCTL_BUILD_DATE__ = info.buildDateglobalThis.__DIFYCTL_CHANNEL__ = info.channel+globalThis.__DIFYCTL_COMPILED__ = falseconst { main } = await import('../src/main.ts')process.exitCode = await main(process.argv.slice(2))diff --git a/cli/scripts/install-cli.sh b/cli/scripts/install-cli.shindex 7bd87886c35..5271344a9c3 100755--- a/cli/scripts/install-cli.sh+++ b/cli/scripts/install-cli.sh@@ -8,14 +8,14 @@# env:# DIFY_VERSION Dify release tag to install difyctl from (e.g. 1.14.2). Primary key.# DIFYCTL_VERSION difyctl version pin (used only when DIFY_VERSION is unset).-# DIFYCTL_PREFIX install dir (default $HOME/.local); binary -> $PREFIX/bin/difyctl+# DIFYCTL_PREFIX install prefix (default $HOME/.local); binary -> $PREFIX/bin/difyctl+# DIFYCTL_INSTALL_DIR the bin folder itself (wins over DIFYCTL_PREFIX); binary -> $DIR/difyctl# DIFYCTL_REPO release source repo (default langgenius/dify)# GITHUB_TOKEN GitHub token (or GH_TOKEN) to raise the API rate limit to 5000/hour.# requires: curl, uname, sort -V, and sha256sum or shasum.set -euREPO="${DIFYCTL_REPO:-langgenius/dify}"-PREFIX="${DIFYCTL_PREFIX:-${HOME}/.local}"DIFY_VERSION="${DIFY_VERSION:-}"DIFYCTL_VERSION="${DIFYCTL_VERSION:-}"GH_AUTH="${GITHUB_TOKEN:-${GH_TOKEN:-}}"@@ -28,6 +28,27 @@ err() { printf '%s\n' "install-cli: $*" >&2; }die() { err "$*"; rm -f "$FETCH_ERR_FILE"; exit 1; }need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }re_escape() { printf '%s' "$1" | sed 's/[][\\.^$*+?(){}|/]/\\&/g'; }+# print_skill_hint BIN: the hint names a v2 command, so a binary without it (any v1 build) gets none.+print_skill_hint() {+ "$1" install skills --help >/dev/null 2>&1 || return 0+ printf '%s\n' 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'+}++# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.+bin_dir_for() {+ printf '%s' "${DIFYCTL_INSTALL_DIR:-${DIFYCTL_PREFIX:-${HOME}/.local}/bin}"+}++# install_binary SRC DEST: stage the copy next to DEST, then rename it over DEST, so a+# running difyctl keeps its old file and DEST is never half written.+install_binary() {+ _stage="$(dirname "$2")/.difyctl.install.$$"+ if cp "$1" "$_stage" && chmod 0755 "$_stage" && mv -f "$_stage" "$2"; then+ return 0+ fi+ rm -f "$_stage"+ die "cannot write $2"+}detect_target() {case "$(uname -s)" in@@ -219,19 +240,17 @@ main() {printf '%s\n' "$_sumline" | $HASH -c -) || die "checksum mismatch for ${asset}"- bin_dir="${PREFIX}/bin"+ bin_dir=$(bin_dir_for)mkdir -p "$bin_dir"target_bin="${bin_dir}/difyctl"- cp "${tmp}/${asset}" "$target_bin"- chmod +x "$target_bin"+ install_binary "${tmp}/${asset}" "$target_bin"printf '\ndifyctl v%s installed (from Dify %s): %s\n' "$version" "$DIFY_TAG" "$target_bin"case ":${PATH}:" in*":${bin_dir}:"*)- "$target_bin" version >/dev/null 2>&1 \- && printf 'verify: run "difyctl version"\n' \- || err "binary present but failed to execute; check ${target_bin}"+ printf 'verify: run "difyctl version"\n'+ print_skill_hint "$target_bin";;*)printf '\n%s is not on your PATH. Add this to your shell profile:\n' "$bin_dir"diff --git a/cli/scripts/install-cli.test.ts b/cli/scripts/install-cli.test.tsindex c07e2b431d2..f69739069f8 100644--- a/cli/scripts/install-cli.test.ts+++ b/cli/scripts/install-cli.test.ts@@ -1,5 +1,5 @@import { execFileSync, spawnSync } from 'node:child_process'-import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'+import { chmodSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { fileURLToPath } from 'node:url'@@ -400,3 +400,102 @@ describe('install-cli fetch_json (real, fake curl on PATH)', () => {).not.toContain('Authorization')})})++describe('install-cli.sh install location', () => {+ const where = (env: Record<string, string>) =>+ runLib('bin_dir_for', { DIFYCTL_PREFIX: '', DIFYCTL_INSTALL_DIR: '', HOME: '/home/u', ...env })+ .stdout++ it('defaults to ~/.local/bin', () => {+ expect(where({})).toBe('/home/u/.local/bin')+ })++ it('puts the binary under <DIFYCTL_PREFIX>/bin', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe('/opt/dify/bin')+ })++ it('takes DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/usr/local/bin' })).toBe(+ '/usr/local/bin',+ )+ })+})++describe('install-cli.sh install_binary', () => {+ it('replaces the binary through a rename, leaving no staged file behind', () => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-install-'))+ try {+ const src = join(dir, 'new')+ const dest = join(dir, 'bin-difyctl')+ writeFileSync(src, 'new build')+ writeFileSync(dest, 'old build')+ const r = runLib(`install_binary "${src}" "${dest}"`)+ expect(r.code).toBe(0)+ expect(readFileSync(dest, 'utf8')).toBe('new build')+ expect(execFileSync('ls', ['-A', dir], { encoding: 'utf8' }).trim().split('\n')).toEqual([+ 'bin-difyctl',+ 'new',+ ])+ // Windows filesystems have no executable bit to check.+ if (process.platform !== 'win32') {+ expect(+ execFileSync('sh', ['-c', `test -x "${dest}" && echo yes`], { encoding: 'utf8' }),+ ).toBe('yes\n')+ }+ } finally {+ rmSync(dir, { recursive: true, force: true })+ }+ })++ // A shared install must stay readable by other users, whatever the installer's umask.+ it.skipIf(process.platform === 'win32')(+ 'installs a 0600 source as mode 0755 under umask 077',+ () => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-install-'))+ try {+ const src = join(dir, 'new')+ const dest = join(dir, 'bin-difyctl')+ writeFileSync(src, 'new build', { mode: 0o600 })+ const r = runLib(`umask 077; install_binary "${src}" "${dest}"`)+ expect(r.code).toBe(0)+ expect(statSync(dest).mode & 0o777).toBe(0o755)+ } finally {+ rmSync(dir, { recursive: true, force: true })+ }+ },+ )++ it('dies without touching the old binary when the folder is not writable', () => {+ const r = runLib('install_binary /nonexistent/src /nonexistent-dir/difyctl')+ expect(r.code).not.toBe(0)+ expect(r.stderr).toMatch(/cannot write \/nonexistent-dir\/difyctl/)+ })+})++// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".+describe.skipIf(process.platform === 'win32')('install-cli.sh print_skill_hint', () => {+ const fakeBins = [+ 'd="$(mktemp -d)"',+ 'printf \'#!/bin/sh\\n[ "$*" = "install skills --help" ]\\n\' > "$d/v2"',+ 'printf \'#!/bin/sh\\necho "unknown command: $*" >&2\\nexit 1\\n\' > "$d/v1"',+ 'chmod 0755 "$d/v2" "$d/v1"',+ ]++ it('prints the hint for a binary that has install skills', () => {+ const r = runLib([...fakeBins, 'print_skill_hint "$d/v2"', 'rm -rf "$d"'].join('\n'))+ expect(r.code).toBe(0)+ expect(r.stdout).toMatch(/difyctl install skills <skills root>/)+ })++ it('prints nothing for a binary without install skills', () => {+ const r = runLib([...fakeBins, 'print_skill_hint "$d/v1"', 'rm -rf "$d"'].join('\n'))+ expect(r.code).toBe(0)+ expect(r.stdout).toBe('')+ })++ it('prints nothing when the binary cannot run', () => {+ const r = runLib('print_skill_hint /nonexistent/difyctl')+ expect(r.code).toBe(0)+ expect(r.stdout).toBe('')+ })+})diff --git a/cli/scripts/install-r2.ps1 b/cli/scripts/install-r2.ps1index 44321d13fac..e3b93809e2c 100644--- a/cli/scripts/install-r2.ps1+++ b/cli/scripts/install-r2.ps1@@ -2,6 +2,7 @@# Usage: $env:DIFYCTL_R2_BASE='<BASE>'; irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-r2.ps1 | iex# Env: DIFYCTL_R2_BASE (required), DIFYCTL_CHANNEL (default edge),# DIFYCTL_INSTALL_DIR (default %LOCALAPPDATA%\difyctl\bin; binary written here as difyctl.exe),+# DIFYCTL_PREFIX (the folder above the bin folder; <prefix>\bin is used when DIFYCTL_INSTALL_DIR is unset),# DIFYCTL_VERSION (pin exact published version),# DIFYCTL_COMMIT (pin by git commit, short or full sha; via index.json),# DIFYCTL_R2_PREFIX (default difyctl; key root for pointer JSONs),@@ -38,22 +39,51 @@ function Get-ChecksumTarget([string]$text, [string]$target) {return $null}-# Download, sha256-verify, place. Returns nothing; throws on mismatch.+# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.+function Resolve-BinDir {+ if ($env:DIFYCTL_INSTALL_DIR) { return $env:DIFYCTL_INSTALL_DIR }+ $prefix = if ($env:DIFYCTL_PREFIX) { $env:DIFYCTL_PREFIX } else { Join-Path $env:LOCALAPPDATA 'difyctl' }+ return Join-Path $prefix 'bin'+}++# The user PATH alone: $env:PATH also holds the machine PATH, which must not be copied into it.+function Get-PathHint([string]$Dir) {+ return " [Environment]::SetEnvironmentVariable('PATH', `"$Dir;`" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')"+}++# The hint names a v2 command, so a binary without it (any v1 build) gets none. Under+# Windows PowerShell 5.1 a redirected stderr line throws when errors stop, hence the catch.+function Write-SkillHint([string]$Bin) {+ try { & $Bin install skills --help *> $null } catch { return }+ if ($LASTEXITCODE -ne 0) { return }+ Write-Host 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'+}++# Download, sha256-verify, place. Returns nothing; throws on a missing or wrong checksum.function Install-DifyctlBinary([string]$dlUrl, [string]$sha, [string]$version, [string]$channel, [string]$installDir) {- $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ([System.IO.Path]::GetFileName($dlUrl))- Invoke-WebRequest -Uri $dlUrl -OutFile $tmp- $actual = (Get-FileHash -Path $tmp -Algorithm SHA256).Hash.ToLower()- if ($actual -ne $sha.ToLower()) { throw "checksum mismatch for $dlUrl" }+ if (-not $sha) { throw "no checksum published for $dlUrl; not installing an unverified binary" }+ $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ('difyctl-' + [guid]::NewGuid().ToString('N') + '.exe')+ try {+ Invoke-WebRequest -Uri $dlUrl -OutFile $tmp+ $actual = (Get-FileHash -Path $tmp -Algorithm SHA256).Hash.ToLower()+ if ($actual -ne $sha.ToLower()) { throw "checksum mismatch for $dlUrl" }- New-Item -ItemType Directory -Path $installDir -Force | Out-Null- $dest = Join-Path $installDir 'difyctl.exe'- try { Move-Item -Path $tmp -Destination $dest -Force }- catch { throw "cannot replace $dest — close any running difyctl and re-run." }+ New-Item -ItemType Directory -Path $installDir -Force | Out-Null+ $dest = Join-Path $installDir 'difyctl.exe'+ try { Move-Item -Path $tmp -Destination $dest -Force }+ catch { throw "cannot replace $dest — close any running difyctl and re-run." }+ }+ finally {+ Remove-Item -Path $tmp -Force -ErrorAction SilentlyContinue+ }Write-Host "difyctl $version (channel $channel) installed: $dest"if (($env:PATH -split ';') -notcontains $installDir) {Write-Host "$installDir is not on your PATH. Add it with:"- Write-Host " [Environment]::SetEnvironmentVariable('PATH', `"$installDir;`$env:PATH`", 'User')"+ Write-Host (Get-PathHint $installDir)+ }+ else {+ Write-SkillHint $dest}}@@ -64,7 +94,7 @@ function Install-DifyctlR2 {$channel = if ($env:DIFYCTL_CHANNEL) { $env:DIFYCTL_CHANNEL } else { 'edge' }$prefix = if ($env:DIFYCTL_R2_PREFIX) { $env:DIFYCTL_R2_PREFIX } else { 'difyctl' }$binPrefix = if ($env:DIFYCTL_R2_BIN_PREFIX) { $env:DIFYCTL_R2_BIN_PREFIX } else { "$prefix/bin" }- $installDir = if ($env:DIFYCTL_INSTALL_DIR) { $env:DIFYCTL_INSTALL_DIR } else { Join-Path (Join-Path $env:LOCALAPPDATA 'difyctl') 'bin' }+ $installDir = Resolve-BinDir$target = 'windows-x64'if ($env:DIFYCTL_VERSION -or $env:DIFYCTL_COMMIT) {diff --git a/cli/scripts/install-r2.ps1.test.ts b/cli/scripts/install-r2.ps1.test.tsindex b7b983a26e0..ee9e623358d 100644--- a/cli/scripts/install-r2.ps1.test.ts+++ b/cli/scripts/install-r2.ps1.test.ts@@ -1,4 +1,7 @@import { spawnSync } from 'node:child_process'+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'import { fileURLToPath } from 'node:url'import { describe, expect, it } from 'vite-plus/test'@@ -17,11 +20,14 @@ const MANIFEST = JSON.stringify({},})-function pwsh(program: string): { code: number; stdout: string; stderr: string } {+function pwsh(+ program: string,+ env: Record<string, string> = {},+): { code: number; stdout: string; stderr: string } {const full = `. '${SCRIPT}'\n${program}`const r = spawnSync('pwsh', ['-NoProfile', '-Command', full], {encoding: 'utf8',- env: { ...process.env, DIFYCTL_INSTALL_LIB: '1' },+ env: { ...process.env, DIFYCTL_INSTALL_LIB: '1', ...env },})return {code: r.status ?? 1,@@ -51,3 +57,81 @@ d('install-r2.ps1', () => {}})})++d('install-r2.ps1 install location, PATH hint and download', () => {+ const where = (env: Record<string, string>) =>+ pwsh('Write-Output (Resolve-BinDir)', {+ DIFYCTL_PREFIX: '',+ DIFYCTL_INSTALL_DIR: '',+ LOCALAPPDATA: '/lad',+ ...env,+ }).stdout++ it('defaults to %LOCALAPPDATA%\\difyctl\\bin', () => {+ expect(where({})).toBe(join('/lad', 'difyctl', 'bin'))+ })++ it('accepts DIFYCTL_PREFIX like the GitHub installer', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe(join('/opt/dify', 'bin'))+ })++ it('keeps DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/custom/bin' })).toBe(+ '/custom/bin',+ )+ })++ it('the PATH command adds to the user PATH, not the whole session PATH', () => {+ const hint = pwsh(`Write-Output (Get-PathHint 'C:\\dify\\bin')`).stdout+ expect(hint).toContain(+ `"C:\\dify\\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User')`,+ )+ expect(hint).not.toContain('$env:PATH')+ })++ it('stops before downloading when the checksum is missing', () => {+ const r = pwsh(+ "function Invoke-WebRequest { throw 'must not download' }\n" ++ "try { Install-DifyctlBinary 'https://x/difyctl.exe' '' '1.0.0' 'edge' '/tmp/none' } " ++ 'catch { Write-Output $_.Exception.Message }',+ )+ expect(r.stdout).toMatch(/^no checksum published for https:\/\/x\/difyctl\.exe/)+ })++ it('downloads to a unique temp file, not one named after the asset', () => {+ const r = pwsh(+ 'function Invoke-WebRequest { param($Uri, $OutFile) Write-Output "OUT=$OutFile"; Set-Content -Path $OutFile -Value x }\n' ++ "try { Install-DifyctlBinary 'https://x/difyctl.exe' 'deadbeef' '1.0.0' 'edge' '/tmp/none' } " ++ 'catch { Write-Output $_.Exception.Message }',+ )+ expect(r.stdout).toMatch(/OUT=.*difyctl-[0-9a-f]{32}\.exe\n/)+ expect(r.stdout).toMatch(/checksum mismatch/)+ })+})++// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".+// The fakes are shell scripts, so this runs where pwsh runs outside Windows.+describe.skipIf(!hasPwsh || process.platform === 'win32')('install-r2.ps1 Write-SkillHint', () => {+ const hint = (bin: string) => pwsh(`Write-SkillHint '${bin}'`)++ it('prints the hint for a binary that has install skills, and stays quiet otherwise', () => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-hint-'))+ try {+ const v2 = join(dir, 'v2')+ const v1 = join(dir, 'v1')+ writeFileSync(v2, '#!/bin/sh\n[ "$*" = "install skills --help" ]\n', { mode: 0o755 })+ writeFileSync(v1, '#!/bin/sh\necho "unknown command: $*" >&2\nexit 1\n', { mode: 0o755 })+ expect(hint(v2)).toMatchObject({+ code: 0,+ stdout: expect.stringContaining('difyctl install skills <skills root>'),+ })+ expect(hint(v1)).toMatchObject({ code: 0, stdout: '' })+ } finally {+ rmSync(dir, { recursive: true, force: true })+ }+ })++ it('prints nothing when the binary cannot run', () => {+ expect(hint('/nonexistent/difyctl')).toMatchObject({ code: 0, stdout: '' })+ })+})diff --git a/cli/scripts/install-r2.sh b/cli/scripts/install-r2.shindex ffb4d980429..d8b549a7bb5 100755--- a/cli/scripts/install-r2.sh+++ b/cli/scripts/install-r2.sh@@ -6,6 +6,7 @@# DIFYCTL_R2_BASE (required) R2 public base, e.g. https://pub-….r2.dev# DIFYCTL_CHANNEL (default edge)# DIFYCTL_INSTALL_DIR (default $HOME/.local/bin) directory the binary is written to as <dir>/difyctl+# DIFYCTL_PREFIX the folder above the bin folder; <prefix>/bin is used when DIFYCTL_INSTALL_DIR is unset# DIFYCTL_VERSION pin an exact published version (e.g. 0.1.0-edge.ce4af868)# DIFYCTL_COMMIT pin by git commit (short or full sha); resolved via index.json# DIFYCTL_R2_PREFIX (default difyctl) key root for pointer JSONs@@ -21,12 +22,33 @@ trap 'rm -f "$tmp_m" "${tmp_c:-}" "${tmp_b:-}"' EXIT INT TERMerr() { printf '%s\n' "install-r2: $*" >&2; }die() { err "$*"; exit 1; }need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }+# print_skill_hint BIN: the hint names a v2 command, so a binary without it (any v1 build) gets none.+print_skill_hint() {+ "$1" install skills --help >/dev/null 2>&1 || return 0+ printf '%s\n' 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'+}++# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.+bin_dir_for() {+ printf '%s' "${DIFYCTL_INSTALL_DIR:-${DIFYCTL_PREFIX:-${HOME}/.local}/bin}"+}++# install_binary SRC DEST: stage the copy next to DEST, then rename it over DEST, so a+# running difyctl keeps its old file and DEST is never half written.+install_binary() {+ _stage="$(dirname "$2")/.difyctl.install.$$"+ if cp "$1" "$_stage" && chmod 0755 "$_stage" && mv -f "$_stage" "$2"; then+ return 0+ fi+ rm -f "$_stage"+ die "cannot write $2"+}detect_target() {case "$(uname -s)" inLinux*) _os=linux ;;Darwin*) _os=darwin ;;- *) die "unsupported OS: $(uname -s) (use install.ps1 on Windows)" ;;+ *) die "unsupported OS: $(uname -s) (use install-r2.ps1 on Windows)" ;;esaccase "$(uname -m)" inx86_64|amd64) _arch=x64 ;;@@ -90,12 +112,11 @@ fetch_verify_install() {sha256_check "$tmp_b" "$2"mkdir -p "$install_dir"- chmod +x "$tmp_b"- mv "$tmp_b" "${install_dir}/difyctl" 2>/dev/null || { cp "$tmp_b" "${install_dir}/difyctl"; rm -f "$tmp_b"; }+ install_binary "$tmp_b" "${install_dir}/difyctl"printf 'difyctl %s (channel %s) installed: %s\n' "$3" "$4" "${install_dir}/difyctl"case ":${PATH}:" in- *":${install_dir}:"*) ;;+ *":${install_dir}:"*) print_skill_hint "${install_dir}/difyctl" ;;*) printf 'note: add %s to your PATH\n' "$install_dir" ;;esac}@@ -147,7 +168,7 @@ install_main() {channel="${DIFYCTL_CHANNEL:-edge}"prefix="${DIFYCTL_R2_PREFIX:-difyctl}"bin_prefix="${DIFYCTL_R2_BIN_PREFIX:-${prefix}/bin}"- install_dir="${DIFYCTL_INSTALL_DIR:-${HOME}/.local/bin}"+ install_dir="$(bin_dir_for)"target="$(detect_target)"if [ -n "${DIFYCTL_VERSION:-}" ] || [ -n "${DIFYCTL_COMMIT:-}" ]; thendiff --git a/cli/scripts/install-r2.test.ts b/cli/scripts/install-r2.test.tsindex d6875524433..026cf5f0f0c 100644--- a/cli/scripts/install-r2.test.ts+++ b/cli/scripts/install-r2.test.ts@@ -146,3 +146,77 @@ describe('install-r2 version/commit pin', () => {expect(r.stdout).toBe('deadbeef\tdifyctl-v0.1.0-edge.ce4af868-linux-x64')})})++describe('install-r2.sh install location', () => {+ const where = (env: Record<string, string>) =>+ lib('bin_dir_for', { DIFYCTL_PREFIX: '', DIFYCTL_INSTALL_DIR: '', HOME: '/home/u', ...env })+ .stdout++ it('defaults to ~/.local/bin', () => {+ expect(where({})).toBe('/home/u/.local/bin')+ })++ it('accepts DIFYCTL_PREFIX like the GitHub installer', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe('/opt/dify/bin')+ })++ it('keeps DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/usr/local/bin' })).toBe(+ '/usr/local/bin',+ )+ })+})++it.skipIf(process.platform === 'win32')(+ 'install-r2.sh points Windows users at install-r2.ps1',+ () => {+ const r = lib('uname() { printf MINGW64_NT; }; detect_target')+ expect(r.code).not.toBe(0)+ expect(r.stderr).toMatch(/use install-r2\.ps1 on Windows/)+ },+)++describe.skipIf(process.platform === 'win32')('install-r2.sh install_binary', () => {+ it('installs a 0600 temp file as mode 0755 next to and then over the target', () => {+ const r = lib(+ [+ 'd="$(mktemp -d)"',+ 'src="$(mktemp)"; chmod 0600 "$src"; printf new > "$src"',+ 'printf old > "$d/difyctl"',+ 'install_binary "$src" "$d/difyctl"',+ 'ls -l "$d/difyctl" | cut -c1-10; cat "$d/difyctl"; echo; ls -A "$d"',+ 'rm -rf "$d" "$src"',+ ].join('\n'),+ )+ expect(r.code).toBe(0)+ expect(r.stdout.split('\n')).toEqual(['-rwxr-xr-x', 'new', 'difyctl'])+ })+})++// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".+describe.skipIf(process.platform === 'win32')('install-r2.sh print_skill_hint', () => {+ const fakeBins = [+ 'd="$(mktemp -d)"',+ 'printf \'#!/bin/sh\\n[ "$*" = "install skills --help" ]\\n\' > "$d/v2"',+ 'printf \'#!/bin/sh\\necho "unknown command: $*" >&2\\nexit 1\\n\' > "$d/v1"',+ 'chmod 0755 "$d/v2" "$d/v1"',+ ]++ it('prints the hint for a binary that has install skills', () => {+ const r = lib([...fakeBins, 'print_skill_hint "$d/v2"', 'rm -rf "$d"'].join('\n'))+ expect(r.code).toBe(0)+ expect(r.stdout).toMatch(/difyctl install skills <skills root>/)+ })++ it('prints nothing for a binary without install skills', () => {+ const r = lib([...fakeBins, 'print_skill_hint "$d/v1"', 'rm -rf "$d"'].join('\n'))+ expect(r.code).toBe(0)+ expect(r.stdout).toBe('')+ })++ it('prints nothing when the binary cannot run', () => {+ const r = lib('print_skill_hint /nonexistent/difyctl')+ expect(r.code).toBe(0)+ expect(r.stdout).toBe('')+ })+})diff --git a/cli/scripts/install.ps1 b/cli/scripts/install.ps1index 19a114eff10..3fae747b150 100644--- a/cli/scripts/install.ps1+++ b/cli/scripts/install.ps1@@ -7,7 +7,8 @@# env:# DIFY_VERSION Dify release tag to install difyctl from (e.g. 1.14.2). Primary key.# DIFYCTL_VERSION difyctl version pin (used only when DIFY_VERSION is unset).-# DIFYCTL_PREFIX install dir (default $env:LOCALAPPDATA\difyctl)+# DIFYCTL_PREFIX install prefix (default $env:LOCALAPPDATA\difyctl); binary -> <prefix>\bin\difyctl.exe+# DIFYCTL_INSTALL_DIR the bin folder itself (wins over DIFYCTL_PREFIX); binary -> <dir>\difyctl.exe# DIFYCTL_REPO release source repo (default langgenius/dify)# GITHUB_TOKEN GitHub token (or GH_TOKEN) sent as a bearer to raise the API# rate limit from 60 to 5000 requests/hour (useful in CI).@@ -17,7 +18,6 @@ $ErrorActionPreference = 'Stop'$repo = if ($env:DIFYCTL_REPO) { $env:DIFYCTL_REPO } else { 'langgenius/dify' }$difyVersion = $env:DIFY_VERSION$difyctlVersion = $env:DIFYCTL_VERSION-$prefix = if ($env:DIFYCTL_PREFIX) { $env:DIFYCTL_PREFIX } else { Join-Path $env:LOCALAPPDATA 'difyctl' }$target = 'windows-x64'$apiBase = "https://api.github.com/repos/$repo"$dlBase = "https://github.com/$repo/releases/download"@@ -115,6 +115,26 @@ function Resolve-Release {}}+# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.+function Resolve-BinDir {+ if ($env:DIFYCTL_INSTALL_DIR) { return $env:DIFYCTL_INSTALL_DIR }+ $prefix = if ($env:DIFYCTL_PREFIX) { $env:DIFYCTL_PREFIX } else { Join-Path $env:LOCALAPPDATA 'difyctl' }+ return Join-Path $prefix 'bin'+}++# The user PATH alone: $env:PATH also holds the machine PATH, which must not be copied into it.+function Get-PathHint([string]$Dir) {+ return " [Environment]::SetEnvironmentVariable('PATH', `"$Dir;`" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')"+}++# The hint names a v2 command, so a binary without it (any v1 build) gets none. Under+# Windows PowerShell 5.1 a redirected stderr line throws when errors stop, hence the catch.+function Write-SkillHint([string]$Bin) {+ try { & $Bin install skills --help *> $null } catch { return }+ if ($LASTEXITCODE -ne 0) { return }+ Write-Host 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'+}+function Invoke-Main {$release = Resolve-Release$difyTag = $release.tag_name@@ -143,20 +163,30 @@ function Invoke-Main {$actual = (Get-FileHash -Path $assetPath -Algorithm SHA256).Hash.ToLower()if ($actual -ne $expected.ToLower()) { throw "checksum mismatch for $assetName" }- $binDir = Join-Path $prefix 'bin'+ $binDir = Resolve-BinDirNew-Item -ItemType Directory -Path $binDir -Force | Out-Null$targetBin = Join-Path $binDir 'difyctl.exe'- Copy-Item -Path $assetPath -Destination $targetBin -Force+ # Stage next to the target, then rename over it, so difyctl.exe is never half written.+ $stage = Join-Path $binDir ('.difyctl.install.' + [guid]::NewGuid().ToString('N') + '.exe')+ try {+ Copy-Item -Path $assetPath -Destination $stage -Force+ Move-Item -Path $stage -Destination $targetBin -Force+ }+ catch {+ Remove-Item -Path $stage -Force -ErrorAction SilentlyContinue+ throw "cannot replace $targetBin — close any running difyctl and re-run."+ }Write-Host ""Write-Host "difyctl v$ver installed (from Dify $difyTag): $targetBin"if (($env:PATH -split ';') -notcontains $binDir) {Write-Host ""Write-Host "$binDir is not on your PATH. Add it with:"- Write-Host " [Environment]::SetEnvironmentVariable('PATH', `"$binDir;`$env:PATH`", 'User')"+ Write-Host (Get-PathHint $binDir)}else {Write-Host 'verify: run "difyctl version"'+ Write-SkillHint $targetBin}}finally {diff --git a/cli/scripts/install.ps1.test.ts b/cli/scripts/install.ps1.test.tsindex a75f4defbea..e56e2b5467b 100644--- a/cli/scripts/install.ps1.test.ts+++ b/cli/scripts/install.ps1.test.ts@@ -1,4 +1,7 @@import { spawnSync } from 'node:child_process'+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'import { fileURLToPath } from 'node:url'import { describe, expect, it } from 'vite-plus/test'@@ -295,3 +298,62 @@ describe.skipIf(!PWSH)('install.ps1 rate limit', () => {expect(r.stderr).not.toContain('not found')})})++describe.skipIf(!PWSH)('install.ps1 install location and PATH hint', () => {+ const where = (env: Record<string, string>) =>+ runPwsh('Write-Output (Resolve-BinDir)', {+ DIFYCTL_PREFIX: '',+ DIFYCTL_INSTALL_DIR: '',+ LOCALAPPDATA: '/lad',+ ...env,+ }).stdout++ it('defaults to %LOCALAPPDATA%\\difyctl\\bin', () => {+ expect(where({})).toBe(join('/lad', 'difyctl', 'bin'))+ })++ it('puts the binary under <DIFYCTL_PREFIX>\\bin', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe(join('/opt/dify', 'bin'))+ })++ it('takes DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/custom/bin' })).toBe(+ '/custom/bin',+ )+ })++ it('the PATH command adds to the user PATH, not the whole session PATH', () => {+ const hint = runPwsh(`Write-Output (Get-PathHint 'C:\\dify\\bin')`).stdout+ expect(hint).toContain(+ `"C:\\dify\\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User')`,+ )+ expect(hint).not.toContain('$env:PATH')+ })+})++// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".+// The fakes are shell scripts, so this runs where pwsh runs outside Windows.+describe.skipIf(!PWSH || process.platform === 'win32')('install.ps1 Write-SkillHint', () => {+ const hint = (bin: string) => runPwsh(`Write-SkillHint '${bin}'`)++ it('prints the hint for a binary that has install skills, and stays quiet otherwise', () => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-hint-'))+ try {+ const v2 = join(dir, 'v2')+ const v1 = join(dir, 'v1')+ writeFileSync(v2, '#!/bin/sh\n[ "$*" = "install skills --help" ]\n', { mode: 0o755 })+ writeFileSync(v1, '#!/bin/sh\necho "unknown command: $*" >&2\nexit 1\n', { mode: 0o755 })+ expect(hint(v2)).toMatchObject({+ code: 0,+ stdout: expect.stringContaining('difyctl install skills <skills root>'),+ })+ expect(hint(v1)).toMatchObject({ code: 0, stdout: '' })+ } finally {+ rmSync(dir, { recursive: true, force: true })+ }+ })++ it('prints nothing when the binary cannot run', () => {+ expect(hint('/nonexistent/difyctl')).toMatchObject({ code: 0, stdout: '' })+ })+})diff --git a/cli/scripts/release-build.sh b/cli/scripts/release-build.shindex 31e22c2526f..7dc320de929 100755--- a/cli/scripts/release-build.sh+++ b/cli/scripts/release-build.sh@@ -41,6 +41,10 @@ DIFYCTL_BUILD_DATE="${DIFYCTL_BUILD_DATE:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"[[ "$CLI_VERSION" != "undefined" ]] || die "CLI_VERSION could not be derived from package.json"+repo_root="$(cd "${cli_root}/.." && pwd)"+skill_dir="${repo_root}/skills/difyctl"+[[ -f "${skill_dir}/SKILL.md" ]] || die "skill not found: ${skill_dir}"+[[ -f "$entry" ]] || die "entry not found: $entry"rm -rf "$out_dir"@@ -53,6 +57,7 @@ defines=("--define" "__DIFYCTL_CHANNEL__=\"${DIFYCTL_CHANNEL}\"""--define" "__DIFYCTL_COMMIT__=\"${DIFYCTL_COMMIT}\"""--define" "__DIFYCTL_BUILD_DATE__=\"${DIFYCTL_BUILD_DATE}\""+ "--define" "__DIFYCTL_COMPILED__=true")# Targets and asset names come from cli/package.json `difyctl.release` via@@ -60,12 +65,15 @@ defines=(while IFS=$'\t' read -r bun_target asset_target _exe; doout="${out_dir}/$(naming asset "$CLI_VERSION" "$asset_target")"log::info "compiling ${asset_target} -> $(basename "$out")..."- bun build "$entry" \+ # Run from the repo root: --asset paths are embedded relative to the cwd, which gives+ # the skill its difyctl/ prefix.+ (cd "$repo_root" && bun build "$entry" \+ --asset "$skill_dir" \--target="$bun_target" \--compile \--minify \"${defines[@]}" \- --outfile="$out" >/dev/null+ --outfile="$out") >/dev/nulldone < <(naming targets)log::info "built $(find "$out_dir" -type f | wc -l | tr -d ' ') binaries:"diff --git a/cli/scripts/release-smoke.sh b/cli/scripts/release-smoke.shnew file mode 100755index 00000000000..93f7e7da196--- /dev/null+++ b/cli/scripts/release-smoke.sh@@ -0,0 +1,18 @@+#!/usr/bin/env bash+# scripts/release-smoke.sh <bin> — run a built binary on this runner and check that+# `install skills` writes exactly the skill tree in skills/difyctl.++set -euo pipefail++_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+# shellcheck source=lib/common.sh+source "${_dir}/lib/common.sh"++bin="${1:?usage: release-smoke.sh <bin>}"+skill_dir="$(cd "$(cli::root)/.." && pwd)/skills/difyctl"+out="$(mktemp -d)"+trap 'rm -rf "$out"' EXIT++"$bin" version+"$bin" install skills "$out"+diff -r "${out}/difyctl" "$skill_dir"diff --git a/cli/scripts/run-smoke.ts b/cli/scripts/run-smoke.tsindex 958c9fe3153..f7249fa10e0 100644--- a/cli/scripts/run-smoke.ts+++ b/cli/scripts/run-smoke.ts@@ -1,7 +1,7 @@#!/usr/bin/env -S bun// scripts/run-smoke.ts — five checks against a running Dify server (or mock),-// through `bun bin/dev.js`. DIFY_SERVER, DIFY_TOKEN, DIFY_CONFIG_DIR, and-// DIFY_CACHE_DIR are read from the environment and passed through unchanged.+// through `bun bin/dev.js`. DIFY_SERVER, DIFY_TOKEN and DIFY_CONFIG_DIR are+// read from the environment and passed through unchanged.import { execFileSync, spawnSync } from 'node:child_process'import { ExitCode } from '../src/errors/codes.js'diff --git a/cli/src/auth/pending-login.ts b/cli/src/auth/pending-login.tsnew file mode 100644index 00000000000..cfcc5842d56--- /dev/null+++ b/cli/src/auth/pending-login.ts@@ -0,0 +1,40 @@+import type { CommandContext } from '@/plugins/base'+import { join } from 'node:path'+import { z } from 'zod'+import { env } from '@/plugins/env'+import { io } from '@/plugins/io'+import { localFile } from '@/store/local-file'++export const PENDING_FILE_NAME = 'login-pending.yml'++const PENDING_SCHEMA = z.object({+ server: z.string(),+ insecure: z.boolean(),+ no_keyring: z.boolean(),+ device_code: z.string(),+})+export type Pending = z.infer<typeof PENDING_SCHEMA>++export type PendingLoginStore = Readonly<{+ read: () => Promise<Pending | null>+ save: (pending: Pending) => Promise<void>+ clear: () => Promise<void>+ /** Clear only while the file still holds `deviceCode`: a newer login's code survives. */+ clearIf: (deviceCode: string) => Promise<void>+}>++/** The device code a `login --no-wait` saved for `login --resume` to finish. */+export async function pendingLoginStore(ctx: CommandContext): Promise<PendingLoginStore> {+ const { configDir } = await ctx.get(env)+ const file = localFile(+ join(configDir, PENDING_FILE_NAME),+ PENDING_SCHEMA,+ (await ctx.get(io)).notice,+ )+ return {+ read: file.read,+ save: file.write,+ clear: file.remove,+ clearIf: (deviceCode) => file.removeIf((pending) => pending.device_code === deviceCode),+ }+}diff --git a/cli/src/call/execute.test.ts b/cli/src/call/execute.test.tsindex 130ecaac1d6..889fd6fcff4 100644--- a/cli/src/call/execute.test.ts+++ b/cli/src/call/execute.test.ts@@ -148,10 +148,28 @@ it('a paused run is exit 0 with status suspended and the server hints', async ()expect(await (await w.ctx.get(commands)).run()).toBe(0)expect(JSON.parse(w.io.outBuf())).toMatchObject({status: 'suspended',+ run_id: 'wf-run-hitl-1',hints: [{ op: 'submit.run.form', input: { form_token: 'ft-hitl-1', action: 'submit' } }],})})+it('a form submit prints the hint to follow the run', async () => {+ const w = await world([+ 'submit',+ 'run',+ 'form',+ '--input',+ '{"app_id":"app-2","form_token":"ft-hitl-1","action":"submit","inputs":{"name":"Bob"}}',+ ])+ expect(await (await w.ctx.get(commands)).run()).toBe(0)+ expect(JSON.parse(w.io.outBuf()).hints).toEqual([+ expect.objectContaining({+ op: 'get.run.event',+ input: { app_id: 'app-2', task_id: 'wf-run-hitl-1', continue_on_pause: false },+ }),+ ])+})+it('a stale catalog is refreshed once and the op is retried', async () => {const w = await world(['help'])await (await w.ctx.get(commands)).run()diff --git a/cli/src/call/execute.ts b/cli/src/call/execute.tsindex d8eeea35205..3e03d98e2d3 100644--- a/cli/src/call/execute.ts+++ b/cli/src/call/execute.ts@@ -7,17 +7,17 @@ import { unsupportedFlags } from '@/call/flags'import { applyPins, loadInput, resolveFileRefs } from '@/call/input'import { rendererFor } from '@/call/render/index'import { buildRequest } from '@/call/request'-import { validateInput } from '@/call/validate'import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { runSignal } from '@/plugins/commands/cancel'-import { helpHint, Outcome } from '@/plugins/commands/command'+import { assertValidInput, Outcome } from '@/plugins/commands/command'import { http } from '@/plugins/http'import { io } from '@/plugins/io'import { session } from '@/plugins/session'import { KIND } from '@/protocol/kinds'-import { spacedId } from '@/protocol/op-id'+import { commandWords } from '@/protocol/op-id'import { PIN } from '@/protocol/pins'+import { flagToken } from '@/util/flag-name'/** One catalog operation, its call flags, and the fields typed as flags of their own. */export type CallRequest = Readonly<{@@ -36,7 +36,7 @@ function assertSupportedFlags(kind: string, flags: CallFlags): void {if (refused !== undefined) {throw new BaseError({code: ErrorCode.UsageInvalidFlag,- message: `--${refused} is not supported by ${kind} operations`,+ message: `${flagToken(refused)} is not supported by ${kind} operations`,})}// --only filters the events --stream emits; on its own it filters nothing.@@ -51,18 +51,6 @@ async function readAll(stream: NodeJS.ReadableStream): Promise<string> {return text}-function assertValidInput(op: CatalogOp, opId: string, input: Record<string, unknown>): void {- const details = validateInput(op.input, input)- if (details.length === 0) return- throw new BaseError({- code: ErrorCode.InputInvalid,- message: `invalid input for "${opId}"`,- hint: helpHint(spacedId(opId)),- details: [...details],- schema: op.input,- })-}-export async function executeCall(req: CallRequest, ctx: CommandContext): Promise<Outcome> {assertSupportedFlags(req.op.kind, req.flags)@@ -75,7 +63,7 @@ export async function executeCall(req: CallRequest, ctx: CommandContext): Promisconst fields = await resolveFileRefs(req.fields, req.op.input, source)const workspaceId = await (await ctx.get(session)).workspaceId()const body = applyPins({ ...whole, ...fields }, req.op.input, { [PIN.Workspace]: workspaceId })- assertValidInput(req.op, req.id, body)+ assertValidInput({ command: commandWords(req.id), schema: req.op.input, input: body })if (req.op.deprecated) out.notice(`${DEPRECATED_NOTICE}: ${req.id}`)diff --git a/cli/src/call/fold.test.ts b/cli/src/call/fold.test.tsindex d0aac2c0e07..69cdc284c15 100644--- a/cli/src/call/fold.test.ts+++ b/cli/src/call/fold.test.ts@@ -91,3 +91,18 @@ it('copies server hints from a pause and suspends; a pause without hints is stil])expect(bare.result).toEqual({ status: 'suspended', text: { answer: '' }, hints: [] })})++it('keeps the run id from any event, even one it has no handler for', () => {+ const { result, code } = run([+ ['workflow_started', { workflow_run_id: 'run-1', data: { id: 'run-1' } }],+ ['human_input_required', { workflow_run_id: 'run-1', hints: [] }],+ ['workflow_paused', { workflow_run_id: 'run-1' }],+ ])+ expect(result).toMatchObject({ status: 'suspended', run_id: 'run-1' })+ expect(code).toBe(0)+})++it('ignores a run id that is not a string', () => {+ const { result } = run([['some_future_event', { workflow_run_id: 42 }]])+ expect(result).not.toHaveProperty('run_id')+})diff --git a/cli/src/call/fold.ts b/cli/src/call/fold.tsindex 2c1a359ad1a..85266b3ebca 100644--- a/cli/src/call/fold.ts+++ b/cli/src/call/fold.ts@@ -1,15 +1,15 @@import type { ExitCodeValue } from '@/errors/codes'import type { FoldResult } from '@/protocol/fold'import { ExitCode } from '@/errors/codes'-import { FOLD_STATUS, FOLD_TABLE } from '@/protocol/fold'+import { FOLD_STATUS, FOLD_TABLE, foldAnyEvent } from '@/protocol/fold'export function newFoldResult(): FoldResult {return { status: FOLD_STATUS.Incomplete, text: { answer: '' }, hints: [] }}export function foldEvent(result: FoldResult, name: string, event: Record<string, unknown>): void {- const handler = FOLD_TABLE[name]- if (handler !== undefined) handler(result, event)+ foldAnyEvent(result, event)+ FOLD_TABLE[name]?.(result, event)}export function finishFold(result: FoldResult): FoldResult {diff --git a/cli/src/call/input.ts b/cli/src/call/input.tsindex 607fe9a7626..ea68ff9c930 100644--- a/cli/src/call/input.ts+++ b/cli/src/call/input.ts@@ -1,7 +1,9 @@import type { JsonSchema } from '@/plugins/catalog'import { inputInvalid } from '@/call/errors'+import { CALL_FLAG } from '@/call/flags'import { errorMessage } from '@/errors/message'import { isScalar, propertiesOf, shapeOf } from '@/protocol/shape'+import { flagToken } from '@/util/flag-name'import { isRecord } from '@/util/is-record'export type InputSource = {@@ -18,8 +20,7 @@ type Referenced = Readonly<{ text: string; source: string }>const FILE_PREFIX = '@'const STDIN_MARKER = '-'const STDIN_SOURCE = `${FILE_PREFIX}${STDIN_MARKER}`-const FLAG_PREFIX = '--'-const INLINE_SOURCE = '--input'+const INLINE_SOURCE = flagToken(CALL_FLAG.Input)const STDIN_LABEL = 'stdin'export function parseJsonValue(raw: string, source: string): unknown {@@ -69,7 +70,7 @@ export async function resolveFileRefs(if (typeof value !== 'string' || !value.startsWith(FILE_PREFIX)) continueif (isScalar(shapeOf(property))) continueconst { text } = await readRef(value, src)- resolved[name] = parseJsonValue(text, `${FLAG_PREFIX}${name}`)+ resolved[name] = parseJsonValue(text, flagToken(name))}return resolved}diff --git a/cli/src/call/render/file.ts b/cli/src/call/render/file.tsindex a23e7e4e812..cb21ca294e5 100644--- a/cli/src/call/render/file.ts+++ b/cli/src/call/render/file.ts@@ -1,12 +1,18 @@import type { Renderer } from './index'import { writeFile } from 'node:fs/promises'-import { join } from 'node:path'-import { unknownError } from '@/errors/base'+import { join, posix } from 'node:path'+import { CALL_FLAG } from '@/call/flags'+import { BaseError, unknownError } from '@/errors/base'+import { ErrorCode } from '@/errors/codes'import { renderJson } from './object'const CONTENT_DISPOSITION_HEADER = 'content-disposition'const CONTENT_TYPE_HEADER = 'content-type'const UNKNOWN_EXTENSION = 'bin'+const EEXIST = 'EEXIST'+// A name the server picked never replaces a file; a path the caller named does.+const CREATE_ONLY = 'wx'+const CREATE_OR_REPLACE = 'w'const EXTENSIONS: Readonly<Record<string, string>> = {'application/json': 'json',@@ -21,10 +27,18 @@ const EXTENSIONS: Readonly<Record<string, string>> = {const QUOTED_FILENAME = /filename="([^"]+)"/const BARE_FILENAME = /filename=([^;]+)/+const NOT_A_FILE_NAME: readonly string[] = ['', '.', '..']++// Only the last part of the server's name is used, so the file stays in the folder.+function baseName(raw: string | undefined): string | undefined {+ if (raw === undefined) return undefined+ const name = posix.basename(raw.replaceAll('\\', '/'))+ return NOT_A_FILE_NAME.includes(name) ? undefined : name+}function filenameFromContentDisposition(value: string | null): string | undefined {if (value === null) return undefined- return QUOTED_FILENAME.exec(value)?.[1] ?? BARE_FILENAME.exec(value)?.[1]?.trim()+ return baseName(QUOTED_FILENAME.exec(value)?.[1] ?? BARE_FILENAME.exec(value)?.[1]?.trim())}function extensionOf(contentType: string | null): string {@@ -39,10 +53,18 @@ export const fileRenderer: Renderer = async (res, io, options, opId) => {filenameFromContentDisposition(res.headers.get(CONTENT_DISPOSITION_HEADER)) ??`${opId}.${extensionOf(contentType)}`const path = options.output ?? join(process.cwd(), filename)+ const flag = options.output === undefined ? CREATE_ONLY : CREATE_OR_REPLACEtry {- await writeFile(path, bytes)+ await writeFile(path, bytes, { flag })} catch (cause) {+ if ((cause as NodeJS.ErrnoException).code === EEXIST)+ throw new BaseError({+ code: ErrorCode.UsageMissingArg,+ message: `${path} already exists; not overwriting it`,+ hint: `pass --${CALL_FLAG.Output} <path> to choose where to save it`,+ cause,+ })throw unknownError(`failed to write file: ${path}`, cause)}diff --git a/cli/src/call/render/render.test.ts b/cli/src/call/render/render.test.tsindex 40fa8f253ab..dafa530f272 100644--- a/cli/src/call/render/render.test.ts+++ b/cli/src/call/render/render.test.ts@@ -1,6 +1,6 @@import type { CallFlags } from '@/call/flags'import { Buffer } from 'node:buffer'-import { mkdtempSync, readFileSync } from 'node:fs'+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { expect, it } from 'vite-plus/test'@@ -138,3 +138,81 @@ it('file names an unnamed download after the op and its content type', async ()process.chdir(cwd)}})++it.each([+ ['../../escape.txt', 'escape.txt'],+ ['/etc/passwd', 'passwd'],+ ['..\\..\\win.txt', 'win.txt'],+ ['..', `${OP_ID}.txt`],+ ['dir/', 'dir'],+])('file keeps only the base name of the server filename %s', async (sent, kept) => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))+ const cwd = process.cwd()+ process.chdir(dir)+ const here = process.cwd()+ try {+ const r = render(+ 'file',+ new Response('x', {+ headers: {+ 'content-type': 'text/plain',+ 'content-disposition': `attachment; filename="${sent}"`,+ },+ }),+ )+ await r.code+ expect(JSON.parse(r.buf.outBuf())).toMatchObject({ path: join(here, kept) })+ expect(readFileSync(join(here, kept), 'utf8')).toBe('x')+ } finally {+ process.chdir(cwd)+ }+})++it('file refuses to overwrite an existing file it named itself, and keeps the old bytes', async () => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))+ const cwd = process.cwd()+ process.chdir(dir)+ const here = join(process.cwd(), 'r.txt')+ writeFileSync(here, 'old')+ try {+ const r = render(+ 'file',+ new Response('new', {+ headers: {+ 'content-type': 'text/plain',+ 'content-disposition': 'attachment; filename="r.txt"',+ },+ }),+ )+ await expect(r.code).rejects.toMatchObject({+ code: 'usage_missing_arg',+ message: `${here} already exists; not overwriting it`,+ hint: 'pass --output <path> to choose where to save it',+ })+ expect(readFileSync(here, 'utf8')).toBe('old')+ expect(r.buf.outBuf()).toBe('')+ } finally {+ process.chdir(cwd)+ }+})++it('file overwrites an existing file when --output names it', async () => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))+ const out = join(dir, 'z.txt')+ writeFileSync(out, 'old')+ const r = render('file', new Response('new', { headers: { 'content-type': 'text/plain' } }), {+ output: out,+ })+ await r.code+ expect(readFileSync(out, 'utf8')).toBe('new')+})++it('file reports other write failures as a failed write, not an existing file', async () => {+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))+ const out = join(dir, 'missing', 'z.txt')+ const r = render('file', new Response('x'), { output: out })+ await expect(r.code).rejects.toMatchObject({+ code: 'unknown',+ message: `failed to write file: ${out}`,+ })+})diff --git a/cli/src/call/validate.ts b/cli/src/call/validate.tsindex 0036e8274f8..4f4ccacdee5 100644--- a/cli/src/call/validate.ts+++ b/cli/src/call/validate.ts@@ -21,17 +21,21 @@ function compile(schema: JsonSchema): ValidateFunction {return validate}-function locFor(error: ErrorObject): (string | number)[] {- const loc = error.instancePath.split('/').filter(Boolean)- if (error.keyword === 'required') {- const missingProperty = (error.params as { missingProperty?: string }).missingProperty- if (missingProperty !== undefined) loc.push(missingProperty)- }- return loc+const INSTANCE_PATH_SEPARATOR = '/'++// Errors that name a field: the ajv param holding the name, and the message to show.+const FIELD_ERRORS: Readonly<Record<string, Readonly<{ param: string; msg: string }>>> = {+ required: { param: 'missingProperty', msg: 'required' },+ additionalProperties: { param: 'additionalProperty', msg: 'unknown field' },}function toDetail(error: ErrorObject): ValidationDetail {- return { type: error.keyword, loc: locFor(error), msg: error.message ?? error.keyword }+ const reading = FIELD_ERRORS[error.keyword]+ const loc: (string | number)[] = error.instancePath.split(INSTANCE_PATH_SEPARATOR).filter(Boolean)+ const named =+ reading === undefined ? undefined : (error.params as Record<string, unknown>)[reading.param]+ if (typeof named === 'string') loc.push(named)+ return { type: error.keyword, loc, msg: reading?.msg ?? error.message ?? error.keyword }}export function validateInput(schema: JsonSchema, input: unknown): readonly ValidationDetail[] {diff --git a/cli/src/commands/get/skills/index.ts b/cli/src/commands/get/skills/index.tsdeleted file mode 100644index 2fc0c8f27f4..00000000000--- a/cli/src/commands/get/skills/index.ts+++ /dev/null@@ -1,16 +0,0 @@-import { z } from 'zod'-import { Command } from '@/plugins/commands/command'-import { loadSkills } from '@/skills/collection'-import { FROM_FIELD, openSource } from '@/skills/source'--const INPUT = z.object({ from: FROM_FIELD })--export default class SkillsList extends Command<typeof INPUT> {- static override summary = 'List the skills in the collection'- static override input = INPUT-- async run(input: z.infer<typeof INPUT>) {- const skills = await loadSkills(await openSource(input.from))- return { skills: skills.map(({ name, description }) => ({ name, description })) }- }-}diff --git a/cli/src/commands/install/skills/index.test.ts b/cli/src/commands/install/skills/index.test.tsindex 17cf0630cd5..67c3b840e13 100644--- a/cli/src/commands/install/skills/index.test.ts+++ b/cli/src/commands/install/skills/index.test.ts@@ -1,23 +1,20 @@import type { TestWorld } from '@test/fixtures/kernel'import { readFile } from 'node:fs/promises'import { join } from 'node:path'-import { fileURLToPath } from 'node:url'import { testContext } from '@test/fixtures/kernel'import { afterEach, expect, it } from 'vite-plus/test'import { commands } from '@/plugins/commands'-const REPO_SKILLS = fileURLToPath(new URL('../../../../../skills', import.meta.url))-const worlds: TestWorld[] = []afterEach(async () => {for (const w of worlds.splice(0)) await w.stop()})-it('writes the repo skills into the given skills root', async () => {+it('writes the difyctl skill into the given skills root', async () => {const seed = await testContext({ login: false })worlds.push(seed)const dir = join(seed.dir, 'target')- const argv = ['install', 'skills', dir, '--from', REPO_SKILLS]+ const argv = ['install', 'skills', dir]const w = await testContext({ login: false, argv, reuseDirOf: seed })worlds.push(w)expect(await (await w.ctx.get(commands)).run()).toBe(0)diff --git a/cli/src/commands/install/skills/index.ts b/cli/src/commands/install/skills/index.tsindex cb9a62ee6eb..95bc788f1a1 100644--- a/cli/src/commands/install/skills/index.ts+++ b/cli/src/commands/install/skills/index.ts@@ -1,8 +1,7 @@import { resolve } from 'node:path'import { z } from 'zod'import { Command } from '@/plugins/commands/command'-import { loadSkills } from '@/skills/collection'-import { installSkills, selectSkills } from '@/skills/install'+import { installSkill } from '@/skills/install'import { FROM_FIELD, openSource } from '@/skills/source'const INPUT = z.object({@@ -10,26 +9,19 @@ const INPUT = z.object({.string().min(1).describe("The agent's skills root: the folder that holds one subfolder per skill"),- skill: z- .array(z.string())- .default([])- .describe('Skill to install (repeatable); default: the whole collection'),from: FROM_FIELD,})export default class SkillsInstall extends Command<typeof INPUT> {- static override summary = 'Write skills from the collection into a skills root'+ static override summary = 'Write the difyctl skill into a skills root'static override effect = 'write' as conststatic override input = INPUTstatic override positional = ['dir'] as conststatic override examples = [- { title: 'Install every skill for Claude Code', input: { dir: '~/.claude/skills' } },- { title: 'Install one skill for Codex', input: { dir: '~/.codex/skills', skill: ['difyctl'] } },+ { title: 'Install the skill for Claude Code', input: { dir: '~/.claude/skills' } },]async run(input: z.infer<typeof INPUT>) {- const source = await openSource(input.from)- const skills = selectSkills(await loadSkills(source), input.skill)- return { wrote: await installSkills(resolve(input.dir), skills, source) }+ return { wrote: await installSkill(resolve(input.dir), await openSource(input.from)) }}}diff --git a/cli/src/commands/login/index.test.ts b/cli/src/commands/login/index.test.tsindex 46f2bc32966..a62cbb7991e 100644--- a/cli/src/commands/login/index.test.ts+++ b/cli/src/commands/login/index.test.ts@@ -1,6 +1,10 @@import type { TestWorld } from '@test/fixtures/kernel'+import { existsSync, readFileSync, writeFileSync } from 'node:fs'+import { join } from 'node:path'import { testContext } from '@test/fixtures/kernel'import { afterEach, expect, it } from 'vite-plus/test'+import { PENDING_FILE_NAME } from '@/auth/pending-login'+import { Context } from '@/kernel/context'import { commands } from '@/plugins/commands'import { session } from '@/plugins/session'import { token } from '@/plugins/token'@@ -95,3 +99,163 @@ it('falls back to the external-SSO subject email when there is no account', asynexpect(login?.email).toBe('[email protected]')expect(login?.account).toBeNull()})++it('resume with no pending login reports the saved login', async () => {+ const w = await testContext({ login: true, argv: ['login', '--resume'] })+ worlds.push(w)+ expect(await (await w.ctx.get(commands)).run()).toBe(0)+ expect(JSON.parse(w.io.outBuf())).toMatchObject({+ server: w.mock.url,+ email: 'me@x',+ workspace_id: 'ws-1',+ })+})++it('resume with no pending login and no saved login is not_logged_in', async () => {+ const w = await testContext({ login: false, argv: ['login', '--resume'] })+ worlds.push(w)+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({+ code: 'not_logged_in',+ message: `not logged in: no login saved in ${w.dir}; DIFY_CONFIG_DIR picks this folder`,+ })+})++it('resume with no pending login and the token gone is not_logged_in', async () => {+ const w = await testContext({ login: true, argv: ['login', '--resume'] })+ worlds.push(w)+ const fresh = new Context()+ const login = await (await fresh.get(session)).require()+ await (await fresh.get(token)).remove(login)+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({ code: 'not_logged_in' })+})++it('resume under an env login reports the env login', async () => {+ const w = await testContext({ login: false, env: true, argv: ['login', '--resume'] })+ worlds.push(w)+ expect(await (await w.ctx.get(commands)).run()).toBe(0)+ expect(JSON.parse(w.io.outBuf())).toMatchObject({ server: w.mock.url, email: 'env' })+})++it('a new login drops a pending --no-wait login', async () => {+ const seed = await testContext({ login: false })+ worlds.push(seed)+ const pendingFile = join(seed.dir, PENDING_FILE_NAME)+ writeFileSync(+ pendingFile,+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: stale\n`,+ )+ const w = await testContext({+ login: false,+ argv: ['login', '--server', seed.mock.url, '--no-browser', '--no-keyring', '--insecure'],+ reuseDirOf: seed,+ })+ worlds.push(w)+ expect(await (await w.ctx.get(commands)).run()).toBe(0)+ expect(existsSync(pendingFile)).toBe(false)+})++it.each([[[]], [['--server', ' ']]])(+ 'refuses to start without a server, keeping a pending login',+ async (flags) => {+ const seed = await testContext({ login: false })+ worlds.push(seed)+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)+ writeFileSync(+ pendingPath,+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: kept\n`,+ )+ const w = await testContext({+ login: false,+ argv: ['login', '--no-wait', ...flags],+ reuseDirOf: seed,+ })+ worlds.push(w)+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({+ code: 'usage_missing_arg',+ hint: 'ask the user which server; Dify Cloud is https://cloud.dify.ai',+ })+ expect(existsSync(pendingPath)).toBe(true)+ },+)++it('keeps a pending login when the new --server is rejected', async () => {+ const seed = await testContext({ login: false })+ worlds.push(seed)+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)+ writeFileSync(+ pendingPath,+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: kept\n`,+ )+ const w = await testContext({+ login: false,+ argv: ['login', '--server', 'http://plain.example.com', '--no-wait'],+ reuseDirOf: seed,+ })+ worlds.push(w)+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({+ code: 'usage_invalid_flag',+ })+ expect(existsSync(pendingPath)).toBe(true)+})++it('resume under an env login refuses a pending login before polling', async () => {+ const seed = await testContext({ login: false, env: true })+ worlds.push(seed)+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)+ writeFileSync(+ pendingPath,+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: kept\n`,+ )+ const w = await testContext({+ login: false,+ env: true,+ argv: ['login', '--resume'],+ reuseDirOf: seed,+ })+ worlds.push(w)+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({+ code: 'usage_invalid_flag',+ message: 'unset DIFY_TOKEN to log in interactively',+ })+ expect(existsSync(pendingPath)).toBe(true)+})++it.each(['happy', 'denied', 'expired'] as const)(+ 'resume (%s) leaves a pending login another process saved meanwhile',+ async (scenario) => {+ const seed = await testContext({ login: false })+ worlds.push(seed)+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)+ const pendingFor = (code: string) =>+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: ${code}\n`+ writeFileSync(pendingPath, pendingFor('dc-1'))+ seed.mock.setScenario(scenario)+ seed.mock.onDeviceTokenPoll(() => writeFileSync(pendingPath, pendingFor('dc-2')))+ const w = await testContext({ login: false, argv: ['login', '--resume'], reuseDirOf: seed })+ worlds.push(w)++ await (await w.ctx.get(commands)).run().catch(() => undefined)++ expect(readFileSync(pendingPath, 'utf8')).toContain('device_code: dc-2')+ },+)++it.each(['happy', 'denied', 'expired'] as const)(+ 'resume (%s) clears its own pending login',+ async (scenario) => {+ const seed = await testContext({ login: false })+ worlds.push(seed)+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)+ writeFileSync(+ pendingPath,+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: dc-1\n`,+ )+ seed.mock.setScenario(scenario)+ const w = await testContext({ login: false, argv: ['login', '--resume'], reuseDirOf: seed })+ worlds.push(w)++ await (await w.ctx.get(commands)).run().catch(() => undefined)++ expect(existsSync(pendingPath)).toBe(false)+ },+)diff --git a/cli/src/commands/login/index.ts b/cli/src/commands/login/index.tsindex f061a734177..c8a2e2a270c 100644--- a/cli/src/commands/login/index.ts+++ b/cli/src/commands/login/index.ts@@ -1,24 +1,28 @@import type { PollSuccess } from '@/auth/device-api'+import type { Pending, PendingLoginStore } from '@/auth/pending-login'import type { CommandContext } from '@/plugins/base'+import type { Login as SavedLogin } from '@/plugins/session'import { hostname } from 'node:os'-import { join } from 'node:path'import { z } from 'zod'import { deviceApi } from '@/auth/device-api'import { awaitAuthorization, pollAuthorization, realClock } from '@/auth/device-flow'import { assertNotEnvLogin, revokeAndClearSession } from '@/auth/logout'+import { pendingLoginStore } from '@/auth/pending-login'import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { Command } from '@/plugins/commands/command'-import { env } from '@/plugins/env'import { io } from '@/plugins/io'import { session } from '@/plugins/session'-import { token } from '@/plugins/token'-import { YamlStore } from '@/store/store'+import { token, TOKENS_FILE_NAME } from '@/plugins/token'import { decideOpen, OpenDecision, openUrl, realEnv } from '@/util/browser'-import { DEFAULT_HOST, resolveHost, validateVerificationURI } from '@/util/host'+import { resolveHost, validateVerificationURI } from '@/util/host'const INPUT = z.object({- server: z.string().default(DEFAULT_HOST).describe('Dify server base URL'),+ server: z+ .string()+ .trim()+ .optional()+ .describe('Dify server base URL. Required to start a login; there is no default'),no_browser: z.boolean().default(false)@@ -27,7 +31,7 @@ const INPUT = z.object({.boolean().default(false).describe(- 'Keep the token in tokens.yml under the config dir instead of the OS keyring. Use in a sandbox, with DIFY_CONFIG_DIR on persistent storage',+ `Keep the token in ${TOKENS_FILE_NAME} under the config dir instead of the OS keyring. Use in a sandbox, with DIFY_CONFIG_DIR on persistent storage`,),insecure: z.boolean()@@ -41,24 +45,17 @@ const INPUT = z.object({.boolean().default(false).describe(- 'Check a login started with --no-wait once. Prints status pending until the user approves',+ 'Check a login started with --no-wait once. Prints status pending until the user approves. With no pending login, prints the saved login, or fails with not_logged_in',),})-const PENDING_FILE_NAME = 'login-pending.yml'const PENDING_STATUS = 'pending'-const PENDING_SCHEMA = z.object({- server: z.string(),- insecure: z.boolean(),- no_keyring: z.boolean(),- device_code: z.string(),-})-type Pending = z.infer<typeof PENDING_SCHEMA>-const NO_PENDING_MESSAGE = 'no pending login; start one with login --no-wait'const FINAL_POLL_ERRORS: readonly string[] = [ErrorCode.AuthExpired, ErrorCode.AccessDenied]const ENV_LOGIN_MESSAGE = 'unset DIFY_TOKEN to log in interactively'const NO_EMAIL_MESSAGE = 'login response carries no account or subject email'+const NO_SERVER_MESSAGE = 'pass --server <url>: the Dify server to log in to'+const NO_SERVER_HINT = 'ask the user which server; Dify Cloud is https://cloud.dify.ai'// A present-but-empty email is the same as absent: neither account.email nor// subject_email is meaningful until it has a value.@@ -68,39 +65,44 @@ function meaningfulEmail(value: string | undefined): string | undefined {export default class Login extends Command<typeof INPUT> {static override summary =- 'Log in via the OAuth device flow. Blocks until approval: run it in the background, never cancel it'+ 'Log in via the OAuth device flow. Agents: use --no-wait, then --resume after the user approves'static override effect = 'write' as conststatic override input = INPUTstatic override examples = [{- title: 'Agent: run in the background, relay the url and code to the user, do not cancel',- input: { server: 'https://dify.example.com', no_browser: true },+ title: 'Agent: start without waiting, give the user the url and code, then end the turn',+ input: { server: 'https://dify.example.com', no_browser: true, no_wait: true },},{title: 'Agent in a sandbox: add --no-keyring and point DIFY_CONFIG_DIR at persistent storage',- input: { server: 'https://dify.example.com', no_browser: true, no_keyring: true },- },- {- title: 'Agent that cannot keep a process alive: start without waiting',- input: { server: 'https://dify.example.com', no_browser: true, no_wait: true },+ input: {+ server: 'https://dify.example.com',+ no_browser: true,+ no_wait: true,+ no_keyring: true,+ },},{- title: 'Then, after the user approves, finish the login (repeat while status is pending)',+ title: 'Finish a --no-wait login once the user says they approved',input: { resume: true },},]async run(input: z.infer<typeof INPUT>, ctx: CommandContext) {+ const pendingLogin = await pendingLoginStore(ctx)+ if (input.resume) return resume(ctx, pendingLogin)+const sessionService = await ctx.get(session)assertNotEnvLogin(sessionService.fromEnv, ENV_LOGIN_MESSAGE)-- const { configDir } = await ctx.get(env)- const pendingStore = new YamlStore(join(configDir, PENDING_FILE_NAME))- if (input.resume) return resume(ctx, pendingStore)+ if (input.server === undefined || input.server === '')+ throw new BaseError({+ code: ErrorCode.UsageMissingArg,+ message: NO_SERVER_MESSAGE,+ hint: NO_SERVER_HINT,+ })const server = resolveHost({ raw: input.server, insecure: input.insecure })const streams = await ctx.get(io)-const current = await sessionService.current()if (current !== null) {await revokeAndClearSession(ctx, current)@@ -125,7 +127,7 @@ export default class Login extends Command<typeof INPUT> {device_code: code.device_code,}if (input.no_wait) {- await pendingStore.setTyped(pending)+ await pendingLogin.save(pending)return {status: PENDING_STATUS,verification_uri: code.verification_uri,@@ -134,28 +136,47 @@ export default class Login extends Command<typeof INPUT> {}}+ await pendingLogin.clear()const success = await awaitAuthorization(api, code, { clock: realClock() })return finish(ctx, pending, success)}}-async function resume(ctx: CommandContext, pendingStore: YamlStore) {- const parsed = PENDING_SCHEMA.safeParse(await pendingStore.getTyped<unknown>())- if (!parsed.success) {- throw new BaseError({ code: ErrorCode.UsageInvalidFlag, message: NO_PENDING_MESSAGE })+function loginReport(login: SavedLogin) {+ return {+ server: login.server,+ email: login.email,+ account: login.account,+ workspace_id: login.workspaceId,+ }+}++// `get` throws not_logged_in when the saved login's token is gone from the store.+async function assertTokenSaved(ctx: CommandContext): Promise<void> {+ await (await ctx.get(token)).get()+}++async function resume(ctx: CommandContext, pendingLogin: PendingLoginStore) {+ const sessionService = await ctx.get(session)+ const pending = await pendingLogin.read()+ if (pending === null) {+ const current = await sessionService.require()+ await assertTokenSaved(ctx)+ return loginReport(current)}- const pending = parsed.data+ assertNotEnvLogin(sessionService.fromEnv, ENV_LOGIN_MESSAGE)const api = deviceApi(pending.server, { insecure: pending.insecure })let success: PollSuccess | undefinedtry {success = await pollAuthorization(api, pending.device_code, { clock: realClock() })} catch (err) {- if (err instanceof BaseError && FINAL_POLL_ERRORS.includes(err.code)) await pendingStore.rm()+ if (err instanceof BaseError && FINAL_POLL_ERRORS.includes(err.code))+ await pendingLogin.clearIf(pending.device_code)throw err}if (success === undefined) return { status: PENDING_STATUS }const result = await finish(ctx, pending, success)- await pendingStore.rm()+ await pendingLogin.clearIf(pending.device_code)return result}@@ -168,7 +189,7 @@ async function finish(ctx: CommandContext, pending: Pending, success: PollSuccesthrow new BaseError({ code: ErrorCode.ServerError, message: NO_EMAIL_MESSAGE })}- const login = {+ const login: SavedLogin = {server: pending.server,email,account: success.account ?? null,@@ -179,11 +200,5 @@ async function finish(ctx: CommandContext, pending: Pending, success: PollSuccesawait sessionService.save(login)await tokenService.write(login, success.token)-- return {- server: pending.server,- email,- account: login.account,- workspace_id: login.workspaceId,- }+ return loginReport(login)}diff --git a/cli/src/commands/logout/index.test.ts b/cli/src/commands/logout/index.test.tsindex 7f33606f9de..7646ddeab76 100644--- a/cli/src/commands/logout/index.test.ts+++ b/cli/src/commands/logout/index.test.ts@@ -1,8 +1,9 @@import type { TestWorld } from '@test/fixtures/kernel'-import { existsSync, readdirSync } from 'node:fs'+import { existsSync, readdirSync, writeFileSync } from 'node:fs'import { join } from 'node:path'import { testContext } from '@test/fixtures/kernel'import { afterEach, expect, it } from 'vite-plus/test'+import { PENDING_FILE_NAME } from '@/auth/pending-login'import { Context } from '@/kernel/context'import { commands } from '@/plugins/commands'import { session } from '@/plugins/session'@@ -32,6 +33,24 @@ it('revokes the session on the server and clears local state', async () => {})})+it('drops a pending --no-wait login', async () => {+ const w = await testContext({ login: true, argv: ['logout'] })+ worlds.push(w)+ const pendingFile = join(w.dir, PENDING_FILE_NAME)+ writeFileSync(pendingFile, 'device_code: stale\n')+ expect(await (await w.ctx.get(commands)).run()).toBe(0)+ expect(existsSync(pendingFile)).toBe(false)+})++it('drops a pending --no-wait login when nobody is logged in', async () => {+ const w = await testContext({ login: false, argv: ['logout'] })+ worlds.push(w)+ const pendingFile = join(w.dir, PENDING_FILE_NAME)+ writeFileSync(pendingFile, 'device_code: stale\n')+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({ code: 'not_logged_in' })+ expect(existsSync(pendingFile)).toBe(false)+})+it('still clears local state and reports a failed server revoke', async () => {const w = await testContext({ login: true, argv: ['logout'] })worlds.push(w)@@ -54,3 +73,14 @@ it('refuses under an env login', async () => {message: 'nothing to log out: the login comes from DIFY_TOKEN',})})++it('refuses under an env login without dropping a pending interactive login', async () => {+ const w = await testContext({ login: false, env: true, argv: ['logout'] })+ worlds.push(w)+ const pendingFile = join(w.dir, PENDING_FILE_NAME)+ writeFileSync(pendingFile, 'device_code: dc-1\n')+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({+ code: 'usage_invalid_flag',+ })+ expect(existsSync(pendingFile)).toBe(true)+})diff --git a/cli/src/commands/logout/index.ts b/cli/src/commands/logout/index.tsindex 74d8691524b..20166d3f42b 100644--- a/cli/src/commands/logout/index.ts+++ b/cli/src/commands/logout/index.ts@@ -1,6 +1,7 @@import type { CommandContext } from '@/plugins/base'import { z } from 'zod'import { assertNotEnvLogin, revokeAndClearSession } from '@/auth/logout'+import { pendingLoginStore } from '@/auth/pending-login'import { Command } from '@/plugins/commands/command'import { session } from '@/plugins/session'@@ -15,9 +16,10 @@ export default class Logout extends Command<typeof INPUT> {async run(_input: z.infer<typeof INPUT>, ctx: CommandContext) {const sessionService = await ctx.get(session)- const login = await sessionService.require()+ // Refuse before touching anything: an env login must leave a pending interactive login alone.assertNotEnvLogin(sessionService.fromEnv, ENV_LOGOUT_MESSAGE)-+ await (await pendingLoginStore(ctx)).clear()+ const login = await sessionService.require()await revokeAndClearSession(ctx, login)return { logged_out: true, server: login.server }diff --git a/cli/src/commands/tree.generated.ts b/cli/src/commands/tree.generated.tsindex 53e89bf67a0..b0de87cb267 100644--- a/cli/src/commands/tree.generated.ts+++ b/cli/src/commands/tree.generated.ts@@ -4,7 +4,6 @@import type { CommandTree } from '@/plugins/commands/registry'import DeleteCache from '@/commands/delete/cache/index'import GetConfig from '@/commands/get/config/index'-import GetSkills from '@/commands/get/skills/index'import InstallSkills from '@/commands/install/skills/index'import Login from '@/commands/login/index'import Logout from '@/commands/logout/index'@@ -23,7 +22,6 @@ export const commandTree: CommandTree = {get: {subcommands: {config: { command: GetConfig, subcommands: {} },- skills: { command: GetSkills, subcommands: {} },},},install: {diff --git a/cli/src/commands/use/workspace/index.test.ts b/cli/src/commands/use/workspace/index.test.tsindex c12953eadb1..26b131b567f 100644--- a/cli/src/commands/use/workspace/index.test.ts+++ b/cli/src/commands/use/workspace/index.test.ts@@ -1,6 +1,8 @@import type { TestWorld } from '@test/fixtures/kernel'+import type { BaseError } from '@/errors/base'import { testContext } from '@test/fixtures/kernel'import { afterEach, expect, it } from 'vite-plus/test'+import { ExitCode } from '@/errors/codes'import { commands } from '@/plugins/commands'import { ENV } from '@/plugins/env'import { session } from '@/plugins/session'@@ -10,13 +12,28 @@ afterEach(async () => {for (const w of worlds.splice(0)) await w.stop()})-it('pins the workspace locally without a server call', async () => {- const w = await testContext({ login: true, argv: ['use', 'workspace', 'ws-9'] })+it('pins a workspace the account belongs to and names it', async () => {+ const w = await testContext({ login: true, argv: ['use', 'workspace', 'ws-2'] })+ worlds.push(w)+ expect(await (await w.ctx.get(commands)).run()).toBe(0)+ expect(JSON.parse(w.io.outBuf())).toEqual({ workspace_id: 'ws-2', name: 'Other' })+ expect(await (await w.ctx.get(session)).workspaceId()).toBe('ws-2')+})++it('describe workspace with no id shows the pinned workspace', async () => {+ const w = await testContext({ login: true, argv: ['describe', 'workspace'] })worlds.push(w)expect(await (await w.ctx.get(commands)).run()).toBe(0)- expect(JSON.parse(w.io.outBuf())).toEqual({ workspace_id: 'ws-9' })- expect(await (await w.ctx.get(session)).workspaceId()).toBe('ws-9')- expect(w.mock.requestCount).toBe(0)+ expect(JSON.parse(w.io.outBuf())).toMatchObject({ id: 'ws-1', name: 'Default' })+})++it('refuses a workspace the account does not belong to and keeps the old pin', async () => {+ const w = await testContext({ login: true, argv: ['use', 'workspace', 'ws-9'] })+ worlds.push(w)+ const err = await (await w.ctx.get(commands)).run().catch((e: unknown) => e)+ expect(err).toMatchObject({ message: 'workspace not found' })+ expect((err as BaseError).exit()).toBe(ExitCode.Generic)+ expect(await (await w.ctx.get(session)).workspaceId()).toBe('ws-1')})it('refuses under an env login and without a login', async () => {diff --git a/cli/src/commands/use/workspace/index.ts b/cli/src/commands/use/workspace/index.tsindex 4a09d4fb18f..62f19f7ad61 100644--- a/cli/src/commands/use/workspace/index.ts+++ b/cli/src/commands/use/workspace/index.ts@@ -1,19 +1,27 @@import type { CommandContext } from '@/plugins/base'import { z } from 'zod'import { assertNotEnvLogin } from '@/auth/logout'+import { readLocalFile } from '@/call/files'+import { parseJsonBody } from '@/call/json-body'+import { buildRequest } from '@/call/request'import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { Command } from '@/plugins/commands/command'import { env } from '@/plugins/env'+import { http } from '@/plugins/http'import { session } from '@/plugins/session'const INPUT = z.object({ workspace_id: z.string().min(1) })+const WORKSPACE = z.object({ id: z.string(), name: z.string() })+const WORKSPACE_DESCRIBE_OP = 'describe.workspace'const ENV_WORKSPACE_ID_MESSAGE = 'DIFY_WORKSPACE_ID is set; unset it to pin locally'const ENV_LOGIN_MESSAGE = 'the login comes from DIFY_TOKEN; set DIFY_WORKSPACE_ID instead'+const MALFORMED_WORKSPACE_MESSAGE = 'describe workspace response has no id and name'export default class WorkspaceUse extends Command<typeof INPUT> {- static override summary = 'Pin the local session to a workspace'+ static override summary =+ 'Pin this device to a workspace; the web console keeps its own current workspace'static override effect = 'write' as conststatic override input = INPUTstatic override positional = ['workspace_id'] as const@@ -28,8 +36,21 @@ export default class WorkspaceUse extends Command<typeof INPUT> {const login = await sessionService.require()assertNotEnvLogin(sessionService.fromEnv, ENV_LOGIN_MESSAGE)- await sessionService.save({ ...login, workspaceId: input.workspace_id })+ // Check membership first so a mistyped id is never pinned.+ const httpService = await ctx.get(http)+ const res = await httpService.request(async (cat) =>+ buildRequest(+ cat.opOrThrow(WORKSPACE_DESCRIBE_OP),+ { workspace_id: input.workspace_id },+ { readFile: readLocalFile },+ ),+ )+ const workspace = WORKSPACE.safeParse(await parseJsonBody(res))+ if (!workspace.success)+ throw new BaseError({ code: ErrorCode.ServerError, message: MALFORMED_WORKSPACE_MESSAGE })- return { workspace_id: input.workspace_id }+ await sessionService.save({ ...login, workspaceId: workspace.data.id })++ return { workspace_id: workspace.data.id, name: workspace.data.name }}}diff --git a/cli/src/commands/workspace/_list/index.test.ts b/cli/src/commands/workspace/_list/index.test.tsdeleted file mode 100644index 97e2b3ce568..00000000000--- a/cli/src/commands/workspace/_list/index.test.ts+++ /dev/null@@ -1,36 +0,0 @@-// Skipped: `get workspace` moved out of the tree; see docs/superpowers/specs/2026-09-22-difyctl-v2-human-output-design.md-import type { TestWorld } from '@test/fixtures/kernel'-import type { BaseError } from '@/errors/base'-import { testContext } from '@test/fixtures/kernel'-import { afterEach, expect, it } from 'vite-plus/test'-import { ExitCode } from '@/errors/codes'-import { commands } from '@/plugins/commands'--const worlds: TestWorld[] = []-afterEach(async () => {- for (const w of worlds.splice(0)) await w.stop()-})--it.skip('marks the pinned workspace, exactly one true', async () => {- const w = await testContext({ login: true, argv: ['get', 'workspace'] })- worlds.push(w)- expect(await (await w.ctx.get(commands)).run()).toBe(0)- const body = JSON.parse(w.io.outBuf()) as { data: Array<{ id: string; pinned: boolean }> }- expect(body.data.length).toBeGreaterThan(0)- const pinned = body.data.filter((row) => row.pinned)- expect(pinned).toHaveLength(1)- expect(pinned[0]?.id).toBe('ws-1')-})--it.skip('a response with no data array is a server error, exit 1', async () => {- const w = await testContext({ login: true, argv: ['get', 'workspace'] })- worlds.push(w)- w.mock.setScenario('workspaces-malformed')- const err = await (await w.ctx.get(commands)).run().catch((e: unknown) => e)- expect(err).toMatchObject({- code: 'server_error',- message: 'get workspace response has no data array',- })- expect((err as BaseError).exit()).toBe(ExitCode.Generic)- expect(w.io.outBuf()).toBe('')-})diff --git a/cli/src/commands/workspace/_list/index.ts b/cli/src/commands/workspace/_list/index.tsdeleted file mode 100644index 98db0d47695..00000000000--- a/cli/src/commands/workspace/_list/index.ts+++ /dev/null@@ -1,47 +0,0 @@-import type { CommandContext } from '@/plugins/base'-import { z } from 'zod'-import { readLocalFile } from '@/call/files'-import { parseJsonBody } from '@/call/json-body'-import { buildRequest } from '@/call/request'-import { BaseError } from '@/errors/base'-import { ErrorCode } from '@/errors/codes'-import { Command } from '@/plugins/commands/command'-import { http } from '@/plugins/http'-import { session } from '@/plugins/session'-import { isRecord } from '@/util/is-record'--const INPUT = z.object({})--const WORKSPACE_LIST_OP = 'get.workspace'-const NO_DATA_ARRAY_MESSAGE = 'get workspace response has no data array'--type WorkspaceListEnvelope = {- data: readonly Record<string, unknown>[]-} & Record<string, unknown>--function asEnvelope(body: unknown): WorkspaceListEnvelope {- if (!isRecord(body) || !Array.isArray(body.data))- throw new BaseError({ code: ErrorCode.ServerError, message: NO_DATA_ARRAY_MESSAGE })- return body as WorkspaceListEnvelope-}--export default class WorkspaceList extends Command<typeof INPUT> {- static override summary = 'List the workspaces visible to the current account'- static override input = INPUT-- async run(_input: z.infer<typeof INPUT>, ctx: CommandContext) {- const httpService = await ctx.get(http)- const res = await httpService.request(async (cat) =>- buildRequest(cat.opOrThrow(WORKSPACE_LIST_OP), {}, { readFile: readLocalFile }),- )- const envelope = asEnvelope(await parseJsonBody(res))-- const sessionService = await ctx.get(session)- const pinnedId = await sessionService.workspaceId()-- return {- ...envelope,- data: envelope.data.map((row) => ({ ...row, pinned: row.id === pinnedId })),- }- }-}diff --git a/cli/src/errors/base.ts b/cli/src/errors/base.tsindex 18f313a7245..b94dba9b393 100644--- a/cli/src/errors/base.ts+++ b/cli/src/errors/base.ts@@ -1,18 +1,25 @@import type { ErrorCodeValue, ExitCodeValue } from './codes'+import type { Hint } from '@/protocol/hint'import { BINARY } from '@/version/info'import { ErrorCode, exitFor } from './codes'+export const LOC_SEPARATOR = '.'+export type ServerErrorDetail = {readonly type: stringreadonly loc?: (string | number)[]readonly msg: string}+/** A detail the CLI reports; `field` is the input as the user typed it. */+export type ErrorDetail = ServerErrorDetail & { readonly field?: string }+export type ServerErrorBody = {readonly code?: stringreadonly message: stringreadonly status?: numberreadonly hint?: string+ readonly hints?: Hint[]readonly details?: ServerErrorDetail[]}@@ -21,7 +28,7 @@ export type ErrorEnvelope = {code: stringmessage: stringhint?: string- details?: ServerErrorDetail[]+ details?: ErrorDetail[]schema?: unknownhttp_status?: numbermethod?: string@@ -36,14 +43,14 @@ export type BaseErrorOptions = {readonly message: stringreadonly hint?: stringreadonly cause?: unknown- readonly details?: ServerErrorDetail[]+ readonly details?: ErrorDetail[]readonly schema?: unknown}export class BaseError extends Error {readonly code: ErrorCodeValuereadonly hint?: string- readonly details?: ServerErrorDetail[]+ readonly details?: ErrorDetail[]readonly schema?: unknownconstructor(opts: BaseErrorOptions) {@@ -116,10 +123,18 @@ export function unknownError(message: string, cause?: unknown): BaseError {return new BaseError({ code: ErrorCode.Unknown, message, cause })}-export const LOGIN_HINT = `run ${BINARY} login`+export const LOGIN_HINT = `run ${BINARY} help login`++export function notLoggedInMessage(reason?: string): string {+ return reason === undefined ? 'not logged in' : `not logged in: ${reason}`+}-export function notLoggedIn(): BaseError {- return new BaseError({ code: ErrorCode.NotLoggedIn, message: 'not logged in', hint: LOGIN_HINT })+export function notLoggedIn(reason?: string): BaseError {+ return new BaseError({+ code: ErrorCode.NotLoggedIn,+ message: notLoggedInMessage(reason),+ hint: LOGIN_HINT,+ })}type HttpClientErrorOptions = BaseErrorOptions & {diff --git a/cli/src/errors/codes.test.ts b/cli/src/errors/codes.test.tsindex df3531e0247..183509e84b7 100644--- a/cli/src/errors/codes.test.ts+++ b/cli/src/errors/codes.test.ts@@ -8,7 +8,6 @@ it('maps every code to the frozen exit taxonomy', () => {expect(exitFor(ErrorCode.UsageInvalidFlag)).toBe(ExitCode.Usage)expect(exitFor(ErrorCode.CatalogUnavailable)).toBe(ExitCode.Catalog)expect(exitFor(ErrorCode.UnknownOp)).toBe(ExitCode.Catalog)- expect(exitFor(ErrorCode.ConfigSchemaUnsupported)).toBe(ExitCode.Catalog)expect(exitFor(ErrorCode.RateLimited)).toBe(ExitCode.RateLimited)expect(exitFor(ErrorCode.ServerError)).toBe(ExitCode.Generic)expect(exitFor('something_from_the_future')).toBe(ExitCode.Generic)diff --git a/cli/src/errors/codes.ts b/cli/src/errors/codes.tsindex 75aa9353e29..ec4851a9331 100644--- a/cli/src/errors/codes.ts+++ b/cli/src/errors/codes.ts@@ -7,13 +7,13 @@ export const ErrorCode = {InputInvalid: 'input_invalid',ConfigInvalidKey: 'config_invalid_key',ConfigInvalidValue: 'config_invalid_value',- ConfigSchemaUnsupported: 'config_schema_unsupported',CatalogUnavailable: 'catalog_unavailable',UnknownOp: 'unknown_op',NetworkConnection: 'network_connection',RateLimited: 'rate_limited',ServerError: 'server_error',KeyringUnavailable: 'keyring_unavailable',+ SkillMissing: 'skill_missing',Unknown: 'unknown',} as const@@ -40,13 +40,13 @@ const CODE_TO_EXIT: Readonly<Record<ErrorCodeValue, ExitCodeValue>> = {input_invalid: ExitCode.Usage,config_invalid_key: ExitCode.Usage,config_invalid_value: ExitCode.Usage,- config_schema_unsupported: ExitCode.Catalog,catalog_unavailable: ExitCode.Catalog,unknown_op: ExitCode.Catalog,network_connection: ExitCode.Generic,rate_limited: ExitCode.RateLimited,server_error: ExitCode.Generic,keyring_unavailable: ExitCode.Generic,+ skill_missing: ExitCode.Generic,unknown: ExitCode.Generic,}diff --git a/cli/src/errors/format.test.ts b/cli/src/errors/format.test.tsindex 022127ba6e5..22d078b5c08 100644--- a/cli/src/errors/format.test.ts+++ b/cli/src/errors/format.test.ts@@ -43,3 +43,24 @@ it('drops schema in text and shows raw_response only when verbose', () => {)expect(renderEnvelope(env, plain, { verbose: true })).toMatch(/raw_response: Bearer \[redacted\]/)})++it('renders each server hint as a next line with the op spelled as a command', () => {+ const text = renderEnvelope(+ {+ error: {+ code: 'dsl_invalid',+ message: 'the DSL has errors',+ server: {+ message: 'the DSL has errors',+ hints: [{ summary: 'See every problem', op: 'check.console_app.dsl', input: {} }],+ },+ },+ },+ plain,+ { verbose: false },+ )+ expect(text.split('\n')).toEqual([+ 'dsl_invalid: the DSL has errors',+ 'next: difyctl check console_app dsl — See every problem',+ ])+})diff --git a/cli/src/errors/format.ts b/cli/src/errors/format.tsindex d9f414a51da..da523f9cee8 100644--- a/cli/src/errors/format.ts+++ b/cli/src/errors/format.ts@@ -1,6 +1,10 @@-import type { ErrorEnvelope } from './base'+import type { ErrorDetail, ErrorEnvelope } from './base'+import type { Hint } from '@/protocol/hint'import type { ColorScheme } from '@/sys/io/color'+import { LOC_SEPARATOR } from '@/errors/base'import { redactBearer } from '@/errors/sanitize'+import { spacedId } from '@/protocol/op-id'+import { BINARY } from '@/version/info'const RAW_RESPONSE_HINT = 'run again with --verbose to see the raw server response'@@ -15,6 +19,16 @@ function resolveHint(e: ErrorEnvelope['error'], opts: RenderOptions): string | ureturn rawHiddenAndUnparsed ? RAW_RESPONSE_HINT : undefined}+function detailLine(d: ErrorDetail): string {+ if (d.field !== undefined) return `${d.field}: ${d.msg}`+ const loc = (d.loc ?? []).join(LOC_SEPARATOR)+ return `${loc ? `${loc}: ` : ''}${d.msg} (${d.type})`+}++function nextLine(h: Hint, style: ColorScheme): string {+ return `${style.magenta('next:')} ${style.cyan(`${BINARY} ${spacedId(h.op)}`)} — ${h.summary}`+}+export function renderEnvelope(env: ErrorEnvelope,style: ColorScheme,@@ -24,12 +38,10 @@ export function renderEnvelope(const server = e.serverconst headerCode = server?.code ?? e.codeconst lines: string[] = [`${headerCode}: ${e.message}`]- for (const d of e.details ?? server?.details ?? []) {- const loc = (d.loc ?? []).join('.')- lines.push(` - ${loc ? `${loc}: ` : ''}${d.msg} (${d.type})`)- }+ for (const d of e.details ?? server?.details ?? []) lines.push(` - ${detailLine(d)}`)const hint = resolveHint(e, opts)if (hint !== undefined) lines.push(`${style.magenta('hint:')} ${style.cyan(hint)}`)+ for (const h of server?.hints ?? []) lines.push(nextLine(h, style))if (e.method !== undefined && e.url !== undefined) lines.push(`request: ${e.method} ${e.url}`)if (e.http_status !== undefined) lines.push(`http_status: ${e.http_status}`)if (opts.verbose && e.raw_response) lines.push(`raw_response: ${redactBearer(e.raw_response)}`)diff --git a/cli/src/main.test.ts b/cli/src/main.test.tsindex ec38375e6a2..321dfdb1874 100644--- a/cli/src/main.test.ts+++ b/cli/src/main.test.ts@@ -12,7 +12,7 @@ afterEach(async () => {it('prints the envelope on stderr and returns the exit code', async () => {w = await testContext({ login: false })- const code = await main(['nope'], w.overrides)+ const code = await main(['versoin'], w.overrides)expect(code).toBe(2)expect(JSON.parse(w.io.errBuf()).error.code).toBe('usage_invalid_flag')expect(w.io.outBuf()).toBe('')diff --git a/cli/src/plugins/catalog/index.test.ts b/cli/src/plugins/catalog/index.test.tsindex 00ddea739bb..7dca98e1c26 100644--- a/cli/src/plugins/catalog/index.test.ts+++ b/cli/src/plugins/catalog/index.test.ts@@ -25,7 +25,6 @@ let dir: stringbeforeEach(() => {dir = mkdtempSync(join(tmpdir(), 'difyctl-cat-'))process.env.DIFY_CONFIG_DIR = dir- process.env.DIFY_CACHE_DIR = dir})afterEach(() => {delete process.env.DIFY_CONFIG_DIR@@ -121,3 +120,22 @@ it('a cache it cannot write is an error naming the path', async () => {})expect(c.loaded).toBe(false)})++it('an unknown op id points at the help map, which lists every operation', async () => {+ const c = await build()+ await c.replace(FIXTURE)+ expect(() => c.opOrThrow('get.nothing_here')).toThrow(+ expect.objectContaining({ code: 'unknown_op', hint: 'run difyctl help' }),+ )+})++it('keeps the cache in the config folder and says once that DIFY_CACHE_DIR is no longer used', async () => {+ process.env.DIFY_CACHE_DIR = join(dir, 'old-cache')+ const { streams, ctx } = await buildWithStreams()+ const c = await ctx.get(catalog)+ await ctx.get(catalog)+ expect(c.path).toBe(join(dir, CATALOG_DIR_NAME, CACHE_FILE))+ expect(streams.errBuf()).toBe(+ 'DIFY_CACHE_DIR is no longer used; the catalog cache follows DIFY_CONFIG_DIR\n',+ )+})diff --git a/cli/src/plugins/catalog/index.ts b/cli/src/plugins/catalog/index.tsindex ed59776757a..f9d0bb8246b 100644--- a/cli/src/plugins/catalog/index.ts+++ b/cli/src/plugins/catalog/index.ts@@ -6,19 +6,19 @@ import { BaseError, notLoggedIn } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { errorMessage } from '@/errors/message'import { definePlugin } from '@/kernel/plugin'-import { env } from '@/plugins/env'+import { helpHint } from '@/plugins/commands/command'+import { ENV, env } from '@/plugins/env'import { io } from '@/plugins/io'import { session } from '@/plugins/session'+import { DIR_PERM, FILE_PERM } from '@/store/dir'import { pid, resolvePlatform } from '@/sys'import { bareHost } from '@/util/host'-import { BINARY } from '@/version/info'import { parseCatalog } from './types'export const CATALOG_DIR_NAME = 'catalog'const HOST_SEPARATOR_REPLACEMENT = '_'-const FILE_MODE = 0o600-const DIR_MODE = 0o700const UNREADABLE_CACHE_PREFIX = 'ignoring unreadable catalog cache '+const CACHE_DIR_RETIRED = `${ENV.CacheDir} is no longer used; the catalog cache follows ${ENV.ConfigDir}`const ENOENT = 'ENOENT'export type { CatalogDoc, CatalogOp, Example, JsonSchema } from './types'@@ -39,9 +39,9 @@ export function fingerprintOf(bytes: Uint8Array): string {return createHash('sha256').update(bytes).digest('hex')}-function cachePath(cacheDir: string, server: string): string {+function cachePath(configDir: string, server: string): string {const key = bareHost(server).split(':').join(HOST_SEPARATOR_REPLACEMENT)- return join(cacheDir, CATALOG_DIR_NAME, `${key}.json`)+ return join(configDir, CATALOG_DIR_NAME, `${key}.json`)}function isMissingFile(err: unknown): boolean {@@ -53,8 +53,8 @@ function isMissingFile(err: unknown): boolean {async function writeAtomically(path: string, bytes: Uint8Array): Promise<void> {const tmp = `${path}.tmp.${pid()}.${Date.now()}`try {- await fsp.mkdir(dirname(path), { recursive: true, mode: DIR_MODE })- await fsp.writeFile(tmp, bytes, { mode: FILE_MODE })+ await fsp.mkdir(dirname(path), { recursive: true, mode: DIR_PERM })+ await fsp.writeFile(tmp, bytes, { mode: FILE_PERM })resolvePlatform().atomicReplace(tmp, path)} catch (cause) {try {@@ -74,10 +74,11 @@ export const catalog = definePlugin({name: 'catalog',needs: [env, session, io],build: async (ctx): Promise<CatalogService> => {- const { cacheDir } = await ctx.get(env)+ const { configDir, cacheDirSet } = await ctx.get(env)+ if (cacheDirSet) (await ctx.get(io)).notice(CACHE_DIR_RETIRED)const sessionService = await ctx.get(session)const login = await sessionService.current()- const path = login === null ? undefined : cachePath(cacheDir, login.server)+ const path = login === null ? undefined : cachePath(configDir, login.server)let bytes: Uint8Array | undefinedlet doc: CatalogDoc | undefined@@ -116,7 +117,7 @@ export const catalog = definePlugin({throw new BaseError({code: ErrorCode.UnknownOp,message: `unknown op "${id}"`,- hint: `run ${BINARY} ops`,+ hint: helpHint(),})},ops: () => doc?.ops ?? {},diff --git a/cli/src/plugins/commands/command.ts b/cli/src/plugins/commands/command.tsindex b590fde155d..64deb027bc5 100644--- a/cli/src/plugins/commands/command.ts+++ b/cli/src/plugins/commands/command.ts@@ -5,10 +5,11 @@ import type { Example, JsonSchema } from '@/plugins/catalog'import type { Printable } from '@/sys/io/view'import { z } from 'zod'import { validateInput } from '@/call/validate'-import { BaseError } from '@/errors/base'+import { BaseError, LOC_SEPARATOR } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { inputSchema } from '@/plugins/argv/parse'import { COMMAND_SEPARATOR } from '@/protocol/op-id'+import { typedName } from '@/util/flag-name'import { BINARY } from '@/version/info'import { commandRow } from './describe'@@ -23,6 +24,34 @@ export function helpHint(...words: readonly string[]): string {return ['run', BINARY, HELP_WORD, ...words].join(COMMAND_SEPARATOR)}+type InputCheck = Readonly<{+ command: readonly string[]+ schema: JsonSchema+ positional?: readonly string[]+ input: Record<string, unknown>+}>++function typedField(loc: readonly (string | number)[], positional: readonly string[] = []) {+ const [head, ...rest] = loc+ if (typeof head !== 'string') return undefined+ return [typedName(head, positional), ...rest].join(LOC_SEPARATOR)+}++export function assertValidInput(check: InputCheck): void {+ const details = validateInput(check.schema, check.input)+ if (details.length === 0) return+ throw new BaseError({+ code: ErrorCode.InputInvalid,+ message: `invalid input for "${check.command.join(COMMAND_SEPARATOR)}"`,+ hint: helpHint(...check.command),+ details: details.map((detail) => ({+ ...detail,+ field: typedField(detail.loc, check.positional),+ })),+ schema: check.schema,+ })+}+/** Returned by a command that already wrote its output or needs a non-zero exit. */export class Outcome {readonly code: ExitCodeValue@@ -69,17 +98,7 @@ export abstract class Command<S extends z.ZodObject = z.ZodObject> {input: Record<string, unknown>,path: readonly string[],): Record<string, unknown> {- const schema = this.schema()- const details = validateInput(schema, input)- if (details.length > 0) {- throw new BaseError({- code: ErrorCode.InputInvalid,- message: `invalid input for "${path.join(COMMAND_SEPARATOR)}"`,- hint: helpHint(...path),- details: [...details],- schema,- })- }+ assertValidInput({ command: path, schema: this.schema(), positional: this.positional, input })const parsed = this.input.safeParse(input)if (!parsed.success) {throw new BaseError({diff --git a/cli/src/plugins/commands/describe.test.ts b/cli/src/plugins/commands/describe.test.tsindex 1a8b392606b..1e052ea43ce 100644--- a/cli/src/plugins/commands/describe.test.ts+++ b/cli/src/plugins/commands/describe.test.ts@@ -24,7 +24,7 @@ it('renders the row from the statics with a JSON Schema input', () => {summary: 'Do a thing',effect: 'write',positional: ['id'],- examples: [{ title: 'Basic', input: { id: 'x' } }],+ examples: [{ title: 'Basic', input: { id: 'x' }, command: 'difyctl fake thing x' }],})expect(row.input).toMatchObject({type: 'object',diff --git a/cli/src/plugins/commands/describe.ts b/cli/src/plugins/commands/describe.tsindex f274878e30d..6f861c1e1f7 100644--- a/cli/src/plugins/commands/describe.ts+++ b/cli/src/plugins/commands/describe.ts@@ -1,6 +1,9 @@import type { CommandConstructor, CommandEffect } from './command'-import type { Example, JsonSchema } from '@/plugins/catalog'+import type { CommandExample } from './examples'+import type { JsonSchema } from '@/plugins/catalog'+import { argToken } from '@/util/flag-name'import { BINARY } from '@/version/info'+import { commandExamples } from './examples'export type CommandRow = {id: string@@ -9,7 +12,7 @@ export type CommandRow = {effect?: CommandEffectinput: JsonSchemapositional: readonly string[]- examples: readonly Example[]+ examples: readonly CommandExample[]}// The op side of a descriptor: present once a command wraps a catalog op instead of a@@ -31,14 +34,15 @@ const FLAGS = '[flags]'export function commandRow(ctor: CommandConstructor, path: readonly string[]): CommandRow {const id = path.join(' ')- const args = ctor.positional.map((name) => `<${name}>`)+ const args = ctor.positional.map(argToken)+ const input = ctor.schema()const row: CommandRow = {id,usage: [BINARY, id, ...args, FLAGS].join(' '),summary: ctor.summary,- input: ctor.schema(),+ input,positional: ctor.positional,- examples: ctor.examples,+ examples: commandExamples({ id, input, positional: ctor.positional }, ctor.examples),}return ctor.effect === undefined ? row : { ...row, effect: ctor.effect }}diff --git a/cli/src/plugins/commands/examples.ts b/cli/src/plugins/commands/examples.tsnew file mode 100644index 00000000000..1c60bfa1188--- /dev/null+++ b/cli/src/plugins/commands/examples.ts@@ -0,0 +1,65 @@+import type { Example, JsonSchema } from '@/plugins/catalog'+import { COMMAND_SEPARATOR } from '@/protocol/op-id'+import { isRepeatable, isScalar, propertiesOf, shapeOf } from '@/protocol/shape'+import { argToken, flagToken } from '@/util/flag-name'+import { shellWord } from '@/util/shell-word'+import { BINARY } from '@/version/info'++export type CommandExample = Example & Readonly<{ command: string }>++type ExampleSource = Readonly<{ id: string; input: JsonSchema; positional: readonly string[] }>++const PLACEHOLDER = /^<[^<>]*>$/+const SKELETON_TITLE = 'Required fields'++// A placeholder stands for a value the caller fills in, whatever the field's shape.+function word(text: string): string {+ return PLACEHOLDER.test(text) ? text : shellWord(text)+}++function valueToken(property: JsonSchema | undefined, value: unknown): string {+ const scalar =+ typeof value === 'string' || (property !== undefined && isScalar(shapeOf(property)))+ return word(scalar ? String(value) : JSON.stringify(value))+}++// How the field is typed: a boolean as its presence, a repeatable list as the flag+// once per item, anything else as one value.+function flagTokens(name: string, property: JsonSchema | undefined, value: unknown): string[] {+ const flag = flagToken(name)+ if (value === true) return [flag]+ if (value === false) return [`${flag}=false`]+ if (property !== undefined && isRepeatable(shapeOf(property)) && Array.isArray(value))+ return value.flatMap((item) => [flag, word(String(item))])+ return [flag, valueToken(property, value)]+}++// Positionals keep their declared order, so an example that skips one does not shift the+// rest along: the one it skipped prints as itself.+export function exampleLine(d: ExampleSource, example: Example): string {+ const properties = propertiesOf(d.input)+ const flags = Object.keys(example.input).filter((name) => !d.positional.includes(name))+ return [+ BINARY,+ d.id,+ ...d.positional.map((name) =>+ name in example.input ? valueToken(properties[name], example.input[name]) : argToken(name),+ ),+ ...flags.flatMap((name) => flagTokens(name, properties[name], example.input[name])),+ ].join(COMMAND_SEPARATOR)+}++export function commandExamples(d: ExampleSource, examples: readonly Example[]): CommandExample[] {+ return examples.map((example) => ({ ...example, command: exampleLine(d, example) }))+}++// The text view of a command that ships no example still gets a runnable line: the+// required fields, each standing for itself.+export function skeletonExample(d: ExampleSource): CommandExample {+ const required = Array.isArray(d.input.required) ? d.input.required.map(String) : []+ const example = {+ title: SKELETON_TITLE,+ input: Object.fromEntries(required.map((name) => [name, argToken(name)])),+ }+ return { ...example, command: exampleLine(d, example) }+}diff --git a/cli/src/plugins/commands/help.test.ts b/cli/src/plugins/commands/help.test.tsindex fcac90ac680..9154a27515e 100644--- a/cli/src/plugins/commands/help.test.ts+++ b/cli/src/plugins/commands/help.test.ts@@ -68,7 +68,7 @@ it('every command the tree hides comes back with includeHidden', () => {})it('search ranks the plain words against ids, summaries, fields and examples', () => {- expect(helpSearch(['chatbot'], tree).entries[0]).toMatchObject({+ expect(helpSearch(['chatbot', 'streams'], tree).entries[0]).toMatchObject({id: 'run console_app chat',kind: 'sse',})@@ -96,7 +96,7 @@ it('the pointer names help and the skill in both forms', () => {expect(pointed.json).toEqual({message: 'difyctl has no built-in business commands; every server operation is a command',help: 'difyctl help',- skill: 'difyctl install skills <dir>',+ skill: 'difyctl install skills <skills root>',})expect(pointed.text(plain).split('\n')).toEqual(Object.values(pointed.json))})diff --git a/cli/src/plugins/commands/help.ts b/cli/src/plugins/commands/help.tsindex cc82074f654..8026ed5e92c 100644--- a/cli/src/plugins/commands/help.ts+++ b/cli/src/plugins/commands/help.ts@@ -4,7 +4,7 @@ import type { SearchDoc } from '@/discovery/search'import type { View } from '@/sys/io/view'import { search, searchDoc } from '@/discovery/search'import { byHead, groupsOf, namespacesOf, under } from '@/discovery/tree'-import { COMMAND_SEPARATOR, OP_SEPARATOR, spacedId } from '@/protocol/op-id'+import { COMMAND_SEPARATOR, commandWords, OP_SEPARATOR } from '@/protocol/op-id'import { view } from '@/sys/io/view'import { BINARY } from '@/version/info'import { HELP_WORD } from './command'@@ -12,7 +12,7 @@ import { collectCommands } from './registry'const SEARCH_LIMIT = 20const NEWLINE = '\n'-const SKILL_WORDS = 'install skills <dir>'+const SKILL_COMMAND = [BINARY, 'install', 'skills', '<skills root>'].join(COMMAND_SEPARATOR)const POINTER_MESSAGE = `${BINARY} has no built-in business commands; every server operation is a command`export type HelpEntry = {@@ -32,7 +32,7 @@ export function pointer(): View<Record<string, string>> {const json = {message: POINTER_MESSAGE,help: [BINARY, HELP_WORD].join(COMMAND_SEPARATOR),- skill: [BINARY, SKILL_WORDS].join(COMMAND_SEPARATOR),+ skill: SKILL_COMMAND,}return view(json, () => Object.values(json).join(NEWLINE))}@@ -41,7 +41,7 @@ export function pointer(): View<Record<string, string>> {export function spacedWords(words: readonly string[]): readonly string[] {const [only] = wordsif (words.length !== 1 || only === undefined || !only.includes(OP_SEPARATOR)) return words- return spacedId(only).split(COMMAND_SEPARATOR)+ return commandWords(only)}function entryOf(ctor: CommandConstructor, id: string): HelpEntry {diff --git a/cli/src/plugins/commands/index.test.ts b/cli/src/plugins/commands/index.test.tsindex e1fec9546b2..b5296214d03 100644--- a/cli/src/plugins/commands/index.test.ts+++ b/cli/src/plugins/commands/index.test.ts@@ -1,10 +1,12 @@import type { TestWorld } from '@test/fixtures/kernel'+import type { BaseError } from '@/errors/base'import type { CommandTree } from '@/plugins/commands/registry'import { readFileSync } from 'node:fs'import { join } from 'node:path'import { testContext } from '@test/fixtures/kernel'import { afterEach, expect, it } from 'vite-plus/test'import { z } from 'zod'+import { ExitCode } from '@/errors/codes'import { parseCatalog } from '@/plugins/catalog'import { Command } from '@/plugins/commands/command'import { propertiesOf } from '@/protocol/shape'@@ -31,7 +33,7 @@ it('bare difyctl prints a pointer to help and the skill, and makes no request',expect(JSON.parse(w.io.outBuf())).toEqual({message: 'difyctl has no built-in business commands; every server operation is a command',help: 'difyctl help',- skill: 'difyctl install skills <dir>',+ skill: 'difyctl install skills <skills root>',})expect(w.mock.requestCount).toBe(0)})@@ -67,7 +69,7 @@ it('the map with no server known is the static half and says so on stderr', asynconst map = JSON.parse(w.io.outBuf())expect(map.version).toMatchObject({ count: 1 })expect(map.console_app).toBeUndefined()- expect(w.io.errBuf()).toMatch(/log in to list server operations/)+ expect(w.io.errBuf()).toMatch(/not logged in: run difyctl help login/)expect(w.mock.requestCount).toBe(0)})@@ -78,8 +80,9 @@ it('the map still prints the static half when the catalog cannot be fetched', asconst map = JSON.parse(w.io.outBuf())expect(map.version).toMatchObject({ count: 1 })expect(map.console_app).toBeUndefined()- expect(w.io.errBuf().trim().split('\n')).toHaveLength(1)- expect(w.io.errBuf()).toMatch(/^could not list server operations: failed to fetch the catalog: /)+ const [couldNotList, ...rest] = w.io.errBuf().trim().split('\n')+ expect(couldNotList).toMatch(/^could not list server operations: failed to fetch the catalog: /)+ expect(rest).toEqual([])})it('help accepts a dotted id and prints the same descriptor as the spaced path', async () => {@@ -145,11 +148,10 @@ it('help routes a word to a namespace listing or a search, and --full is the flaconst c = await world(true, ['help', 'get'])await (await c.ctx.get(commands)).run()const ids = JSON.parse(c.io.outBuf()).entries.map((e: { id: string }) => e.id)- expect(ids).toContain('get skills')expect(ids).toContain('get workspace member')expect(ids).toEqual([...ids].sort())- const d = await world(true, ['help', 'chatbot'])+ const d = await world(true, ['help', 'chatbot', 'streams'])await (await d.ctx.get(commands)).run()expect(JSON.parse(d.io.outBuf()).entries[0]).toMatchObject({id: 'run console_app chat',@@ -218,7 +220,7 @@ it('takes --verbose anywhere and keeps it out of the command input', async () =>const b = await world(false, ['--verbose', 'version'])expect(await (await b.ctx.get(commands)).run()).toBe(0)expect(JSON.parse(b.io.outBuf()).client.version).toBe('0.0.0-test')- const c = await world(false, ['nope', '--verbose'])+ const c = await world(false, ['versoin', '--verbose'])await expect((await c.ctx.get(commands)).run()).rejects.toMatchObject({code: 'usage_invalid_flag',})@@ -254,18 +256,29 @@ it('a command word may be spelled with dashes where the op id has underscores',})})-it('an unknown path refetches the catalog once before giving up', async () => {- const w = await world(true, ['get', 'nope'])- await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({- code: 'usage_invalid_flag',- message: 'unknown command: get nope',+it('an unknown path refetches the catalog once, then is unknown_op (exit 6)', async () => {+ const w = await world(true, ['get', 'qqqq'])+ const miss = (await w.ctx.get(commands)).run()+ await expect(miss).rejects.toMatchObject({+ code: 'unknown_op',+ message: 'no command or server operation named get qqqq',hint: 'run difyctl help',})+ await expect(miss).rejects.toSatisfy((err: BaseError) => err.exit() === ExitCode.Catalog)expect(w.mock.requestCount).toBe(2) // the cached catalog, then one refetchconst typo = await world(true, ['get', 'consol_app'])await expect((await typo.ctx.get(commands)).run()).rejects.toMatchObject({- hint: 'did you mean: get console_app',+ code: 'unknown_op',+ hint: 'did you mean: get console_app, get console_app version',+ })+})++it('a typo of a static command stays exit 2 once the catalog is loaded', async () => {+ const w = await world(true, ['versoin'])+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({+ code: 'usage_invalid_flag',+ hint: 'did you mean: version',})})@@ -302,13 +315,33 @@ it('an unreachable catalog costs a notice, not the static suggestion', async ()expect(w.io.errBuf()).toMatch(/^could not list server operations: failed to fetch the catalog: /)})-it('without a login only statics resolve and the hint says to log in', async () => {+it('an unreachable catalog makes a word no static claims catalog_unavailable (exit 6)', async () => {+ const w = await world(true, ['get', 'console_app'])+ w.mock.setScenario('no-catalog')+ const miss = (await w.ctx.get(commands)).run()+ await expect(miss).rejects.toMatchObject({+ code: 'catalog_unavailable',+ message: expect.stringMatching(/^failed to fetch the catalog: /),+ hint: expect.any(String),+ })+ await expect(miss).rejects.toSatisfy((err: BaseError) => err.exit() === ExitCode.Catalog)+})++it('without a login a word no static claims is not_logged_in (exit 4)', async () => {const w = await world(false, ['get', 'console_app'])- await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({- code: 'usage_invalid_flag',- message: 'unknown command: get console_app',- hint: 'log in to use server operations',+ const miss = (await w.ctx.get(commands)).run()+ await expect(miss).rejects.toMatchObject({+ code: 'not_logged_in',+ message: 'not logged in: get console_app may be a server operation; log in to load them',+ hint: 'run difyctl help login',})+ await expect(miss).rejects.toSatisfy((err: BaseError) => err.exit() === ExitCode.Auth)+ expect(w.mock.requestCount).toBe(0)+})++it('without a login a namespace still lists its static commands', async () => {+ const w = await world(false, ['get'])+ expect(await (await w.ctx.get(commands)).run()).toBe(0)expect(w.mock.requestCount).toBe(0)})diff --git a/cli/src/plugins/commands/index.ts b/cli/src/plugins/commands/index.tsindex f6abcbf5431..be1109107a7 100644--- a/cli/src/plugins/commands/index.ts+++ b/cli/src/plugins/commands/index.ts@@ -4,7 +4,7 @@ import type { CollectOptions, CommandTree, ResolvedCommand } from '@/plugins/comimport type { IOService } from '@/plugins/io'import type { OpsService, TreeOptions } from '@/plugins/ops'import { commandTree } from '@/commands/tree'-import { BaseError } from '@/errors/base'+import { BaseError, isBaseError, notLoggedInMessage } from '@/errors/base'import { ErrorCode, ExitCode } from '@/errors/codes'import { errorMessage } from '@/errors/message'import { definePlugin } from '@/kernel/plugin'@@ -41,8 +41,8 @@ const HELP_FLAGS: readonly string[] = ['--help', '-h']const FULL_FLAG = '--full'const ALL_FLAG = '--all'const FLAG_PREFIX = '-'-const NO_SERVER_NOTICE = 'log in to list server operations'-const NO_SERVER_HINT = 'log in to use server operations'+const NO_SERVER_NOTICE = notLoggedInMessage(helpHint('login'))+const MAYBE_AN_OP = 'may be a server operation; log in to load them'const OPS_UNAVAILABLE_PREFIX = 'could not list server operations: 'const NO_MATCH_NOTICE = `nothing matched; ${helpHint()} for the map`const NO_REST: readonly string[] = []@@ -77,41 +77,92 @@ function leadingWords(tokens: readonly string[]): number {return at === -1 ? tokens.length : at}+/** What a catalog load gave: the value, or why there is none (`failure` unset when logged out). */+type Fetched<T> = Readonly<{ value: T }> | Readonly<{ value?: undefined; failure?: unknown }>+// An unreachable server must not cost the caller the static half of help.async function fromOps<T>(ctx: CommandContext,streams: IOService,load: (service: OpsService) => Promise<T>,-): Promise<T | undefined> {+): Promise<Fetched<T>> {const login = await (await ctx.get(session)).current()if (login === null) {streams.notice(NO_SERVER_NOTICE)- return undefined+ return {}}try {- return await load(await ctx.get(ops))- } catch (err) {- streams.notice(`${OPS_UNAVAILABLE_PREFIX}${errorMessage(err)}`)- return undefined+ return { value: await load(await ctx.get(ops)) }+ } catch (failure) {+ streams.notice(`${OPS_UNAVAILABLE_PREFIX}${errorMessage(failure)}`)+ return { failure }}}-function unknownCommand(tree: CommandTree, words: readonly string[], fallback: string): BaseError {+function suggestionHint(tree: CommandTree, words: readonly string[]): string | undefined {const suggestions = findSuggestions(tree, [...words])+ return suggestions.length > 0 ? `did you mean: ${suggestions.join(', ')}` : undefined+}++function unknownCommand(words: readonly string[], hint: string): BaseError {return new BaseError({code: ErrorCode.UsageInvalidFlag,message: `unknown command: ${words.join(COMMAND_SEPARATOR)}`,- hint: suggestions.length > 0 ? `did you mean: ${suggestions.join(', ')}` : fallback,+ hint,})}+/** The error for words no command claimed, given the widest tree resolution got. */+type Miss = (tree: CommandTree, words: readonly string[]) => BaseError++const unresolved: Miss = (tree, words) =>+ unknownCommand(words, suggestionHint(tree, words) ?? helpHint())++// A near miss of a static command is a typo (exit 2) whether or not ops could load.+function unlessStaticTypo(statics: CommandTree, miss: Miss): Miss {+ return (tree, words) => {+ const typo = suggestionHint(statics, words)+ return typo === undefined ? miss(tree, words) : unknownCommand(words, typo)+ }+}++const loggedOut: Miss = (_tree, words) =>+ new BaseError({+ code: ErrorCode.NotLoggedIn,+ message: notLoggedInMessage(`${words.join(COMMAND_SEPARATOR)} ${MAYBE_AN_OP}`),+ hint: helpHint('login'),+ })++const unknownOp: Miss = (tree, words) =>+ new BaseError({+ code: ErrorCode.UnknownOp,+ message: `no command or server operation named ${words.join(COMMAND_SEPARATOR)}`,+ hint: suggestionHint(tree, words) ?? helpHint(),+ })++function catalogUnavailable(failure: unknown): BaseError {+ return isBaseError(failure)+ ? failure+ : new BaseError({+ code: ErrorCode.CatalogUnavailable,+ message: `${OPS_UNAVAILABLE_PREFIX}${errorMessage(failure)}`,+ cause: failure,+ })+}++// Words that might name an op cannot be called unknown when the ops never loaded.+function unloaded(statics: CommandTree, fetched: Fetched<unknown>): Miss | undefined {+ if (!('failure' in fetched)) return undefined+ return unlessStaticTypo(statics, () => catalogUnavailable(fetched.failure))+}+type Discovery = Readonly<{tree: CommandTreepath: readonly string[]full: booleanlisting: CollectOptionswantsHelp: boolean- missHint?: string+ miss: Missctx: CommandContextstreams: IOService}>@@ -140,7 +191,7 @@ async function discover(args: Discovery): Promise<number> {await streams.document(listingView(under))return ExitCode.Success}- if (!args.wantsHelp) throw unknownCommand(tree, path, args.missHint ?? helpHint())+ if (!args.wantsHelp) throw args.miss(tree, path)const found = helpSearch(path, tree, listing)if (found.total === 0) streams.notice(NO_MATCH_NOTICE)@@ -151,8 +202,8 @@ async function discover(args: Discovery): Promise<number> {type Resolution = {readonly resolved: ResolvedCommand | undefinedreadonly tree: CommandTree- /** Set only when a miss has a better explanation than the generic help hint. */- readonly missHint?: string+ /** Set only when a miss has a better explanation than an unknown command. */+ readonly miss?: Miss}type Walk = Readonly<{@@ -172,30 +223,36 @@ function answerable(walk: Walk, cached: CommandTree): boolean {// Statics resolve without touching the catalog. A miss walks the server's ops as// commands too: the cached catalog first, then one refetch in case the op is newer-// than the cache. A server that cannot answer costs the caller nothing but a notice —+// than the cache. A server that cannot answer costs help nothing but a notice —// resolution falls back to the widest tree it did get, which is also the tree help-// lists, so the catalog is loaded at most once per run.+// lists, so the catalog is loaded at most once per run. A plain miss then reports the+// failed load rather than an unknown command.async function resolveWithOps(walk: Walk): Promise<Resolution> {const { ctx, streams, tree } = walkconst path = [...walk.path]const direct = resolveCommand(tree, path)if (direct !== undefined) return { resolved: direct, tree }- // A help view explains a missing catalog on stderr; a plain miss gets the hint instead.+ // A help view explains a missing catalog on stderr; a plain miss says to log in.if (!walk.wantsHelp && (await (await ctx.get(session)).current()) === null)- return { resolved: undefined, tree, missHint: NO_SERVER_HINT }+ return { resolved: undefined, tree, miss: unlessStaticTypo(tree, loggedOut) }const known = await fromOps(ctx, streams, (service) => service.commands(EVERY_OP))- if (known === undefined) return { resolved: undefined, tree }- const cached = mergeTrees(tree, known).tree+ if (known.value === undefined) return { resolved: undefined, tree, miss: unloaded(tree, known) }+ const cached = mergeTrees(tree, known.value).treeconst fromCache = resolveCommand(cached, path)if (fromCache !== undefined || answerable(walk, cached))return { resolved: fromCache, tree: cached }const refetched = await fromOps(ctx, streams, (service) => service.commands(EVERY_OP_FRESH))- if (refetched === undefined) return { resolved: undefined, tree: cached }- const fresh = mergeTrees(tree, refetched).tree- return { resolved: resolveCommand(fresh, path), tree: fresh }+ if (refetched.value === undefined)+ return { resolved: undefined, tree: cached, miss: unloaded(tree, refetched) }+ const fresh = mergeTrees(tree, refetched.value).tree+ return {+ resolved: resolveCommand(fresh, path),+ tree: fresh,+ miss: unlessStaticTypo(tree, unknownOp),+ }}export async function runPipeline(tree: CommandTree, ctx: CommandContext): Promise<number> {@@ -225,7 +282,7 @@ export async function runPipeline(tree: CommandTree, ctx: CommandContext): Promifull: argv.includes(FULL_FLAG),listing: { includeHidden: argv.includes(ALL_FLAG) },wantsHelp,- missHint: walked.missHint,+ miss: walked.miss ?? unresolved,ctx,streams,})diff --git a/cli/src/plugins/commands/text.test.ts b/cli/src/plugins/commands/text.test.tsindex fb4567a6248..a6abdb70d21 100644--- a/cli/src/plugins/commands/text.test.ts+++ b/cli/src/plugins/commands/text.test.ts@@ -7,8 +7,9 @@ import SkillsInstall from '@/commands/install/skills/index'import { parseCatalog } from '@/plugins/catalog'import { colorScheme } from '@/sys/io/color'import { commandRow } from './describe'+import { commandExamples, exampleLine } from './examples'import { helpMap } from './help'-import { descriptorView, exampleLine, fieldRows, listingView, mapView, SECTIONS } from './text'+import { descriptorView, fieldRows, listingView, mapView, SECTIONS } from './text'const OPS = parseCatalog(readFileSync(join(__dirname, '../../../test/fixtures/catalog.json'))).opsconst plain = colorScheme(false)@@ -23,7 +24,7 @@ function opDescriptor(id: string, path: readonly string[]): Descriptor {effect: 'write',input: op.input,positional: [],- examples: op.examples,+ examples: commandExamples({ id: path.join(' '), input: op.input, positional: [] }, op.examples),op: id,method: op.method,path: op.path,@@ -59,18 +60,18 @@ it('renders an op descriptor with input, options, global and examples', () => {difyctl run console_app workflow [flags]Flags- --app-id string required- --attachments file[] optional Local files attached to the run itself (the app's- \`sys.files\`), not to a variable- --files map<string, json> optional Local files keyed by the app's file variable name; the- server uploads each one and sets \`inputs[<name>]\`. Send a- list (part name \`files[<name>][]\`) for a file-list variable- --inputs map<string, json> required Variables declared by the app. The exact shape is per app:- read \`input_schema\` from describe.console_app. A file- variable takes a Dify file mapping (remote url or upload id)- here, or a local file in \`files\`, not both.- --workflow-id string optional Pin a published workflow version- --workspace-id string optional Workspace that owns the app+ --app-id string required+ --attachments file[] optional Local files attached to the run itself (the app's+ \`sys.files\`), not to a variable+ --files map<string, file | file[]> optional Local files keyed by the app's file variable name; the+ server uploads each one and sets \`inputs[<name>]\`. Send a+ list (part name \`files[<name>][]\`) for a file-list variable+ --inputs map<string, json> required Variables declared by the app. The exact shape is per app:+ read \`input_schema\` from describe.console_app. A file+ variable takes a Dify file mapping (remote url or upload id)+ here, or a local file in \`files\`, not both.+ --workflow-id string optional Pin a published workflow version+ --workspace-id string optional Workspace that owns the appOptions--input string optional Operation input as JSON, @file or @- for stdin@@ -92,7 +93,7 @@ it('renders an op descriptor with input, options, global and examples', () => {it('renders a static descriptor with arguments and flags', () => {expect(descriptorView(skillsInstall).text(plain)).toMatchInlineSnapshot(`- "install skills Write skills from the collection into a skills root write+ "install skills Write the difyctl skill into a skills root writeUsagedifyctl install skills <dir> [flags]@@ -102,19 +103,16 @@ it('renders a static descriptor with arguments and flags', () => {per skillFlags- --skill string[] [] Skill to install (repeatable); default: the whole collection- --from string "https://github.com/langgenius/dify/tree/0000000/skills" Where the skills come from: a GitHub folder URL or a local- folder+ --from string optional A local skill folder to install instead of the one built+ into difyctlGlobal--verbose boolean false Keep the raw server response in error envelopes--json boolean false Print JSON even on a terminalExamples- # Install every skill for Claude Code- difyctl install skills ~/.claude/skills- # Install one skill for Codex- difyctl install skills ~/.codex/skills --skill difyctl"+ # Install the skill for Claude Code+ difyctl install skills ~/.claude/skills"`)})@@ -125,9 +123,9 @@ it('example lines put positionals first, scalars as --flag value, non-scalars asexpect(exampleLine(skillsInstall, {title: 't',- input: { dir: '~/.claude/skills', skill: ['difyctl'] },+ input: { dir: '~/.claude/skills', from: './skill' },}),- ).toBe('difyctl install skills ~/.claude/skills --skill difyctl')+ ).toBe('difyctl install skills ~/.claude/skills --from ./skill')})it('a missing positional prints as itself and a non-scalar one as json', () => {@@ -205,10 +203,9 @@ it('a description prints its first line only', () => {})it('an op without examples prints a skeleton of its required fields', () => {+ const skeleton = 'difyctl run console_app workflow --app-id <app_id> --inputs <inputs>'expect(workflowRun.examples).toEqual([])- expect(descriptorView(workflowRun).text(plain)).toContain(- 'difyctl run console_app workflow --app-id <app_id> --inputs <inputs>',- )+ expect(descriptorView(workflowRun).text(plain)).toContain(skeleton)})it('the map names each head, leaves by summary and groups by count', () => {diff --git a/cli/src/plugins/commands/text.ts b/cli/src/plugins/commands/text.tsindex e60b44dee45..0e25c2d2f02 100644--- a/cli/src/plugins/commands/text.ts+++ b/cli/src/plugins/commands/text.ts@@ -1,16 +1,16 @@import type { CommandEffect } from './command'import type { Descriptor } from './describe'import type { HelpEntry, HelpHead, HelpListing, HelpMap } from './help'-import type { Example, JsonSchema } from '@/plugins/catalog'+import type { JsonSchema } from '@/plugins/catalog'import type { ColorScheme } from '@/sys/io/color'import type { View } from '@/sys/io/view'import { inputSchema } from '@/plugins/argv/parse'import { GLOBAL_INPUT } from '@/plugins/global-flags'import { COMMAND_SEPARATOR } from '@/protocol/op-id'-import { isRepeatable, isScalar, labelOf, propertiesOf, shapeOf } from '@/protocol/shape'+import { labelOf, propertiesOf, shapeOf } from '@/protocol/shape'import { view } from '@/sys/io/view'-import { flagFor } from '@/util/flag-name'-import { BINARY } from '@/version/info'+import { argToken, flagToken } from '@/util/flag-name'+import { skeletonExample } from './examples'export type FieldRow = Readonly<{name: string@@ -25,7 +25,6 @@ type Tagged = Readonly<{ effect?: CommandEffect; kind?: string; deprecated?: booconst PRESENCE = { Required: 'required', Optional: 'optional' } as constconst FIRST_LINE = /\r?\n/-const PLACEHOLDER = /^<[^<>]*>$/const GAP = ' 'const MAX_COLUMN_WIDTH = 60const WORD_SEPARATOR = ' '@@ -37,7 +36,6 @@ const LIST_SEPARATOR = ', 'const COMMAND_NOUN = { one: 'command', many: 'commands' } as constconst DEPRECATED = 'deprecated'const NO_PIN = '(none)'-const SKELETON_TITLE = 'Required fields'const COMMENT = '#'const NO_POSITIONAL: readonly string[] = []@@ -100,7 +98,7 @@ export function fieldRows(schema: JsonSchema, positional: readonly string[]): Fifunction rowsToLines(rows: readonly FieldRow[]): string[] {return aligned(rows.map((row) => [- row.positional ? `<${row.name}>` : `--${flagFor(row.name)}`,+ row.positional ? argToken(row.name) : flagToken(row.name),row.label,row.presence,row.description,@@ -108,47 +106,6 @@ function rowsToLines(rows: readonly FieldRow[]): string[] {)}-// A placeholder stands for a value the caller fills in, whatever the field's shape.-function valueToken(property: JsonSchema | undefined, value: unknown): string {- const placeholder = typeof value === 'string' && PLACEHOLDER.test(value)- const scalar = property !== undefined && isScalar(shapeOf(property))- return placeholder || scalar ? String(value) : `'${JSON.stringify(value)}'`-}--// How the field is typed: a boolean as its presence, a repeatable list as the flag-// once per item, anything else as one value.-function flagTokens(name: string, property: JsonSchema | undefined, value: unknown): string[] {- const flag = `--${flagFor(name)}`- if (value === true) return [flag]- if (value === false) return [`${flag}=false`]- if (property !== undefined && isRepeatable(shapeOf(property)) && Array.isArray(value))- return value.flatMap((item) => [flag, String(item)])- return [flag, valueToken(property, value)]-}--// Positionals keep their declared order, so an example that skips one does not shift the-// rest along: the one it skipped prints as itself.-export function exampleLine(d: Descriptor, example: Example): string {- const properties = propertiesOf(d.input)- const flags = Object.keys(example.input).filter((name) => !d.positional.includes(name))- return [- BINARY,- d.id,- ...d.positional.map((name) =>- name in example.input ? valueToken(properties[name], example.input[name]) : `<${name}>`,- ),- ...flags.flatMap((name) => flagTokens(name, properties[name], example.input[name])),- ].join(COMMAND_SEPARATOR)-}--// A server that ships no example still gets a runnable line: the required fields,-// each standing for itself.-function examplesOf(d: Descriptor): readonly Example[] {- if (d.examples.length > 0) return d.examples- const required = Array.isArray(d.input.required) ? d.input.required.map(String) : []- return [{ title: SKELETON_TITLE, input: Object.fromEntries(required.map((n) => [n, `<${n}>`])) }]-}-export const SECTIONS: readonly Section[] = [{ title: 'Usage', lines: (d) => [d.usage] },{@@ -170,9 +127,9 @@ export const SECTIONS: readonly Section[] = [{title: 'Examples',lines: (d, style) =>- examplesOf(d).flatMap((example) => [+ (d.examples.length > 0 ? d.examples : [skeletonExample(d)]).flatMap((example) => [style.dim(`${COMMENT} ${example.title}`),- exampleLine(d, example),+ example.command,]),},{diff --git a/cli/src/plugins/config/index.test.ts b/cli/src/plugins/config/index.test.tsindex 216aa9b55fe..31f84cfdc22 100644--- a/cli/src/plugins/config/index.test.ts+++ b/cli/src/plugins/config/index.test.ts@@ -1,46 +1,84 @@-import { mkdtempSync, writeFileSync } from 'node:fs'+import type { BufferStreams } from '@/sys/io/streams'+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterEach, beforeEach, expect, it } from 'vite-plus/test'import { Context } from '@/kernel/context'-import { config } from './index'+import { io, ioService } from '@/plugins/io'+import { bufferStreams } from '@/sys/io/streams'+import { config, CONFIG_FILE_NAME } from './index'let dir: string+let file: string+let streams: BufferStreamsbeforeEach(() => {dir = mkdtempSync(join(tmpdir(), 'difyctl-cfg-'))+ file = join(dir, CONFIG_FILE_NAME)process.env.DIFY_CONFIG_DIR = dir+ streams = bufferStreams()})afterEach(() => {delete process.env.DIFY_CONFIG_DIR})+const load = () => new Context([[io, ioService(streams)]]).get(config)+it('returns defaults and the file path when nothing is on disk', async () => {- const c = await new Context().get(config)- expect(await c.get()).toEqual({- schema_version: 1,- http: { timeout: 30_000 },- path: join(dir, 'config.yml'),- })+ const c = await load()+ expect(await c.get()).toEqual({ http: { timeout: 30_000 }, path: file })})it('set / get / unset round-trip through yaml', async () => {- const c = await new Context().get(config)+ const c = await load()await c.set('http.timeout', '5000')expect(await c.get('http.timeout')).toBe(5000)await c.unset('http.timeout')expect(await c.get('http.timeout')).toBe(30_000)})-it('rejects unknown keys and wrong types with exit 2', async () => {- const c = await new Context().get(config)+it('rejects unknown keys and wrong types with exit 2, naming the file', async () => {+ const c = await load()await expect(c.set('nope', '1')).rejects.toMatchObject({ code: 'config_invalid_key' })await expect(c.set('http.timeout', 'fast')).rejects.toMatchObject({code: 'config_invalid_value',+ hint: expect.stringContaining(file),})})-it('rejects a newer schema_version with exit 6', async () => {- writeFileSync(join(dir, 'config.yml'), 'schema_version: 2\n')- const c = await new Context().get(config)- await expect(c.get()).rejects.toMatchObject({ code: 'config_schema_unsupported' })+it('loads a difyctl v1 file and drops its defaults and state on the next set', async () => {+ writeFileSync(+ file,+ 'schema_version: 1\ndefaults:\n format: json\nstate:\n current_app: app-1\nhttp:\n timeout: 5000\n',+ )+ const c = await load()+ expect(await c.get('http.timeout')).toBe(5000)+ await c.set('http.timeout', '6000')+ expect(readFileSync(file, 'utf8')).toBe('http:\n timeout: 6000\n')+ expect(streams.errBuf()).toBe('')+})++it('ignores unknown and future keys without a notice', async () => {+ writeFileSync(file, 'schema_version: 99\nfuture_key: x\nhttp:\n timeout: 5000\n later: 1\n')+ const c = await load()+ expect(await c.get()).toEqual({ http: { timeout: 5000 }, path: file })+ expect(streams.errBuf()).toBe('')+})++it('falls back to the default for an invalid value, naming the key', async () => {+ writeFileSync(file, 'http:\n timeout: fast\n')+ const c = await load()+ expect(await c.get('http.timeout')).toBe(30_000)+ expect(streams.errBuf()).toBe(`${file}: ignoring the invalid value of http.timeout\n`)+})++it.each([+ ['not valid YAML', 'http: [unclosed\n', /is not valid YAML/],+ ['not a mapping', '- a\n- b\n', /is not a YAML mapping/],+])('reads a file that is %s as empty and replaces it on the next set', async (_l, raw, note) => {+ writeFileSync(file, raw)+ const c = await load()+ expect(await c.get('http.timeout')).toBe(30_000)+ expect(streams.errBuf()).toMatch(note)+ await c.set('http.timeout', '5000')+ expect(readFileSync(file, 'utf8')).toBe('http:\n timeout: 5000\n')})diff --git a/cli/src/plugins/config/index.ts b/cli/src/plugins/config/index.tsindex f857d3cbd34..37ab1b22afa 100644--- a/cli/src/plugins/config/index.ts+++ b/cli/src/plugins/config/index.ts@@ -5,18 +5,15 @@ import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { definePlugin } from '@/kernel/plugin'import { env } from '@/plugins/env'-import { YamlStore } from '@/store/store'+import { io } from '@/plugins/io'+import { localFile } from '@/store/local-file'import { isRecord } from '@/util/is-record'export const CONFIG_FILE_NAME = 'config.yml'-export const CONFIG_SCHEMA_VERSION = 1-export const CONFIG_SCHEMA = z- .object({- schema_version: z.literal(1).default(1),- http: z.object({ timeout: z.number().int().positive().default(30_000) }).prefault({}),- })- .strict()+const CONFIG_SCHEMA = z.object({+ http: z.object({ timeout: z.number().int().positive().default(30_000) }).prefault({}),+})export type ConfigDoc = z.infer<typeof CONFIG_SCHEMA>@@ -84,25 +81,13 @@ function parseRawValue(raw: string): unknown {}}-function checkSchemaVersion(raw: unknown): void {- if (!isRecord(raw)) return- const version = raw.schema_version- if (typeof version === 'number' && version > CONFIG_SCHEMA_VERSION) {- throw new BaseError({- code: ErrorCode.ConfigSchemaUnsupported,- message: `config schema_version ${version} is newer than the supported version ${CONFIG_SCHEMA_VERSION}`,- hint: 'upgrade difyctl to read this config file',- })- }-}--function validateDoc(raw: unknown): ConfigDoc {- checkSchemaVersion(raw)+function validateDoc(raw: unknown, path: string): ConfigDoc {const result = CONFIG_SCHEMA.safeParse(raw)if (!result.success) {throw new BaseError({code: ErrorCode.ConfigInvalidValue,message: result.error.issues.map((issue) => issue.message).join('; '),+ hint: `the value was not saved to ${path}`,})}return result.data@@ -110,27 +95,23 @@ function validateDoc(raw: unknown): ConfigDoc {export const config = definePlugin({name: 'config',- needs: [env],+ needs: [env, io],build: async (ctx): Promise<ConfigService> => {- const { configDir } = await ctx.get(env)- const path = join(configDir, CONFIG_FILE_NAME)- const store = new YamlStore(path)+ const path = join((await ctx.get(env)).configDir, CONFIG_FILE_NAME)+ const file = localFile(path, CONFIG_SCHEMA, (await ctx.get(io)).notice)let cached: ConfigDoc | undefinedasync function doc(): Promise<ConfigDoc> {- if (cached === undefined) {- const raw = await store.getTyped<Record<string, unknown>>()- cached = validateDoc(raw ?? {})- }+ if (cached === undefined) cached = (await file.read()) ?? CONFIG_SCHEMA.parse({})return cached}async function persist(mutate: (target: Record<string, unknown>) => void): Promise<void> {const current = structuredClone(await doc()) as Record<string, unknown>mutate(current)- const validated = validateDoc(current)- await store.setTyped(validated)+ const validated = validateDoc(current, path)+ await file.write(validated)cached = validated}diff --git a/cli/src/plugins/env/index.test.ts b/cli/src/plugins/env/index.test.tsindex 493e0150d39..d81e71b9f37 100644--- a/cli/src/plugins/env/index.test.ts+++ b/cli/src/plugins/env/index.test.ts@@ -23,6 +23,17 @@ it('rejects a token without a server with exit 2', async () => {await expect(new Context().get(env)).rejects.toMatchObject({ code: 'usage_invalid_flag' })})+it('names the rename when the v1 DIFY_HOST stands in for DIFY_SERVER', async () => {+ delete process.env.DIFY_SERVER+ process.env.DIFY_HOST = 'https://dify.example'+ process.env.DIFY_TOKEN = 'dfoa_x'+ await expect(new Context().get(env)).rejects.toMatchObject({+ code: 'usage_invalid_flag',+ message: 'DIFY_TOKEN requires DIFY_SERVER to be set',+ hint: 'DIFY_HOST was renamed to DIFY_SERVER; set DIFY_SERVER instead',+ })+})+it('rejects a non-http server url', async () => {process.env.DIFY_SERVER = 'ftp://x'await expect(new Context().get(env)).rejects.toMatchObject({ code: 'usage_invalid_flag' })diff --git a/cli/src/plugins/env/index.ts b/cli/src/plugins/env/index.tsindex 7c21d43ba8e..793f37ae432 100644--- a/cli/src/plugins/env/index.ts+++ b/cli/src/plugins/env/index.ts@@ -1,7 +1,7 @@import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { definePlugin } from '@/kernel/plugin'-import { resolveCacheDir, resolveConfigDir } from '@/store/dir'+import { resolveConfigDir } from '@/store/dir'import { getEnv } from '@/sys'export const ENV = {@@ -9,8 +9,11 @@ export const ENV = {Token: 'DIFY_TOKEN',WorkspaceId: 'DIFY_WORKSPACE_ID',ConfigDir: 'DIFY_CONFIG_DIR',- CacheDir: 'DIFY_CACHE_DIR',Output: 'DIFY_OUTPUT',+ // No longer read: the catalog lives in the config folder. Read only to say so.+ CacheDir: 'DIFY_CACHE_DIR',+ // difyctl v1's name for DIFY_SERVER; read only to name the rename.+ V1Host: 'DIFY_HOST',} as constexport type EnvService = Readonly<{@@ -18,7 +21,7 @@ export type EnvService = Readonly<{token?: stringworkspaceId?: stringconfigDir: string- cacheDir: string+ cacheDirSet: boolean}>const HTTP_SCHEMES: readonly string[] = ['http:', 'https:']@@ -54,6 +57,10 @@ export const env = definePlugin({throw new BaseError({code: ErrorCode.UsageInvalidFlag,message: `${ENV.Token} requires ${ENV.Server} to be set`,+ hint:+ getEnv(ENV.V1Host) === undefined+ ? undefined+ : `${ENV.V1Host} was renamed to ${ENV.Server}; set ${ENV.Server} instead`,})}return Object.freeze({@@ -61,7 +68,7 @@ export const env = definePlugin({token,workspaceId: getEnv(ENV.WorkspaceId),configDir: resolveConfigDir(),- cacheDir: resolveCacheDir(),+ cacheDirSet: getEnv(ENV.CacheDir) !== undefined,})},})diff --git a/cli/src/plugins/global-flags/index.ts b/cli/src/plugins/global-flags/index.tsindex 57a61f1faa0..050e8fb4770 100644--- a/cli/src/plugins/global-flags/index.ts+++ b/cli/src/plugins/global-flags/index.ts@@ -4,6 +4,7 @@ import { ErrorCode } from '@/errors/codes'import { definePlugin } from '@/kernel/plugin'import { argv } from '@/plugins/argv'import { inputSchema, parseArgv, partitionArgv } from '@/plugins/argv/parse'+import { flagToken } from '@/util/flag-name'export const GLOBAL_INPUT = z.object({verbose: z.boolean().default(false).describe('Keep the raw server response in error envelopes'),@@ -21,7 +22,7 @@ const NO_POSITIONALS: readonly string[] = []function invalidGlobalFlags(error: z.ZodError): BaseError {const message = error.issues- .map((issue) => `--${issue.path.join('.')}: ${issue.message}`)+ .map((issue) => `${flagToken(issue.path.join('.'))}: ${issue.message}`).join('; ')return new BaseError({ code: ErrorCode.UsageInvalidFlag, message, cause: error })}diff --git a/cli/src/plugins/http/index.test.ts b/cli/src/plugins/http/index.test.tsindex b3195ee5b0f..f48dcf447a2 100644--- a/cli/src/plugins/http/index.test.ts+++ b/cli/src/plugins/http/index.test.ts@@ -2,7 +2,7 @@ import type { DifyMock } from '@test/fixtures/dify-mock/server'import { mkdtempSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'-import { startMock } from '@test/fixtures/dify-mock/server'+import { FORBIDDEN_HINT, startMock } from '@test/fixtures/dify-mock/server'import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'import { Context } from '@/kernel/context'import { catalog, CATALOG_PATH } from '@/plugins/catalog'@@ -15,22 +15,20 @@ let mock: DifyMocklet dir: stringfunction writeTimeout(ms: number): void {- writeFileSync(join(dir, CONFIG_FILE_NAME), `schema_version: 1\nhttp:\n timeout: ${ms}\n`)+ writeFileSync(join(dir, CONFIG_FILE_NAME), `http:\n timeout: ${ms}\n`)}beforeEach(async () => {mock = await startMock()dir = mkdtempSync(join(tmpdir(), 'difyctl-http-'))Object.assign(process.env, {DIFY_CONFIG_DIR: dir,- DIFY_CACHE_DIR: dir,DIFY_SERVER: mock.url,DIFY_TOKEN: 'dfoa_test',})})afterEach(async () => {await mock.stop()- for (const k of ['DIFY_CONFIG_DIR', 'DIFY_CACHE_DIR', 'DIFY_SERVER', 'DIFY_TOKEN'])- delete process.env[k]+ for (const k of ['DIFY_CONFIG_DIR', 'DIFY_SERVER', 'DIFY_TOKEN']) delete process.env[k]})const account = () => ({ method: 'GET', path: '/openapi/v1/account' })@@ -103,6 +101,35 @@ describe('http plugin', () => {await expect(h.request(account)).rejects.toMatchObject({ code: 'rate_limited' })})+ it('a 401 says to log in again', async () => {+ const h = await new Context().get(http)+ mock.setScenario('auth-expired')+ await expect(h.request(account)).rejects.toMatchObject({ hint: 'run difyctl help login' })+ })++ it("a 403 keeps the server's hint and never says to log in", async () => {+ const h = await new Context().get(http)+ mock.setScenario('forbidden')+ await expect(h.request(account)).rejects.toMatchObject({+ code: 'access_denied',+ message: 'you may not do this',+ hint: FORBIDDEN_HINT,+ })+ })++ it('a 403 without a server hint says permission denied', async () => {+ process.env.DIFY_TOKEN = 'sk-test-resource'+ const h = await new Context().get(http)+ mock.setScenario('resource-token')+ await expect(+ h.request(() => ({ method: 'GET', path: '/openapi/v1/account' })),+ ).rejects.toMatchObject({+ code: 'access_denied',+ httpStatus: 403,+ hint: expect.stringMatching(/^permission denied/),+ })+ })+it('surfaces 5xx as server_error with the server body and details', async () => {const h = await new Context().get(http)mock.setScenario('server-5xx')@@ -166,7 +193,7 @@ describe('http plugin', () => {await expect((await new Context().get(http)).request(account)).rejects.toMatchObject({code: 'catalog_unavailable',message: `failed to fetch the catalog: HTTP 404 from ${CATALOG_PATH}`,- hint: expect.stringContaining('refresh cache'),+ hint: expect.stringContaining('server is reachable'),})})diff --git a/cli/src/plugins/http/index.ts b/cli/src/plugins/http/index.tsindex 1b19931889a..6128f6d747f 100644--- a/cli/src/plugins/http/index.ts+++ b/cli/src/plugins/http/index.ts@@ -12,6 +12,7 @@ import { config } from '@/plugins/config'import { env } from '@/plugins/env'import { session } from '@/plugins/session'import { token } from '@/plugins/token'+import { parseHints } from '@/protocol/hint'import { userAgent } from '@/version/info'export type HttpRequest = Readonly<{@@ -40,7 +41,9 @@ const HttpStatus = {const CATALOG_STALE_CODE = 'catalog_stale'const CATALOG_UNAVAILABLE_PREFIX = 'failed to fetch the catalog: '-const CATALOG_UNAVAILABLE_HINT = 'check the server URL or run difyctl refresh cache'+// `refresh cache` would only repeat the fetch that failed, so it is not suggested.+const CATALOG_UNAVAILABLE_HINT =+ 'check that the saved server URL is right and the server is reachable, then retry'// The catalog fetch is the CLI's first request, so its failure has to name itself:// a rejected status for the catalog route, or whatever the network said.@@ -50,11 +53,15 @@ function catalogFailure(cause: unknown): string {return errorMessage(cause)}-type StatusMapping = Readonly<{ code: ErrorCodeValue; hint?: string }>+const PERMISSION_DENIED_HINT = 'permission denied: this account may not do this'++// `hint` replaces the server's hint; `fallbackHint` only fills in when it sent none.+type StatusMapping = Readonly<{ code: ErrorCodeValue; hint?: string; fallbackHint?: string }>const STATUS_MAPPINGS: Readonly<Record<number, StatusMapping>> = {[HttpStatus.Unauthorized]: { code: ErrorCode.AuthExpired, hint: LOGIN_HINT },- [HttpStatus.Forbidden]: { code: ErrorCode.AccessDenied, hint: LOGIN_HINT },+ // Logging in again does not grant a permission, and `login` revokes the session first.+ [HttpStatus.Forbidden]: { code: ErrorCode.AccessDenied, fallbackHint: PERMISSION_DENIED_HINT },[HttpStatus.TooManyRequests]: { code: ErrorCode.RateLimited },}@@ -75,7 +82,8 @@ function parseServerErrorBody(raw: string): ServerErrorBody | undefined {if (record.code !== undefined && typeof record.code !== 'string') return undefinedconst message = typeof record.message === 'string' ? record.message : record.errorif (typeof message !== 'string') return undefined- return { ...record, message } as ServerErrorBody+ const body = { ...record, message } as ServerErrorBody+ return record.hints === undefined ? body : { ...body, hints: parseHints(record.hints) }}function appendQuery(url: URL, query: HttpRequest['query']): void {@@ -194,11 +202,11 @@ export const http = definePlugin({const rawResponse = await res.text()const serverError = parseServerErrorBody(rawResponse)- const { code, hint } = classifyStatus(res)+ const { code, hint, fallbackHint } = classifyStatus(res)throw new HttpClientError({code,message: serverError?.message ?? `HTTP ${res.status}`,- hint: hint ?? serverError?.hint,+ hint: hint ?? serverError?.hint ?? fallbackHint,httpStatus: res.status,method: req.method,url: url.toString(),diff --git a/cli/src/plugins/ops/command.ts b/cli/src/plugins/ops/command.tsindex 9420ded7c8f..ef7e88e2405 100644--- a/cli/src/plugins/ops/command.ts+++ b/cli/src/plugins/ops/command.ts@@ -58,7 +58,6 @@ export function opCommand(id: string, op: CatalogOp): CommandConstructor {return class OpCommand extends Command {static override summary = op.summarystatic override effect = effectOf(op.method)- static override positional = [] as conststatic override examples = op.examplesstatic override hidden = op.internaldiff --git a/cli/src/plugins/ops/tree.ts b/cli/src/plugins/ops/tree.tsindex 791533dc809..286d26d32a5 100644--- a/cli/src/plugins/ops/tree.ts+++ b/cli/src/plugins/ops/tree.ts@@ -1,7 +1,7 @@import type { CatalogOp } from '@/plugins/catalog'import type { CommandConstructor } from '@/plugins/commands/command'import type { CommandTree } from '@/plugins/commands/registry'-import { OP_SEPARATOR } from '@/protocol/op-id'+import { commandWords } from '@/protocol/op-id'import { opCommand } from './command'// A node is readonly once it is in a tree; building one needs a mutable view of it.@@ -10,7 +10,7 @@ type BuildingNode = { command?: CommandConstructor; subcommands: Record<string,export function opsTree(ops: Readonly<Record<string, CatalogOp>>): CommandTree {const tree: Record<string, BuildingNode> = {}for (const [id, op] of Object.entries(ops)) {- const segments = id.split(OP_SEPARATOR)+ const segments = commandWords(id)let level = treefor (const [index, segment] of segments.entries()) {const node = (level[segment] ??= { subcommands: {} })diff --git a/cli/src/plugins/session/index.test.ts b/cli/src/plugins/session/index.test.tsindex 4e5cae8888c..df39442dea3 100644--- a/cli/src/plugins/session/index.test.ts+++ b/cli/src/plugins/session/index.test.ts@@ -1,10 +1,12 @@import type { Login } from './index'-import { mkdtempSync } from 'node:fs'+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterEach, beforeEach, expect, it } from 'vite-plus/test'import { Context } from '@/kernel/context'-import { session } from './index'+import { io, ioService } from '@/plugins/io'+import { bufferStreams } from '@/sys/io/streams'+import { LOGIN_FILE_NAME, session } from './index'const LOGIN: Login = {server: 'https://d.example',@@ -65,3 +67,43 @@ it('DIFY_WORKSPACE_ID overrides the pin', async () => {process.env.DIFY_WORKSPACE_ID = 'ws-env'expect(await (await new Context().get(session)).workspaceId()).toBe('ws-env')})++function withLoginFile(content: string) {+ writeFileSync(join(dir, LOGIN_FILE_NAME), content)+ const streams = bufferStreams()+ return { streams, load: () => new Context([[io, ioService(streams)]]).get(session) }+}++it.each([+ ['server', 'email: me@x\ntoken_storage: file\n'],+ ['email', 'server: https://d.example\ntoken_storage: file\n'],+])('reads a login.yml without %s as logged out, with one notice', async (key, content) => {+ const { streams, load } = withLoginFile(content)+ const s = await load()+ expect(await s.current()).toBeNull()+ expect(await s.current()).toBeNull()+ expect(streams.errBuf()).toMatch(new RegExp(`has no valid ${key}; ignoring it\n$`))+ await s.save(LOGIN)+ expect(await s.current()).toEqual(LOGIN)+})++it('reads a login.yml with only its identity, defaulting the rest and ignoring unknown keys', async () => {+ const { streams, load } = withLoginFile(+ 'schema_version: 99\nfuture_key: x\nserver: https://d.example\nemail: me@x\ntoken_storage: file\ninsecure: maybe\n',+ )+ expect(await (await load()).current()).toEqual({+ server: 'https://d.example',+ email: 'me@x',+ account: null,+ workspaceId: null,+ tokenStorage: 'file',+ insecure: false,+ })+ expect(streams.errBuf()).toMatch(/ignoring the invalid value of insecure\n$/)+})++it('saves only the current shape', async () => {+ const { load } = withLoginFile('future_key: x\n')+ await (await load()).save(LOGIN)+ expect(readFileSync(join(dir, LOGIN_FILE_NAME), 'utf8')).not.toContain('future_key')+})diff --git a/cli/src/plugins/session/index.ts b/cli/src/plugins/session/index.tsindex ae49873108f..0316c35ee03 100644--- a/cli/src/plugins/session/index.ts+++ b/cli/src/plugins/session/index.ts@@ -4,26 +4,27 @@ import { z } from 'zod'import { BaseError, notLoggedIn } from '@/errors/base'import { ErrorCode } from '@/errors/codes'import { definePlugin } from '@/kernel/plugin'-import { env } from '@/plugins/env'-import { STORAGE_MODES, YamlStore } from '@/store/store'+import { ENV, env } from '@/plugins/env'+import { io } from '@/plugins/io'+import { localFile } from '@/store/local-file'+import { STORAGE_MODES } from '@/store/store'export const LOGIN_FILE_NAME = 'login.yml'-export const LOGIN_SCHEMA_VERSION = 1export const ENV_LOGIN_EMAIL = 'env'-const ACCOUNT_SCHEMA = z.object({ id: z.string(), email: z.string(), name: z.string() })+const LOGIN_SCHEMA = z.object({+ server: z.string(),+ email: z.string(),+ token_storage: z.enum(STORAGE_MODES),+ account: z+ .object({ id: z.string(), email: z.string(), name: z.string() })+ .nullable()+ .default(null),+ workspace_id: z.string().nullable().default(null),+ insecure: z.boolean().default(false),+})-const LOGIN_SCHEMA = z- .object({- schema_version: z.literal(LOGIN_SCHEMA_VERSION),- server: z.string(),- email: z.string(),- account: ACCOUNT_SCHEMA.nullable(),- workspace_id: z.string().nullable(),- token_storage: z.enum(STORAGE_MODES),- insecure: z.boolean(),- })- .strict()+type LoginDoc = z.infer<typeof LOGIN_SCHEMA>export type Login = Readonly<{server: string@@ -43,9 +44,8 @@ export type SessionService = {readonly fromEnv: boolean}-function loginToDoc(login: Login): z.infer<typeof LOGIN_SCHEMA> {+function loginToDoc(login: Login): LoginDoc {return {- schema_version: LOGIN_SCHEMA_VERSION,server: login.server,email: login.email,account: login.account,@@ -55,7 +55,7 @@ function loginToDoc(login: Login): z.infer<typeof LOGIN_SCHEMA> {}}-function docToLogin(doc: z.infer<typeof LOGIN_SCHEMA>): Login {+function docToLogin(doc: LoginDoc): Login {return {server: doc.server,email: doc.email,@@ -68,13 +68,16 @@ function docToLogin(doc: z.infer<typeof LOGIN_SCHEMA>): Login {export const session = definePlugin({name: 'session',- needs: [env],+ needs: [env, io],build: async (ctx): Promise<SessionService> => {const { server, token: envToken, workspaceId: envWorkspaceId, configDir } = await ctx.get(env)// An env login is the pair: a server on its own only says where to log in.const fromEnv = server !== undefined && envToken !== undefined- const path = join(configDir, LOGIN_FILE_NAME)- const store = new YamlStore(path)+ const file = localFile(+ join(configDir, LOGIN_FILE_NAME),+ LOGIN_SCHEMA,+ (await ctx.get(io)).notice,+ )const envLogin: Login | null = fromEnv? {@@ -87,17 +90,13 @@ export const session = definePlugin({}: null+ // Read once: a broken file warns on its first read only.+ let saved: Login | null | undefinedasync function readLogin(): Promise<Login | null> {- const raw = await store.getTyped<unknown>()- if (raw === null) return null- const result = LOGIN_SCHEMA.safeParse(raw)- if (!result.success) {- throw new BaseError({- code: ErrorCode.Unknown,- message: `${path} failed validation: ${result.error.issues.map((issue) => issue.message).join('; ')}`,- })- }- return docToLogin(result.data)+ if (saved !== undefined) return saved+ const doc = await file.read()+ saved = doc === null ? null : docToLogin(doc)+ return saved}const current = async (): Promise<Login | null> => envLogin ?? readLogin()@@ -106,7 +105,8 @@ export const session = definePlugin({current,require: async () => {const login = await current()- if (login === null) throw notLoggedIn()+ if (login === null)+ throw notLoggedIn(`no login saved in ${configDir}; ${ENV.ConfigDir} picks this folder`)return login},save: async (login: Login) => {@@ -116,11 +116,13 @@ export const session = definePlugin({message: 'cannot save a login while DIFY_SERVER/DIFY_TOKEN are set',})}- await store.setTyped(loginToDoc(login))+ await file.write(loginToDoc(login))+ saved = login},clear: async () => {if (fromEnv) return- await store.rm()+ await file.remove()+ saved = null},workspaceId: async () => {if (envWorkspaceId !== undefined) return envWorkspaceIddiff --git a/cli/src/plugins/token/index.ts b/cli/src/plugins/token/index.tsindex e8fdb874be1..735ca940d9c 100644--- a/cli/src/plugins/token/index.ts+++ b/cli/src/plugins/token/index.ts@@ -1,12 +1,19 @@import type { Login } from '@/plugins/session'import type { StorageMode } from '@/store/store'+import type { TokenStore } from '@/store/token-store'+import { join } from 'node:path'import { notLoggedIn } from '@/errors/base'import { definePlugin } from '@/kernel/plugin'import { env } from '@/plugins/env'+import { io } from '@/plugins/io'import { session } from '@/plugins/session'+import { localFile } from '@/store/local-file'import { detectTokenStore, getTokenStore } from '@/store/manager'+import { TOKENS_SCHEMA } from '@/store/token-store'import { bareHost } from '@/util/host'+export const TOKENS_FILE_NAME = 'tokens.yml'+export type DetectOptions = Readonly<{ skipKeyring: boolean }>export type TokenService = {@@ -14,21 +21,28 @@ export type TokenService = {readonly write: (login: Login, bearer: string) => Promise<void>readonly remove: (login: Login) => Promise<void>readonly detect: (opts: DetectOptions) => Promise<StorageMode>+ readonly store: (mode: StorageMode) => TokenStore}export const token = definePlugin({name: 'token',- needs: [env, session],+ needs: [env, session, io],build: async (ctx): Promise<TokenService> => {- const { token: envToken } = await ctx.get(env)+ const { token: envToken, configDir } = await ctx.get(env)const sessionService = await ctx.get(session)+ const file = localFile(+ join(configDir, TOKENS_FILE_NAME),+ TOKENS_SCHEMA,+ (await ctx.get(io)).notice,+ )let cached: string | undefined+ const store = (mode: StorageMode): TokenStore => getTokenStore(mode, { file })+async function readFromStore(): Promise<string> {const login = await sessionService.require()- const store = getTokenStore(login.tokenStorage)- return store.read(bareHost(login.server), login.email)+ return store(login.tokenStorage).read(bareHost(login.server), login.email)}return {@@ -39,16 +53,15 @@ export const token = definePlugin({return cached},write: async (login: Login, bearer: string) => {- const store = getTokenStore(login.tokenStorage)- await store.write(bareHost(login.server), login.email, bearer)+ await store(login.tokenStorage).write(bareHost(login.server), login.email, bearer)cached = bearer},remove: async (login: Login) => {- const store = getTokenStore(login.tokenStorage)- await store.remove(bareHost(login.server), login.email)+ await store(login.tokenStorage).remove(bareHost(login.server), login.email)cached = ''},- detect: async (opts) => (await detectTokenStore(opts)).mode,+ detect: async (opts) => (await detectTokenStore({ ...opts, file })).mode,+ store,}},})diff --git a/cli/src/protocol/fold.ts b/cli/src/protocol/fold.tsindex 225f582ce2d..e4b66b7bafb 100644--- a/cli/src/protocol/fold.ts+++ b/cli/src/protocol/fold.ts@@ -1,12 +1,7 @@+import type { Hint } from '@/protocol/hint'+import { parseHints } from '@/protocol/hint'import { isRecord } from '@/util/is-record'-export type Hint = {- summary: string- op: string- input: Record<string, unknown>- form?: unknown-}-export type FoldResult = {status: FoldStatustext: { answer: string; by_source?: Record<string, string> }@@ -14,6 +9,7 @@ export type FoldResult = {total_tokens?: numbermessage_id?: stringconversation_id?: string+ run_id?: stringerror?: { message: string; code?: string }hints: Hint[]}@@ -51,7 +47,7 @@ function asString(value: unknown): string | undefined {}function appendHints(result: FoldResult, hints: unknown): void {- if (Array.isArray(hints)) result.hints.push(...(hints as Hint[]))+ result.hints.push(...parseHints(hints))}function appendAnswer(result: FoldResult, event: Record<string, unknown>): void {@@ -113,6 +109,12 @@ function markError(result: FoldResult, event: Record<string, unknown>): void {raise(result, FOLD_STATUS.Failed)}+/** Runs for every event before its own handler: any workflow event names its run. */+export const foldAnyEvent: EventHandler = (result, event) => {+ const runId = asString(event.workflow_run_id)+ if (runId !== undefined) result.run_id = runId+}+export const FOLD_TABLE: Readonly<Record<string, EventHandler>> = Object.freeze({message: appendAnswer,agent_message: appendAnswer,diff --git a/cli/src/protocol/hint.test.ts b/cli/src/protocol/hint.test.tsnew file mode 100644index 00000000000..2ff29565a69--- /dev/null+++ b/cli/src/protocol/hint.test.ts@@ -0,0 +1,16 @@+import { expect, it } from 'vite-plus/test'+import { parseHints } from './hint'++it('keeps only hints with a string op and summary', () => {+ const good = { op: 'get.app', summary: 'list apps', input: {} }+ expect(parseHints([good, { summary: 'no op' }, { op: 1, summary: 'x' }, 'text', null])).toEqual([+ good,+ ])+})++it.each([undefined, null, 'hints', { op: 'get.app', summary: 'x' }])(+ 'reads %j as no hints',+ (value) => {+ expect(parseHints(value)).toEqual([])+ },+)diff --git a/cli/src/protocol/hint.ts b/cli/src/protocol/hint.tsnew file mode 100644index 00000000000..9708c810616--- /dev/null+++ b/cli/src/protocol/hint.ts@@ -0,0 +1,16 @@+import { isRecord } from '@/util/is-record'++export type Hint = {+ summary: string+ op: string+ input?: Record<string, unknown>+ form?: unknown+}++function isHint(value: unknown): value is Hint {+ return isRecord(value) && typeof value.op === 'string' && typeof value.summary === 'string'+}++export function parseHints(value: unknown): Hint[] {+ return Array.isArray(value) ? value.filter(isHint) : []+}diff --git a/cli/src/protocol/op-id.ts b/cli/src/protocol/op-id.tsindex 308621a81f9..9a35cb58c80 100644--- a/cli/src/protocol/op-id.ts+++ b/cli/src/protocol/op-id.ts@@ -1,9 +1,13 @@export const OP_SEPARATOR = '.'export const COMMAND_SEPARATOR = ' '+export function commandWords(id: string): readonly string[] {+ return id.split(OP_SEPARATOR)+}+/** An op id as the words it is typed as: `get.console_app` -> `get console_app`. */export function spacedId(id: string): string {- return id.split(OP_SEPARATOR).join(COMMAND_SEPARATOR)+ return commandWords(id).join(COMMAND_SEPARATOR)}export function dottedId(path: readonly string[]): string {diff --git a/cli/src/protocol/shape.test.ts b/cli/src/protocol/shape.test.tsindex 99847da1ff0..7dd81587884 100644--- a/cli/src/protocol/shape.test.ts+++ b/cli/src/protocol/shape.test.ts@@ -18,7 +18,9 @@ it.each([[nullable({ type: 'string', enum: ['x'] }), SHAPE.Enum, 'x'],[{ enum: [] }, SHAPE.Json, 'json'],[{ type: 'string', enum: [] }, SHAPE.Json, 'json'],- [{ oneOf: [{ type: 'string' }, { type: 'integer' }] }, SHAPE.Json, 'json'],+ [{ oneOf: [{ type: 'string' }, { type: 'integer' }] }, SHAPE.Union, 'string | integer'],+ [{ anyOf: [{ type: 'string' }, { type: 'integer' }] }, SHAPE.Union, 'string | integer'],+ [{ anyOf: [{ type: 'string' }], oneOf: [{ type: 'integer' }] }, SHAPE.Json, 'json'],[{ someFutureKeyword: true }, SHAPE.Json, 'json'],])('%j classifies as %s labelled %s', (schema, shape, label) => {const node = shapeOf(schema)diff --git a/cli/src/protocol/shape.ts b/cli/src/protocol/shape.tsindex 325f06e47e9..f2cce705d58 100644--- a/cli/src/protocol/shape.ts+++ b/cli/src/protocol/shape.ts@@ -12,9 +12,15 @@ export const SHAPE = {Map: 'map',Object: 'object',Json: 'json',+ Union: 'union',} as constexport type Shape = (typeof SHAPE)[keyof typeof SHAPE]-export type ShapeNode = Readonly<{ shape: Shape; item?: ShapeNode; values?: readonly string[] }>+export type ShapeNode = Readonly<{+ shape: Shape+ item?: ShapeNode+ values?: readonly string[]+ alternatives?: readonly ShapeNode[]+}>type Coercion = (raw: string) => unknown@@ -24,7 +30,7 @@ const ARRAY_TYPE = 'array'const OBJECT_TYPE = 'object'const STRING_TYPE = 'string'const FILE_REF_PREFIX = '@'-const ENUM_SEPARATOR = ' | '+const ALTERNATIVE_SEPARATOR = ' | 'const BOOLEAN_LITERALS: Readonly<Record<string, boolean>> = { true: true, false: false }const keepRaw: Coercion = (raw) => raw@@ -64,7 +70,7 @@ const SHAPE_INFO: Readonly<Record<Shape, ShapeInfo>> = {[SHAPE.Number]: { label: () => SHAPE.Number, coerce: () => toNumber, scalar: true },[SHAPE.Boolean]: { label: () => SHAPE.Boolean, coerce: () => toBoolean, scalar: true },[SHAPE.Enum]: {- label: (n) => (n.values ?? []).join(ENUM_SEPARATOR),+ label: (n) => (n.values ?? []).join(ALTERNATIVE_SEPARATOR),coerce: () => keepRaw,scalar: true,},@@ -81,19 +87,28 @@ const SHAPE_INFO: Readonly<Record<Shape, ShapeInfo>> = {},[SHAPE.Object]: { label: () => SHAPE.Object, coerce: () => toJson, scalar: false },[SHAPE.Json]: { label: () => SHAPE.Json, coerce: () => toJson, scalar: false },+ [SHAPE.Union]: {+ label: (n) => (n.alternatives ?? []).map(labelOf).join(ALTERNATIVE_SEPARATOR),+ coerce: () => toJson,+ scalar: false,+ },}-// pydantic optional: anyOf [T, null]. Anything else with anyOf is json.-function unwrapNullable(schema: JsonSchema): JsonSchema | undefined {- const branches = schema.anyOf- if (!Array.isArray(branches) || branches.length !== 2) return undefined- const real = branches.filter((b) => !(isRecord(b) && b.type === NULL_TYPE))- return real.length === 1 && isRecord(real[0]) ? (real[0] as JsonSchema) : undefined+// One list of branches, from anyOf or oneOf. A schema with both is not one union, so it+// reads as no alternatives and falls through to its type.+function alternativesOf(schema: JsonSchema): JsonSchema[] {+ const lists = [schema.anyOf, schema.oneOf].filter(Array.isArray)+ const [branches] = lists+ if (lists.length !== 1 || branches === undefined) return []+ return branches.filter((b) => isRecord(b) && b.type !== NULL_TYPE) as JsonSchema[]}export function shapeOf(schema: JsonSchema): ShapeNode {- const inner = unwrapNullable(schema)- if (inner !== undefined) return shapeOf(inner)+ const alternatives = alternativesOf(schema)+ const [only] = alternatives+ if (alternatives.length === 1 && only !== undefined) return shapeOf(only)+ if (alternatives.length > 1)+ return { shape: SHAPE.Union, alternatives: alternatives.map(shapeOf) }const type = typeof schema.type === 'string' ? schema.type : undefined// An enum with no members names no value at all, so it degrades to json rather than// labelling as the empty string.diff --git a/cli/src/skills/collection.ts b/cli/src/skills/collection.tsdeleted file mode 100644index 88bf0918ba3..00000000000--- a/cli/src/skills/collection.ts+++ /dev/null@@ -1,76 +0,0 @@-import type { SkillEntry, SkillSource } from './source'-import { posix } from 'node:path'-import { BaseError } from '@/errors/base'-import { ErrorCode } from '@/errors/codes'-import { parseFrontmatter } from './frontmatter'-import { SKILL_FILE } from './source'--export const BASIC_SKILL = 'difyctl'-const ROOT_DIR = '.'-const SKILL_NAME_RE = /^[a-z0-9-]{1,64}$/--export type Skill = {- readonly name: string- readonly description: string- readonly dir: string- readonly files: readonly SkillEntry[]-}--function skillDirs(entries: readonly SkillEntry[]): string[] {- const dirs = entries- .filter(- (entry) => entry.path.split('/').length <= 2 && posix.basename(entry.path) === SKILL_FILE,- )- .map((entry) => posix.dirname(entry.path))- return dirs.includes(ROOT_DIR) ? [ROOT_DIR] : dirs-}--function filesIn(entries: readonly SkillEntry[], dir: string): SkillEntry[] {- return entries- .filter((entry) => dir === ROOT_DIR || entry.path.startsWith(`${dir}/`))- .map((entry) => ({- ...entry,- path: dir === ROOT_DIR ? entry.path : entry.path.slice(dir.length + 1),- }))-}--async function loadSkill(source: SkillSource, dir: string): Promise<Skill> {- const path = posix.join(dir, SKILL_FILE)- const meta = parseFrontmatter(new TextDecoder().decode(await source.read(path)))- const { name, description } = meta- if (typeof name !== 'string' || !SKILL_NAME_RE.test(name) || typeof description !== 'string') {- throw new BaseError({- code: ErrorCode.ServerError,- message: `${path}: frontmatter needs a name (lowercase letters, digits, dashes) and a description`,- })- }- return { name, description, dir, files: filesIn(source.entries, dir) }-}--export async function loadSkills(source: SkillSource): Promise<Skill[]> {- const skills = await Promise.all(skillDirs(source.entries).map((dir) => loadSkill(source, dir)))- if (skills.length === 0) {- throw new BaseError({- code: ErrorCode.UsageInvalidFlag,- message: 'no skills found',- hint: 'point --from at a folder of skills, or at one skill folder',- })- }- return skills-}--export function isScenario(skill: Skill): boolean {- return skill.name !== BASIC_SKILL-}--export function findSkill(skills: readonly Skill[], name: string): Skill {- const skill = skills.find((candidate) => candidate.name === name)- if (skill === undefined) {- throw new BaseError({- code: ErrorCode.UsageInvalidFlag,- message: `unknown skill "${name}"`,- hint: `known skills: ${skills.map((candidate) => candidate.name).join(', ')}`,- })- }- return skill-}diff --git a/cli/src/skills/frontmatter.ts b/cli/src/skills/frontmatter.tsdeleted file mode 100644index adcdc0885f7..00000000000--- a/cli/src/skills/frontmatter.ts+++ /dev/null@@ -1,19 +0,0 @@-import { load } from 'js-yaml'-import { isRecord } from '@/util/is-record'--const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/--export type Frontmatter = { readonly head: string; readonly body: string }--export function splitFrontmatter(text: string): Frontmatter | undefined {- const match = FRONTMATTER_RE.exec(text)- if (match === null) return undefined- return { head: match[1] as string, body: text.slice(match[0].length) }-}--export function parseFrontmatter(text: string): Record<string, unknown> {- const split = splitFrontmatter(text)- if (split === undefined) return {}- const doc: unknown = load(split.head)- return isRecord(doc) ? doc : {}-}diff --git a/cli/src/skills/github.ts b/cli/src/skills/github.tsdeleted file mode 100644index 6a5c9901dd9..00000000000--- a/cli/src/skills/github.ts+++ /dev/null@@ -1,112 +0,0 @@-import type { SkillSource } from './source'-import { createHash } from 'node:crypto'-import { z } from 'zod'-import { BaseError } from '@/errors/base'-import { ErrorCode } from '@/errors/codes'-import { buildFetchInit } from '@/net/fetch-init'-import { proxyDispatcher } from '@/net/proxy'-import { getEnv } from '@/sys'--export const GITHUB_ORIGIN = 'https://github.com'-const API_ORIGIN = 'https://api.github.com'-const RAW_ORIGIN = 'https://raw.githubusercontent.com'-const TREE_SEGMENT = 'tree'-const DEFAULT_REF = 'HEAD'-const TOKEN_ENV = 'GITHUB_TOKEN'-const RATE_LIMIT_HEADER = 'x-ratelimit-remaining'-const TOO_MANY_REQUESTS = 429-const EXECUTABLE_MODE = '100755'-const FILE_MODES: readonly string[] = ['100644', EXECUTABLE_MODE]-const FROM_HINT = 'check --from, or download the skills folder and pass --from <folder>'--const TREE_SCHEMA = z.object({- truncated: z.boolean(),- tree: z.array(z.object({ path: z.string(), mode: z.string(), sha: z.string() })),-})--export type GitHubFolder = {- readonly owner: string- readonly repo: string- readonly ref: string- readonly path: string-}--export function parseGitHubUrl(url: string): GitHubFolder {- const [owner, repo, segment, ref, ...rest] = new URL(url).pathname.split('/').filter(Boolean)- const tree = segment === undefined || (segment === TREE_SEGMENT && ref !== undefined)- if (owner === undefined || repo === undefined || !tree) {- throw new BaseError({- code: ErrorCode.UsageInvalidFlag,- message: `unsupported GitHub URL "${url}"`,- hint: `use ${GITHUB_ORIGIN}/<owner>/<repo>/tree/<ref>/<folder>`,- })- }- return { owner, repo, ref: ref ?? DEFAULT_REF, path: rest.join('/') }-}--async function get(url: string, token?: string): Promise<Response> {- const headers = token === undefined ? undefined : { authorization: `Bearer ${token}` }- let res: Response- try {- res = await fetch(- url,- buildFetchInit({ headers }, { insecure: false, dispatcher: proxyDispatcher() }),- )- } catch (cause) {- throw new BaseError({- code: ErrorCode.NetworkConnection,- message: `GET ${url} failed`,- hint: FROM_HINT,- cause,- })- }- if (res.ok) return res- const limited = res.status === TOO_MANY_REQUESTS || res.headers.get(RATE_LIMIT_HEADER) === '0'- throw new BaseError({- code: limited ? ErrorCode.RateLimited : ErrorCode.ServerError,- message: `GET ${url} returned ${res.status}`,- hint: limited ? `set ${TOKEN_ENV} to raise GitHub's rate limit, or ${FROM_HINT}` : FROM_HINT,- })-}--function gitBlobSha(bytes: Uint8Array): string {- return createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex')-}--export async function openGitHub(url: string): Promise<SkillSource> {- const { owner, repo, ref, path } = parseGitHubUrl(url)- const treeUrl = `${API_ORIGIN}/repos/${owner}/${repo}/git/trees/${encodeURIComponent(`${ref}:${path}`)}?recursive=1`- const parsed = TREE_SCHEMA.safeParse(await (await get(treeUrl, getEnv(TOKEN_ENV))).json())- if (!parsed.success)- throw new BaseError({- code: ErrorCode.ServerError,- message: `unexpected response from ${treeUrl}`,- })- if (parsed.data.truncated) {- throw new BaseError({- code: ErrorCode.UsageInvalidFlag,- message: `${url} holds too many files to list`,- hint: 'point --from at the skills folder',- })- }- const files = parsed.data.tree.filter((entry) => FILE_MODES.includes(entry.mode))- const shas = new Map(files.map((entry) => [entry.path, entry.sha]))- return {- entries: files.map((entry) => ({- path: entry.path,- executable: entry.mode === EXECUTABLE_MODE,- })),- read: async (file) => {- const rawUrl = [RAW_ORIGIN, owner, repo, ref, path, file].filter(Boolean).join('/')- const bytes = new Uint8Array(await (await get(rawUrl)).arrayBuffer())- if (gitBlobSha(bytes) !== shas.get(file)) {- throw new BaseError({- code: ErrorCode.ServerError,- message: `${rawUrl} changed during the install`,- hint: 'retry in a few minutes',- })- }- return bytes- },- }-}diff --git a/cli/src/skills/install.test.ts b/cli/src/skills/install.test.tsindex 0f04c9a2e94..7fa38052b14 100644--- a/cli/src/skills/install.test.ts+++ b/cli/src/skills/install.test.ts@@ -1,13 +1,9 @@-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'-import { tmpdir } from 'node:os'+import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'+import { platform, tmpdir } from 'node:os'import { dirname, join } from 'node:path'-import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'-import { ErrorCode } from '@/errors/codes'-import { BASIC_SKILL, loadSkills } from './collection'-import { installSkills, selectSkills } from './install'-import { openSource } from './source'--const SCENARIO = 'difyctl-demo'+import { afterEach, beforeEach, expect, it } from 'vite-plus/test'+import { installSkill } from './install'+import { openDir, SKILL_FILE, SKILL_NAME } from './source'let tmp: stringlet from: string@@ -19,47 +15,32 @@ async function put(path: string, text: string): Promise<void> {await writeFile(abs, text)}-function skillMd(name: string): string {- return `---\nname: ${name}\ndescription: ${name} skill\n---\n\n# ${name}\n`-}-beforeEach(async () => {- tmp = await mkdtemp(join(tmpdir(), 'difyctl-skills-'))+ tmp = await mkdtemp(join(tmpdir(), 'difyctl-skill-'))from = join(tmp, 'source')root = join(tmp, 'root')- await put(`${BASIC_SKILL}/SKILL.md`, skillMd(BASIC_SKILL))- await put(`${SCENARIO}/SKILL.md`, skillMd(SCENARIO))+ await put(SKILL_FILE, `---\nname: ${SKILL_NAME}\ndescription: d\n---\n`)+ await put('references/setup.md', 'setup')})afterEach(async () => {await rm(tmp, { recursive: true, force: true })})-describe('selectSkills', () => {- it('selects the whole collection when no names are given', async () => {- const skills = await loadSkills(await openSource(from))- expect(selectSkills(skills, [])).toEqual(skills)- })-- it('selects the named skills', async () => {- const skills = await loadSkills(await openSource(from))- expect(selectSkills(skills, [BASIC_SKILL]).map((s) => s.name)).toEqual([BASIC_SKILL])- })-- it('rejects an unknown name as a usage error', async () => {- const skills = await loadSkills(await openSource(from))- expect(() => selectSkills(skills, ['nope'])).toThrow(- expect.objectContaining({ code: ErrorCode.UsageInvalidFlag }),- )- })+it('writes every file under <root>/difyctl', async () => {+ const wrote = await installSkill(root, await openDir(from))+ expect(wrote.sort()).toEqual(+ [join(root, SKILL_NAME, SKILL_FILE), join(root, SKILL_NAME, 'references/setup.md')].sort(),+ )+ expect(await readFile(join(root, SKILL_NAME, 'references/setup.md'), 'utf8')).toBe('setup')})-describe('installSkills', () => {- it('writes <root>/<skill>/<file> for every file of every skill', async () => {- const source = await openSource(from)- const basic = selectSkills(await loadSkills(source), [BASIC_SKILL])- const target = join(root, BASIC_SKILL, 'SKILL.md')- expect(await installSkills(root, basic, source)).toEqual([target])- expect(await readFile(target, 'utf8')).toBe(skillMd(BASIC_SKILL))- })-})+it.skipIf(platform() === 'win32')(+ 'keeps the permission bits of files from a local folder',+ async () => {+ await put('scripts/run', 'no shebang')+ await chmod(join(from, 'scripts/run'), 0o755)+ await installSkill(root, await openDir(from))+ expect((await stat(join(root, SKILL_NAME, 'scripts/run'))).mode & 0o111).toBe(0o111)+ },+)diff --git a/cli/src/skills/install.ts b/cli/src/skills/install.tsindex 858be55d546..e28825e49cd 100644--- a/cli/src/skills/install.ts+++ b/cli/src/skills/install.ts@@ -1,37 +1,20 @@-import type { Skill } from './collection'import type { SkillSource } from './source'import { mkdir, rm, writeFile } from 'node:fs/promises'-import { dirname, join, posix } from 'node:path'-import { BASIC_SKILL, findSkill, isScenario } from './collection'+import { dirname, join } from 'node:path'+import { SKILL_NAME } from './source'-const FILE_MODE = 0o644-const EXECUTABLE_MODE = 0o755--export function selectSkills(skills: readonly Skill[], names: readonly string[]): Skill[] {- if (names.length === 0) return [...skills]- const chosen = new Map(names.map((name) => [name, findSkill(skills, name)]))- const basic = skills.find((skill) => skill.name === BASIC_SKILL)- if (basic !== undefined && [...chosen.values()].some(isScenario)) chosen.set(BASIC_SKILL, basic)- return [...chosen.values()]-}--export async function installSkills(- root: string,- skills: readonly Skill[],- source: SkillSource,-): Promise<string[]> {- const downloads = []- for (const skill of skills) {- for (const file of skill.files)- downloads.push({ skill, file, bytes: await source.read(posix.join(skill.dir, file.path)) })- }- for (const skill of skills) await rm(join(root, skill.name), { recursive: true, force: true })+export async function installSkill(root: string, source: SkillSource): Promise<string[]> {+ const files = await Promise.all(+ source.paths.map(async (path) => ({ path, file: await source.read(path) })),+ )+ const target = join(root, SKILL_NAME)+ await rm(target, { recursive: true, force: true })const wrote: string[] = []- for (const { skill, file, bytes } of downloads) {- const path = join(root, skill.name, file.path)- await mkdir(dirname(path), { recursive: true })- await writeFile(path, bytes, { mode: file.executable ? EXECUTABLE_MODE : FILE_MODE })- wrote.push(path)+ for (const { path, file } of files) {+ const abs = join(target, path)+ await mkdir(dirname(abs), { recursive: true })+ await writeFile(abs, file.bytes, { mode: file.mode })+ wrote.push(abs)}return wrote}diff --git a/cli/src/skills/source.ts b/cli/src/skills/source.tsindex 2dc2c33ca9f..63ff4cf65a3 100644--- a/cli/src/skills/source.ts+++ b/cli/src/skills/source.ts@@ -1,76 +1,94 @@-import type { Dirent } from 'node:fs'+import type { EmbeddedFile } from '@/sys'import { readdir, readFile, stat } from 'node:fs/promises'import { join, relative, sep } from 'node:path'+import { fileURLToPath } from 'node:url'import { z } from 'zod'import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'-import { versionInfo } from '@/version/info'-import { GITHUB_ORIGIN, openGitHub } from './github'+import { embeddedFiles, isCompiledBinary } from '@/sys'+export const SKILL_NAME = 'difyctl'export const SKILL_FILE = 'SKILL.md'-const EXECUTABLE_BITS = 0o111-const URL_RE = /^https?:\/\//+const EMBED_PREFIX = `${SKILL_NAME}/`+const REPO_SKILL_DIR = fileURLToPath(new URL(`../../../skills/${EMBED_PREFIX}`, import.meta.url))+const NO_EMBEDDED_SKILL =+ 'this difyctl build has no embedded skill; reinstall difyctl or pass --from <folder>'-export type SkillEntry = { readonly path: string; readonly executable: boolean }+const EXECUTABLE_MODE = 0o755+const FILE_MODE = 0o644+const PERMISSION_BITS = 0o777+const SHEBANG = [0x23, 0x21]++export type SkillFile = {+ readonly bytes: Uint8Array+ readonly mode: number+}export type SkillSource = {- readonly entries: readonly SkillEntry[]- readonly read: (path: string) => Promise<Uint8Array>+ readonly paths: readonly string[]+ readonly read: (path: string) => Promise<SkillFile>}-export const DEFAULT_SOURCE = `${GITHUB_ORIGIN}/langgenius/dify/tree/${versionInfo.commit}/skills`+// Embedded files carry no permission bits, so a script is recognised by its shebang.+function embeddedMode(bytes: Uint8Array): number {+ return SHEBANG.every((byte, i) => bytes[i] === byte) ? EXECUTABLE_MODE : FILE_MODE+}++async function readLocal(abs: string): Promise<SkillFile> {+ const [bytes, info] = await Promise.all([readFile(abs), stat(abs)])+ return { bytes, mode: info.mode & PERMISSION_BITS }+}export const FROM_FIELD = z.string().min(1)- .default(DEFAULT_SOURCE)- .describe('Where the skills come from: a GitHub folder URL or a local folder')+ .optional()+ .describe('A local skill folder to install instead of the one built into difyctl')-async function hasSkillFile(dir: string): Promise<boolean> {- return stat(join(dir, SKILL_FILE)).then(+export async function openDir(root: string): Promise<SkillSource> {+ const found = await stat(join(root, SKILL_FILE)).then(() => true,() => false,)-}--async function walk(root: string, dir: string): Promise<SkillEntry[]> {- const entries: SkillEntry[] = []- for (const entry of await readdir(dir, { recursive: true, withFileTypes: true })) {- if (!entry.isFile()) continue- const abs = join(entry.parentPath, entry.name)- const executable = ((await stat(abs)).mode & EXECUTABLE_BITS) !== 0- entries.push({ path: relative(root, abs).split(sep).join('/'), executable })- }- return entries-}--async function openDir(root: string): Promise<SkillSource> {- let children: Dirent[]- try {- children = await readdir(root, { withFileTypes: true })- } catch (cause) {+ if (!found) {throw new BaseError({code: ErrorCode.UsageInvalidFlag,- message: `cannot read folder "${root}"`,- cause,+ message: `no ${SKILL_FILE} in "${root}"`,})}- const dirs = (await hasSkillFile(root))- ? [root]- : children.filter((child) => child.isDirectory()).map((child) => join(root, child.name))- const entries: SkillEntry[] = []- for (const dir of dirs) if (await hasSkillFile(dir)) entries.push(...(await walk(root, dir)))- return { entries, read: (path) => readFile(join(root, path)) }+ const paths: string[] = []+ for (const entry of await readdir(root, { recursive: true, withFileTypes: true })) {+ if (entry.isFile())+ paths.push(relative(root, join(entry.parentPath, entry.name)).split(sep).join('/'))+ }+ return { paths, read: (path) => readLocal(join(root, path)) }}-export function openSource(from: string): Promise<SkillSource> {- if (from.startsWith(`${GITHUB_ORIGIN}/`)) return openGitHub(from)- if (URL_RE.test(from)) {- throw new BaseError({- code: ErrorCode.UsageInvalidFlag,- message: `unsupported --from URL "${from}"`,- hint: `use a ${GITHUB_ORIGIN} folder URL or a local folder`,- })+function embeddedSource(files: readonly EmbeddedFile[]): SkillSource {+ const byPath = new Map(files.map((file) => [file.name.slice(EMBED_PREFIX.length), file]))+ return {+ paths: [...byPath.keys()],+ read: async (path) => {+ const file = byPath.get(path)+ if (file === undefined)+ throw new BaseError({+ code: ErrorCode.SkillMissing,+ message: `the embedded skill has no ${path}`,+ })+ const bytes = new Uint8Array(await file.arrayBuffer())+ return { bytes, mode: embeddedMode(bytes) }+ },}- return openDir(from)+}++async function defaultSource(): Promise<SkillSource> {+ const files = embeddedFiles().filter((file) => file.name.startsWith(EMBED_PREFIX))+ if (files.length > 0) return embeddedSource(files)+ if (isCompiledBinary())+ throw new BaseError({ code: ErrorCode.SkillMissing, message: NO_EMBEDDED_SKILL })+ return openDir(REPO_SKILL_DIR)+}++export function openSource(from: string | undefined): Promise<SkillSource> {+ return from === undefined ? defaultSource() : openDir(from)}diff --git a/cli/src/store/dir.ts b/cli/src/store/dir.tsindex 3917417e28b..e7e7465db35 100644--- a/cli/src/store/dir.ts+++ b/cli/src/store/dir.ts@@ -1,16 +1,9 @@import { getEnv, resolvePlatform } from '@/sys'export const ENV_CONFIG_DIR = 'DIFY_CONFIG_DIR'-export const ENV_CACHE_DIR = 'DIFY_CACHE_DIR'export const FILE_PERM = 0o600export const DIR_PERM = 0o700-export function resolveCacheDir(): string {- const override = getEnv(ENV_CACHE_DIR)- if (override !== undefined && override !== '') return override- return resolvePlatform().cacheDir()-}-export function resolveConfigDir(): string {const override = getEnv(ENV_CONFIG_DIR)if (override !== undefined && override !== '') return overridediff --git a/cli/src/store/keychain-token-store.test.ts b/cli/src/store/keychain-token-store.test.tsindex 685660b3e9e..879b599a069 100644--- a/cli/src/store/keychain-token-store.test.ts+++ b/cli/src/store/keychain-token-store.test.ts@@ -72,7 +72,7 @@ describe('KeychainTokenStore', () => {await expect(store.remove('h', 'absent')).resolves.not.toThrow()})- it('uses the legacy entry name tokens.<host>.<email> (back-compat)', async () => {+ it('names the entry tokens.<host>.<email>', async () => {const store = new KeychainTokenStore(SERVICE)await store.write('https://cloud.dify.ai', '[email protected]', 'dfoa_secret')expect(constructed).toContainEqual({@@ -131,3 +131,11 @@ describe('KeychainTokenStore', () => {expect((caught as BaseError).code).toBe(ErrorCode.KeyringUnavailable)})})++it('a locked keychain points at login --no-keyring', async () => {+ getPasswordError = new Error('keyring locked')+ await expect(new KeychainTokenStore(SERVICE).read('h', 'e')).rejects.toMatchObject({+ code: ErrorCode.KeyringUnavailable,+ hint: expect.stringContaining('login --server <url> --no-keyring'),+ })+})diff --git a/cli/src/store/keyring-based-store.test.ts b/cli/src/store/keyring-based-store.test.tsdeleted file mode 100644index df11d3832e1..00000000000--- a/cli/src/store/keyring-based-store.test.ts+++ /dev/null@@ -1,102 +0,0 @@-import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'--const passwords = new Map<string, string>()-const setPassword = vi.fn()-const getPassword = vi.fn()-const deletePassword = vi.fn()--class FakeEntry {- private readonly key: string- constructor(service: string, username: string) {- this.key = `${service}::${username}`- }-- async setPassword(value: string): Promise<void> {- setPassword(this.key, value)- passwords.set(this.key, value)- }-- async getPassword(): Promise<string | undefined> {- getPassword(this.key)- return passwords.get(this.key) ?? undefined- }-- async deletePassword(): Promise<boolean> {- deletePassword(this.key)- if (!passwords.has(this.key)) return false- passwords.delete(this.key)- return true- }-}--vi.mock('@napi-rs/keyring', () => ({- AsyncEntry: FakeEntry,-}))--const { KeyringBasedStore } = await import('./store')--const SERVICE = 'difyctl-test'--beforeEach(() => {- passwords.clear()- setPassword.mockClear()- getPassword.mockClear()- deletePassword.mockClear()-})--describe('KeyringBasedStore', () => {- it('returns default when entry missing', async () => {- const s = new KeyringBasedStore(SERVICE)- expect(await s.get({ key: 'k', default: 'fallback' })).toBe('fallback')- })-- it('round-trips strings via JSON encoding', async () => {- const s = new KeyringBasedStore(SERVICE)- await s.set({ key: 'k', default: '' }, 'tok-abc')- expect(await s.get({ key: 'k', default: '' })).toBe('tok-abc')- })-- it('isolates entries by key', async () => {- const s = new KeyringBasedStore(SERVICE)- await s.set({ key: 'a', default: '' }, 'A')- await s.set({ key: 'b', default: '' }, 'B')- expect(await s.get({ key: 'a', default: '' })).toBe('A')- expect(await s.get({ key: 'b', default: '' })).toBe('B')- })-- it('unset removes the entry', async () => {- const s = new KeyringBasedStore(SERVICE)- await s.set({ key: 'k', default: '' }, 'v')- await s.unset({ key: 'k', default: '' })- expect(await s.get({ key: 'k', default: '' })).toBe('')- })-- it('unset is a no-op when entry missing', async () => {- const s = new KeyringBasedStore(SERVICE)- await expect(s.unset({ key: 'gone', default: '' })).resolves.not.toThrow()- })-- it('swallows getPassword exceptions and returns default', async () => {- const s = new KeyringBasedStore(SERVICE)- getPassword.mockImplementationOnce(() => {- throw new Error('NoEntry')- })- expect(await s.get({ key: 'k', default: 'd' })).toBe('d')- })-- it('swallows unset exceptions', async () => {- const s = new KeyringBasedStore(SERVICE)- deletePassword.mockImplementationOnce(() => {- throw new Error('NoEntry')- })- await expect(s.unset({ key: 'k', default: '' })).resolves.not.toThrow()- })-- it('lets set propagate exceptions (caller decides fallback)', async () => {- const s = new KeyringBasedStore(SERVICE)- setPassword.mockImplementationOnce(() => {- throw new Error('keyring locked')- })- await expect(s.set({ key: 'k', default: '' }, 'v')).rejects.toThrow(/keyring locked/)- })-})diff --git a/cli/src/store/local-file.test.ts b/cli/src/store/local-file.test.tsnew file mode 100644index 00000000000..efd3b0a85d8--- /dev/null+++ b/cli/src/store/local-file.test.ts@@ -0,0 +1,71 @@+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { afterEach, beforeEach, expect, it } from 'vite-plus/test'+import { z } from 'zod'+import { localFile } from './local-file'++const SCHEMA = z.object({ name: z.string(), size: z.number().default(1) })++let dir: string+let path: string+beforeEach(() => {+ dir = mkdtempSync(join(tmpdir(), 'difyctl-local-file-'))+ path = join(dir, 'doc.yml')+})+afterEach(() => rmSync(dir, { recursive: true, force: true }))++it('writes the whole file in the schema shape, dropping keys the schema does not know', async () => {+ const file = localFile(path, SCHEMA, () => {})+ await file.write({ name: 'a', size: 2, legacy: true } as z.output<typeof SCHEMA>)+ expect(readFileSync(path, 'utf8')).toBe('name: a\nsize: 2\n')+})++it('refuses to write a document the schema rejects', async () => {+ const file = localFile(path, SCHEMA, () => {})+ await expect(file.write({ name: 1 } as unknown as z.output<typeof SCHEMA>)).rejects.toThrow()+ expect(await file.read()).toBeNull()+})++const NESTED = z.object({+ host: z.string(),+ account: z.object({ id: z.string(), name: z.string() }).optional(),+ tags: z.array(z.object({ key: z.string() })).default([]),+})++function readNested(yaml: string) {+ writeFileSync(path, yaml)+ const notices: string[] = []+ return { notices, doc: localFile(path, NESTED, (text) => notices.push(text)).read() }+}++it('drops a bad nested leaf by dropping the nearest value that exists on its path', async () => {+ const { notices, doc } = readNested('host: h\naccount:\n id: 1\n name: n\n')+ expect(await doc).toEqual({ host: 'h', tags: [] })+ expect(notices).toEqual([+ `${path}: ignoring the invalid value of account.id`,+ `${path}: ignoring the invalid value of account`,+ ])+})++it('drops an optional parent whose required key is missing', async () => {+ const { notices, doc } = readNested('host: h\naccount:\n id: a\n')+ expect(await doc).toEqual({ host: 'h', tags: [] })+ expect(notices).toEqual([`${path}: ignoring the invalid value of account`])+})++it('drops only the bad items of an array', async () => {+ const { doc } = readNested('host: h\ntags:\n - key: a\n - key: 2\n - {}\n - key: d\n')+ expect(await doc).toEqual({ host: 'h', tags: [{ key: 'a' }, { key: 'd' }] })+})++it('drops a parent that is not a mapping at all', async () => {+ const { doc } = readNested('host: h\naccount: plain\n')+ expect(await doc).toEqual({ host: 'h', tags: [] })+})++it('ignores the file when a required top-level key is missing', async () => {+ const { notices, doc } = readNested('account:\n id: a\n name: n\n')+ expect(await doc).toBeNull()+ expect(notices).toEqual([`${path} has no valid host; ignoring it`])+})diff --git a/cli/src/store/local-file.ts b/cli/src/store/local-file.tsnew file mode 100644index 00000000000..1b250f609e5--- /dev/null+++ b/cli/src/store/local-file.ts@@ -0,0 +1,96 @@+import type { z } from 'zod'+import { isRecord } from '@/util/is-record'+import { BadYamlFormatError } from './errors'+import { YamlStore } from './store'++export type Notice = (text: string) => void++type Path = readonly PropertyKey[]++function childOf(container: unknown, key: PropertyKey): unknown {+ if (Array.isArray(container) && typeof key === 'number') return container[key]+ return isRecord(container) && Object.hasOwn(container, key) ? container[key as string] : undefined+}++// The longest prefix of `path` that names a value in `doc`; empty when not even the+// first key exists.+function existing(doc: Record<string, unknown>, path: Path): Path {+ let at: unknown = doc+ for (const [depth, key] of path.entries()) {+ const child = childOf(at, key)+ if (child === undefined) return path.slice(0, depth)+ at = child+ }+ return path+}++function remove(doc: Record<string, unknown>, path: Path): void {+ const last = path.at(-1)+ const parent = path.slice(0, -1).reduce<unknown>(childOf, doc)+ if (Array.isArray(parent)) parent.splice(last as number, 1)+ else if (isRecord(parent)) delete parent[last as string]+}++async function readTolerant<S extends z.ZodType>(+ store: YamlStore,+ schema: S,+ notice: Notice,+): Promise<z.output<S> | null> {+ const path = store.filePath+ let raw: unknown+ try {+ raw = await store.getTyped<unknown>()+ } catch (err) {+ if (!(err instanceof BadYamlFormatError)) throw err+ notice(`${path} is not valid YAML; ignoring it`)+ return null+ }+ if (raw === null) return null+ if (!isRecord(raw)) {+ notice(`${path} is not a YAML mapping; ignoring it`)+ return null+ }+ const doc = structuredClone(raw)+ // One drop per pass: an earlier drop can resolve, move or shift a later issue's path.+ for (;;) {+ const result = schema.safeParse(doc)+ if (result.success) return result.data+ const keys = result.error.issues.map((issue) => issue.path)+ const droppable = keys.map((key) => existing(doc, key)).find((key) => key.length > 0)+ if (droppable === undefined) {+ notice(`${path} has no valid ${keys.map((key) => key.join('.')).join(', ')}; ignoring it`)+ return null+ }+ remove(doc, droppable)+ notice(`${path}: ignoring the invalid value of ${droppable.join('.')}`)+ }+}++export type LocalFile<T> = Readonly<{+ path: string+ read: () => Promise<T | null>+ write: (doc: T) => Promise<void>+ remove: () => Promise<void>+ /** Remove the file only while it still holds a document `matches` accepts. */+ removeIf: (matches: (doc: T) => boolean) => Promise<void>+}>++/** Tolerant read (bad value → default + notice; unusable file → null); write replaces the whole file. */+export function localFile<S extends z.ZodType>(+ path: string,+ schema: S,+ notice: Notice,+): LocalFile<z.output<S>> {+ const store = new YamlStore(path)+ return {+ path,+ read: () => readTolerant(store, schema, notice),+ write: async (doc) => store.setTyped(schema.parse(doc)),+ remove: () => store.rm(),+ removeIf: (matches) =>+ store.rmIf((doc) => {+ const parsed = schema.safeParse(doc)+ return parsed.success && matches(parsed.data)+ }),+ }+}diff --git a/cli/src/store/manager.test.ts b/cli/src/store/manager.test.tsindex 43d534dbfba..f964214281d 100644--- a/cli/src/store/manager.test.ts+++ b/cli/src/store/manager.test.ts@@ -1,6 +1,24 @@import type { TokenStore } from './token-store'-import { describe, expect, it, vi } from 'vite-plus/test'-import { detectTokenStore, getTokenStore } from './manager'+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'+import { localFile } from './local-file'+import { detectTokenStore, getTokenStore, keyringDurable } from './manager'+import { TOKENS_SCHEMA } from './token-store'++const DBUS_SESSION = 'DBUS_SESSION_BUS_ADDRESS'+const sys = vi.hoisted(() => ({ platform: 'darwin' as NodeJS.Platform }))+vi.mock('@/sys', async (importOriginal) => ({+ ...(await importOriginal<typeof import('@/sys')>()),+ platform: () => sys.platform,+}))++const file = localFile('', TOKENS_SCHEMA, () => {})++beforeEach(() => {+ sys.platform = 'darwin'+})+afterEach(() => {+ vi.unstubAllEnvs()+})function memStore(label: string): TokenStore & { _label: string } {const map = new Map<string, string>()@@ -25,6 +43,7 @@ describe('detectTokenStore', () => {const f = memStore('file')const writeSpy = vi.spyOn(k, 'write')const result = await detectTokenStore({+ file,skipKeyring: true,factory: { keyring: () => k, file: () => f },})@@ -37,6 +56,7 @@ describe('detectTokenStore', () => {const k = memStore('keyring')const f = memStore('file')const result = await detectTokenStore({+ file,factory: { keyring: () => k, file: () => f },})expect(result.mode).toBe('keychain')@@ -50,6 +70,7 @@ describe('detectTokenStore', () => {throw new Error('locked')}) as TokenStore['write']const result = await detectTokenStore({+ file,factory: { keyring: () => k, file: () => f },})expect(result.mode).toBe('file')@@ -61,6 +82,7 @@ describe('detectTokenStore', () => {const f = memStore('file')k.read = vi.fn(async () => 'something-else') as TokenStore['read']const result = await detectTokenStore({+ file,factory: { keyring: () => k, file: () => f },})expect(result.mode).toBe('file')@@ -70,6 +92,7 @@ describe('detectTokenStore', () => {it('falls back to file when keyring constructor throws', async () => {const f = memStore('file')const result = await detectTokenStore({+ file,factory: {keyring: () => {throw new Error('no backend')@@ -85,6 +108,7 @@ describe('detectTokenStore', () => {const k = memStore('keyring')const f = memStore('file')await detectTokenStore({+ file,factory: { keyring: () => k, file: () => f },})expect(await k.read('__difyctl_probe__', '__difyctl_probe__')).toBe('')@@ -98,6 +122,7 @@ describe('detectTokenStore', () => {throw new Error('read boom')}) as TokenStore['read']const result = await detectTokenStore({+ file,factory: { keyring: () => k, file: () => f },})expect(removeSpy).toHaveBeenCalledWith('__difyctl_probe__', '__difyctl_probe__')@@ -114,6 +139,7 @@ describe('getTokenStore', () => {throw new Error('probe must never run on the read path')}) as TokenStore['write']const store = getTokenStore('keychain', {+ file,factory: { keyring: () => k, file: () => f },})expect(store).toBe(k)@@ -123,9 +149,36 @@ describe('getTokenStore', () => {const keyringFactory = vi.fn(() => memStore('keyring'))const f = memStore('file')const store = getTokenStore('file', {+ file,factory: { keyring: keyringFactory, file: () => f },})expect(store).toBe(f)expect(keyringFactory).not.toHaveBeenCalled()})})++describe('keyringDurable', () => {+ it.each([+ ['linux', undefined, false],+ ['linux', '', false],+ ['linux', 'unix:path=/run/user/1000/bus', true],+ ['darwin', undefined, true],+ ['win32', undefined, true],+ ['freebsd', undefined, true],+ ] as const)('%s with DBus %o → %s', (platform, dbus, durable) => {+ sys.platform = platform+ vi.stubEnv(DBUS_SESSION, dbus)+ expect(keyringDurable()).toBe(durable)+ })++ it('a non-durable keyring skips the probe and uses the file store', async () => {+ sys.platform = 'linux'+ vi.stubEnv(DBUS_SESSION, undefined)+ const k = memStore('keyring')+ const f = memStore('file')+ const writeSpy = vi.spyOn(k, 'write')+ const result = await detectTokenStore({ file, factory: { keyring: () => k, file: () => f } })+ expect(writeSpy).not.toHaveBeenCalled()+ expect(result.mode).toBe('file')+ })+})diff --git a/cli/src/store/manager.ts b/cli/src/store/manager.tsindex 86b78736a4a..8e8919f635f 100644--- a/cli/src/store/manager.ts+++ b/cli/src/store/manager.ts@@ -1,28 +1,18 @@import type { StorageMode } from './store'-import type { TokenStore } from './token-store'-import { join } from 'node:path'-import { resolveConfigDir } from './dir'-import { YamlStore } from './store'+import type { TokensFile, TokenStore } from './token-store'+import { getEnv, platform } from '@/sys'import { FileTokenStore, KeychainTokenStore } from './token-store'-const TOKENS_FILE = 'tokens.yml'-export const CONFIG_FILE_NAME = 'config.yml'-const KEYRING_SERVICE = 'difyctl'--function getStore(filePath: string): YamlStore {- return new YamlStore(filePath)-}--export function getConfigurationStore(): YamlStore {- return getStore(join(resolveConfigDir(), CONFIG_FILE_NAME))-}+const LINUX = 'linux'+const DBUS_SESSION = 'DBUS_SESSION_BUS_ADDRESS'const PROBE_HOST = '__difyctl_probe__'const PROBE_EMAIL = '__difyctl_probe__'const PROBE_VALUE = 'probe-v1'export type GetTokenStoreOptions = {+ readonly file: TokensFilereadonly factory?: {readonly keyring?: () => TokenStorereadonly file?: () => TokenStore@@ -33,9 +23,16 @@ export type DetectTokenStoreOptions = GetTokenStoreOptions & {readonly skipKeyring?: boolean}+/**+ * Without a DBus session, the Linux keyring falls back to the kernel keyutils+ * store: the probe round-trips, but the token is gone when the session ends.+ */+export function keyringDurable(): boolean {+ return platform() !== LINUX || Boolean(getEnv(DBUS_SESSION))+}+const TOKEN_STORE_OPENERS: Record<StorageMode, (opts: GetTokenStoreOptions) => TokenStore> = {- file: (opts) =>- opts.factory?.file?.() ?? new FileTokenStore(join(resolveConfigDir(), TOKENS_FILE)),+ file: (opts) => opts.factory?.file?.() ?? new FileTokenStore(opts.file),keychain: (opts) => opts.factory?.keyring?.() ?? new KeychainTokenStore(KEYRING_SERVICE),}@@ -45,9 +42,10 @@ const TOKEN_STORE_OPENERS: Record<StorageMode, (opts: GetTokenStoreOptions) => T* only where a credential is about to be written anyway (login).*/export async function detectTokenStore(- opts: DetectTokenStoreOptions = {},+ opts: DetectTokenStoreOptions,): Promise<{ store: TokenStore; mode: StorageMode }> {- if (opts.skipKeyring === true) return { store: TOKEN_STORE_OPENERS.file(opts), mode: 'file' }+ if (opts.skipKeyring === true || !keyringDurable())+ return { store: TOKEN_STORE_OPENERS.file(opts), mode: 'file' }try {const k = TOKEN_STORE_OPENERS.keychain(opts)await k.write(PROBE_HOST, PROBE_EMAIL, PROBE_VALUE)@@ -67,6 +65,6 @@ export async function detectTokenStore(/*** Construct the credential backend the registry already recorded at login.*/-export function getTokenStore(mode: StorageMode, opts: GetTokenStoreOptions = {}): TokenStore {+export function getTokenStore(mode: StorageMode, opts: GetTokenStoreOptions): TokenStore {return TOKEN_STORE_OPENERS[mode](opts)}diff --git a/cli/src/store/store.test.ts b/cli/src/store/store.test.tsindex 0bfaf7e8588..2660d7f6cff 100644--- a/cli/src/store/store.test.ts+++ b/cli/src/store/store.test.ts@@ -1,116 +1,79 @@-import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'+import { existsSync, readFileSync, statSync } from 'node:fs'import { mkdtemp, rm, writeFile } from 'node:fs/promises'import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'-import { BadYamlFormatError, ConcurrentAccessError } from './errors'+import { BadYamlFormatError } from './errors'import { YamlStore } from './store'-describe('YamlStore.doGet', () => {- it('returns default when content is undefined', () => {- const store = new YamlStore('/irrelevant')- expect(store.doGet({ key: 'name', default: 'fallback' })).toBe('fallback')- })+let dir: string+let path: string- it('returns default when content is empty', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('')- expect(store.doGet({ key: 'name', default: 'fallback' })).toBe('fallback')- })+beforeEach(async () => {+ dir = await mkdtemp(join(tmpdir(), 'difyctl-yaml-store-'))+ path = join(dir, 'config.yml')+})- it('returns default when content contains only comments', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('# empty configuration\n')- expect(store.doGet({ key: 'name', default: 'fallback' })).toBe('fallback')- })+afterEach(async () => {+ await rm(dir, { recursive: true, force: true })+})- it('reads a flat key', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('name: alice\n')- expect(store.doGet({ key: 'name', default: '' })).toBe('alice')- })+async function parsed<T = Record<string, unknown>>(content: string): Promise<T | null> {+ await writeFile(path, content)+ return new YamlStore(path).getTyped<T>()+}- it('reads a nested key via dot notation', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('user:\n id: 42\n')- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(42)+describe('YamlStore.getTyped', () => {+ it('returns null when the file does not exist', async () => {+ expect(await new YamlStore(path).getTyped()).toBeNull()})- it('resolves YAML merge keys', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('defaults: &defaults\n format: json\nselected:\n <<: *defaults\n')- expect(store.doGet({ key: 'selected.format', default: '' })).toBe('json')+ it('reads an empty or comment-only file as an empty mapping', async () => {+ expect(await parsed('')).toEqual({})+ expect(await parsed('# empty configuration\n')).toEqual({})})- it('parses timestamp scalars as dates', () => {- const store = new YamlStore('/irrelevant')- const timestamp = '2026-07-10T03:04:05.000Z'- store.setRawContent(`created_at: ${timestamp}\n`)- expect(store.doGet<Date | null>({ key: 'created_at', default: null })).toEqual(- new Date(timestamp),- )+ it('reads nested mappings', async () => {+ expect(await parsed('name: alice\nuser:\n id: 42\n')).toEqual({+ name: 'alice',+ user: { id: 42 },+ })})- it('rejects multiple YAML documents', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('name: alice\n---\nname: bob\n')-- expect(() => store.doGet({ key: 'name', default: '' })).toThrowError(/single document/)+ it('resolves YAML merge keys', async () => {+ const doc = await parsed('defaults: &defaults\n format: json\nselected:\n <<: *defaults\n')+ expect(doc?.selected).toEqual({ format: 'json' })})- it('rejects duplicate mapping keys', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('name: alice\nname: bob\n')-- expect(() => store.doGet({ key: 'name', default: '' })).toThrowError(/duplicated mapping key/)- })-- it('rejects complex mapping keys', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('? [name, region]\n: deployment\n')-- expect(() => store.doGet({ key: 'name', default: '' })).toThrowError(- /does not support complex keys/,- )+ it('parses timestamp scalars as dates', async () => {+ const timestamp = '2026-07-10T03:04:05.000Z'+ expect((await parsed(`created_at: ${timestamp}\n`))?.created_at).toEqual(new Date(timestamp))})- it('parses explicit YAML sets as JavaScript sets', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('features: !!set\n workflow:\n chat:\n')-- expect(store.doGet<Set<string>>({ key: 'features', default: new Set() })).toEqual(+ it('parses explicit YAML sets as JavaScript sets', async () => {+ expect((await parsed('features: !!set\n workflow:\n chat:\n'))?.features).toEqual(new Set(['workflow', 'chat']),)})- it('returns default for a missing flat key', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('name: alice\n')- expect(store.doGet({ key: 'age', default: -1 })).toBe(-1)+ it('rejects multiple YAML documents', async () => {+ await expect(parsed('name: alice\n---\nname: bob\n')).rejects.toThrowError(/single document/)})- it('returns default when an intermediate path segment is absent', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('user:\n name: bob\n')- expect(store.doGet({ key: 'user.address.city', default: 'unknown' })).toBe('unknown')+ it('rejects duplicate mapping keys', async () => {+ await expect(parsed('name: alice\nname: bob\n')).rejects.toThrowError(/duplicated mapping key/)})- it('returns default when an intermediate path segment is a scalar', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('user: scalar\n')- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(0)+ it('rejects complex mapping keys', async () => {+ await expect(parsed('? [name, region]\n: deployment\n')).rejects.toThrowError(+ /does not support complex keys/,+ )})- it('throws BadYamlFormatError with file path, location, and snippet for malformed YAML', () => {- const path = '/irrelevant'- const store = new YamlStore(path)- store.setRawContent('name: alice\nuser:\n id: 42\n bad: indent\n')- let caught: unknown- try {- store.doGet({ key: 'name', default: '' })- } catch (err) {- caught = err- }+ it('throws BadYamlFormatError with file path, location, and snippet for malformed YAML', async () => {+ const caught = await parsed('name: alice\nuser:\n id: 42\n bad: indent\n').catch(+ (err: unknown) => err,+ )expect(caught).toBeInstanceOf(BadYamlFormatError)const msg = (caught as BadYamlFormatError).messageexpect(msg).toContain(path)@@ -119,143 +82,71 @@ describe('YamlStore.doGet', () => {})})-describe('YamlStore.doSet', () => {- it('sets a flat key from empty content', () => {- const store = new YamlStore('/irrelevant')- store.doSet({ key: 'name', default: '' }, 'alice')- expect(store.doGet({ key: 'name', default: '' })).toBe('alice')- })-- it('sets a nested key, creating intermediate objects', () => {- const store = new YamlStore('/irrelevant')- store.doSet({ key: 'user.id', default: 0 }, 42)- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(42)- })-- it('overwrites an existing key without disturbing siblings', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('name: alice\nage: 30\n')- store.doSet({ key: 'name', default: '' }, 'bob')- expect(store.doGet({ key: 'name', default: '' })).toBe('bob')- expect(store.doGet({ key: 'age', default: 0 })).toBe(30)- })-- it('replaces a scalar intermediate with an object when path deepens', () => {- const store = new YamlStore('/irrelevant')- store.setRawContent('user: scalar\n')- store.doSet({ key: 'user.id', default: 0 }, 99)- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(99)- })-})--describe('FileBasedStore.withLock concurrency', () => {- let dir: string-- beforeEach(async () => {- dir = await mkdtemp(join(tmpdir(), 'difyctl-yaml-store-'))- })-- afterEach(async () => {- await rm(dir, { recursive: true, force: true })- })+describe('YamlStore.withLock concurrency', () => {+ const HOLD_MS = 200+ const releaseLater = (store: YamlStore) =>+ new Promise<void>((resolve) => setTimeout(() => void store.unlock().then(resolve), HOLD_MS))- it('second get throws while first holds the lock, succeeds after release', async () => {- const path = join(dir, 'config.yml')+ it('a second read waits while the first holds the lock, then reads', async () => {await writeFile(path, 'key: value\n')-const s1 = new YamlStore(path)const s2 = new YamlStore(path)await s1.lock()+ const [value] = await Promise.all([s2.getTyped(), releaseLater(s1)])- await expect(s2.get({ key: 'key', default: '' })).rejects.toThrow(ConcurrentAccessError)-- await s1.unlock()-- expect(await s2.get({ key: 'key', default: '' })).toBe('value')+ expect(value).toEqual({ key: 'value' })})- it('second set throws while first holds the lock, succeeds after release', async () => {- const path = join(dir, 'config.yml')+ it('a second write waits while the first holds the lock, then writes', async () => {await writeFile(path, 'key: original\n')-const s1 = new YamlStore(path)const s2 = new YamlStore(path)await s1.lock()+ await Promise.all([s2.setTyped({ key: 'written' }), releaseLater(s1)])- await expect(s2.set({ key: 'key', default: '' }, 'blocked')).rejects.toThrow(- ConcurrentAccessError,- )-- await s1.unlock()-- await s2.set({ key: 'key', default: '' }, 'written')- expect(await s2.get({ key: 'key', default: '' })).toBe('written')+ expect(await s2.getTyped()).toEqual({ key: 'written' })})})-describe('YamlStore persistence', () => {- let dir: string-- beforeEach(async () => {- dir = await mkdtemp(join(tmpdir(), 'difyctl-yaml-store-'))+describe('YamlStore.rmIf', () => {+ it('removes the file when the predicate accepts what it holds', async () => {+ await writeFile(path, 'device_code: dc-1\n')+ await new YamlStore(path).rmIf((doc) => doc?.device_code === 'dc-1')+ expect(existsSync(path)).toBe(false)})- afterEach(async () => {- await rm(dir, { recursive: true, force: true })+ it('keeps the file when it holds something else', async () => {+ await writeFile(path, 'device_code: dc-2\n')+ await new YamlStore(path).rmIf((doc) => doc?.device_code === 'dc-1')+ expect(readFileSync(path, 'utf8')).toBe('device_code: dc-2\n')})- it('round-trips a flat value through disk', async () => {- const path = join(dir, 'config.yml')- await writeFile(path, '')-- const s1 = new YamlStore(path)- s1.setRawContent('')- s1.doSet({ key: 'workspace', default: '' }, 'ws-123')- writeFileSync(path, s1.getRawContent() ?? '')-- const s2 = new YamlStore(path)- s2.setRawContent(readFileSync(path, 'utf8'))- expect(s2.doGet({ key: 'workspace', default: '' })).toBe('ws-123')- })-- it('round-trips a deep nested value through disk', async () => {- const path = join(dir, 'config.yml')- await writeFile(path, '')-- const s1 = new YamlStore(path)- s1.setRawContent('')- s1.doSet({ key: 'a.b.c', default: '' }, 'deep')- writeFileSync(path, s1.getRawContent() ?? '')-- const s2 = new YamlStore(path)- s2.setRawContent(readFileSync(path, 'utf8'))- expect(s2.doGet({ key: 'a.b.c', default: '' })).toBe('deep')+ it('is a no-op when the file does not exist', async () => {+ await new YamlStore(path).rmIf(() => true)+ expect(existsSync(path)).toBe(false)})+})- it('second doSet on a reloaded store does not clobber the first key', async () => {- const path = join(dir, 'config.yml')- await writeFile(path, '')-- const s1 = new YamlStore(path)- s1.setRawContent('')- s1.doSet({ key: 'x', default: '' }, 'first')- writeFileSync(path, s1.getRawContent() ?? '')-- const s2 = new YamlStore(path)- s2.setRawContent(readFileSync(path, 'utf8'))- s2.doSet({ key: 'y', default: '' }, 'second')- writeFileSync(path, s2.getRawContent() ?? '')-- const s3 = new YamlStore(path)- s3.setRawContent(readFileSync(path, 'utf8'))- expect(s3.doGet({ key: 'x', default: '' })).toBe('first')- expect(s3.doGet({ key: 'y', default: '' })).toBe('second')- })+describe('YamlStore persistence', () => {+ it('round-trips a nested document through disk', async () => {+ await new YamlStore(path).setTyped({ a: { b: { c: 'deep' } }, workspace: 'ws-123' })+ expect(await new YamlStore(path).getTyped()).toEqual({+ a: { b: { c: 'deep' } },+ workspace: 'ws-123',+ })+ })++ it.skipIf(process.platform === 'win32')(+ 'writes the file with owner-only permissions',+ async () => {+ await new YamlStore(path).setTyped({ token: 'abc-123' })+ expect(statSync(path).mode & 0o777).toBe(0o600)+ },+ )it('forgets its cached content once the file is deleted and reloaded', async () => {- const path = join(dir, 'config.yml')await writeFile(path, 'key: value\n')const store = new YamlStore(path)@@ -265,24 +156,7 @@ describe('YamlStore persistence', () => {expect(await store.getTyped<{ key: string }>()).toBeNull()})- it('load → doSet → flush writes the value to disk', async () => {- const path = join(dir, 'config.yml')- await writeFile(path, 'existing: value\n')-- const store = new YamlStore(path)- await store.load()- store.doSet({ key: 'token', default: '' }, 'abc-123')- await store.flush()-- const raw = readFileSync(path, 'utf8')- const store2 = new YamlStore(path)- store2.setRawContent(raw)- expect(store2.doGet({ key: 'token', default: '' })).toBe('abc-123')- expect(store2.doGet({ key: 'existing', default: '' })).toBe('value')- })-it('flush writes file when dirty (content changed from undefined)', async () => {- const path = join(dir, 'config.yml')const store = new YamlStore(path)store.setRawContent('key: value\n')await store.flush()@@ -291,7 +165,6 @@ describe('YamlStore persistence', () => {})it('flush is a no-op when loaded content is set back unchanged', async () => {- const path = join(dir, 'config.yml')await writeFile(path, 'key: value\n')const store = new YamlStore(path)await store.load()diff --git a/cli/src/store/store.ts b/cli/src/store/store.tsindex f692ed55474..172783d4653 100644--- a/cli/src/store/store.ts+++ b/cli/src/store/store.ts@@ -2,7 +2,6 @@ import type { Options as LockOptions } from 'lockfile'import type { Platform } from '@/sys'import { promises as fsp } from 'node:fs'import { dirname } from 'node:path'-import { AsyncEntry } from '@napi-rs/keyring'import {binaryTag,CORE_SCHEMA,@@ -17,11 +16,12 @@ import {} from 'js-yaml'import lockfile from 'lockfile'import { pid, resolvePlatform } from '@/sys'+import { DIR_PERM, FILE_PERM } from './dir'import { BadYamlFormatError, ConcurrentAccessError } from './errors'-const FILE_PERM = 0o600-const DIR_PERM = 0o700const LOCK_STALE_MS = 30_000+// Parallel difyctl runs (an agent's usual case) wait their turn instead of failing.+const LOCK_WAIT_MS = 5_000const YAML_LOAD_SCHEMA = CORE_SCHEMA.withTags(binaryTag,mergeTag,@@ -43,21 +43,10 @@ function unlockAsync(path: string): Promise<void> {})}-export type Key<T> = {- default: T- key: string-}--export type Store = {- get: <T>(key: Key<T>) => Promise<T>- set: <T>(key: Key<T>, value: T) => Promise<void>- unset: <T>(key: Key<T>) => Promise<void>-}-export const STORAGE_MODES = ['keychain', 'file'] as constexport type StorageMode = (typeof STORAGE_MODES)[number]-abstract class FileBasedStore implements Store {+export class YamlStore {filePath: stringprivate rawContent: string | undefinedprivate readonly platform: Platform@@ -110,6 +99,7 @@ abstract class FileBasedStore implements Store {try {await lockAsync(`${this.filePath}.lock`, {stale: LOCK_STALE_MS,+ wait: LOCK_WAIT_MS,})} catch (err) {const code = (err as NodeJS.ErrnoException).code@@ -142,7 +132,7 @@ abstract class FileBasedStore implements Store {return this.rawContent}- protected async withLock<R>(body: () => R | Promise<R>): Promise<R> {+ private async withLock<R>(body: () => R | Promise<R>): Promise<R> {await this.lock()try {return await body()@@ -151,29 +141,6 @@ abstract class FileBasedStore implements Store {}}- async get<T>(key: Key<T>): Promise<T> {- return this.withLock(async () => {- await this.load()- return this.doGet(key)- })- }-- async set<T>(key: Key<T>, value: T): Promise<void> {- await this.withLock(async () => {- await this.load()- this.doSet(key, value)- await this.flush()- })- }-- async unset<T>(key: Key<T>): Promise<void> {- await this.withLock(async () => {- await this.load()- this.doUnset(key)- await this.flush()- })- }-/*** Remove the underlying file of the store. No-op if file doesn't exist.*/@@ -185,26 +152,15 @@ abstract class FileBasedStore implements Store {}}- abstract doGet<T>(key: Key<T>): T- abstract doSet<T>(key: Key<T>, value: T): void- abstract doUnset<T>(key: Key<T>): void-}--export class YamlStore extends FileBasedStore {- constructor(file_path: string) {- super(file_path)- }-- doGet<T>(key: Key<T>): T {- const data = loadYaml(this.getRawContent(), this.filePath)- const parts = key.key.split('.')- let current: unknown = data- for (const part of parts) {- if (current === null || current === undefined || typeof current !== 'object')- return key.default- current = (current as Record<string, unknown>)[part]- }- return (current as T) ?? key.default+ /**+ * Remove the file only when `matches` accepts what it holds now. The read and the+ * removal share one lock, so a file another process rewrote in between survives.+ */+ async rmIf(matches: (doc: Record<string, unknown> | null) => boolean): Promise<void> {+ await this.withLock(async () => {+ await this.load()+ if (matches(loadYaml(this.getRawContent(), this.filePath))) await this.rm()+ })}async getTyped<T>(): Promise<T | null> {@@ -221,41 +177,6 @@ export class YamlStore extends FileBasedStore {await this.flush()})}-- doSet<T>(key: Key<T>, value: T): void {- const data = loadYaml(this.getRawContent(), this.filePath) || {}- const parts = key.key.split('.')- const lastKey = parts.pop()- if (lastKey === undefined) return- let current: Record<string, unknown> = data- for (const part of parts) {- if (- current[part] === null ||- current[part] === undefined ||- typeof current[part] !== 'object'- )- current[part] = {}- current = current[part] as Record<string, unknown>- }- current[lastKey] = value- this.setRawContent(dump(data, { lineWidth: -1, noRefs: true }))- }-- doUnset<T>(key: Key<T>): void {- const data = loadYaml(this.getRawContent(), this.filePath) || {}- const parts = key.key.split('.')- const lastKey = parts.pop()- if (lastKey === undefined) return- let current: Record<string, unknown> = data- for (const part of parts) {- const next = current[part]- if (next === null || next === undefined || typeof next !== 'object') return- current = next as Record<string, unknown>- }- if (!(lastKey in current)) return- delete current[lastKey]- this.setRawContent(dump(data, { lineWidth: -1, noRefs: true }))- }}function loadYaml(raw: string | undefined, file_path: string): Record<string, unknown> | null {@@ -270,38 +191,3 @@ function loadYaml(raw: string | undefined, file_path: string): Record<string, unthrow err}}--/**- * OS-keyring-based storage primitive. Sits at the same layer as- * `FileBasedStore`: implements `Store` with each `Key<T>` corresponding to a- * single keyring entry under the configured service. Values are JSON-encoded.- */-export class KeyringBasedStore implements Store {- private readonly service: string-- constructor(service: string) {- this.service = service- }-- async get<T>(key: Key<T>): Promise<T> {- try {- const v = await new AsyncEntry(this.service, key.key).getPassword()- if (v === null || v === undefined || v === '') return key.default- return JSON.parse(v) as T- } catch {- return key.default- }- }-- async set<T>(key: Key<T>, value: T): Promise<void> {- await new AsyncEntry(this.service, key.key).setPassword(JSON.stringify(value))- }-- async unset<T>(key: Key<T>): Promise<void> {- try {- await new AsyncEntry(this.service, key.key).deletePassword()- } catch {- /* missing entry is fine */- }- }-}diff --git a/cli/src/store/token-store.test.ts b/cli/src/store/token-store.test.tsindex eb609c6929e..6efd2ed0dc6 100644--- a/cli/src/store/token-store.test.ts+++ b/cli/src/store/token-store.test.ts@@ -1,32 +1,45 @@+import type { BufferStreams } from '@/sys/io/streams'import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'-import { FileTokenStore } from './token-store'+import { ioService } from '@/plugins/io'+import { TOKENS_FILE_NAME } from '@/plugins/token'+import { bufferStreams } from '@/sys/io/streams'+import { localFile } from './local-file'+import { FileTokenStore, TOKENS_SCHEMA } from './token-store'describe('FileTokenStore', () => {let dir: stringlet file: string+ let streams: BufferStreamsbeforeEach(() => {+ streams = bufferStreams()dir = mkdtempSync(join(tmpdir(), 'difyctl-tok-'))- file = join(dir, 'tokens.yml')+ file = join(dir, TOKENS_FILE_NAME)})- afterEach(() => rmSync(dir, { recursive: true, force: true }))+ afterEach(() => {+ rmSync(dir, { recursive: true, force: true })+ })++ function open(): FileTokenStore {+ return new FileTokenStore(localFile(file, TOKENS_SCHEMA, ioService(streams).notice))+ }it('returns empty string for a missing credential', async () => {- const s = new FileTokenStore(file)+ const s = open()expect(await s.read('https://cloud.dify.ai', '[email protected]')).toBe('')})it('round-trips a bearer with dots and @ kept literal', async () => {- const s = new FileTokenStore(file)+ const s = open()await s.write('https://cloud.dify.ai', '[email protected]', 'dfoa_secret')expect(await s.read('https://cloud.dify.ai', '[email protected]')).toBe('dfoa_secret')})it('keeps multiple accounts under one host and isolates hosts', async () => {- const s = new FileTokenStore(file)+ const s = open()await s.write('https://cloud.dify.ai', '[email protected]', 'A')await s.write('https://cloud.dify.ai', '[email protected]', 'B')await s.write('https://self.example.com', '[email protected]', 'C')@@ -35,38 +48,53 @@ describe('FileTokenStore', () => {expect(await s.read('https://self.example.com', '[email protected]')).toBe('C')})- it('persists the versioned nested shape on disk', async () => {- const s = new FileTokenStore(file)+ it('persists the nested shape on disk', async () => {+ const s = open()await s.write('https://cloud.dify.ai', '[email protected]', 'A')- const raw = readFileSync(file, 'utf8')- expect(raw).toContain('version: 1')- expect(raw).toContain('https://cloud.dify.ai')- expect(raw).toContain('[email protected]')+ expect(readFileSync(file, 'utf8')).toBe('tokens:\n https://cloud.dify.ai:\n [email protected]: A\n')})- it('reads empty when the document version is an unknown future version', async () => {- writeFileSync(file, 'version: 999\ntokens:\n "h":\n "e": "x"\n')- const s = new FileTokenStore(file)- expect(await s.read('h', 'e')).toBe('')+ it('reads a difyctl v1 file in place and drops its version on the next write', async () => {+ writeFileSync(file, 'version: 1\ntokens:\n h:\n e: dfoa_v1\n')+ const s = open()+ expect(await s.read('h', 'e')).toBe('dfoa_v1')+ await s.write('h', 'f', 'dfoa_v2')+ expect(readFileSync(file, 'utf8')).toBe('tokens:\n h:\n e: dfoa_v1\n f: dfoa_v2\n')+ expect(streams.errBuf()).toBe('')})- it('reads tokens from legacy format (no version field) for transparent migration', async () => {- writeFileSync(file, 'tokens:\n "h":\n "e": "dfoa_legacy"\n')- const s = new FileTokenStore(file)- expect(await s.read('h', 'e')).toBe('dfoa_legacy')+ it('ignores unknown and future keys without a notice', async () => {+ writeFileSync(file, 'schema_version: 99\nfuture_key: x\ntokens:\n h:\n e: dfoa_x\n')+ expect(await open().read('h', 'e')).toBe('dfoa_x')+ expect(streams.errBuf()).toBe('')})- it('preserves existing tokens and stamps version when writing to a legacy file', async () => {- writeFileSync(file, 'tokens:\n "h":\n "existing@x": "dfoa_existing"\n')- const s = new FileTokenStore(file)- await s.write('h', 'new@x', 'dfoa_new')- expect(await s.read('h', 'existing@x')).toBe('dfoa_existing')- expect(await s.read('h', 'new@x')).toBe('dfoa_new')- expect(readFileSync(file, 'utf8')).toContain('version: 1')+ it('drops a bad entry with a notice and keeps the rest', async () => {+ writeFileSync(file, 'tokens:\n h:\n e: dfoa_x\n bad: 7\n g: nope\n')+ const s = open()+ expect(await s.read('h', 'e')).toBe('dfoa_x')+ expect(streams.errBuf()).toBe(+ `${file}: ignoring the invalid value of tokens.h.bad\n${file}: ignoring the invalid value of tokens.g\n`,+ )})+ it.each([+ ['not valid YAML', 'tokens: [unclosed\n', /is not valid YAML/],+ ['not a mapping', 'just text\n', /is not a YAML mapping/],+ ])(+ 'reads a file that is %s as empty and replaces it on the next write',+ async (_l, raw, note) => {+ writeFileSync(file, raw)+ const s = open()+ expect(await s.read('h', 'e')).toBe('')+ expect(streams.errBuf()).toMatch(note)+ await s.write('h', 'e', 'dfoa_y')+ expect(readFileSync(file, 'utf8')).toBe('tokens:\n h:\n e: dfoa_y\n')+ },+ )+it('remove deletes the credential and prunes the empty host map', async () => {- const s = new FileTokenStore(file)+ const s = open()await s.write('https://cloud.dify.ai', '[email protected]', 'A')await s.remove('https://cloud.dify.ai', '[email protected]')expect(await s.read('https://cloud.dify.ai', '[email protected]')).toBe('')@@ -75,7 +103,7 @@ describe('FileTokenStore', () => {})it('remove is a no-op for an absent credential', async () => {- const s = new FileTokenStore(file)+ const s = open()await expect(s.remove('h', 'e')).resolves.not.toThrow()})})diff --git a/cli/src/store/token-store.ts b/cli/src/store/token-store.tsindex 1dc4d643b89..2728a02e895 100644--- a/cli/src/store/token-store.ts+++ b/cli/src/store/token-store.ts@@ -1,7 +1,9 @@+import type { LocalFile } from './local-file'import { AsyncEntry } from '@napi-rs/keyring'+import { z } from 'zod'import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'-import { YamlStore } from './store'+import { BINARY } from '@/version/info'/*** Credential store keyed by an opaque (host, email) pair.@@ -12,60 +14,40 @@ export type TokenStore = {remove: (host: string, email: string) => Promise<void>}-const DOC_VERSION = 1+const KEYCHAIN_ENTRY_PREFIX = 'tokens'-export type TokenDoc = {- version?: number- tokens?: Record<string, Record<string, string>>-}+export const TOKENS_SCHEMA = z.object({+ tokens: z.record(z.string(), z.record(z.string(), z.string())).default({}),+})++type TokensDoc = z.infer<typeof TOKENS_SCHEMA>++export type TokensFile = LocalFile<TokensDoc>export class FileTokenStore implements TokenStore {- private readonly store: YamlStore+ private readonly file: TokensFile- constructor(filePath: string) {- this.store = new YamlStore(filePath)+ constructor(file: TokensFile) {+ this.file = file}async read(host: string, email: string): Promise<string> {- const doc = await this.store.getTyped<TokenDoc>()- if (doc === null) return ''- // missing version = legacy pre-v1 format (same data shape); future unknown versions are rejected- if (doc.version !== undefined && doc.version !== DOC_VERSION) return ''- return doc.tokens?.[host]?.[email] ?? ''+ return (await this.file.read())?.tokens[host]?.[email] ?? ''}async write(host: string, email: string, bearer: string): Promise<void> {- const doc = await this.load()- const hostMap = doc.tokens[host] ?? {}- hostMap[email] = bearer- doc.tokens[host] = hostMap- await this.store.setTyped(doc)+ const doc = (await this.file.read()) ?? { tokens: {} }+ doc.tokens[host] = { ...doc.tokens[host], [email]: bearer }+ await this.file.write(doc)}async remove(host: string, email: string): Promise<void> {- const doc = await this.store.getTyped<TokenDoc>()- if (doc === null) return- if (doc.version !== undefined && doc.version !== DOC_VERSION) return- const tokens = doc.tokens ?? {}- const hostMap = tokens[host]- if (hostMap === undefined || !(email in hostMap)) return+ const doc = await this.file.read()+ const hostMap = doc?.tokens[host]+ if (doc === null || hostMap === undefined || !(email in hostMap)) returndelete hostMap[email]- if (Object.keys(hostMap).length === 0) delete tokens[host]- await this.store.setTyped({ version: DOC_VERSION, tokens })- }-- private async load(): Promise<{- version: number- tokens: Record<string, Record<string, string>>- }> {- const doc = await this.store.getTyped<TokenDoc>()- if (doc === null) return { version: DOC_VERSION, tokens: {} }- if (doc.version !== undefined && doc.version !== DOC_VERSION)- return { version: DOC_VERSION, tokens: {} }- return {- version: DOC_VERSION,- tokens: (doc.tokens ?? {}) as Record<string, Record<string, string>>,- }+ if (Object.keys(hostMap).length === 0) delete doc.tokens[host]+ await this.file.write(doc)}}@@ -82,7 +64,7 @@ export class KeychainTokenStore implements TokenStore {async read(host: string, email: string): Promise<string> {let raw: string | null | undefinedtry {- raw = await new AsyncEntry(this.service, entryName(host, email)).getPassword()+ raw = await new AsyncEntry(this.service, this.entry(host, email)).getPassword()} catch (err) {throw keyringUnavailableError(err)}@@ -97,7 +79,9 @@ export class KeychainTokenStore implements TokenStore {async write(host: string, email: string, bearer: string): Promise<void> {try {- await new AsyncEntry(this.service, entryName(host, email)).setPassword(JSON.stringify(bearer))+ await new AsyncEntry(this.service, this.entry(host, email)).setPassword(+ JSON.stringify(bearer),+ )} catch (err) {throw keyringUnavailableError(err)}@@ -105,22 +89,22 @@ export class KeychainTokenStore implements TokenStore {async remove(host: string, email: string): Promise<void> {try {- await new AsyncEntry(this.service, entryName(host, email)).deletePassword()+ await new AsyncEntry(this.service, this.entry(host, email)).deletePassword()} catch {/* missing entry is fine */}}-}-function entryName(host: string, email: string): string {- return `tokens.${host}.${email}`+ private entry(host: string, email: string): string {+ return `${KEYCHAIN_ENTRY_PREFIX}.${host}.${email}`+ }}function keyringUnavailableError(cause: unknown): BaseError {return new BaseError({code: ErrorCode.KeyringUnavailable,message: 'OS keychain is unreachable',- hint: 'credentials are stored in the system keychain but it could not be accessed; unlock the keychain (or the login session) and retry',+ hint: `unlock the keychain (or the login session) and retry, or run ${BINARY} login --server <url> --no-keyring to keep the token in a file`,cause,})}diff --git a/cli/src/sys/index.test.ts b/cli/src/sys/index.test.tsindex 95208d63fe7..485eb5f316d 100644--- a/cli/src/sys/index.test.ts+++ b/cli/src/sys/index.test.ts@@ -18,17 +18,6 @@ describe('resolvePlatform', () => {}})- it('cacheDir ends with the difyctl subdir', () => {- const p = resolvePlatform()- if (p.id() === 'win32') {- expect(p.cacheDir()).toMatch(/difyctl$/)- } else if (p.id() === 'darwin') {- expect(p.cacheDir()).toBe(join(homedir(), 'Library', 'Caches', SUBDIR))- } else {- expect(p.cacheDir()).toBe(join(homedir(), '.cache', SUBDIR))- }- })-it('atomicReplace is a function', () => {expect(resolvePlatform().atomicReplace).toBeTypeOf('function')})diff --git a/cli/src/sys/index.ts b/cli/src/sys/index.tsindex 513a86fd4bf..e4af246ebac 100644--- a/cli/src/sys/index.ts+++ b/cli/src/sys/index.ts@@ -6,6 +6,18 @@ export function getEnv(name: string): string | undefined {return process.env[name]}+export type EmbeddedFile = Blob & { readonly name: string }++type BunGlobal = { embeddedFiles?: readonly EmbeddedFile[] }++export function embeddedFiles(): readonly EmbeddedFile[] {+ return (globalThis as { Bun?: BunGlobal }).Bun?.embeddedFiles ?? []+}++export function isCompiledBinary(): boolean {+ return __DIFYCTL_COMPILED__+}+export function env(): NodeJS.ProcessEnv {return process.env}@@ -51,16 +63,22 @@ export function pid(): number {export type Platform = {id: () => NodeJS.PlatformconfigDir: () => string- cacheDir: () => stringatomicReplace: (src: string, dst: string) => void}export const SUBDIR = 'difyctl'export const ENV_XDG_CONFIG_HOME = 'XDG_CONFIG_HOME'-export const ENV_XDG_CACHE_HOME = 'XDG_CACHE_HOME'-function appDataDir(): string | undefined {- return getEnv('APPDATA') ?? getEnv('LOCALAPPDATA')+const APP_DATA_VARS = ['APPDATA', 'LOCALAPPDATA'] as const++// The first of these that is set.+function appDataDir(): string {+ const dir = APP_DATA_VARS.map(getEnv).find((value) => value !== undefined && value !== '')+ if (dir === undefined)+ throw new Error(+ `cannot resolve ${APP_DATA_VARS.map((name) => `%${name}%`).join(' or ')} on Windows`,+ )+ return join(dir, SUBDIR)}type PlatformFactory = () => Platform@@ -82,32 +100,16 @@ const platformImpls: Partial<Record<NodeJS.Platform, PlatformFactory>> = {? join(xdg, SUBDIR): join(homedir(), '.config', SUBDIR)},- cacheDir: () => {- const xdg = getEnv(ENV_XDG_CACHE_HOME)- return xdg !== undefined && xdg !== '' ? join(xdg, SUBDIR) : join(homedir(), '.cache', SUBDIR)- },atomicReplace: posixAtomicReplace,}),darwin: () => ({id: () => 'darwin',configDir: () => join(homedir(), '.config', SUBDIR),- cacheDir: () => join(homedir(), 'Library', 'Caches', SUBDIR),atomicReplace: posixAtomicReplace,}),win32: () => ({id: () => 'win32',- configDir: () => {- const appData = appDataDir()- if (appData === undefined || appData === '')- throw new Error('cannot resolve %APPDATA% on Windows')- return join(appData, SUBDIR)- },- cacheDir: () => {- const appData = appDataDir()- if (appData === undefined || appData === '')- throw new Error('cannot resolve %LOCALAPPDATA% on Windows')- return join(appData, SUBDIR)- },+ configDir: appDataDir,atomicReplace: win32AtomicReplace,}),}@@ -115,7 +117,6 @@ const platformImpls: Partial<Record<NodeJS.Platform, PlatformFactory>> = {const defaultPlatformFactory: PlatformFactory = () => ({id: () => platform(),configDir: () => join(homedir(), '.config', SUBDIR),- cacheDir: () => join(homedir(), '.cache', SUBDIR),atomicReplace: posixAtomicReplace,})diff --git a/cli/src/util/flag-name.ts b/cli/src/util/flag-name.tsindex f398273298d..73d7eb7efae 100644--- a/cli/src/util/flag-name.ts+++ b/cli/src/util/flag-name.ts@@ -1,5 +1,8 @@const FLAG_WORD_SEPARATOR = '-'const PROPERTY_WORD_SEPARATOR = '_'+const FLAG_PREFIX = '--'+const ARG_OPEN = '<'+const ARG_CLOSE = '>'/** The name a typed word stands for: dashes are an alias for the underscores ids use. */export function propertyFor(name: string): string {@@ -10,3 +13,15 @@ export function propertyFor(name: string): string {export function flagFor(name: string): string {return name.split(PROPERTY_WORD_SEPARATOR).join(FLAG_WORD_SEPARATOR)}++export function flagToken(name: string): string {+ return `${FLAG_PREFIX}${flagFor(name)}`+}++export function argToken(name: string): string {+ return `${ARG_OPEN}${name}${ARG_CLOSE}`+}++export function typedName(name: string, positional: readonly string[]): string {+ return positional.includes(name) ? argToken(name) : flagToken(name)+}diff --git a/cli/src/util/host.ts b/cli/src/util/host.tsindex 6d8a35a8ed9..48881070cc1 100644--- a/cli/src/util/host.ts+++ b/cli/src/util/host.ts@@ -1,8 +1,6 @@import { BaseError } from '@/errors/base'import { ErrorCode } from '@/errors/codes'-export const DEFAULT_HOST = 'https://cloud.dify.ai'-export function openAPIBase(host: string): string {return `${host.replace(/\/+$/, '')}/openapi/v1/`}@@ -14,7 +12,6 @@ export type ResolveHostOptions = {export function resolveHost(opts: ResolveHostOptions): string {let raw = opts.raw.trim()- if (raw === '') raw = DEFAULT_HOSTif (!raw.includes('://')) raw = `https://${raw}`let url: URLtry {diff --git a/cli/src/util/shell-word.ts b/cli/src/util/shell-word.tsnew file mode 100644index 00000000000..c4a919de44d--- /dev/null+++ b/cli/src/util/shell-word.ts@@ -0,0 +1,8 @@+const SHELL_SAFE = /^[\w@%+=:,./~-]+$/+const QUOTE = "'"+const ESCAPED_QUOTE = `'\\''`++export function shellWord(text: string): string {+ if (SHELL_SAFE.test(text)) return text+ return `${QUOTE}${text.split(QUOTE).join(ESCAPED_QUOTE)}${QUOTE}`+}diff --git a/cli/src/version/build-info.d.ts b/cli/src/version/build-info.d.tsindex 886954c0dfc..c28d3e60668 100644--- a/cli/src/version/build-info.d.ts+++ b/cli/src/version/build-info.d.ts@@ -4,3 +4,4 @@ declare const __DIFYCTL_VERSION__: stringdeclare const __DIFYCTL_COMMIT__: stringdeclare const __DIFYCTL_BUILD_DATE__: stringdeclare const __DIFYCTL_CHANNEL__: string+declare const __DIFYCTL_COMPILED__: booleandiff --git a/cli/test/e2e/helpers/cli.ts b/cli/test/e2e/helpers/cli.tsindex a744ab1e451..25edce9e9ec 100644--- a/cli/test/e2e/helpers/cli.ts+++ b/cli/test/e2e/helpers/cli.ts@@ -8,7 +8,6 @@* withTempConfig) to prevent session state leaking between tests.*/-import type { TokenDoc } from '@/store/token-store'import { Buffer } from 'node:buffer'import { execSync, spawn } from 'node:child_process'import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'@@ -203,6 +202,11 @@ function splitHost(host: string): { bare: string; scheme: string } {return { bare, scheme }}+type TokenDoc = {+ version: number+ tokens: Record<string, Record<string, string>>+}+async function writeFileToken(configDir: string,host: string,@@ -291,8 +295,7 @@ export async function injectAuth(configDir: string, opts: AuthInjectionOptions):const account = `tokens.${bare}.${email}`new Entry('difyctl', account).setPassword(JSON.stringify(opts.bearer))} else {- // Fall back to tokens.yml — FileTokenStore uses getTyped<TokenDoc>()- // which expects flat tokens[host][email] with version: 1.+ // Fall back to tokens.yml, which FileTokenStore reads as tokens[host][email].await writeFileToken(configDir, bare, email, opts.bearer)}}diff --git a/cli/test/fixtures/catalog-v2.json b/cli/test/fixtures/catalog-v2.jsonindex 80815ea680b..613cc038677 100644--- a/cli/test/fixtures/catalog-v2.json+++ b/cli/test/fixtures/catalog-v2.json@@ -92,6 +92,33 @@"workspace_id": "body"},"deprecated": false,+ "examples": [+ {+ "input": {+ "app_id": "<app_id>",+ "query": "Summarise the latest release"+ },+ "title": "Start a new conversation"+ },+ {+ "input": {+ "app_id": "<app_id>",+ "conversation_id": "<conversation_id>",+ "query": "Make it shorter"+ },+ "title": "Reply in an existing conversation"+ },+ {+ "input": {+ "app_id": "<app_id>",+ "files": {+ "document": "./report.pdf"+ },+ "query": "Summarise the document"+ },+ "title": "Fill a file variable with a local file"+ }+ ],"input": {"properties": {"app_id": {@@ -111,7 +138,7 @@}],"default": null,- "description": "Local files attached to the run itself (the app's `sys.files`), not to a variable",+ "description": "Local file paths attached to the run itself (the app's `sys.files`), not to a variable","title": "Attachments"},"auto_generate_name": {@@ -158,12 +185,12 @@}],"default": null,- "description": "Local files keyed by the app's file variable name; the server uploads each one and sets `inputs[<name>]`. Send a list (part name `files[<name>][]`) for a file-list variable",+ "description": "Local file paths keyed by the app's file variable name; each file is uploaded and becomes that variable's value. Give a list of paths for a file-list variable","title": "Files"},"inputs": {"additionalProperties": true,- "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local file in `files`, not both.",+ "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local path in `files`, not both.","title": "Inputs","type": "object"},@@ -199,7 +226,7 @@"title": "Workspace Id"}},- "required": ["app_id", "inputs", "query"],+ "required": ["app_id", "query"],"type": "object"},"internal": false,@@ -510,6 +537,7 @@"bind": {"app_id": "body","description": "body",+ "draft_hash": "body","icon": "body","icon_background": "body","icon_type": "body",@@ -520,6 +548,30 @@"yaml_url": "body"},"deprecated": false,+ "examples": [+ {+ "input": {+ "mode": "yaml-content",+ "yaml_content": "<yaml text of the app DSL>"+ },+ "title": "Import an app from inline YAML"+ },+ {+ "input": {+ "mode": "yaml-url",+ "yaml_url": "https://example.com/apps/release-summary.yml"+ },+ "title": "Import an app from a URL"+ },+ {+ "input": {+ "app_id": "<app_id>",+ "mode": "yaml-content",+ "yaml_content": "<yaml text of the app DSL>"+ },+ "title": "Overwrite an existing workflow app from YAML"+ }+ ],"input": {"properties": {"app_id": {@@ -548,6 +600,19 @@"description": "Override the app description from the DSL","title": "Description"},+ "draft_hash": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "draft_hash from the export or restore this import is based on. The import fails if the draft's graph, features, environment variables or conversation variables changed since. Requires app_id",+ "title": "Draft Hash"+ },"icon": {"anyOf": [{diff --git a/cli/test/fixtures/catalog.json b/cli/test/fixtures/catalog.jsonindex e9c7b838d90..8677f45da3c 100644--- a/cli/test/fixtures/catalog.json+++ b/cli/test/fixtures/catalog.json@@ -57,6 +57,20 @@"path": "/openapi/v1/account/sessions/self","summary": "Revoke the session behind this token"},+ "restore.console_app.version": {+ "bind": { "app_id": "path", "version_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "version_id": {} },+ "required": ["app_id", "version_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/apps/{app_id}/versions/{version_id}:restore",+ "summary": "Copy a published version into the draft; publish again to make it live"+ },"run.console_app.advanced_chat": {"bind": {"app_id": "path",@@ -70,6 +84,28 @@"workspace_id": "body"},"deprecated": false,+ "examples": [+ {+ "input": { "app_id": "<app_id>", "query": "Summarise the latest release" },+ "title": "Start a new conversation"+ },+ {+ "input": {+ "app_id": "<app_id>",+ "conversation_id": "<conversation_id>",+ "query": "Make it shorter"+ },+ "title": "Reply in an existing conversation"+ },+ {+ "input": {+ "app_id": "<app_id>",+ "files": { "document": "./report.pdf" },+ "query": "Summarise the document"+ },+ "title": "Fill a file variable with a local file"+ }+ ],"input": {"properties": {"app_id": { "type": "string" },@@ -79,7 +115,7 @@{ "type": "null" }],"default": null,- "description": "Local files attached to the run itself (the app's `sys.files`), not to a variable",+ "description": "Local file paths attached to the run itself (the app's `sys.files`), not to a variable","title": "Attachments"},"auto_generate_name": {@@ -108,12 +144,12 @@{ "type": "null" }],"default": null,- "description": "Local files keyed by the app's file variable name; the server uploads each one and sets `inputs[<name>]`. Send a list (part name `files[<name>][]`) for a file-list variable",+ "description": "Local file paths keyed by the app's file variable name; each file is uploaded and becomes that variable's value. Give a list of paths for a file-list variable","title": "Files"},"inputs": {"additionalProperties": true,- "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local file in `files`, not both.",+ "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local path in `files`, not both.","title": "Inputs","type": "object"},@@ -131,7 +167,7 @@"title": "Workspace Id"}},- "required": ["app_id", "inputs", "query"],+ "required": ["app_id", "query"],"type": "object"},"internal": false,@@ -346,6 +382,7 @@"bind": {"app_id": "body","description": "body",+ "draft_hash": "body","icon": "body","icon_background": "body","icon_type": "body",@@ -356,6 +393,27 @@"yaml_url": "body"},"deprecated": false,+ "examples": [+ {+ "input": { "mode": "yaml-content", "yaml_content": "<yaml text of the app DSL>" },+ "title": "Import an app from inline YAML"+ },+ {+ "input": {+ "mode": "yaml-url",+ "yaml_url": "https://example.com/apps/release-summary.yml"+ },+ "title": "Import an app from a URL"+ },+ {+ "input": {+ "app_id": "<app_id>",+ "mode": "yaml-content",+ "yaml_content": "<yaml text of the app DSL>"+ },+ "title": "Overwrite an existing workflow app from YAML"+ }+ ],"input": {"properties": {"app_id": {@@ -370,6 +428,12 @@"description": "Override the app description from the DSL","title": "Description"},+ "draft_hash": {+ "anyOf": [{ "type": "string" }, { "type": "null" }],+ "default": null,+ "description": "draft_hash from the export or restore this import is based on. The import fails if the draft's graph, features, environment variables or conversation variables changed since. Requires app_id",+ "title": "Draft Hash"+ },"icon": {"anyOf": [{ "type": "string" }, { "type": "null" }],"default": null,@@ -917,6 +981,846 @@"method": "POST","path": "/openapi/v1/workspaces/{workspace_id}:switch","summary": "Server-side current switch workspace (shared with the web console)"+ },+ "create.console_app.workflow": {+ "bind": {+ "description": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "name": "body",+ "workspace_id": "path"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "description": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "name": {},+ "workspace_id": {}+ },+ "required": ["workspace_id", "name"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/workspaces/{workspace_id}/apps/workflow",+ "summary": "Create a blank workflow app; export its DSL to start building"+ },+ "create.console_app.advanced_chat": {+ "bind": {+ "description": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "name": "body",+ "workspace_id": "path"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "description": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "name": {},+ "workspace_id": {}+ },+ "required": ["workspace_id", "name"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/workspaces/{workspace_id}/apps/advanced-chat",+ "summary": "Create a blank advanced-chat app; export its DSL to start building"+ },+ "test.node.workflow": {+ "bind": { "app_id": "path", "files": "body", "inputs": "body", "node_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "files": {}, "inputs": {}, "node_id": {} },+ "required": ["app_id", "node_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/apps/{app_id}/draft/workflow/nodes/{node_id}:run",+ "summary": "Test one node of a workflow draft, reusing what the last draft run saved"+ },+ "test.node.advanced_chat": {+ "bind": {+ "app_id": "path",+ "files": "body",+ "inputs": "body",+ "node_id": "path",+ "query": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "files": {}, "inputs": {}, "node_id": {}, "query": {} },+ "required": ["app_id", "node_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/apps/{app_id}/draft/advanced-chat/nodes/{node_id}:run",+ "summary": "Test one node of an advanced-chat draft, reusing what the last draft run saved"+ },+ "test.console_app.workflow": {+ "bind": {+ "app_id": "path",+ "attachments": "file",+ "files": "file",+ "inputs": "body",+ "workspace_id": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "attachments": {},+ "files": {},+ "inputs": {},+ "workspace_id": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "sse",+ "method": "POST",+ "path": "/openapi/v1/apps/{app_id}/draft/workflow:run",+ "summary": "Test-run the draft of a workflow app; streams workflow events. A human-input pause in a draft run cannot be resumed over openapi."+ },+ "test.console_app.advanced_chat": {+ "bind": {+ "app_id": "path",+ "attachments": "file",+ "auto_generate_name": "body",+ "conversation_id": "body",+ "files": "file",+ "inputs": "body",+ "query": "body",+ "workspace_id": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "attachments": {},+ "auto_generate_name": {},+ "conversation_id": {},+ "files": {},+ "inputs": {},+ "query": {},+ "workspace_id": {}+ },+ "required": ["app_id", "query"]+ },+ "internal": false,+ "kind": "sse",+ "method": "POST",+ "path": "/openapi/v1/apps/{app_id}/draft/advanced-chat:run",+ "summary": "Test-run the draft of an advanced-chat app; streams message and workflow events. A human-input pause in a draft run cannot be resumed over openapi."+ },+ "check.console_app.dsl": {+ "bind": { "app_id": "body", "workspace_id": "path", "yaml_content": "body" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "workspace_id": {}, "yaml_content": {} },+ "required": ["workspace_id", "yaml_content"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/workspaces/{workspace_id}/apps/imports:check",+ "summary": "Check app DSL and list every problem"+ },+ "check.console_app.release": {+ "bind": { "app_id": "path" },+ "deprecated": false,+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/apps/{app_id}/release:check",+ "summary": "Check whether an app draft is ready to publish and what changed"+ },+ "get.knowledge_base": {+ "bind": { "limit": "query", "page": "query", "query": "query", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "limit": {}, "page": {}, "query": {}, "workspace_id": {} },+ "required": ["workspace_id"]+ },+ "internal": false,+ "kind": "list",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/knowledge-bases",+ "summary": "List knowledge bases"+ },+ "describe.service_api": {+ "bind": { "app_id": "path" },+ "deprecated": false,+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/apps/{app_id}/service-api",+ "summary": "Show an app's Service API settings"+ },+ "set.service_api": {+ "bind": { "app_id": "path", "enabled": "body" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "enabled": {} },+ "required": ["app_id", "enabled"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/service-api",+ "summary": "Turn an app's Service API on or off"+ },+ "describe.webapp_access": {+ "bind": { "app_id": "path" },+ "deprecated": false,+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/apps/{app_id}/webapp-access",+ "summary": "Show who can open an app's web app"+ },+ "set.webapp_access": {+ "bind": { "access_mode": "body", "app_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "access_mode": {}, "app_id": {} },+ "required": ["app_id", "access_mode"]+ },+ "internal": false,+ "kind": "object",+ "method": "PUT",+ "path": "/openapi/v1/apps/{app_id}/webapp-access",+ "summary": "Set who can open an app's web app"+ },+ "reset.webapp": {+ "bind": { "app_id": "path" },+ "deprecated": false,+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/apps/{app_id}/webapp:reset",+ "summary": "Reset an app's web app address"+ },+ "get.node_type": {+ "bind": {},+ "deprecated": false,+ "input": { "type": "object", "properties": {} },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/node-types",+ "summary": "Every node type this server can run; import decides which a mode allows"+ },+ "describe.node_type": {+ "bind": { "node_type": "path" },+ "deprecated": false,+ "input": { "type": "object", "properties": { "node_type": {} }, "required": ["node_type"] },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/node-types/{node_type}",+ "summary": "The JSON schema of a node type's data and its default config"+ },+ "get.run": {+ "bind": {+ "app_id": "path",+ "last_id": "query",+ "limit": "query",+ "status": "query",+ "triggered_from": "query"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "last_id": {},+ "limit": {},+ "status": {},+ "triggered_from": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/apps/{app_id}/runs",+ "summary": "List runs of a workflow or advanced-chat app, newest first"+ },+ "get.run.node": {+ "bind": { "app_id": "path", "run_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "run_id": {} },+ "required": ["app_id", "run_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/apps/{app_id}/runs/{run_id}/nodes",+ "summary": "Each node step of a run, to find the one that failed"+ },+ "publish.console_app": {+ "bind": { "app_id": "path", "marked_comment": "body", "marked_name": "body" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "marked_comment": {}, "marked_name": {} },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/apps/{app_id}:publish",+ "summary": "Publish the draft as a new version and make the app use it"+ },+ "get.console_app.version": {+ "bind": { "app_id": "path", "limit": "query", "named_only": "query", "page": "query" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "limit": {}, "named_only": {}, "page": {} },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/apps/{app_id}/versions",+ "summary": "List published versions, newest first"+ },+ "set.webapp.workflow": {+ "bind": {+ "app_id": "path",+ "copyright": "body",+ "custom_disclaimer": "body",+ "default_language": "body",+ "description": "body",+ "enabled": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "privacy_policy": "body",+ "show_workflow_steps": "body",+ "title": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "copyright": {},+ "custom_disclaimer": {},+ "default_language": {},+ "description": {},+ "enabled": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "privacy_policy": {},+ "show_workflow_steps": {},+ "title": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/webapp/workflow",+ "summary": "Change a workflow app's web app; only the fields passed change"+ },+ "set.webapp.advanced_chat": {+ "bind": {+ "app_id": "path",+ "chat_color_theme": "body",+ "chat_color_theme_inverted": "body",+ "copyright": "body",+ "custom_disclaimer": "body",+ "default_language": "body",+ "description": "body",+ "enabled": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "input_placeholder": "body",+ "privacy_policy": "body",+ "show_workflow_steps": "body",+ "title": "body",+ "use_icon_as_answer_icon": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "chat_color_theme": {},+ "chat_color_theme_inverted": {},+ "copyright": {},+ "custom_disclaimer": {},+ "default_language": {},+ "description": {},+ "enabled": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "input_placeholder": {},+ "privacy_policy": {},+ "show_workflow_steps": {},+ "title": {},+ "use_icon_as_answer_icon": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/webapp/advanced-chat",+ "summary": "Change an advanced-chat app's web app; only the fields passed change"+ },+ "set.webapp.chat": {+ "bind": {+ "app_id": "path",+ "chat_color_theme": "body",+ "chat_color_theme_inverted": "body",+ "copyright": "body",+ "custom_disclaimer": "body",+ "default_language": "body",+ "description": "body",+ "enabled": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "input_placeholder": "body",+ "privacy_policy": "body",+ "title": "body",+ "use_icon_as_answer_icon": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "chat_color_theme": {},+ "chat_color_theme_inverted": {},+ "copyright": {},+ "custom_disclaimer": {},+ "default_language": {},+ "description": {},+ "enabled": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "input_placeholder": {},+ "privacy_policy": {},+ "title": {},+ "use_icon_as_answer_icon": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/webapp/chat",+ "summary": "Change a chat app's web app; only the fields passed change"+ },+ "set.webapp.agent_chat": {+ "bind": {+ "app_id": "path",+ "chat_color_theme": "body",+ "chat_color_theme_inverted": "body",+ "copyright": "body",+ "custom_disclaimer": "body",+ "default_language": "body",+ "description": "body",+ "enabled": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "input_placeholder": "body",+ "privacy_policy": "body",+ "title": "body",+ "use_icon_as_answer_icon": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "chat_color_theme": {},+ "chat_color_theme_inverted": {},+ "copyright": {},+ "custom_disclaimer": {},+ "default_language": {},+ "description": {},+ "enabled": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "input_placeholder": {},+ "privacy_policy": {},+ "title": {},+ "use_icon_as_answer_icon": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/webapp/agent-chat",+ "summary": "Change an agent-chat app's web app; only the fields passed change"+ },+ "set.webapp.completion": {+ "bind": {+ "app_id": "path",+ "copyright": "body",+ "custom_disclaimer": "body",+ "default_language": "body",+ "description": "body",+ "enabled": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "privacy_policy": "body",+ "title": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "copyright": {},+ "custom_disclaimer": {},+ "default_language": {},+ "description": {},+ "enabled": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "privacy_policy": {},+ "title": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/webapp/completion",+ "summary": "Change a completion app's web app; only the fields passed change"+ },+ "set.webapp.agent": {+ "bind": {+ "app_id": "path",+ "chat_color_theme": "body",+ "chat_color_theme_inverted": "body",+ "copyright": "body",+ "custom_disclaimer": "body",+ "default_language": "body",+ "description": "body",+ "enabled": "body",+ "icon": "body",+ "icon_background": "body",+ "icon_type": "body",+ "input_placeholder": "body",+ "privacy_policy": "body",+ "title": "body",+ "use_icon_as_answer_icon": "body"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "app_id": {},+ "chat_color_theme": {},+ "chat_color_theme_inverted": {},+ "copyright": {},+ "custom_disclaimer": {},+ "default_language": {},+ "description": {},+ "enabled": {},+ "icon": {},+ "icon_background": {},+ "icon_type": {},+ "input_placeholder": {},+ "privacy_policy": {},+ "title": {},+ "use_icon_as_answer_icon": {}+ },+ "required": ["app_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/webapp/agent",+ "summary": "Change an agent app's web app; only the fields passed change"+ },+ "set.service_api.agent": {+ "bind": { "app_id": "path", "enabled": "body" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "app_id": {}, "enabled": {} },+ "required": ["app_id", "enabled"]+ },+ "internal": false,+ "kind": "object",+ "method": "PATCH",+ "path": "/openapi/v1/apps/{app_id}/service-api/agent",+ "summary": "Turn an agent app's Service API on or off"+ },+ "set.webapp_access.agent": {+ "bind": { "access_mode": "body", "app_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "access_mode": {}, "app_id": {} },+ "required": ["app_id", "access_mode"]+ },+ "internal": false,+ "kind": "object",+ "method": "PUT",+ "path": "/openapi/v1/apps/{app_id}/webapp-access/agent",+ "summary": "Set who may open an agent app's web app (Enterprise)"+ },+ "get.marketplace.plugin": {+ "bind": {+ "category": "query",+ "limit": "query",+ "page": "query",+ "query": "query",+ "workspace_id": "path"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "category": {}, "limit": {}, "page": {}, "query": {}, "workspace_id": {} },+ "required": ["workspace_id"]+ },+ "internal": false,+ "kind": "list",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/marketplace/plugins",+ "summary": "Search the marketplace for plugins to install; each hit says if it is installed here"+ },+ "get.plugin": {+ "bind": { "category": "query", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "category": {}, "workspace_id": {} },+ "required": ["workspace_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/plugins",+ "summary": "Plugins installed in the workspace, with the provider ids each one adds"+ },+ "install.plugin": {+ "bind": { "identifiers": "body", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "identifiers": {}, "workspace_id": {} },+ "required": ["workspace_id", "identifiers"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/workspaces/{workspace_id}/plugins:install",+ "summary": "Start installing marketplace plugins; finishes in the background, check describe.plugin.task"+ },+ "describe.plugin.task": {+ "bind": { "task_id": "path", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "task_id": {}, "workspace_id": {} },+ "required": ["task_id", "workspace_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/plugin-tasks/{task_id}",+ "summary": "Progress of a plugin install or upgrade; check again while pending or running"+ },+ "delete.plugin": {+ "bind": { "plugin_id": "path", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "plugin_id": {}, "workspace_id": {} },+ "required": ["plugin_id", "workspace_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "DELETE",+ "path": "/openapi/v1/workspaces/{workspace_id}/plugins/{plugin_id}",+ "summary": "Uninstall a plugin from the workspace"+ },+ "describe.model_provider": {+ "bind": { "provider": "path", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "provider": {}, "workspace_id": {} },+ "required": ["provider", "workspace_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/model-providers/{provider}",+ "summary": "One model provider with its credential form and saved credentials (names only)"+ },+ "create.model_provider.credential": {+ "bind": { "credentials": "body", "name": "body", "provider": "path", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "credentials": {}, "name": {}, "provider": {}, "workspace_id": {} },+ "required": ["provider", "workspace_id", "credentials"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/workspaces/{workspace_id}/model-providers/{provider}/credentials",+ "summary": "Save a credential for a model provider; the provider checks it first"+ },+ "get.model": {+ "bind": {+ "limit": "query",+ "model_type": "query",+ "page": "query",+ "provider": "query",+ "query": "query",+ "workspace_id": "path"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "limit": {},+ "model_type": {},+ "page": {},+ "provider": {},+ "query": {},+ "workspace_id": {}+ },+ "required": ["workspace_id"]+ },+ "internal": false,+ "kind": "list",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/models",+ "summary": "Models in the workspace across providers, with whether each can be used now"+ },+ "create.model.credential": {+ "bind": {+ "credentials": "body",+ "model": "body",+ "model_type": "body",+ "name": "body",+ "provider": "path",+ "workspace_id": "path"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "credentials": {},+ "model": {},+ "model_type": {},+ "name": {},+ "provider": {},+ "workspace_id": {}+ },+ "required": ["provider", "workspace_id", "model", "model_type", "credentials"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/workspaces/{workspace_id}/model-providers/{provider}/models/credentials",+ "summary": "Save a credential for one model you name, for providers such as OpenAI-compatible or Ollama"+ },+ "get.tool": {+ "bind": {+ "limit": "query",+ "page": "query",+ "provider": "query",+ "provider_type": "query",+ "query": "query",+ "workspace_id": "path"+ },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": {+ "limit": {},+ "page": {},+ "provider": {},+ "provider_type": {},+ "query": {},+ "workspace_id": {}+ },+ "required": ["workspace_id"]+ },+ "internal": false,+ "kind": "list",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/tools",+ "summary": "Tools a workflow can call here, each with a ready tool node data"+ },+ "describe.tool_provider": {+ "bind": { "provider": "path", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "provider": {}, "workspace_id": {} },+ "required": ["provider", "workspace_id"]+ },+ "internal": false,+ "kind": "object",+ "method": "GET",+ "path": "/openapi/v1/workspaces/{workspace_id}/tool-providers/{provider}",+ "summary": "One tool provider with its API-key form and saved credentials (names only)"+ },+ "create.tool_provider.credential": {+ "bind": { "credentials": "body", "name": "body", "provider": "path", "workspace_id": "path" },+ "deprecated": false,+ "input": {+ "type": "object",+ "properties": { "credentials": {}, "name": {}, "provider": {}, "workspace_id": {} },+ "required": ["provider", "workspace_id", "credentials"]+ },+ "internal": false,+ "kind": "object",+ "method": "POST",+ "path": "/openapi/v1/workspaces/{workspace_id}/tool-providers/{provider}/credentials",+ "summary": "Save an API-key credential for a tool provider; the provider checks it first"}}}diff --git a/cli/test/fixtures/dify-mock/scenarios.ts b/cli/test/fixtures/dify-mock/scenarios.tsindex 8316192fe92..2fb6c78359f 100644--- a/cli/test/fixtures/dify-mock/scenarios.ts+++ b/cli/test/fixtures/dify-mock/scenarios.ts@@ -6,6 +6,7 @@ export type Scenario =| 'denied'| 'expired'| 'auth-expired'+ | 'forbidden'| 'rate-limited'| 'server-5xx'| 'slow-down'@@ -36,7 +37,6 @@ export type WorkspaceFixture = {name: stringrole: stringstatus: string- is_current: boolean}export type AppFixture = {@@ -81,14 +81,12 @@ export const WORKSPACES: WorkspaceFixture[] = [name: 'Default',role: 'owner',status: 'normal',- is_current: true,},{id: 'ws-2',name: 'Other',role: 'normal',status: 'normal',- is_current: false,},]diff --git a/cli/test/fixtures/dify-mock/server.test.ts b/cli/test/fixtures/dify-mock/server.test.tsindex 5eabcc5539b..49ee8b24079 100644--- a/cli/test/fixtures/dify-mock/server.test.ts+++ b/cli/test/fixtures/dify-mock/server.test.ts@@ -75,8 +75,6 @@ describe('dify-mock fixture server', () => {expect(body.data).toHaveLength(2)expect(body.data[0]?.id).toBe('ws-1')expect(body.data[0]?.status).toBe('normal')- expect(body.data[0]?.current).toBe(true)- expect(body.data[1]?.current).toBe(false)expect(body.hints).toEqual([])})diff --git a/cli/test/fixtures/dify-mock/server.ts b/cli/test/fixtures/dify-mock/server.tsindex cfd8d97cdf8..4dc78c65ae6 100644--- a/cli/test/fixtures/dify-mock/server.ts+++ b/cli/test/fixtures/dify-mock/server.ts@@ -44,6 +44,8 @@ export type DifyMock = {lastRequest: LastRequest | null/** Number of requests received, including GET _catalog */requestCount: number+ /** Runs before each device-token poll is answered: lets a test act while a resume waits. */+ onDeviceTokenPoll: (hook: () => void) => void}const TOKEN_RE = /^Bearer\s+dfo[ae]_[\w-]+$/@@ -53,6 +55,7 @@ const EMPTY_ERROR_PATH = '/empty-error'const BAD_VERIFICATION_URI = 'ftp://elsewhere.example/device'const HANG_MS = 30_000const OAUTH_PREFIX = '/openapi/v1/oauth/'+export const FORBIDDEN_HINT = 'ask a workspace owner for the editor role'const ServerErrorCode = {Unauthorized: 'unauthorized',@@ -71,6 +74,7 @@ const OpId = {ChatRun: 'run.console_app.chat',AdvancedChatRun: 'run.console_app.advanced_chat',FormSubmit: 'submit.run.form',+ RunEvents: 'get.run.event',} as constconst CATALOG_STALE_MESSAGE =@@ -195,7 +199,13 @@ function streamingRunResponse(function hitlPauseResponse(appId: string): string {return sseChunks([- { event: 'workflow_started', data: { id: 'wf-run-hitl-1', workflow_id: 'wf-1' } },+ {+ event: 'workflow_started',+ data: {+ workflow_run_id: 'wf-run-hitl-1',+ data: { id: 'wf-run-hitl-1', workflow_id: 'wf-1' },+ },+ },{ event: 'node_started', data: { id: 'n1', title: 'First Node' } },{event: 'human_input_required',@@ -255,6 +265,7 @@ export type MockState = {lastImportBody: Record<string, unknown> | nulllastRequest: LastRequest | nullrequestCount: number+ beforeDeviceToken?: () => void}async function readMultipartRunBody(@@ -435,6 +446,8 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {return c.json({ code: 'forbidden', message: 'resource_not_authorized', status: 403 }, 403)const scenario = getScenario()if (scenario === 'auth-expired') return unauthorized()+ if (scenario === 'forbidden')+ return errorResponse(ServerErrorCode.Forbidden, 'you may not do this', 403, FORBIDDEN_HINT)await next()})@@ -548,7 +561,6 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {name: w.name,role: getScenario() === 'resource-token' ? '' : w.role,status: w.status,- current: w.is_current,}))const total = rows.lengthconst hasMore = page * limit < total@@ -562,6 +574,12 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {})})+ app.get('/openapi/v1/workspaces/:wsId', (c) => {+ const ws = WORKSPACES.find((w) => w.id === c.req.param('wsId'))+ if (ws === undefined) return errorResponse(ServerErrorCode.NotFound, 'workspace not found', 404)+ return c.json({ id: ws.id, name: ws.name, role: ws.role, status: ws.status, created_at: null })+ })+// Reachable only under the `catalog-changed` scenario: the op that catalog v2 adds.app.get('/openapi/v1/workspaces/:wsId/ping', (c) => c.json({ ok: true }))@@ -747,9 +765,18 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {return c.json({ result: 'success' })})- app.post('/openapi/v1/apps/:id/human-input-forms/:formToken:submit', (c) => {- return c.json({})- })+ // Like the server: the submit names the run to follow, stopping at the next pause.+ app.post('/openapi/v1/apps/:id/human-input-forms/:formToken:submit', (c) =>+ c.json({+ hints: [+ {+ summary: 'Follow the run',+ op: OpId.RunEvents,+ input: { app_id: c.req.param('id'), task_id: 'wf-run-hitl-1', continue_on_pause: false },+ },+ ],+ }),+ )app.get('/openapi/v1/apps/:id/tasks/:task_id/events', (_c) => sseResponse(hitlResumedResponse()))@@ -777,6 +804,7 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {})app.post('/openapi/v1/oauth/device/token', async (c) => {+ state?.beforeDeviceToken?.()const scenario = getScenario()if (scenario === 'denied')return c.json({ error: 'access_denied', error_description: 'user rejected' }, { status: 400 })@@ -872,6 +900,9 @@ export function startMock(opts: DifyMockOptions = {}): Promise<DifyMock> {get requestCount() {return state.requestCount},+ onDeviceTokenPoll(hook) {+ state.beforeDeviceToken = hook+ },})})server.on('error', reject)diff --git a/cli/test/fixtures/kernel.ts b/cli/test/fixtures/kernel.tsindex e0aaba23d49..ad4217df46b 100644--- a/cli/test/fixtures/kernel.ts+++ b/cli/test/fixtures/kernel.ts@@ -80,7 +80,6 @@ export async function testContext(opts: TestWorldOptions): Promise<TestWorld> {const restoreEnv = applyEnv({[ENV.ConfigDir]: dir,- [ENV.CacheDir]: dir,[ENV.Server]: opts.env === true ? mock.url : undefined,[ENV.Token]: opts.env === true ? ENV_LOGIN_TOKEN : undefined,[ENV.WorkspaceId]: undefined,diff --git a/cli/test/setup.ts b/cli/test/setup.tsindex 70ec0406c20..a869384bc1f 100644--- a/cli/test/setup.ts+++ b/cli/test/setup.ts@@ -3,3 +3,4 @@;(globalThis as unknown as Record<string, string>).__DIFYCTL_BUILD_DATE__ ='1970-01-01T00:00:00.000Z';(globalThis as unknown as Record<string, string>).__DIFYCTL_CHANNEL__ = 'dev'+;(globalThis as unknown as Record<string, boolean>).__DIFYCTL_COMPILED__ = falsediff --git a/cli/test/skills/tree.test.ts b/cli/test/skills/tree.test.tsnew file mode 100644index 00000000000..74369e0f12e--- /dev/null+++ b/cli/test/skills/tree.test.ts@@ -0,0 +1,202 @@+import type { CommandConstructor } from '@/plugins/commands/command'+import type { CommandTree } from '@/plugins/commands/registry'+import { readdir, readFile } from 'node:fs/promises'+import { dirname, join, normalize, relative, sep } from 'node:path'+import { fileURLToPath } from 'node:url'+import { describe, expect, it } from 'vite-plus/test'+import { commandTree } from '@/commands/tree.generated'+import { parseCatalog } from '@/plugins/catalog'+import { HELP_WORD } from '@/plugins/commands/command'+import { mergeTrees, nodeAt } from '@/plugins/commands/registry'+import { GLOBAL_INPUT } from '@/plugins/global-flags'+import { opsTree } from '@/plugins/ops/tree'+import { propertiesOf } from '@/protocol/shape'+import { propertyFor } from '@/util/flag-name'++const SKILL_DIR = fileURLToPath(new URL('../../../skills/difyctl/', import.meta.url))+const CATALOG = fileURLToPath(new URL('../fixtures/catalog.json', import.meta.url))+const ROOT_DOC = 'SKILL.md'+const MAX_HOPS = 2+const LEAF_DEPTH = MAX_HOPS+const MAP_MAX_LINES = 60+const TOC_AFTER_LINES = 100+const TOC_HEADING = '## Contents'+const H2 = /^## .*$/m+const LINK = /\]\(([^)#\s]+\.md)\)/g+const COMMAND = /`difyctl ([^`]+)`/g+const FENCE = /^(`{3,})/+const CONTINUATION = /\\\s*\n\s*/g+const CODE_COMMAND = /^difyctl (.+)$/+const PIPE = ' | '+const FLAG = /(?:^|\s)--([a-z][a-z0-9-]*)/g+const PLACEHOLDER = /^<[^>]+>$/+const WORD = /^[a-z_]+(?:-[a-z_]+)*$/+const DOTTED_ID = /^[a-z_]+(?:\.[a-z_]+)+$/+const SPAN = /`([^`]+)`/g+const NON_WORD_START = /^[-<]/+const GLOBAL_FLAGS = [...Object.keys(GLOBAL_INPUT.shape), HELP_WORD]++async function docs(): Promise<string[]> {+ const out: string[] = []+ for (const entry of await readdir(SKILL_DIR, { recursive: true, withFileTypes: true })) {+ if (entry.isFile() && entry.name.endsWith('.md'))+ out.push(relative(SKILL_DIR, join(entry.parentPath, entry.name)).split(sep).join('/'))+ }+ return out+}++function links(doc: string, text: string): string[] {+ return [...text.matchAll(LINK)].map((m) =>+ normalize(join(dirname(doc), m[1] as string))+ .split(sep)+ .join('/'),+ )+}++function depths(text: ReadonlyMap<string, string>): Map<string, number> {+ const depth = new Map([[ROOT_DOC, 0]])+ const queue = [ROOT_DOC]+ while (queue.length > 0) {+ const doc = queue.shift() as string+ for (const next of links(doc, text.get(doc) ?? '')) {+ if (depth.has(next)) continue+ depth.set(next, (depth.get(doc) as number) + 1)+ queue.push(next)+ }+ }+ return depth+}++/** `difyctl` command lines inside fenced code blocks, with `\` continuations joined. */+function fencedCommands(body: string): string[] {+ const code: string[] = []+ let fence: string | undefined+ for (const line of body.split('\n')) {+ const open = FENCE.exec(line.trim())?.[1]+ if (fence === undefined) {+ if (open !== undefined) fence = open+ } else if (open !== undefined && open.length >= fence.length && line.trim() === open) {+ fence = undefined+ } else {+ code.push(line)+ }+ }+ return code+ .join('\n')+ .replace(CONTINUATION, ' ')+ .split('\n')+ .map((line) => CODE_COMMAND.exec(line.trim())?.[1])+ .filter((span): span is string => span !== undefined)+}++function leadingWords(span: string): string[] {+ const words: string[] = []+ for (const word of span.split(' ')) {+ if (!WORD.test(word)) break+ words.push(word)+ }+ return words+}++/**+ * The commands a line names: the exact command, or — when a `<placeholder>` follows a+ * group — every command one word below it.+ */+function commandsNamed(tree: CommandTree, span: string, words: readonly string[]) {+ const node = nodeAt(tree, words)+ if (node === undefined) return []+ if (node.command !== undefined) return [node.command]+ if (!PLACEHOLDER.test(span.split(' ')[words.length] ?? '')) return []+ return Object.values(node.subcommands)+ .map((child) => child.command)+ .filter((command): command is CommandConstructor => command !== undefined)+}++function flagsOf(command: CommandConstructor): string[] {+ return [...Object.keys(propertiesOf(command.flags())), ...GLOBAL_FLAGS]+}++function typedFlags(span: string): string[] {+ return [...(span.split(PIPE)[0] as string).matchAll(FLAG)].map((m) => propertyFor(m[1] as string))+}++describe('skills/difyctl tree', async () => {+ const all = await docs()+ const text = new Map(+ await Promise.all(+ all.map(async (d) => [d, await readFile(join(SKILL_DIR, d), 'utf8')] as const),+ ),+ )+ const catalog = parseCatalog(await readFile(CATALOG)).ops+ const ops = Object.keys(catalog)+ const { tree } = mergeTrees(commandTree, opsTree(catalog))+ const depth = depths(text)+ const commands = [...text].flatMap(([doc, body]) => [+ ...[...body.matchAll(COMMAND)].map((m) => ({ doc, span: m[1] as string })),+ ...fencedCommands(body).map((span) => ({ doc, span })),+ ])++ it('every relative link resolves', () => {+ for (const [doc, body] of text)+ for (const target of links(doc, body)) expect(all, `${doc} → ${target}`).toContain(target)+ })++ it('every doc is reachable within two hops of SKILL.md', () => {+ for (const doc of all) {+ expect(depth.has(doc), `${doc} unreachable`).toBe(true)+ expect(depth.get(doc) as number, doc).toBeLessThanOrEqual(MAX_HOPS)+ }+ })++ it('maps stay short and leaves link only to siblings', () => {+ for (const [doc, body] of text) {+ if ((depth.get(doc) as number) < LEAF_DEPTH) {+ expect(body.split('\n').length, doc).toBeLessThan(MAP_MAX_LINES)+ continue+ }+ for (const target of links(doc, body))+ expect(dirname(target), `${doc} → ${target}`).toBe(dirname(doc))+ }+ })++ it('long leaves open with contents', () => {+ for (const [doc, body] of text) {+ if ((depth.get(doc) as number) < LEAF_DEPTH) continue+ if (body.split('\n').length <= TOC_AFTER_LINES) continue+ expect(H2.exec(body)?.[0], doc).toBe(TOC_HEADING)+ }+ })++ it('every difyctl command exists locally or in the catalog', () => {+ for (const { doc, span } of commands) {+ const words = leadingWords(span)+ if (words.length === 0) {+ expect(span, `${doc}: difyctl ${span} names no command`).toMatch(NON_WORD_START)+ continue+ }+ const found = words[0] === HELP_WORD || nodeAt(tree, words) !== undefined+ expect(found, `${doc}: difyctl ${span}`).toBe(true)+ }+ })++ it('every flag on a command is one that command parses', () => {+ for (const { doc, span } of commands) {+ const named = commandsNamed(tree, span, leadingWords(span))+ if (named.length === 0) continue+ const allowed = new Set(named.flatMap(flagsOf))+ for (const flag of typedFlags(span))+ expect(allowed.has(flag), `${doc}: difyctl ${span}: ${flag}`).toBe(true)+ }+ })++ it('every dotted op id exists in the catalog', () => {+ const verbs = new Set(ops.map((op) => op.split('.')[0]))+ for (const [doc, body] of text) {+ for (const m of body.matchAll(SPAN)) {+ const span = m[1] as string+ if (!DOTTED_ID.test(span) || !verbs.has(span.split('.')[0])) continue+ expect(ops, `${doc}: ${span}`).toContain(span)+ }+ }+ })+})diff --git a/cli/vite.config.ts b/cli/vite.config.tsindex a7381e317ca..755aee4c4be 100644--- a/cli/vite.config.ts+++ b/cli/vite.config.ts@@ -29,6 +29,7 @@ export default defineConfig({__DIFYCTL_COMMIT__: JSON.stringify(buildInfo.commit),__DIFYCTL_BUILD_DATE__: JSON.stringify(buildInfo.buildDate),__DIFYCTL_CHANNEL__: JSON.stringify(buildInfo.channel),+ __DIFYCTL_COMPILED__: 'false',},},test: {diff --git a/cli/vitest.e2e.config.ts b/cli/vitest.e2e.config.tsindex 3c3a1347ef1..23c08ba2da9 100644--- a/cli/vitest.e2e.config.ts+++ b/cli/vitest.e2e.config.ts@@ -49,6 +49,7 @@ export default defineConfig({__DIFYCTL_COMMIT__: JSON.stringify(buildInfo.commit),__DIFYCTL_BUILD_DATE__: JSON.stringify(buildInfo.buildDate),__DIFYCTL_CHANNEL__: JSON.stringify(buildInfo.channel),+ __DIFYCTL_COMPILED__: 'false',},},test: {diff --git a/skills/README.md b/skills/README.mdindex 65015a5ed6e..971f617e962 100644--- a/skills/README.md+++ b/skills/README.md@@ -1,26 +1,34 @@-# difyctl skills+# difyctl skill-Agent skills for the difyctl CLI. They use the standard Agent Skills layout: one-folder per skill, each with a `SKILL.md`. There is no index to maintain.+One agent skill for the difyctl CLI: `skills/difyctl/`. It uses the standard+Agent Skills layout. `SKILL.md` is the root; the docs it links to sit under+`references/`.-`difyctl install skills <dir>` downloads them from GitHub at install time, from-the commit that difyctl was built from. `--from` points at any GitHub folder-with the same layout, or at a local folder. The same files install through the-Vercel installer: `npx skills add langgenius/dify --skill difyctl -g`.+The difyctl binary carries a built-in copy. `difyctl install skills <dir>`+writes that copy into `<dir>`. `--from <folder>` installs a local folder with+the same layout instead. The same files install through the Vercel installer:+`npx skills add langgenius/dify --skill difyctl -g`.-## Adding a skill+## Changing the skill-- One folder per skill: `difyctl` is the base skill, scenario skills are- `difyctl-<scenario>`.-- `SKILL.md` frontmatter has `name` (equal to the folder name: lowercase- letters, digits, dashes) and `description`. The description says when to use- the skill; the base skill quotes it.-- Any files may sit beside `SKILL.md`: `references/`, `scripts/`, `assets/`.- Commit scripts as executable (`chmod +x`); the installer keeps the bit.-- A scenario skill opens with: Read `../difyctl/SKILL.md` first.-- Every `difyctl <command>` named in backticks must exist in the command tree.- Every dotted op id must exist in `cli/test/fixtures/catalog.json`.-- List every scenario skill in the base skill's "Other skills" section.+The skill is a tree of linked docs, so an agent reads only the branch it needs.-A change here reaches users with the next difyctl build. Anyone can get it-sooner with `--from https://github.com/langgenius/dify/tree/main/skills`.+- `SKILL.md` frontmatter has `name` (`difyctl`) and `description`. The+ description says when to use the skill.+- `SKILL.md` and the docs it links to are maps. Keep each map under 60 lines.+- The docs one level further down are leaves. A leaf may link only to other+ leaves in its own folder.+- Every doc is at most 2 hops from `SKILL.md`.+- Write links as "Read X when ...", so the agent knows when to follow them.+- In a leaf over 100 lines, `## Contents` is the first `##` heading.+- Put each fact in one place and link to it from elsewhere.+- Any file in `skills/difyctl/` ships. Files starting with `#!` are installed+ executable.++`cli/test/skills/tree.test.ts` checks links, depth, sizes, and every `difyctl`+command, in backticks or in code blocks. Each command must exist locally or in+`cli/test/fixtures/catalog.json`, and each flag must be one that command+parses. Add an op's descriptor there when a doc starts+naming it.++A change here reaches users with the next difyctl build.diff --git a/skills/difyctl/SKILL.md b/skills/difyctl/SKILL.mdindex e62b3ccece6..9689c1d901d 100644--- a/skills/difyctl/SKILL.md+++ b/skills/difyctl/SKILL.md@@ -1,6 +1,6 @@---name: difyctl-description: 'Base skill for the difyctl CLI: find any command or Dify operation through help and run it as a command. Use when the task involves difyctl or a Dify server from the command line.'+description: 'Operate a Dify server through difyctl: find and run any operation, and build, test, publish and change Workflow and Chatflow apps. Use when the task involves difyctl, a Dify server, or Dify apps.'---# difyctl@@ -9,6 +9,8 @@ difyctl talks to a Dify server. Business commands are not built in: the server pAlways pass `--json`. Help and errors are text on a terminal and JSON in a pipe; `--json` (or `DIFY_OUTPUT=json`) forces JSON. Results and streams are always JSON.+Operations that remove or revoke have no confirmation prompt. Confirm with the human first.+## Finding what the CLI can doAn operation id is dotted, `run.console_app.chat`, and is typed as words: `difyctl run console_app chat`. Ids come from the server and can change, so look them up instead of assuming them.@@ -24,36 +26,9 @@ Four views under `help`, covering local commands and server operations as one trNot logged in, or the server unreachable, gives the local commands plus one line on stderr.-## Running an operation--`difyctl run console_app workflow --app-id <id> --inputs '{"a":1}'`. Each top-level field of `input` is a flag, dashes for underscores. Scalars take a value; objects, maps and lists of objects take a JSON literal or `@file.json`; lists of scalars repeat the flag. Fields named `input`, `stream`, `only`, `output`, `verbose`, `json` or `help` have no flag; pass them through `--input`.--`--input '{"a":1}'`, `--input @file.json` or `--input @-` (stdin) sends the whole body; field flags merge over it. A dotted id is a command with the dots as spaces: `run.console_app.workflow` is `difyctl run console_app workflow`.--Run an app with the op for its mode: `run console_app workflow`, `run console_app chat`, `run console_app advanced_chat`, `run console_app completion`. First `difyctl describe console_app --app-id <id> --json` and read `input_schema`; that is the shape of `inputs`. Local files go under `files`, keyed by the app's file variable name (`{"files":{"doc":"./r.pdf"}}` or a list of paths); files for the run itself under `attachments`; URLs straight into `inputs`.--## difyctl-only flags--`--stream` prints each event of a streaming op as one JSON line instead of folding them. `--only <event>` filters streamed events (repeatable). `--output <path>` saves a file-kind response; the default is the current directory under the server's filename, or `<op-id>.<ext>`. `--verbose` adds the raw server response to errors. A flag the operation's kind does not support exits 2.--## Reading results--Streaming ops fold to `{status, text, outputs?, total_tokens?, message_id?, conversation_id?, error?, hints}`. `text.answer` is the reply; `text.by_source` appears only while `status` is `incomplete`. `status` is `ended`, `failed` (exit 1), `suspended` (a form is waiting; follow `hints`) or `incomplete` (the stream broke early). Any response may carry `hints: [{summary, op, input, form?}]`, the server's next steps: next page, confirm step, reply op, form submit. Fill any `null` in `input` and pass it back with `difyctl <op, dots as spaces> --input '<input>'`.--## Errors and exit codes--Errors are one envelope on stderr: `{"error":{"code","message","hint"?,"details"?,"schema"?}}`. Exit 2 is bad input (schema included), 4 not logged in or forbidden, 6 catalog unavailable or unknown op (run `difyctl refresh cache` or upgrade difyctl), 7 rate limited.--## Login and environment--`difyctl login --server https://...` (device flow; `--no-browser` prints the URL and code; `--no-keyring` keeps the token in a file; `--insecure` skips TLS verification). One login at a time. `difyctl use workspace <id>` pins a workspace; `difyctl get workspace` shows them. Scripts skip login with `DIFY_SERVER` and `DIFY_TOKEN`; `DIFY_WORKSPACE_ID` overrides the pin; `DIFY_CONFIG_DIR` and `DIFY_CACHE_DIR` move the files.--`login` blocks until the browser approval arrives. Run `difyctl login --server <url> --no-browser` as a background job, relay the `open <url>` and `code <code>` lines from its stderr to the user, and do not cancel the job. Its exit code reports the result. In a sandbox, add `--no-keyring` and set `DIFY_CONFIG_DIR` to persistent storage on every call, so the login survives the next session. If background jobs do not survive between calls, run `login --no-wait` instead, relay the `verification_uri` and `user_code` it prints, and after the user approves run `login --resume` until it stops printing `status: pending`.--## Destructive operations--Operations that remove or revoke have no confirmation prompt. Confirm with the person first.--## Other skills+## Where to read next-Scenario skills add guidance for one kind of task. `difyctl get skills` shows them; `difyctl install skills <skills root> --skill <name>` installs one, where `<skills root>` is the folder above this file's folder. Re-running `difyctl install skills <skills root>` after upgrading difyctl refreshes every skill.+- Read [`references/setup.md`](references/setup.md) to check login or log in, switching server or workspace, or running in a sandbox or CI.+- Read [`references/operations.md`](references/operations.md) before running any operation: flags, inputs, files, results, hints, errors and exit codes.+- Read [`references/build-workflow.md`](references/build-workflow.md) when asked to create, change, test or publish a Workflow or Chatflow app.+- Read [`references/plugins.md`](references/plugins.md) to find tools, models and knowledge bases before building, when a plugin, model, tool or credential is missing, or when the human asks to install or remove a plugin.diff --git a/skills/difyctl/references/build-workflow.md b/skills/difyctl/references/build-workflow.mdnew file mode 100644index 00000000000..8531836f7a3--- /dev/null+++ b/skills/difyctl/references/build-workflow.md@@ -0,0 +1,35 @@+# Build a Workflow or Chatflow app++Four phases. Each ends with a gate; never skip one, even for a small app.++1. **Spec**: agree what the app must do. Gate: the human approves `spec.md`.+2. **Plan**: decide every node and config. Gate: the human approves `plan.md` and chooses how to build.+3. **Build**: create the app and build it slice by slice. Gate: each slice passes its tests and review.+4. **Hand over**: final checks, then publish and open access. Gate: the human says yes to going live.++## Rules++- Keep the working files in `difyctl/<app-slug>/` in the current folder: `spec.md`, `plan.md`, `app.yml`, and `live.yml` when changing an existing app.+- Requirement ids (`R1`, `R2`, …) from the spec run through the plan, the build and the final report.+- One writer per draft at a time.+- Nothing goes live without the human's yes.+- **Report problems; never work around them.** When something blocks the agreed design, stop and tell the human what you found and the options. Examples: a tool that isn't configured, a missing credential or plugin, a requirement a node can't meet, a check you can't pass. Never swap in a substitute on your own: an HTTP Request or Code node in place of a tool, prompt text in place of a knowledge base, a dropped or weakened requirement.+- **Every change from the approved spec or plan needs the human's yes before you build it.** List each one: what changes, why, and what it costs. "Use defaults" or "go" approves only the options you already showed with your recommendation. It never approves a substitute you didn't show.+- **Prefer an existing tool; the human picks.** For each outside service or model, rank the options: an installed and configured tool, then an official or partner plugin, then a workflow tool. HTTP Request or Code comes last. A missing key is not a reason to pick HTTP Request or Code: ask the human for it.++## Read next++- [`build-workflow/change.md`](build-workflow/change.md): read first when the app already exists.+- [`build-workflow/spec.md`](build-workflow/spec.md): read in the spec phase.+- [`build-workflow/plan.md`](build-workflow/plan.md): read in the plan phase.+- [`build-workflow/build.md`](build-workflow/build.md): read in the build phase.+- [`build-workflow/handover.md`](build-workflow/handover.md): read when the build is done.+- [`build-workflow/dsl.md`](build-workflow/dsl.md): read when writing or reading app YAML.+- Read [`plugins.md`](plugins.md) in the spec phase to find tools, models and knowledge bases, and when a plugin, model, tool or credential is missing.++## Limits++- A draft run paused on a human-input node can't be resumed over difyctl.+- Trigger-started workflows (webhook, schedule, plugin) can't be draft-tested.+- Loop and iteration nodes can't be tested alone; use a full draft run.+- With an app's Service API off, difyctl can't find, describe, export (exit 4), test, run or publish it; only import works. An admin turns it on with `difyctl set service_api --app-id <app_id> --enabled`.diff --git a/skills/difyctl/references/build-workflow/build.md b/skills/difyctl/references/build-workflow/build.mdnew file mode 100644index 00000000000..47117a59e2e--- /dev/null+++ b/skills/difyctl/references/build-workflow/build.md@@ -0,0 +1,76 @@+# Build phase++Start only when the human approved the plan and chose how to build. `<mode>` is `workflow` for a Workflow app and `advanced_chat` for a Chatflow app.++## Before the first slice++When you change an existing app, skip creating it and the skeleton slice. Start from the current draft.++Otherwise create the app once, and write its `app_id` into `plan.md`:++```bash+difyctl create console_app <mode> --name "<name>" --json+```++Build this one app; never make copies.++## Each slice++1. Export the draft. Keep `draft_hash`. Save `data` as `app.yml` on the first slice.++ ```bash+ difyctl export console_app dsl --app-id <app_id> --json+ ```++2. Write the slice's nodes and edges into `app.yml` from the node table. Make no new decisions. Read [dsl.md](dsl.md).+3. Check the YAML. Fix every `error` by its `loc` and check again until `valid` is true.++ ```bash+ jq -Rs '{yaml_content: .}' difyctl/<app-slug>/app.yml |+ difyctl check console_app dsl --app-id <app_id> --input @- --json+ ```++4. Import over the draft. Always send the YAML through stdin.++ ```bash+ jq -Rs '{yaml_content: .}' difyctl/<app-slug>/app.yml |+ difyctl import console_app dsl --app-id <app_id> --mode yaml-content --draft-hash <draft_hash> --input @- --json+ ```++ - `completed`: go on. Export again before the next import; the hash changed.+ - `completed-with-warnings`: stop and read `warnings`.+ - `pending`: the DSL version differs from the server's. Show the human both versions. On a yes, run `difyctl confirm console_app dsl_import --import-id <id> --json`.+ - `dsl_invalid`: fix the issues in `details` by `loc`.+ - `draft_changed` (409, also on `confirm`): someone else edited the draft since your export. Export again, show the human the difference, and never overwrite it.+ - Any other failure: stop and show the human the message.++5. Test each new node alone. It reuses the last full run's values; override them with `--inputs`, keyed `#<node_id>.<var>#`. Give a file variable a local file with `--files '{"<variable>": "<path>"}'`.++ ```bash+ difyctl test node <mode> --app-id <app_id> --node-id <node_id> --inputs '{"#<node_id>.<var>#": "<value>"}' --json+ ```++6. Run the whole draft on the slice's acceptance cases; check each by its check type. Chatflow also takes `--query "<message>"`. Leave out `--inputs` when the start node has no variables.++ ```bash+ difyctl test console_app <mode> --app-id <app_id> --inputs '{"<var>": "<value>"}' --json+ ```++7. Review the slice against the plan, and the YAML against the node table.+8. Tick the slice in `plan.md` with its run ids. A new session resumes at the first unticked slice.++## When something fails++Find the node that failed and what it received:++```bash+difyctl get run node --app-id <app_id> --run-id <run_id> --json+```++A fix that changes the plan or spec follows the next section.++## Changes to the plan or spec++Never build a change first and report it later; ask as the rules in `build-workflow.md` say. On a yes, update the plan (and the spec, if it changes), then the YAML. Log it under "Changes during build" with when the human approved it.++The build phase never publishes.diff --git a/skills/difyctl/references/build-workflow/change.md b/skills/difyctl/references/build-workflow/change.mdnew file mode 100644index 00000000000..a1705f08913--- /dev/null+++ b/skills/difyctl/references/build-workflow/change.md@@ -0,0 +1,43 @@+# Change an existing app++Use this path when the app already exists. It reuses the four phases.++1. Find the app and confirm with the human that it is the right one:++ ```bash+ difyctl get console_app --name <name> --json+ ```++ If the app is missing, its Service API may be off (see Limits in `build-workflow.md`). Ask the human for its id.++2. Export first.+ - List the versions. Note the `id` of the row with `current: true`: that is the live version.+ - Export that version and save it as `difyctl/<app-slug>/live.yml`. This is the live baseline.+ - Export the draft separately and keep its `draft_hash`. An export without `--workflow-id` returns the draft, not the live version.++ ```bash+ difyctl get console_app version --app-id <app_id> --json+ difyctl export console_app dsl --app-id <app_id> --workflow-id <version_id> --json | jq -r .data > difyctl/<app-slug>/live.yml+ difyctl export console_app dsl --app-id <app_id> --json+ ```++ If the draft differs from the live version, show the human the difference. Ask which one to start from. If the human picks live, import `live.yml` over the draft with the draft's `draft_hash`. Check the result as in [build.md](build.md).++ ```bash+ jq -Rs '{yaml_content: .}' difyctl/<app-slug>/live.yml |+ difyctl import console_app dsl --app-id <app_id> --mode yaml-content --draft-hash <draft_hash> --input @- --json+ ```++ Publishing replaces the live version, so that version id is the one to go back to. To go back, copy it into the draft, then publish:++ ```bash+ difyctl restore console_app version --app-id <app_id> --version-id <version_id> --json+ difyctl publish console_app --app-id <app_id> --json+ ```++ If restore fails, export the draft for a fresh `draft_hash`, import `live.yml` over the draft instead, then publish.++3. If `difyctl/<app-slug>/` has no `spec.md`, the app was built elsewhere. Rebuild a baseline spec from the export: the graph, the requirements you can infer, the inputs and outputs. The human confirms it.+4. Write the change as a "Change" section in the spec: new, changed and removed requirements and cases. Existing cases become regression cases.+5. Plan only the nodes that change, in slices as usual. After you edit the export, run `difyctl check console_app dsl` on it before every import, as in [build.md](build.md).+6. At the end, run every old case again. Then hand over as usual.diff --git a/skills/difyctl/references/build-workflow/dsl.md b/skills/difyctl/references/build-workflow/dsl.mdnew file mode 100644index 00000000000..f8ece50be6c--- /dev/null+++ b/skills/difyctl/references/build-workflow/dsl.md@@ -0,0 +1,39 @@+# App DSL++Start from an export of the app's draft. A new Workflow app's export is empty. A new Chatflow's is `start` → `llm` (no model, so `resource_unavailable`) → `answer` (`{{#llm.text#}}`). Keep the export's `version`, `kind`, `features`, `environment_variables` and `conversation_variables`.++## Where things go++- `app.mode` is `workflow` for a Workflow app and `advanced-chat` for a Chatflow app.+- `workflow.graph.nodes[]`: `{id, type: custom, data: {type, title, version, ...}, position: {x, y}}`. The rest of `data`, and `version`, come from `difyctl describe node_type --node-type <type>`.+- `workflow.graph.edges[]`: `{id, source, target, sourceHandle, targetHandle: target}`. `sourceHandle` is `source`, except on branch nodes:+ - if-else: each case's `case_id`, plus `false` for else;+ - question classifier: each class's `id`;+ - human input: each `user_actions` id, plus `__timeout`;+ - `error_strategy: fail-branch` adds a `fail-branch` handle for failure. Success still leaves by the node's usual handles: `source`, or the branch handles above.+- Give every branch an edge, including `false` and `__timeout`.+- End node output names must be unique across all End nodes.+- A node id is any unique string. Never change the id of an existing node.+- Read another node's output as `{{#<node_id>.<var>#}}` in text, and `[<node_id>, <var>]` in a `value_selector`.+- An LLM node's `model` is the `node_model` of a row from `difyctl get model --model-type llm`, as the plan names it.+- A knowledge-retrieval node starts from a row's `node_data` in `difyctl get knowledge_base`.+- Never put secret values in the DSL.+- Don't use `datasource` or `knowledge-index` nodes. They belong to knowledge pipelines.+- An import over an existing app copies the YAML's `app.name`, description and icon onto the app.+- Import fills empty containers, such as Start `variables` and tool parameter maps. It never fills in a model, classes or a prompt.++## Tool node++- Start from the tool's `node_data` in `difyctl get tool`. Put it in the node's `data` as it is.+- Keep `tool_node_version: "2"`. Every value in `tool_parameters` and `tool_configurations` stays `{type, value}`.+- Fill every `null` value: `{type: constant, value: …}`, `{type: mixed, value: "{{#node_id.var#}}"}`, or `{type: variable, value: [node_id, var]}`.+- Leave out `credential_id`; the workspace's default credential is used.++## The check++`difyctl check console_app dsl` and the import run the same check. Each issue has a `code`, a `severity`, a `node_id`, a `loc` that points to the field, and a `message`.++- An `error` stops the import. Fix it by its `loc`.+- A `warning` does not stop the import, but the release check fails on it. Fix it, or report it to the human:+ - `resource_unavailable`: a model, tool or plugin the workspace lacks. Runs fail on it.+ - `branch_unconnected`: a branch with no edge. A run that takes it stops there.diff --git a/skills/difyctl/references/build-workflow/handover.md b/skills/difyctl/references/build-workflow/handover.mdnew file mode 100644index 00000000000..e4a59f6b8cb--- /dev/null+++ b/skills/difyctl/references/build-workflow/handover.md@@ -0,0 +1,49 @@+# Hand-over phase++Start when every slice in `plan.md` is ticked. `<mode>` is `workflow` or `advanced_chat`.++1. Run every acceptance case in the spec on the draft. Report pass or fail per requirement and per case, with your reasoning for each `judged` case.+2. Check the release, after the acceptance run so `tested` covers the current draft:++ ```bash+ difyctl check console_app release --app-id <app_id> --json+ ```++ Fix every item in `issues`. If `tested` fails, run the draft again. Go on only when `ready` is true.++3. Stop at the human gate. Show in plain words: the `changes` against the published version, the `checks`, the acceptance results, the "Changes during build" list, and anything still open.+4. On a yes, publish. Show any `warning` in the result. Then confirm the row whose `id` is the result's `version_id` shows `current: true`:++ ```bash+ difyctl publish console_app --app-id <app_id> --json+ difyctl get console_app version --app-id <app_id> --json+ ```++5. Settle access. A new app starts with the web app and the Service API on. Ask the human about each one. `--enabled=false` turns a setting off.+ - Web app. When it stays on, give the human the `url` from the result.++ ```bash+ difyctl set webapp <mode> --app-id <app_id> --enabled --json+ ```++ - Service API (needs an admin). Warn the human first what turning it off costs (see Limits in `build-workflow.md`), and note the app id. If the human wants it off, record that and turn it off after the smoke test in step 6: `difyctl run` fails with `service_api_disabled` while it is off.++ ```bash+ difyctl set service_api --app-id <app_id> --enabled --json+ ```++ - Who may open the web app (Enterprise): `public`, `private_all` or `sso_verified`. Picking members or groups (`private`) is done in the Dify console. `difyctl run` obeys this too, so the logged-in account must be allowed for the smoke test. `public` exits 4 with `webapp_public_access_disabled` when the server disables public web apps; offer the human `private_all` or `sso_verified`.++ ```bash+ difyctl set webapp_access --app-id <app_id> --access-mode <access_mode> --json+ ```++6. Smoke test the live app with one acceptance case. Chatflow also takes `--query "<message>"`.++ ```bash+ difyctl run console_app <mode> --app-id <app_id> --inputs '{"<var>": "<value>"}' --json+ ```++ Then, if the human chose to turn the Service API off in step 5, turn it off now with `--enabled=false`.++7. Close. Mark `plan.md` as published with the `version_id`, the date and the url. Give the human a short summary that lists every change from the spec and plan, and when the human approved it.diff --git a/skills/difyctl/references/build-workflow/plan.md b/skills/difyctl/references/build-workflow/plan.mdnew file mode 100644index 00000000000..c1b24d4f990--- /dev/null+++ b/skills/difyctl/references/build-workflow/plan.md@@ -0,0 +1,58 @@+# Plan phase++Start only when the human has approved `spec.md`. The plan phase ends when the human approves `difyctl/<app-slug>/plan.md` and chooses how to build.++## How to plan++1. Turn each spec step into nodes. Use only node types `difyctl get node_type` lists. Read each type's schema, defaults and `version` with `difyctl describe node_type --node-type <type>`.+2. Settle every config in full, so the build only changes format:+ - LLM: model, prompt text and outputs.+ - If-else: conditions, and where each branch goes.+ - Tool: the row from `difyctl get tool --provider <id>`, and a value for every parameter. Never guess one.+ - Human input: the form, the actions, the timeout, and where each action and `__timeout` goes.+ - Code: the code itself.+ - Variable references, written as `{{#node_id.var#}}`.+3. Draw the node-level Mermaid graph with real node ids, every edge, and a label on every branch.+4. Cut the build into slices. Each slice is small and connected, and imports and runs on its own. Slice 1 is the skeleton: start → end (Chatflow: start → answer; set the starter `llm` node's model or remove it and rewrite `answer`) with the final inputs and outputs.+5. Map the tests: a `difyctl test node <mode>` call with inputs for each new node, and a full draft run (`difyctl test console_app <mode>`) at the end of each slice on the cases it can pass. `<mode>` is `workflow` or `advanced_chat`.+6. Check coverage. Every requirement maps to a node and a test. Every resource is confirmed, and each chosen plugin is installed and configured. An open resource blocks approval.+7. Ask the human to review the plan, and to choose how to build:+ - you build it alone; or+ - one fresh subagent per slice, one after another, given the slice text, the file paths and the `app_id`. A reviewer subagent checks each slice. Never run two on one app at once: their imports collide on the draft hash.++## Template++Copy this into `plan.md` and fill it in.++````markdown+# <App name>: plan++App: <name>. Mode: <workflow or advanced_chat>. `app_id`: <filled in at build>. Spec: spec.md.++## Node graph++```mermaid+flowchart LR+ start --> classify+ classify -- order --> order_llm --> answer+ classify -- other --> answer+```++## Node table++| Id | Type | Version | Title | Config | Inputs used | Outputs | Covers |+| --------- | ---- | ------- | ----------- | ---------------------------------------------------- | ----------------- | ------- | ------ |+| order_llm | llm | 1 | Order reply | model: <provider>/<model>; system prompt: "<prompt>" | `{{#sys.query#}}` | text | R1 |++## Slices++- [ ] Slice 2: add `classify`, `order_llm`. Covers R1. Node tests: `order_llm` with query "Où est ma commande ?". Full run: A1. Runs: <run ids>++## Test map++- A1: `test console_app advanced_chat`, query "Où est ma commande ?", judged.++## Changes during build++- <what changed>: <why>. Cost if wrong: <cost>. Approved: <when>.+````diff --git a/skills/difyctl/references/build-workflow/spec.md b/skills/difyctl/references/build-workflow/spec.mdnew file mode 100644index 00000000000..aa0b016305a--- /dev/null+++ b/skills/difyctl/references/build-workflow/spec.md@@ -0,0 +1,64 @@+# Spec phase++The spec phase ends when the human approves `difyctl/<app-slug>/spec.md`. Don't plan before that.++## How to run the spec talk++1. Start from intent: what the app is for, who uses it, what a good result looks like. Ask one question at a time, with choices where you can.+2. Choose the mode early and say why. Workflow: one run, inputs to outputs. Chatflow: a conversation with memory.+3. As you talk, keep two things:+ - **Requirements.** Each condition or feature the human states becomes `R<n>`, in their words, typed `feature` (something the app does), `rule` (a condition or limit) or `failure` (what happens when something goes wrong).+ - **Process graph.** A Mermaid graph of business steps, not nodes.+4. Walk 3 to 6 realistic cases through the graph with the human. Include edge cases: empty input, a tool failing, an answer too long.+5. Collect resources: models, tools and plugins, knowledge bases, credentials.+ - For each step that calls an outside service or needs a model, search first: `difyctl get tool --query <service>`, `difyctl get model --model-type llm`, `difyctl get knowledge_base --query <words>`, then `difyctl get marketplace plugin --query <service>`.+ - Show the human a short list per step, ranked by the tool rule in `build-workflow.md`: name, brief, publisher type, install count, installed and configured or not.+ - If the best option needs something from the human (an API key, an install, a knowledge base to upload), ask for it.+ - Record the human's choice and the options shown. Write an unknown item as open; never guess a name.+6. Before you ask for approval, read the requirements back and ask "anything missing?". Each requirement needs a graph step and at least one acceptance case. Raise any gap with the human.+7. Write the spec, check it against itself, and ask the human to review it.++Acceptance check types: `exact` (the output must match), `contains` (given text or a pattern), `judged` (you grade against the case's rubric and show your reasoning).++## Template++Copy this into `spec.md` and fill it in.++````markdown+# <App name>: spec++## Goal++<What it does, for whom, what success looks like.>++## Mode++<Workflow or Chatflow>, because <why>.++## Requirements++- R1 (feature): Reply in the language the customer wrote in. Step: Answer.++## Inputs and outputs++- <name>: <type>, <required or optional>, e.g. <example>.++## Process++```mermaid+flowchart LR+ A[Read the question] --> B[Find the answer] --> C[Reply]+```++## Acceptance cases++- A1: Customer asks in French. Inputs: query "Où est ma commande ?". Expected: French, gives the status. Check: judged, French and under 80 words. Covers R1.++## Resources++- <need>: <choice>. Shown: <options>. <confirmed or open>, provided by <who>.++## Out of scope and open questions++- <item>+````diff --git a/skills/difyctl/references/operations.md b/skills/difyctl/references/operations.mdnew file mode 100644index 00000000000..340079f2d8e--- /dev/null+++ b/skills/difyctl/references/operations.md@@ -0,0 +1,25 @@+# Running operations++`difyctl run console_app workflow --app-id <id> --inputs '{"a":1}'`. Each top-level field of `input` is a flag, dashes for underscores. Scalars take a value; objects, maps and lists of objects take a JSON literal or `@file.json`; lists of scalars repeat the flag. Fields named `input`, `stream`, `only`, `output`, `verbose`, `json` or `help` have no flag; pass them through `--input`.++`--input '{"a":1}'`, `--input @file.json` or `--input @-` (stdin) sends the whole body; field flags merge over it. A dotted id is a command with the dots as spaces: `run.console_app.workflow` is `difyctl run console_app workflow`.++Run an app with the op for its mode: `run console_app workflow`, `run console_app chat`, `run console_app advanced_chat`, `run console_app completion`. First `difyctl describe console_app --app-id <id> --json` and read `input_schema`; that is the shape of `inputs`. Local files go under `files`, keyed by the app's file variable name (`{"files":{"doc":"./r.pdf"}}` or a list of paths); files for the run itself under `attachments`; URLs straight into `inputs`.++## difyctl-only flags++`--stream` prints each event of a streaming op as one JSON line instead of folding them. `--only <event>` filters streamed events (repeatable). `--output <path>` saves a file-kind response; the default is the current directory under the server's filename, or `<op-id>.<ext>`. The default never replaces an existing file: it exits 2, and you pass `--output` to choose the path (an `--output` path is replaced). `--verbose` adds the raw server response to errors. A flag the operation's kind does not support exits 2.++## Reading results++Streaming ops fold to `{status, text, outputs?, total_tokens?, message_id?, conversation_id?, run_id?, error?, hints}`. `text.answer` is the reply; `text.by_source` appears only while `status` is `incomplete`. `status` is `ended`, `failed` (exit 1), `suspended` (a form is waiting; follow `hints`) or `incomplete` (stream broke early; exit 0, so check `status`). Any response may carry `hints: [{summary, op, input, form?}]`, the server's next steps: next page, confirm step, reply op, form submit. Errors can carry them too, at `error.server.hints`. Fill any `null` in `input` and pass it back with `difyctl <op, dots as spaces> --input '<input>'`.++After `submit.run.form`, run its `get.run.event` hint to follow the run; repeat if it suspends again.++## Errors and exit codes++Stderr envelope: `{"error":{"code","message","hint"?,"details"?,"schema"?,"http_status"?,"server"?}}`. `code` is difyctl's (`server_error` for server rejections); the server's code is `error.server.code` (e.g. `dsl_invalid`). `details`: `[{loc,msg}]`.++Exit: 2 bad input caught locally (incl. near-miss command); 1 server rejection or other failure; 4 not logged in (incl. unknown word while logged out), 401, 403 (a domain `error.server.code` such as `webapp_public_access_disabled`, `service_api_disabled` or `plugin_install_forbidden` is not a login problem: read the code and its hint); 6 catalog unavailable or `unknown_op`; 7 rate limited.++PowerShell: use `--input @file.json`, and `$env:VAR='v'; difyctl ...`.diff --git a/skills/difyctl/references/plugins.md b/skills/difyctl/references/plugins.mdnew file mode 100644index 00000000000..8682c226eb0--- /dev/null+++ b/skills/difyctl/references/plugins.md@@ -0,0 +1,38 @@+# Plugins, models and credentials++## Find tools, models and knowledge bases++1. `difyctl get tool --query <service>` lists tools the workspace can use: built-in and plugin tools, workflows published as tools, API tools and MCP tools. Each row has `configured` and a ready `node_data`.+2. `difyctl get model --model-type llm` lists models across providers (`--provider <id>` for one). Use one whose `status` is `active`. Paste the row's `node_model` as the LLM node's `model` block; don't build it by hand.+3. For knowledge bases: `difyctl get knowledge_base --query <words>`. A knowledge-retrieval node needs a row's `node_data`.+4. Nothing fits: `difyctl get marketplace plugin --query <service> --category tool` (or `--category model`).+5. When building an app, rank the options by the tool rule in [build-workflow.md](build-workflow.md).++## Missing plugins after an import++1. `difyctl check console_app dependency --app-id <app_id>` lists what the app needs and lacks. Its hint is a ready `install.plugin` call with every missing marketplace plugin.+2. Plugins from GitHub or a package file can't be installed with difyctl. Tell the human to install them in the console.++## Find and install++1. `difyctl get marketplace plugin --query <words>` searches the marketplace. Each hit has `identifier` (the versioned id to install) and `installed`.+2. Confirm with the human before installing. Then `difyctl install plugin --identifiers <identifier>`.+3. Install finishes in the background. Run the `describe.plugin.task` hint until `status` is `success` or `failed`. On `failed`, show the human each plugin's `message`. If `all_installed` is true there is no task; follow the provider hint.+4. On success the hint names the provider to set up: `describe.model_provider` or `describe.tool_provider`.++`get.plugin` lists installed plugins; `provides` gives their provider ids.++## Credentials++1. `difyctl describe model_provider --provider <id>` (or `describe tool_provider`) shows `credential_form` and the saved `credentials` (names only).+2. Ask the human for each form value. Never invent one, never print it, never write it into the working folder.+3. Pass the values on stdin: `difyctl create model_provider credential --provider <id> --credentials @-` (for tools, `difyctl create tool_provider credential --provider <id> --credentials @-`), then write the JSON object to stdin.+4. Rejected (model 422, tool 400): nothing saved; show the message, ask again.+5. Model providers only: if a credential is already active, the hint offers `set` to replace it. `active: false` with no hint means the model has saved credentials but none in use: ask the human to pick one in the console.+6. A tool provider whose `credential_types` lacks `api-key` uses OAuth. Ask the human to authorize it in the console.++Self-hosted or OpenAI-compatible models: `create model credential` with `--provider <id>`, `--model`, `--model-type` and `--credentials @-`.++## Remove++Only when the human asks: `delete.plugin`. Removing a plugin breaks apps that use it; say so first. Uninstalling also deletes the plugin's saved credentials.diff --git a/skills/difyctl/references/setup.md b/skills/difyctl/references/setup.mdnew file mode 100644index 00000000000..5290715fbec--- /dev/null+++ b/skills/difyctl/references/setup.md@@ -0,0 +1,37 @@+# Login and environment++## Log in++`login` uses the device flow: it prints a URL and a code, the human approves in a browser, and difyctl stores a token. One login at a time. A new login replaces the old one, and it replaces the code the human is looking at.++**Check first.** Run `difyctl login --resume`. If it prints an `email`, you are logged in: skip login. If it fails with `not_logged_in`, log in.++**Server.** Always pass `--server <url>`; `login` fails with `usage_missing_arg` without it. If the human has not named a server, ask which one. Never guess one.++Log in only this way:++1. `difyctl login --server <url> --no-browser --no-wait`. It saves a pending login and prints `verification_uri`, `user_code` and `expires_in` (seconds), then exits.+2. Give the human the URL and the code. Ask them to reply when they have approved. Then end your turn. Do not poll, do not sleep, and do not start a background job.+3. When the human replies, run `difyctl login --resume` once. If it prints the account `email`, you are logged in. If it prints `status: pending`, tell the human it is not approved yet and end your turn again.+4. If the code expires or the human denies it, `--resume` fails. Start again from step 1.++Never run `login` without `--no-wait`. It blocks until the human approves.++A script that already has a token skips login: set `DIFY_SERVER` and `DIFY_TOKEN`. (v1's `DIFY_HOST` is not read.)++`--no-browser` prints the URL instead of opening one; always pass it as an agent. `--insecure` skips TLS verification and allows `http://` (local dev only).++## Sandboxes and machines without a keyring++The token goes to the OS keyring by default. On Linux without a DBus session, difyctl uses a file instead, because the keyring there is lost when the session ends. In a sandbox, a container or a headless VM, the keyring can still be lost between sessions. There:++- Add `--no-keyring` to `login`, so the token goes to a file. Pass it on the `--no-wait` call; `--resume` remembers it.+- Leave `DIFY_CONFIG_DIR` unset unless the default folder is lost between sessions (macOS `~/.config/difyctl`, Linux `${XDG_CONFIG_HOME:-~/.config}/difyctl`, Windows `%APPDATA%\difyctl`). If you set it, put it on every command (`DIFY_CONFIG_DIR=<dir> difyctl ...`): an `export` does not carry over when each command runs in a new shell. The pending login from `--no-wait` lives there too, so `--resume` needs the same value. A `not_logged_in` error names the folder it checked.++## Workspace++`difyctl get workspace` lists your workspaces. `difyctl use workspace <id>` pins one on this device; later commands fill `workspace_id` from it. The pin is difyctl's own: it does not change the workspace open in the web console. `difyctl describe workspace` with no id shows the pinned workspace. `DIFY_WORKSPACE_ID` overrides the pin for one call.++## Files++`DIFY_CONFIG_DIR` holds login, tokens and catalog. `DIFY_CACHE_DIR` is unused.