@freelog-cli/cli2 0.5.0 → 0.5.1

package/dist/docs/09-/346/214/211/345/234/272/346/231/257/346/223/215/344/275/234.md

@@ -0,0 +1,108 @@
+# 按场景操作
+
+先判断资源是否已经在线上存在、是否已经发行过版本、当前工程是否已有 `.freelog/` 身份。不要把 `init`、`create`、`bind` 当成同义词：它们分别是立项、建线上资源壳、接入已有线上资源。
+
+所有例子以 `--env dev` 为例；多资源工程中，每一条涉及某资源的命令都补上该资源已记录的 `--file <path>`。
+
+## 先选入口
+
+| 你现在的情况 | 从这里开始 | 不要做 |
+|---|---|---|
+| 空目录，普通文件资源还未上线 | `init --type <最终叶子>`，再 `create` | 把父类型或类型名称交给 `--type`。 |
+| 已有普通文件工程、没有线上资源 | `create --type <最终叶子> --file <文件>` | 为了建壳强行覆盖工程执行 `init`。 |
+| 空目录，要从官方主题/插件模板开始 | `init theme|widget <目录> --template <id>` | 选择资源类型，或手工复制本地模板。 |
+| 已有主题/插件工程、没有线上资源 | `create --type RT001|RT002 --file <dist|build>` | 对非空工程再执行 `init`，或自己先打 zip。 |
+| 线上有自己的壳但没有发行版本 | `bind --file <文件或构建目录>`，再 `create-version` | 再次 `create`。 |
+| 线上已有发行版本 | `bind --file <文件或构建目录>`，再 `draft pull` 和 `update-version` | 用 `create-version` 再发 1.0.0。 |
+| 已有本地身份和未提交工作稿 | `version show --local` 后继续编辑或丢稿 | 手工编辑工作稿 JSON。 |
+| 只改展示信息、策略或上下架 | 进入资源管理命令 | 为此创建新版本或新资源壳。 |
+
+## 场景一：从空目录发行普通文件首版
+
+```powershell
+freelog-cli login --env dev
+freelog-cli init . --type RT006003 --yes --env dev
+freelog-cli create --title "我的视频" --name my-video --file video.mp4 --yes --env dev
+freelog-cli create-version --prepare --file video.mp4 --env dev
+freelog-cli version show --local --env dev
+freelog-cli create-version --yes --file video.mp4 --env dev
+```
+
+不知道最终叶子 code 时，先运行 `type search <关键词>`，或省略 `init` 的 `--type` 进入层级、搜索和直接输入 code 的选择器。首版固定为 `1.0.0`。
+
+## 场景二：已有普通文件工程，创建首版资源
+
+不需要也不能为了写状态覆盖已有工程。登录后直接明确类型与文件：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli create --title "已有视频" --name existing-video --type RT006003 --file video.mp4 --yes --env dev
+freelog-cli create-version --file video.mp4 --prepare --env dev
+freelog-cli create-version --file video.mp4 --yes --env dev
+```
+
+`create` 只登记文件路径并创建资源壳；文件不存在、为空、过大或解析失败时，会在 `create-version` 停止，线上不会出现半个版本。
+
+## 场景三：从官方模板创建主题或插件并发行首版
+
+```powershell
+freelog-cli login --env dev
+freelog-cli template list
+freelog-cli init theme my-theme --template vite-react-ts --yes
+freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
+# 在工程自己的流程中运行构建，得到 dist/
+freelog-cli create-version --cwd my-theme --file dist --prepare --env dev
+freelog-cli create-version --cwd my-theme --file dist --yes --env dev
+```
+
+插件把 `theme` 换为 `widget`；它的固定类型是 `RT002`，主题是 `RT001`。模板初始化后的建壳不传 `--type`，固定类型已在身份中。
+
+## 场景四：已有主题或插件工程，创建首版资源
+
+既有非空工程不运行 `init`，也没有必要补造模板元数据。明确其固定类型和构建目录：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli create --title "已有主题" --name existing-theme --type RT001 --file dist --yes --env dev
+# 自己完成构建后
+freelog-cli create-version --file dist --prepare --env dev
+freelog-cli create-version --file dist --yes --env dev
+```
+
+插件使用 `--type RT002`。`dist` / `build` 是目录；CLI 仅在提交前临时压缩其中内容，绝不把 zip 写进 `filePath`。
+
+## 场景五：自己的线上资源未发行，在本地补接后发首版
+
+```powershell
+freelog-cli login --env dev
+freelog-cli bind <resourceId或username/name> --file video.mp4 --env dev
+freelog-cli create-version --file video.mp4 --prepare --env dev
+freelog-cli create-version --file video.mp4 --yes --env dev
+```
+
+主题/插件把 `video.mp4` 换成 `dist` 或 `build`。`bind` 会从平台读取类型；对主题/插件，没有已记录目录时 `--file` 是必填项。
+
+## 场景六：自己的线上资源已发行，在本地接入并发新版本
+
+```powershell
+freelog-cli login --env dev
+freelog-cli bind <resourceId或username/name> --file dist --env dev
+freelog-cli version draft pull --env dev
+# 编辑属性、可选配置、依赖或说明
+freelog-cli update-version --file dist --bump patch --yes --env dev
+```
+
+普通文件把 `dist` 换成文件。使用 `--version 1.1.0` 也可以代替 `--bump patch`；两者不能同时传。若已有本地工作稿，先 `version show --local`，决定继续、`version draft discard`，或用 `version draft pull --yes` 明确覆盖。
+
+## 场景七：构建路径、工作稿或多资源工程发生变化
+
+- 构建输出从 `dist` 变成 `build`：单份资源用 `version set --artifact build`；多份资源用 `version set --file dist --artifact build`。只更新记录，不上传也不提交。
+- 文件或目录不存在：先恢复真实产物；CLI 不会复用旧 SHA1 发新版本。
+- 一个工程中有多份身份：`create`、`bind`、`create-version`、`update-version`、`version draft pull` 都传对应的已记录 `--file`；发版要换产物时再传 `--artifact`。不传时 CLI 会停止，不会猜第一份。
+- 想从另一线上版本重新开始：`version draft pull --version <版本> --yes`；这会覆盖当前未提交工作稿，先看命令打印的摘要。
+
+## 场景八：版本表单、依赖和上线
+
+首版先 `create-version --prepare`，更新版先 `version draft pull`，之后再用 `version attr`、`version dep` 和 `version draft description` 编辑；仅当当前类型支持时才用 `version option`。依赖签约时从对方显示的**全部启用策略**中选择；签约成功后才写入工作稿。详情见 [版本工作稿](./04-版本工作稿.md)。
+
+展示信息、策略、上架和下架不属于版本工作稿；按 [资源管理](./05-资源管理.md) 单独操作。合集、批量资源、前端库/package 模板和支付不在本期单资源 CLI 范围内。

