@hi-man/himan 0.1.0 → 0.2.2

package/.nvmrc

@@ -0,0 +1 @@
+22.22.1

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on Keep a Changelog, and this project follows semver for the npm package version.
+
+## [Unreleased]
+
+## [0.2.2] - 2026-05-07
+
+### Added
+
+- Added a PR verify workflow that runs typecheck, tests, and build before merging to `master`.
+
+## [0.2.1] - 2026-05-07
+
+### Added
+
+- Added this changelog to make release notes and user-visible changes explicit.
+- Added npm package metadata for Node.js engine compatibility and package discovery.
+- Added public contributing, security, and code of conduct documents.
+
+### Changed
+
+- Clean `dist` before every build so npm packages cannot include stale generated files.
+- Aligned MVP, v1.0, and roadmap docs with current resource type and multi-agent behavior.
+- Added publish preflight checks for resource metadata and entry files, with stable publish error codes.
+- Restored lock-file installs from the source recorded in `himan.lock` instead of the current default source.
+- Updated repository links to `https://github.com/himan-group/himan`.
+- Updated Git source refresh to fast-forward clean cached working trees after fetch while preserving dirty local edits.
+- Updated list cache invalidation to track `himan.yaml` metadata content instead of parent directory mtimes.
+- Moved developer, testing, release, and CI maintenance documentation from README to `docs/development.md`.
+- Improved README installation guidance for npm, one-off execution, local development, and CLI entry points.
+- Included README-linked user documentation in the npm package and changed GitHub workflow links to repository URLs.
+
+## [0.2.0] - 2026-05-06
+
+### Added
+
+- Added command groups for `source`, `resource`, `project`, and `agent`, while keeping backward-compatible top-level lifecycle commands.
+- Added dedicated binaries: `himan-source`, `himan-resource`, and `himan-project`.
+- Added default agent configuration commands for project and global scopes.
+- Added multi-agent installation targets for `cursor`, `claude-code`, `codex`, and `openclaw`.
+- Added `command` and `skill` lifecycle support across create, list, history, install, dev, publish, and uninstall flows.
+- Added project `himan.lock` support for reproducible installs.
+- Added copy install mode in addition to symlink mode.
+- Added local index cache support for resource listing.
+- Added repository guidance files for Codex workflows.
+
+### Changed
+
+- Split CLI registration into source, resource, project, agent, and shared command modules.
+- Expanded README and planning docs to reflect multi-type resources, lock behavior, multi-agent targets, and source management.
+
+## [0.1.0] - 2026-04-08
+
+### Added
+
+- Initial Git-backed CLI for managing prompt and agent assets.
+- Added source initialization, resource listing, history, install, dev, publish, create, and uninstall workflows.
+- Added resource metadata scanning from `himan.yaml`.
+- Added semver tag-based resource versioning.
+- Added local store, repo cache, config, and index state foundations.
+- Added npm publishing and version tag GitHub Actions workflows.
+- Added Vitest coverage for adapters, state, utilities, and CLI integration paths.

package/README.md

@@ -2,26 +2,48 @@
 
 himan（含义为"Hey, man"），AI Coding 时代的 Prompt / Agent 资产管理系统（CLI + Git source）
 
+## 环境要求
+
+- Node.js 22.x；本仓库开发环境由 [.nvmrc](./.nvmrc) 固定为 `22.22.1`。
+- Git；Git source 的初始化、版本查询、安装和发布都依赖本机 Git。
+
 ## 安装与运行
 
+### 使用 npm 包
+
+全局安装后可直接使用 `himan`：
+
 ```bash
-pnpm install
-pnpm run build
+npm install -g @hi-man/himan
+himan --help
 ```
 
-之后任选其一执行命令：
+也可以一次性运行主入口：
+
+```bash
+npx @hi-man/himan --help
+pnpm dlx @hi-man/himan --help
+```
+
+### 命令入口
+
+包内提供四个 CLI 入口：
 
-- 已全局安装本包：`himan <子命令>`
-- 本地开发：`pnpm run dev -- <子命令>`
-- 或直接：`node dist/index.js <子命令>`
+- `himan <子命令>`（主入口）
+- `himan-source <子命令>`（source 相关）
+- `himan-resource <子命令>`（resource/project 相关）
+- `himan-project <子命令>`（project 相关）
 
