@hagicode/skillsbase 0.1.0-dev.1.1.426f4b0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HagiCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @hagicode/skillsbase
+
+[中文文档](./README.zh-CN.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)
+[![license](https://img.shields.io/badge/license-MIT-ffd43b)](./LICENSE)
+[![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
+npm install --global @hagicode/skillsbase
+```
+
+Then run:
+
+```bash
+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
+```
+
+Remove one skill and sync immediately:
+
+```bash
+skillsbase remove documentation-writer --repo /path/to/target-repo
+```
+
+Generate managed GitHub Actions assets:
+
+```bash
+skillsbase github_action --repo /path/to/target-repo --kind all
+```
+
+## Commands
+
+| 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` |
+| `remove <skill-name>` | Remove a skill from a source block, then run sync. | `skillsbase remove 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` |
+
+Global options:
+
+- `--repo <path>`: target repository path, defaults to the current directory
+- `--help`, `-h`: show help
+- `--version`, `-v`: show version
+
+## Managed Repository Contract
+
+`skillsbase` manages files in the target repository, including:
+
+- `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
+
+- 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` writes to the first declared source block unless `--source <key>` is provided.
+- `remove` deletes from the only matching source block automatically; if multiple source blocks include the same skill, pass `--source <key>`.
+- `add`, `remove`, and `sync` accept `--allow-missing-sources` to keep path-resolution behavior consistent in CI or repo-external execution.
+- `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.
+
+## Development
+
+Common commands for working on this package:
+
+```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`
+
+Before relying on trusted publishing, make sure the npm package settings for `@hagicode/skillsbase` trust the `HagiCode-org/skillsbase` repository.
+Use workflow filename `npm-publish.yml` in npm trusted publisher settings, not the full `.github/workflows/...` path.
+If the package has not been published before, that is still acceptable as long as the `hagicode` scope already exists and the publishing identity can create `@hagicode/skillsbase`.
+The npm docs currently require Node.js `>= 22.14.0` and npm `>= 11.5.1` for trusted publishing.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,127 @@
+# @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
+```
+
+删除单个技能并立即同步：
+
+```bash
+skillsbase remove 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` |
+| `remove <skill-name>` | 从 source block 删除技能后执行同步 | `skillsbase remove 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>`。
+- `remove` 若仅命中一个 source block，会直接删除；若同名技能存在于多个 source block，必须显式传 `--source <key>`。
+- `add`、`remove`、`sync` 均接受 `--allow-missing-sources`，以便在 CI 或仓库外 cwd 下保持一致的路径解析与失败语义。
+- `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 trusted publisher 设置里填写的 workflow filename 应为 `npm-publish.yml`，不要填完整的 `.github/workflows/...` 路径。
+如果这个包还没有首发，只要 npm 上已经存在 `hagicode` scope，且当前发布身份有权创建 `@hagicode/skillsbase`，也仍然可以正常发布。
+npm 官方当前要求 Node.js `>= 22.14.0` 且 npm `>= 11.5.1`。

package/bin/skillsbase.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { access } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const bundledEntry = path.resolve(moduleDir, "..", "dist", "cli.mjs");
+const sourceEntry = path.resolve(moduleDir, "..", "src", "cli-entry.ts");
+
+async function canAccess(targetPath) {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (await canAccess(bundledEntry)) {
+  await import(pathToFileURL(bundledEntry).href);
+} else if (await canAccess(sourceEntry)) {
+  const exitCode = await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ["--import", "tsx", sourceEntry, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`skillsbase CLI terminated with signal ${signal}.`));
+        return;
+      }
+
+      resolve(code ?? 1);
+    });
+  });
+
+  process.exitCode = exitCode;
+} else {
+  throw new Error("Unable to locate the skillsbase CLI entrypoint.");
+}