package/dist/docs/README.md

@@ -0,0 +1,74 @@
+# Freelog CLI 使用手册
+
+这套命令只处理**单资源**：普通文件资源、主题和插件。每份资源有独立的本地身份和版本工作稿；合集、批量发行、前端库模板、支付、session 与 studio 多账号不在本期范围。
+
+## 先安装 CLI
+
+CLI 要求 Node.js 20 或更高版本。确认版本后，用 npm 全局安装：
+
+```powershell
+node --version
+npm install --global @freelog-cli/cli2
+freelog-cli --cli-version
+```
+
+若最后一条提示找不到 `freelog-cli`，先重新打开终端；仍无效时，检查 npm 的全局可执行目录是否已经加入 `PATH`。不要以仓库内的 `node packages/...` 命令替代正常使用方式，那只用于本项目开发。
+
+安装完成后运行：
+
+```powershell
+freelog-cli --help
+```
+
+顶层帮助会打印这份本机手册的绝对路径。CLI 不会联网下载文档；发布包内自带完整手册。
+
+## 使用前先知道
+
+开始操作前请先明确两件事：
+
+1. 当前联调使用 `--env dev` 或 `--env test`；省略环境会按 `prod` 处理，而 prod 目前被 CLI 拦截。
+2. 所有命令都以 `--cwd <工程目录>`（或当前目录）定位工程和账号选择器；一个工程只能管理一个资源。
+
+文档仅供阅读，不会在执行命令时修改工程状态。
+
+## 从哪一篇开始
+
+| 你的目标 | 阅读 |
+|---|---|
+| 第一次登录并发行一个普通文件 | [快速开始](./01-快速上手.md) |
+| 先按自己所处的情形找到完整操作路径 | [按场景操作](./09-按场景操作.md) |
+| 创建、发新版本、接入已有资源 | [日常操作](./02-日常路径.md) |
+| 创建主题或插件并发布构建产物 | [主题与插件](./03-主题与插件.md) |
+| 继续、覆盖或丢弃未提交的版本内容 | [版本工作稿](./04-版本工作稿.md) |
+| 修改展示信息、策略和上下架 | [资源管理](./05-资源管理.md) |
+| 命令失败后的处理方式 | [常见问题](./06-常见情况与报错.md) |
+| 环境、登录和本地文件 | [环境与账号](./07-环境与凭据.md) · [本地文件](./08-本地文件参考.md) |
+
+## 三条常用路径
+
+```text
+普通文件：login → init . → create → create-version --prepare → create-version --yes
+主题/插件：login → init theme|widget . --template <id> → create → 构建产物 → create-version --yes
+已有资源：login → bind →（无线上版本则 create-version；有线上版本则 draft pull → update-version）
+```
+
+`create` 只创建线上资源壳，`create-version` 才提交首个 `1.0.0`，`update-version` 才提交后续版本。`version show --local` 看的是未提交工作稿；不带 `--local` 的 `version show` 看的是线上已发版本。
+
+## 通用参数
+
+| 参数 | 含义 |
+|---|---|
+| `--env dev|test` | 选择联调环境。推荐每次显式传入。 |
+| `--cwd <dir>` | 工程目录；决定 `.freelog/` 与工作区账号选择器的位置。 |
+| `--artifact <path>` | 唯一的本地产物路径：`create` / `bind` 可记录默认路径；发版时表示本次上传路径；`version set` 只更新默认路径。 |
+| `--yes` | 不进行交互确认；不会放宽校验，也不会覆盖已有文件。 |
+| `--json` | 将 CLI 错误输出为 `{ "code", "message" }`。 |
+
+新脚本只使用 `--type`，不要使用 `--resource-type`；后者仅为迁移期兼容别名，CLI 会给出弃用警告。`--scaffold`、`artifactMode`、`publish` 和 `release` 不存在于当前命令面。
+
+## 先记住四条规则
+
+1. `init` 只创建本地身份，`create` 只创建线上资源壳，`bind` 只接入已有线上资源；三者都不会上传或发布版本。
+2. 无线上版本时只能用 `create-version` 发布固定的 `1.0.0`；已有线上版本时只能用 `update-version --version ...` 或 `--bump ...`。
+3. 每次真实发版都会从当前文件或构建目录重新上传、分析；工作稿里的旧 SHA1 不能替代已丢失的产物。
+4. 主题/插件传构建目录，CLI 临时压缩目录内容；普通资源传单个文件。两类资源都不需要、也不能由用户先手工打 zip。

