@hagicode/skillsbase 0.1.0-dev.20260406025440.0.0.local → 0.1.1

package/README.md

@@ -1,78 +1,116 @@
-# skillsbase
+# @hagicode/skillsbase
 
-`skillsbase` 是一个独立 Node CLI，用于初始化和维护“别的 skills 仓库”。
-重点是：本仓库只放 CLI 代码与模板，不提交受管 `skills/` 内容。
-当前源码使用 `TypeScript + Vite 8`。
+[中文文档](./README.zh-CN.md)
 
-## Commands
+[![npm version](https://img.shields.io/npm/v/%40hagicode%2Fskillsbase?logo=npm&color=cb3837)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![npm downloads](https://img.shields.io/npm/dm/%40hagicode%2Fskillsbase?logo=npm&color=2d8cf0)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+`skillsbase` is a standalone Node.js CLI for bootstrapping and maintaining managed skills repositories.
+It ships the CLI and templates only. The generated `skills/` content belongs in the target repository, not in this package repository.
+
+## Install
+
+Requirements:
+
+- Node.js `>= 22.12.0`
+- npm `>= 10.9.2`
+
+Install globally:
 
 ```bash
-node ./bin/skillsbase.mjs init
-node ./bin/skillsbase.mjs sync
-node ./bin/skillsbase.mjs sync --check
-node ./bin/skillsbase.mjs add <skill-name>
-node ./bin/skillsbase.mjs github_action --kind all
+npm install --global @hagicode/skillsbase
 ```
 
-开发期常用：
+Then run:
 
 ```bash
-npm run build
-npm run cli -- --help
-npm test
-npm run smoke
-node ./bin/skillsbase.mjs <command> --repo /path/to/target-repo
+skillsbase --help
+```
+
+## Quick Start
+
+Initialize a managed repository:
+
+```bash
+skillsbase init --repo /path/to/target-repo
+```
+
+Sync managed skills from `sources.yaml`:
+
+```bash
+skillsbase sync --repo /path/to/target-repo
+```
+
+Add one skill and sync immediately:
+
+```bash
+skillsbase add documentation-writer --repo /path/to/target-repo
+```
+
+Generate managed GitHub Actions assets:
+
+```bash
+skillsbase github_action --repo /path/to/target-repo --kind all
 ```
 
-打包产物仍为 `dist/cli.mjs`，`bin/skillsbase.mjs` 只负责发布态加载与开发态回退。
+## Commands
 
-## npm Publish
+| Command | Purpose | Example |
+| --- | --- | --- |
+| `init` | Create the managed repository baseline. | `skillsbase init --repo ./my-skills-repo` |
+| `sync` | Reconcile managed skills from `sources.yaml`. | `skillsbase sync --repo ./my-skills-repo` |
+| `sync --check` | Validate drift without writing files. | `skillsbase sync --check --repo ./my-skills-repo` |
+| `add <skill-name>` | Add a skill to a source block, then run sync. | `skillsbase add documentation-writer --repo ./my-skills-repo` |
+| `github_action` | Generate managed GitHub Actions workflow or action files. | `skillsbase github_action --repo ./my-skills-repo --kind workflow` |
 
-- workflow: `.github/workflows/npm-publish-dev.yml`
-- `push` 到 `main` 时发布 `dev` dist-tag
-- GitHub Release `published` 且非 draft / prerelease 时发布 `latest`
-- 发布前会执行：
-  - `npm test`
-  - `npm run pack:check`
-- 当前包名：`@hagicode/skillsbase`
+Global options:
 
-发布依赖 npm Trusted Publishing；仓库侧需要在 npm 绑定此 GitHub repository。
+- `--repo <path>`: target repository path, defaults to the current directory
+- `--help`, `-h`: show help
+- `--version`, `-v`: show version
 
-## Managed Repo Contract
+## Managed Repository Contract
 
-- `sources.yaml`
-  清单单一真相源，声明来源根目录、命名规则、包含列表与非交互默认值。
-- `skills/<name>/SKILL.md`
-  受管输出。内容来自当前仓库内临时 `npx skills add` 安装结果，再转换为最终形态。
-- `skills/<name>/.skill-source.json`
-  来源、转换、目标路径与安装元数据。
-- `.github/workflows/skills-sync.yml`
-  受管 workflow，执行 `npm test` 与 `skillsbase sync --check`。
-- `.github/actions/skillsbase-sync/action.yml`
-  可复用 composite action。
+`skillsbase` manages files in the target repository, including:
 
-以上文件属于 **目标 skills 仓库**，不属于本 CLI 仓库本身。
+- `sources.yaml`: the single source of truth for source roots, naming rules, include lists, and defaults
+- `skills/<name>/SKILL.md`: managed skill output converted from installed source content
+- `skills/<name>/.skill-source.json`: source, conversion, target-path, and install metadata
+- `docs/maintainer-workflow.md`: maintainer guidance generated from the bundled templates
+- `.github/workflows/skills-sync.yml`: reusable workflow for validation and sync checks
+- `.github/actions/skillsbase-sync/action.yml`: reusable composite action
 
 ## Non-Interactive Defaults
 
-- 目标仓库默认为当前工作目录。
-- `init` 默认来源根目录：
+- The target repository defaults to the current working directory.
+- `init` defaults the source roots to:
   - first-party: `$HOME/.agents/skills`
   - system: `$HOME/.codex/skills/.system`
-- `add` 默认写入第一个已声明 source block。
-- `github_action` 默认 `--kind workflow`。
-- 若上下文不足以安全写入，命令直接失败并给出诊断；不会进入交互提问。
+- `add` writes to the first declared source block unless `--source <key>` is provided.
+- `github_action` defaults to `--kind workflow`.
+- When the CLI does not have enough context to write safely, it fails with diagnostics instead of prompting interactively.
 
-## Usage Notes
+## Development
 
-- `sync` 会执行“安装到当前仓库 -> 转换 -> 卸载临时产物 -> 对账写盘”闭环。
-- `sync --check` 不修改最终仓库状态；若发现漂移则返回非零退出码。
-- `sync --allow-missing-sources` 可在来源根目录暂缺时跳过该来源。
-- `github_action` 仅覆盖带 `Managed by skillsbase CLI` 标记的文件；冲突文件需显式 `--force`。
+Common commands for working on this package:
 
-## Development
+```bash
+npm run build
+npm run cli -- --help
+npm test
+npm run smoke
+npm run pack:check
+```
+
+The published entry point is `bin/skillsbase.mjs`. In development, `npm run cli -- <args>` runs the TypeScript entry directly.
+
+## Publishing Notes
+
+The GitHub Actions workflow supports two npm authentication modes:
+
+- Preferred: npm trusted publishing via GitHub Actions OIDC
+- Fallback: `NPM_TOKEN` repository secret mapped to `NODE_AUTH_TOKEN`
 
-- `npm test`
-  跑 CLI 单测。
-- `npm run smoke`
-  在临时目录创建一个示例 managed repo，验证 `init -> sync -> sync --check -> github_action`。
+Before relying on trusted publishing, make sure the npm package settings for `@hagicode/skillsbase` trust the `HagiCode-org/skillsbase` repository.
+The npm docs currently require Node.js `>= 22.14.0` and npm `>= 11.5.1` for trusted publishing.

package/README.zh-CN.md

@@ -0,0 +1,116 @@
+# @hagicode/skillsbase
+
+[English README](./README.md)
+
+[![npm version](https://img.shields.io/npm/v/%40hagicode%2Fskillsbase?logo=npm&color=cb3837)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![npm downloads](https://img.shields.io/npm/dm/%40hagicode%2Fskillsbase?logo=npm&color=2d8cf0)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+`skillsbase` 是一个独立的 Node.js CLI，用于初始化并维护受管 skills 仓库。
+本仓库只提供 CLI 与模板，不提交目标仓库中的 `skills/` 产物。
+
+## 安装
+
+要求：
+
+- Node.js `>= 22.12.0`
+- npm `>= 10.9.2`
+
+全局安装：
+
+```bash
+npm install --global @hagicode/skillsbase
+```
+
+安装后可直接执行：
+
+```bash
+skillsbase --help
+```
+
+## 快速开始
+
+初始化受管仓库：
+
+```bash
+skillsbase init --repo /path/to/target-repo
+```
+
+按 `sources.yaml` 同步技能：
+
+```bash
+skillsbase sync --repo /path/to/target-repo
+```
+
+添加单个技能并立即同步：
+
+```bash
+skillsbase add documentation-writer --repo /path/to/target-repo
+```
+
+生成受管 GitHub Actions 资产：
+
+```bash
+skillsbase github_action --repo /path/to/target-repo --kind all
+```
+
+## 命令
+
+| 命令 | 用途 | 示例 |
+| --- | --- | --- |
+| `init` | 创建受管仓库基础结构 | `skillsbase init --repo ./my-skills-repo` |
+| `sync` | 按 `sources.yaml` 对账并同步技能 | `skillsbase sync --repo ./my-skills-repo` |
+| `sync --check` | 只校验漂移，不写文件 | `skillsbase sync --check --repo ./my-skills-repo` |
+| `add <skill-name>` | 将技能写入 source block 后执行同步 | `skillsbase add documentation-writer --repo ./my-skills-repo` |
+| `github_action` | 生成受管 GitHub Actions 工作流或 action 文件 | `skillsbase github_action --repo ./my-skills-repo --kind workflow` |
+
+全局选项：
+
+- `--repo <path>`：目标仓库路径，默认当前目录
+- `--help`、`-h`：显示帮助
+- `--version`、`-v`：显示版本
+
+## 受管仓库约定
+
+`skillsbase` 会在目标仓库中管理以下文件：
+
+- `sources.yaml`：来源根目录、命名规则、包含列表与默认值的单一真相源
+- `skills/<name>/SKILL.md`：由安装源内容转换得到的受管技能输出
+- `skills/<name>/.skill-source.json`：来源、转换、目标路径与安装元数据
+- `docs/maintainer-workflow.md`：由模板生成的维护说明
+- `.github/workflows/skills-sync.yml`：用于校验与同步检查的工作流
+- `.github/actions/skillsbase-sync/action.yml`：可复用 composite action
+
+## 非交互默认行为
+
+- 目标仓库默认是当前工作目录。
+- `init` 默认来源根目录为：
+  - first-party：`$HOME/.agents/skills`
+  - system：`$HOME/.codex/skills/.system`
+- `add` 默认写入第一个已声明的 source block；如需指定，传 `--source <key>`。
+- `github_action` 默认使用 `--kind workflow`。
+- 若上下文不足以安全写入，CLI 会直接失败并输出诊断，不会进入交互提问。
+
+## 开发
+
+常用命令：
+
+```bash
+npm run build
+npm run cli -- --help
+npm test
+npm run smoke
+npm run pack:check
+```
+
+发布入口为 `bin/skillsbase.mjs`。开发期可用 `npm run cli -- <args>` 直接运行 TypeScript 入口。
+
+## 发布说明
+
+GitHub Actions 发布流支持两种 npm 认证模式：
+
+- 推荐：GitHub Actions OIDC 的 npm trusted publishing
+- 兜底：仓库 `NPM_TOKEN` secret，经 `NODE_AUTH_TOKEN` 注入
+
+若使用 trusted publishing，需先在 npm 的 `@hagicode/skillsbase` 包设置中，将 `HagiCode-org/skillsbase` 配置为 trusted publisher。
+npm 官方当前要求 Node.js `>= 22.14.0` 且 npm `>= 11.5.1`。

package/dist/cli.mjs

@@ -258,7 +258,7 @@ async function loadManifest(repoPath) {
 		const sourceStartMatch = /^  - key:\s*(.+)$/.exec(line);
 		if (sourceStartMatch) {
 			currentSource = {
-				key: parseScalar(sourceStartMatch[1]),
+				key: String(parseScalar(sourceStartMatch[1])),
 				include: []
 			};
 			manifest.sources.push(currentSource);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/skillsbase",
-  "version": "0.1.0-dev.20260406025440.0.0.local",
+  "version": "0.1.1",
   "description": "Managed skills repository CLI",
   "homepage": "https://github.com/HagiCode-org/skillsbase#readme",
   "bugs": {
@@ -19,17 +19,20 @@
     "bin",
     "dist",
     "templates",
-    "README.md"
+    "README.md",
+    "README.zh-CN.md"
   ],
   "scripts": {
     "build": "vite build",
     "clean": "rm -rf dist",
     "cli": "node --import tsx ./src/cli-entry.ts",
     "pack:check": "node ./scripts/verify-package.mjs",
-    "publish:prepare-dev-version": "node ./scripts/prepare-dev-version.mjs",
+    "publish:resolve-dev-version": "node ./scripts/resolve-dev-version.mjs",
+    "publish:verify-readiness": "node ./scripts/verify-publish-readiness.mjs",
     "publish:verify-release": "node ./scripts/verify-release-version.mjs",
     "test": "node --import tsx --test ./tests/*.test.ts",
-    "smoke": "node --import tsx ./scripts/smoke.mjs"
+    "smoke": "node --import tsx ./scripts/smoke.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "engines": {
     "node": ">=22.12.0",