-下文用 `himan` 代指上述入口。
+下文默认使用 `himan` 主入口；三个专用入口在对应章节单独列出。
 
 ## 一分钟上手
 
+以下示例假设你已有一个可访问的 himan Git source 仓库，仓库中存在 `my-rule` 的资源版本 tag，并且你拥有发布所需的 Git push 权限。
+
 ```bash
 himan init https://github.com/your-org/your-himan-registry.git
 himan list rule
+himan agent use codex
 himan install rule my-rule
 himan dev rule my-rule
 # 编辑项目下 .himan/dev/rule/my-rule/
@@ -29,15 +51,18 @@ himan publish rule my-rule --patch
 ```
 
 - **rule / command / skill**：都支持 `create`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`。
-- 安装后项目链接位置：
-  - `rule` -> `.cursor/rules/<name>`
-  - `command` -> `.cursor/commands/<name>`
-  - `skill` -> `.cursor/skills/<name>`
+- 安装后项目目标位置（按 `agents`，默认 `cursor`）：
+  - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
+  - `claude-code` -> `.claude/{rules|commands|skills}/<name>`
+  - `codex` -> `.agents/{rules|commands|skills}/<name>`
+  - `openclaw` -> `.openclaw/{rules|commands|skills}/<name>`
 - 开发态目录：
   - `rule` -> `.himan/dev/rule/<name>`
   - `command` -> `.himan/dev/command/<name>`
   - `skill` -> `.himan/dev/skill/<name>`
-- lock 文件：`install <type> <name[@version]>` 会写入 `himan.lock`；`himan install`（无参数）会按 lock 批量恢复安装。
+- lock 文件：`install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。
+- 安装模式：默认 `--mode link` 使用软链；也可用 `--mode copy` 将资源复制到目标 agent 目录，lock 会记录并复现该模式。
+- 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
 
 版本以 Git tag 为准，格式：`rule/my-rule@1.0.0`。更多设计见 [docs/mvp](./docs/mvp/README.md)。
 
@@ -51,33 +76,62 @@ himan publish rule my-rule --patch
 | `source add <name> <git_url>` | 添加命名 Git 源                                    |
 | `source use <name>`           | 切换默认源                                          |
 | `source list [--json]`        | 查看已配置源（标记当前 default）                     |
+| `source init <git_url>`       | 与 `init` 等价，便于统一走 `himan source ...` 入口     |
+
+等价独立命令：
+
+- `himan-source init <git_url>`
+- `himan-source add <name> <git_url>`
+- `himan-source use <name>`
+- `himan-source list [--json]`
 
 ### 2) resource（资源）
 
 | 命令                             | 说明                                                                                |
 | -------------------------------- | ----------------------------------------------------------------------------------- |
-| `list [type] [--json]`           | 列出当前 default source 的资源；`type` 为 `rule` / `command` / `skill`，默认 `rule` |
+| `list [type] [--agent a,b] [--json]` | 列出当前 default source 的资源；可按 agent 过滤；`type` 默认 `rule` |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
-| `create <type> <name>`           | 脚手架；常用选项：`--description`、`--target a,b`、`--dry-run`、`--force`、`--json` |
+| `create <type> <name>`           | 脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
 
 ### 3) project（当前项目）
 
 | 命令                              | 说明                                                      |
 | --------------------------------- | --------------------------------------------------------- |
-| `install [type] [name[@version]]` | 有参数时安装指定资源；**无参数**时按 `himan.lock` 批量安装 |
-| `dev <type> <name>`               | 切换到开发态并把项目链接指向 `.himan/dev/...`              |
-| `uninstall <type> <name>`         | 从项目移除安装链接，并同步删除 `himan.lock` 条目           |
+| `install [type] [name[@version]] [--agent a,b] [--mode link\|copy]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；可覆盖安装目标 agent 或安装模式 |
+| `dev <type> <name>`               | 切换到开发态，并按安装模式将项目目标指向或复制自 `.himan/dev/...` |
+| `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
 | `publish <type> <name>`           | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个） |
 