package/package.json

@@ -1,83 +1,45 @@
 {
   "name": "@freelog-cli/cli2",
-  "version": "0.5.0",
-  "description": "Freelog CLI — scaffold, publish, and manage Freelog resources",
+  "version": "0.5.1",
+  "description": "Freelog CLI",
   "type": "module",
   "license": "MIT",
   "bin": {
     "freelog-cli": "./dist/bin/index.js"
   },
   "files": [
-    "dist",
-    "compat"
+    "dist"
   ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "dev": "tsdown --watch",
-    "build": "tsdown && node ./scripts/postbuild.mjs",
-    "test": "vitest run",
+    "dev": "tsup --watch",
+    "build": "tsup && node scripts/copy-usage-docs.mjs",
+    "test": "vitest run --maxWorkers=1 --minWorkers=1",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "check:compat": "node ./scripts/check-compat.mjs",
-    "pack:dry-run": "npm pack --dry-run",
-    "pub": "npm publish --registry=https://registry.npmjs.org/",
-    "verify": "pnpm test && pnpm typecheck && pnpm i18n:audit && pnpm check:compat && pnpm build && pnpm pack:dry-run",
-    "verify:scenarios": "pnpm build && node ./scripts/verify-scenarios.mjs --env dev",
-    "verify:payload": "pnpm build && node ./scripts/verify-payload-parity.mjs --env dev",
-    "verify:meta": "pnpm build && node ./scripts/verify-meta-api.mjs --env dev",
-    "verify:console": "pnpm build && node ./scripts/verify-console-parity.mjs --env dev",
-    "verify:cover": "pnpm build && node ./scripts/verify-cover-parity.mjs --env dev",
-    "verify:collection": "pnpm build && node ./scripts/verify-collection-parity.mjs --env dev",
-    "verify:batch": "pnpm build && node ./scripts/verify-batch-parity.mjs --env dev",
-    "verify:properties-sync": "pnpm build && node ./scripts/verify-properties-sync.mjs --env dev",
-    "verify:single-create": "pnpm build && node ./scripts/verify-single-create.mjs --env dev",
-    "verify:create-batch": "pnpm build && node ./scripts/verify-create-batch.mjs --env dev",
-    "verify:collection-attrs": "pnpm build && node ./scripts/verify-collection-attrs.mjs --env dev",
-    "verify:console-forms": "node ./scripts/verify-console-form-contract.mjs",
-    "verify:l3g-automated": "pnpm build && node ./scripts/verify-l3g-automated.mjs",
-    "verify:l3h-automated": "pnpm build && node ./scripts/verify-l3h-automated.mjs",
-    "verify:rss": "pnpm build && node ./scripts/verify-rss-parity.mjs",
-    "verify:negative-gates": "pnpm build && node ./scripts/verify-negative-gates.mjs --env dev",
-    "verify:batch-boundary": "pnpm build && node ./scripts/verify-batch-boundary.mjs --env dev",
-    "verify:json-envelope": "pnpm build && node ./scripts/verify-json-envelope.mjs --env dev",
-    "verify:chaos": "pnpm build && node ./scripts/verify-chaos.mjs --env dev",
-    "verify:offline": "pnpm build && node ./scripts/verify-scenarios-offline.mjs",
-    "verify:session-smoke": "pnpm build && node ./scripts/verify-session-smoke.mjs --env dev",
-    "verify:template-registry": "node ./scripts/verify-template-registry.mjs",
-    "verify:p6-parity": "pnpm build && node ./scripts/verify-p6-parity.mjs --env dev",
-    "provision:frozen-fixture": "pnpm build && node ./scripts/provision-frozen-fixture.mjs --env dev",
-    "verify:parity": "pnpm build && node ./scripts/verify-console-parity.mjs --env dev && node ./scripts/verify-collection-parity.mjs --env dev && node ./scripts/verify-collection-attrs.mjs --env dev && node ./scripts/verify-properties-sync.mjs --env dev && node ./scripts/verify-single-create.mjs --env dev && node ./scripts/verify-create-batch.mjs --env dev && node ./scripts/verify-cover-parity.mjs --env dev && node ./scripts/verify-batch-parity.mjs --env dev && node ./scripts/verify-payload-parity.mjs --env dev && node ./scripts/verify-meta-api.mjs --env dev",
-    "i18n:audit": "node ./scripts/i18n-audit.mjs",
-    "prepublishOnly": "pnpm --filter @freelog-cli/tools-lib2 build && pnpm verify && pnpm verify:template-registry"
+    "verify": "pnpm test && pnpm typecheck && pnpm build && pnpm verify:package",
+    "verify:package": "node scripts/verify-package.mjs",
+    "pack:dry-run": "pnpm build && npm pack --dry-run",
+    "release:check": "pnpm --filter @freelog-cli/tools-lib2 verify && pnpm verify && npm pack --dry-run",
+    "prepublishOnly": "pnpm release:check",
+    "release:publish": "npm publish"
   },
   "dependencies": {
-    "@clack/prompts": "^0.11.0",
-    "adm-zip": "^0.6.0",
-    "citty": "^0.1.6",
-    "consola": "^3.4.2",
-    "ejs": "^3.1.10",
-    "fs-extra": "^11.3.0",
-    "ofetch": "^1.4.1",
+    "@inquirer/prompts": "^7.8.0",
+    "@napi-rs/keyring": "^2.0.0",
+    "archiver": "^7.0.1",
+    "commander": "^14.0.0",
     "semver": "^7.7.2",
-    "yaml": "^2.8.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@freelog-cli/tools-lib2": "workspace:^",
-    "@types/adm-zip": "^0.5.8",
-    "@types/ejs": "^3.1.5",
-    "@types/fs-extra": "^11.0.4",
+    "@types/archiver": "^6.0.3",
     "@types/node": "^22.15.30",
     "@types/semver": "^7.7.0",
-    "tsdown": "^0.22.14",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.3"
   },

package/compat/template-compat.json

@@ -1,44 +0,0 @@
-{
-  "schemaVersion": 1,
-  "cliVersion": "0.5.0",
-  "defaultRuntime": "0.5",
-  "runtimes": {
-    "0.5": {
-      "freelogRuntimeRange": "^5.0.7",
-      "templates": {
-        "vite-vue-ts": {
-          "npmName": "@freelog-cli/template-vite-vue-ts",
-          "version": "latest"
-        },
-        "vite-vue": {
-          "npmName": "@freelog-cli/template-vite-vue",
-          "version": "latest"
-        },
-        "vite-react-ts": {
-          "npmName": "@freelog-cli/template-vite-react-ts",
-          "version": "latest"
-        },
-        "vite-react": {
-          "npmName": "@freelog-cli/template-vite-react",
-          "version": "latest"
-        }
-      }
-    }
-  },
-  "noRuntime": {
-    "templates": {
-      "package-js": {
-        "npmName": "@freelog-cli/template-package-js",
-        "version": "0.5.0"
-      },
-      "package-react": {
-        "npmName": "@freelog-cli/template-package-react",
-        "version": "0.5.0"
-      },
-      "package-vue": {
-        "npmName": "@freelog-cli/template-package-vue",
-        "version": "0.5.0"
-      }
-    }
-  }
-}

package/dist/bin/index.d.ts

@@ -1 +0,0 @@
-export {}