-`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。需要可推送的 Git 权限。若该资源已在 lock 中，发布后会同步更新 lock 版本。
+### 4) agent（默认 Agent）
+
+| 命令 | 说明 |
+|------|------|
+| `agent list [--json]` | 查看支持的 agent |
+| `agent use <agent[,agent]> [--project\|--global] [--json]` | 设置当前项目或全局默认 agent；默认 `--project` |
+| `agent current [--json]` | 查看当前项目、全局和最终生效的默认 agent |
+| `agent clear [--project\|--global] [--json]` | 清除当前项目或全局默认 agent；默认 `--project` |
+
+也可使用分组命令（与上面等价）：
+
+- `himan resource list|history|create ...`
+- `himan-resource list|history|create ...`（兼容保留：也可执行 install/dev/uninstall/publish）
+- `himan project install|dev|uninstall|publish ...`
+- `himan-project install|dev|uninstall|publish ...`
+- `himan agent list|use|current|clear ...`
+
+说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
+若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。
+
+`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。发布前会校验 `himan.yaml` 与入口文件；需要可推送的 Git 权限。若该资源已在 lock 中，发布后会同步更新 lock 版本。
 
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 
-多源说明：当前是「**多来源可配置，单来源生效**」模型。业务命令（`list/install/history/dev/publish`）只作用于当前 default source；切换后再执行命令。
+多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。
 
 ## 当前范围
 
 - 源：**仅 Git**（`init`）。Registry 适配器已预留，尚未实现。
+- 包定位：当前仅承诺 CLI 使用，不提供稳定的 Node.js 程序化 API。
 
 ## FAQ
 
@@ -95,51 +149,6 @@ himan source list
 **Q: `list` 和 `source list` 有什么区别？**  
 A: `source list` 查看「我配置了哪些来源」；`list` 查看「当前 default source 里有哪些资源」。
 
-## 开发与测试
-
-```bash
-pnpm test
-```
-
-## 发布 npm 包（维护者）
-
-### 流程概览
-
-1. **在分支上完成开发与合并前检查**  
-   本地可执行 `pnpm run verify`（类型检查、单测、`build`），确认通过后再提 PR。
-
-2. **更新 `package.json` 中的 `version`**  
-   npm 不允许重复发布同一版本号。合并进 `master` 前，在 PR 里把版本改成 registry 上尚未存在的号。  
-   - 手动改 `version` 字段，或  
-   - 在分支上执行其一（只改版本号，**不会**发包）：`pnpm run version:patch` / `version:minor` / `version:major`（使用 `npm version … --no-git-tag-version`，需自行 `git add` / `commit` 版本变更）。  
-   Git 标签约定：与 `version` 对应、带前缀 **`v`**（如 `1.2.0` → 标签 `v1.2.0`）。
-
-3. **合并到 `master`**  
-   推送合并后的 `master` 会触发 GitHub Actions 工作流 [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml)：安装依赖后执行 **`pnpm run release`**（即再次 `verify` + `npm publish`）。  
-   需在仓库 **Settings → Secrets → Actions** 中配置 **`NPM_TOKEN`**（npm 侧「Access Tokens」，建议 Automation / 具备发包权限的 granular token）。
-
-4. **手动从 CI 再发一次（可选）**  
-   在 GitHub **Actions → Publish to npm → Run workflow** 可手动运行同一流程（例如在修复密钥后重试）。
-
-### 本地命令（与 CI 中的 `pnpm run release` 一致）
-
-| 命令 | 作用 |
-|------|------|
-| `pnpm run verify` | 仅检查（类型 / 测试 / 构建） |
-| `pnpm run release:dry` | 检查 + `npm publish --dry-run`（演练，不上传） |
-| `pnpm run release:test` | 检查 + 将版本打成 `*-test.*` 预发布号并发布到 **`@test` 标签** |
-| `pnpm run release` | 检查 + 发布 **latest**（维护者本地发包时用；**请写 `pnpm run release`**，勿用裸命令 `pnpm publish`，二者不是同一套流程） |
-| `pnpm run version:patch` / `version:minor` / `version:major` | 仅提升 `package.json` 版本号，不发包 |
-
-发测试标签后，安装示例：`npm i @hi-man/himan@test`。
-
-### CI：合并前校验与合并后打 Git 标签
-
-| 工作流 | 文件 | 说明 |
-|--------|------|------|
-| **PR version tag check** | [`.github/workflows/pr-master-version-tag.yml`](.github/workflows/pr-master-version-tag.yml) | 目标分支为 `master` 的 PR：读取 **PR 头提交**上的 `package.json` 的 `version`，若远端已存在同名标签 **`v{version}`**，则 **检查失败**（用于在合并前拦截重复版本）。 |
-| **Tag version on master** | [`.github/workflows/push-master-version-tag.yml`](.github/workflows/push-master-version-tag.yml) | 向 `master` **推送**后（含合并 PR）：在 **当前推送提交**上创建并推送注释标签 **`v{version}`**。若标签已存在、创建或 `git push` 失败，仅输出 **告警**（`::warning::`），**工作流仍成功**，不撤销已发生的 merge；请按日志提示在本机补打标签并 `git push origin v{x.y.z}`。 |
-
-**启用「合并前拦截」**：在 GitHub **Settings → Branches** 中为 `master` 配置分支保护，勾选 **Require status checks to pass before merging**，并勾选必选检查 **`PR version tag check / version-tag-available`**（名称以仓库里 Actions 界面为准）。
+## 开发与维护
 
-说明：来自 fork 的 PR 同样会跑上述 PR 检查；打标签工作流需要 **Actions 对仓库有写权限**（工作流内已设 `contents: write`）。若组织策略禁止 `GITHUB_TOKEN` 写标签，推送标签会失败，需按告警手动推送。
+源码开发、测试和 npm 发包流程见 [docs/development.md](./docs/development.md)。

package/dist/adapters/git/repo-manager.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { simpleGit } from "simple-git";
+import { HimanError, errorCodes } from "../../utils/errors.js";
 export class RepoManager {
     async cloneOrFetch(repo, targetDir) {
         const gitDir = path.join(targetDir, ".git");
@@ -12,6 +13,7 @@ export class RepoManager {
         }
         const git = simpleGit(targetDir);
         await git.fetch(["--tags", "--prune"]);
+        await this.fastForwardCleanWorkingTree(git);
     }
     async listTags(repoDir, pattern) {
         const git = simpleGit(repoDir);
@@ -44,14 +46,21 @@ export class RepoManager {
             await fs.writeFile(destination, content, "utf8");
         }
     }
-    async commitTagAndPush(repoDir, message, tag, branch) {
+    async commitTagAndPush(repoDir, message, tag, branch, paths = ["."]) {
         const git = simpleGit(repoDir);
-        await git.add(["."]);
-        const status = await git.status();
-        if (status.isClean()) {
-            throw new Error("No changes to publish.");
+        const pathspecs = paths.length > 0 ? paths : ["."];
+        await git.add(pathspecs);
+        const stagedFiles = await git.raw([
+            "diff",
+            "--cached",
+            "--name-only",
+            "--",
+            ...pathspecs,
+        ]);
+        if (!stagedFiles.trim()) {
+            throw new HimanError(errorCodes.PUBLISH_NO_CHANGES, "No changes to publish.");
         }
-        await git.commit(message);
+        await git.commit(message, pathspecs);
         await git.addTag(tag);
         const currentBranch = (await git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
         const targetBranch = branch ?? currentBranch;
@@ -67,4 +76,30 @@ export class RepoManager {
             return false;
         }
     }
+    async fastForwardCleanWorkingTree(git) {
+        const status = await git.status();
+        if (!status.isClean()) {
+            return;
+        }
+        const upstream = await this.getCurrentUpstream(git);
+        if (!upstream) {
+            return;
+        }
+        await git.raw(["merge", "--ff-only", upstream]);
+    }
+    async getCurrentUpstream(git) {
+        try {
+            const upstream = await git.raw([
+                "rev-parse",
+                "--abbrev-ref",
+                "--symbolic-full-name",
+                "@{u}",
+            ]);
+            const trimmed = upstream.trim();
+            return trimmed.length > 0 ? trimmed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
 }

package/dist/adapters/resource/resource-scanner.js

@@ -30,7 +30,9 @@ export class ResourceScanner {
                 type,
                 entry: parsed.entry,
                 description: parsed.description,
-                targets: parsed.targets,
+                agents: Array.isArray(parsed.agents)
+                    ? (parsed.agents ?? [])
+                    : (parsed.targets ?? []),
             });
         }
         return result;

package/dist/adapters/source/git-source-adapter.js

@@ -3,6 +3,7 @@ import { ResourceScanner } from "../resource/resource-scanner.js";
 import semver from "semver";
 import { HimanError, errorCodes } from "../../utils/errors.js";
 import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import YAML from "yaml";
 import { IndexCacheStore } from "../../state/index-cache-store.js";
@@ -23,13 +24,13 @@ export class GitSourceAdapter {
         const repoId = this.sourceConfig?.repoId ?? "default";
         const typeDir = this.getTypeDir(type);
         const baseDir = path.join(repoDir, typeDir);
-        const baseDirMtimeMs = await this.getMtimeMs(baseDir);
+        const metadataHash = await this.getResourceMetadataHash(baseDir);
         const cached = await this.indexStore.get(repoId, type);
-        if (cached && cached.baseDirMtimeMs === baseDirMtimeMs) {
+        if (cached && cached.metadataHash === metadataHash) {
             return cached.resources;
         }
         const scanned = await this.scanner.scanByType(repoDir, type);
-        await this.indexStore.upsert(repoId, type, baseDirMtimeMs, scanned);
+        await this.indexStore.upsert(repoId, type, metadataHash, scanned);
         return scanned;
     }
     async history(type, name) {
@@ -47,6 +48,7 @@ export class GitSourceAdapter {
     async publish(type, name, version, sourceDir) {
         const repoDir = this.getRepoDir();
         const targetDir = path.join(repoDir, `${type}s`, name);
+        const metadata = await this.validatePublishResource(type, name, sourceDir);
         const sameDir = await this.isSameDirectory(sourceDir, targetDir);
         if (!sameDir) {
             await fs.rm(targetDir, { recursive: true, force: true });
@@ -54,21 +56,17 @@ export class GitSourceAdapter {
             await fs.cp(sourceDir, targetDir, { recursive: true });
         }
         const yamlPath = path.join(targetDir, "himan.yaml");
-        if (await this.exists(yamlPath)) {
-            const raw = await fs.readFile(yamlPath, "utf8");
-            const parsed = YAML.parse(raw);
-            parsed.version = version;
-            await fs.writeFile(yamlPath, YAML.stringify(parsed), "utf8");
-        }
+        metadata.version = version;
+        await fs.writeFile(yamlPath, YAML.stringify(metadata), "utf8");
         const tag = `${type}/${name}@${version}`;
-        await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag);
+        await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag, undefined, [path.relative(repoDir, targetDir)]);
         return { version, tag };
     }
     async create(type, name, options) {
         const repoDir = this.getRepoDir();
         const resourceDir = path.join(repoDir, this.getTypeDir(type), name);
         const entry = options.entry ?? this.getDefaultEntry(type);
-        const targets = options.targets?.length ? options.targets : ["cursor"];
+        const agents = options.agents?.length ? options.agents : ["cursor"];
         if ((await this.exists(resourceDir)) && !options.force) {
             throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`);
         }
@@ -82,7 +80,7 @@ export class GitSourceAdapter {
                 version: "0.1.0",
                 entry,
                 description: options.description ?? `${type} resource ${name}`,
-                targets,
+                agents,
             }), "utf8");
             await fs.writeFile(path.join(resourceDir, entry), this.getDefaultContent(type, name), "utf8");
         }
@@ -118,14 +116,66 @@ export class GitSourceAdapter {
             return false;
         }
     }
-    async getMtimeMs(targetPath) {
+    async validatePublishResource(type, name, resourceDir) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (!(await this.exists(yamlPath))) {
+            throw this.invalidResourceMetadata(type, name, "Missing himan.yaml for publish.", { yamlPath });
+        }
+        const raw = await fs.readFile(yamlPath, "utf8");
+        let parsed;
         try {
-            const stat = await fs.stat(targetPath);
-            return stat.mtimeMs;
+            parsed = YAML.parse(raw);
         }
-        catch {
-            return 0;
+        catch (error) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml is not valid YAML.", { yamlPath, reason: error instanceof Error ? error.message : String(error) });
+        }
+        if (!this.isRecord(parsed)) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml must be an object.", { yamlPath });
+        }
+        if (parsed.name !== name) {
+            throw this.invalidResourceMetadata(type, name, `himan.yaml name must be "${name}".`, { yamlPath, actual: parsed.name });
+        }
+        if (parsed.type !== type) {
+            throw this.invalidResourceMetadata(type, name, `himan.yaml type must be "${type}".`, { yamlPath, actual: parsed.type });
+        }
+        if (typeof parsed.entry !== "string" || parsed.entry.trim().length === 0) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml entry is required.", { yamlPath });
+        }
+        const entry = parsed.entry.trim();
+        const entryPath = path.resolve(resourceDir, entry);
+        const resourceRoot = path.resolve(resourceDir);
+        const relativeEntryPath = path.relative(resourceRoot, entryPath);
+        if (path.isAbsolute(entry) ||
+            relativeEntryPath === "" ||
+            relativeEntryPath.startsWith("..") ||
+            path.isAbsolute(relativeEntryPath)) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml entry must point to a file inside the resource directory.", { yamlPath, entry });
+        }
+        let entryStat;
+        try {
+            entryStat = await fs.stat(entryPath);
+        }
+        catch (error) {
+            if (!this.isNotFoundError(error)) {
+                throw error;
+            }
+            throw this.invalidResourceMetadata(type, name, `Resource entry file not found: ${entry}`, { yamlPath, entry, entryPath });
         }
+        if (!entryStat.isFile()) {
+            throw this.invalidResourceMetadata(type, name, `Resource entry is not a file: ${entry}`, { yamlPath, entry, entryPath });
+        }
+        return {
+            ...parsed,
+            name,
+            type,
+            entry,
+        };
+    }
+    invalidResourceMetadata(type, name, message, details) {
+        return new HimanError(errorCodes.INVALID_RESOURCE_METADATA, `Invalid metadata for ${type}/${name}: ${message}`, details);
+    }
+    isRecord(value) {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
     }
     getTypeDir(type) {
         if (type === "rule")
@@ -134,6 +184,42 @@ export class GitSourceAdapter {
             return "commands";
         return "skills";
     }
+    async getResourceMetadataHash(baseDir) {
+        const hash = createHash("sha256");
+        hash.update("himan-resource-index-v1");
+        if (!(await this.exists(baseDir))) {
+            hash.update("\0missing");
+            return hash.digest("hex");
+        }
+        const entries = await fs.readdir(baseDir, { withFileTypes: true });
+        const resourceDirNames = entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+        for (const resourceDirName of resourceDirNames) {
+            hash.update("\0dir:");
+            hash.update(resourceDirName);
+            const yamlPath = path.join(baseDir, resourceDirName, "himan.yaml");
+            try {
+                const raw = await fs.readFile(yamlPath);
+                hash.update("\0yaml:");
+                hash.update(raw);
+            }
+            catch (error) {
+                if (!this.isNotFoundError(error)) {
+                    throw error;
+                }
+                hash.update("\0yaml-missing");
+            }
+        }
+        return hash.digest("hex");
+    }
+    isNotFoundError(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT");
+    }
     getDefaultEntry(type) {
         return type === "skill" ? "SKILL.md" : "content.md";
     }

package/dist/bin/himan-project.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildProjectCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildProjectCli);
+}
+void main();

package/dist/bin/himan-resource.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildResourceCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildResourceCli);
+}
+void main();

package/dist/bin/himan-source.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildSourceCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildSourceCli);
+}
+void main();

package/dist/bin/himan.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildCli);
+}
+void main();

package/dist/{index.js → bin/shared.js}

@@ -1,8 +1,7 @@
-#!/usr/bin/env node
 import { CommanderError } from "commander";
-import { buildCli, writeCliError } from "./cli/index.js";
-async function main() {
-    const program = buildCli();
+import { writeCliError } from "../cli/index.js";
+export async function runCliMain(buildProgram) {
+    const program = buildProgram();
     try {
         await program.parseAsync(process.argv);
     }
@@ -14,4 +13,3 @@ async function main() {
         process.exitCode = error instanceof CommanderError ? error.exitCode : 1;
     }
 }
-void main();