@hi-man/himan 0.3.5 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-14
+
+### Added
+
+- Added `himan doctor` to check local Node/Git availability, Himan home state, current source scanning, effective agents, project lock state, and installed targets.
+
+### Changed
+
+- Changed `create` and `dev` to use current project agent target directories for resource authoring, while `publish` now logs stages and can install the published version either into the current project or globally.
+- Changed `himan init` to support quick-start setup with optional `--agent`, `--install type/name[@version],...`, `--mode`, and `--json`.
+
+## [0.4.0] - 2026-05-13
+
+### Added
+
+- Added the `github-npm-publish` skill for reusable GitHub Actions npm release workflow guidance.
+- Added `himan resource rename` and top-level `himan rename`, currently marked not recommended, to rename source resources, update metadata/docs, preserve old tags, create a latest-version tag for the new name, and migrate the current project's install targets and lock entry by default.
+- Added `himan source clone` and `himan source sync` for cloning Git sources and syncing latest resource snapshots into another Git source.
+- Added static `analysis` metadata to newly scaffolded skill `himan.yaml` files and a `himan-skill-metadata` skill for generating matching metadata when agents create skills.
+
 ## [0.3.5] - 2026-05-12
 
 ### Changed

package/README.md

@@ -41,16 +41,22 @@ pnpm dlx @hi-man/himan --help
 以下示例假设你已有一个可访问的 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 init https://github.com/your-org/your-himan-registry.git \
+  --agent codex \
+  --install rule/my-rule
+himan doctor
+himan create skill my-skill
+# 编辑并验证项目下 .agents/skills/my-skill/
+himan publish skill my-skill --patch
 himan dev rule my-rule
-# 编辑项目下 .himan/dev/rule/my-rule/
+# 直接编辑项目下 .agents/rules/my-rule/；若只存在全局安装，dev 会先复制到当前项目
 himan publish rule my-rule --patch
 ```
 
-- **rule / command / skill**：都支持 `create`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`。
+- `init` 的 `--agent` 会写入当前项目默认 agent；`--install` 可一次选择要安装的资源，格式为 `type/name[@version]`，多个资源用逗号分隔，例如 `rule/my-rule,skill/my-skill@1.0.0`。
+- 也可以只执行 `himan init <git_url>` 跳过 agent 和资源安装，后续再用 `himan agent use ...`、`himan list ...`、`himan install ...` 单独配置。
+- `himan doctor` 会检查本机 Node/Git、Himan home、当前 source、资源扫描、默认 agent、lock 和已安装目标。
+- **rule / command / skill**：都支持 `create`、`rename`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`；其中 `rename` 暂不推荐使用。
 - 安装后项目目标位置（按 `agents`，默认 `cursor`）：
   - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
   - `claude-code` -> `.claude/{rules|commands|skills}/<name>`
@@ -61,10 +67,11 @@ himan publish rule my-rule --patch
   - `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>`
+- 创建与开发态目录默认就是当前项目的 agent 目标目录；例如 Codex：
+  - `rule` -> `.agents/rules/<name>`
+  - `command` -> `.agents/commands/<name>`
+  - `skill` -> `.agents/skills/<name>`
+  `dev` 修改项目内资源时不再创建 `.himan/dev`，只在资源仅存在于用户级全局目录时复制到当前项目对应 agent 目录。
 - lock 文件：项目安装 `install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。`--global` 安装不写当前项目的 `himan.lock`。
 - 安装模式：默认 `--mode copy` 将资源复制到目标 agent 目录；也可用 `--mode link` 使用软链，lock 会记录并复现该模式。
 - 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
@@ -96,15 +103,47 @@ your-himan-source/
 - `README.md`：source 仓库入口文档，建议记录资源目录说明、推荐安装方式、默认 agent 策略、常用资源索引和维护约定。
 - `CHANGELOG.md`：source 仓库级变更记录，建议记录新增、变更、废弃、移除的资源，以及重要版本发布说明。
 - `rules/`、`commands/`、`skills/`：按资源类型分组；每个子目录是一份 himan 资源。
-- `himan.yaml`：可选资源元数据；存在时供 himan 扫描、校验、读取入口和默认 agent。
+- `himan.yaml`：可选资源元数据；存在时供 himan 扫描、校验、读取入口和默认 agent；skill 资源可包含 `analysis` 静态分析信息。
 - `content.md` / `SKILL.md`：资源主入口；没有 `himan.yaml` 时，`rule` / `command` 默认使用 `content.md`，`skill` 默认使用 `SKILL.md`。
 
+skill 的 `himan.yaml` 推荐包含静态分析 metadata，便于 hooks、日志和后续分析系统关联 skill 内容成本与依赖：
+
+```yaml
+name: my-skill
+type: skill
+version: 0.1.0
+entry: SKILL.md
+description: Do the skill workflow.
+agents:
+  - codex
+analysis:
+  content:
+    tokenizer: approx-char-v1
+    tokenEstimator: ceil(chars/4)
+    entryTokens: 120
+    packageTokens: 180
+    contentHash: sha256:...
+    measuredAt: "2026-05-13T00:00:00.000Z"
+    measuredBy: codex
+  dependencies:
+    skills: []
+    scripts: []
+    mcpTools: []
+  generation:
+    generatedBy: codex
+    generatedAt: "2026-05-13T00:00:00.000Z"
+```
+
+`analysis` 是静态构建信息，不记录运行时 token 或执行耗时；`himan create skill` 会为新 skill scaffold 生成基础 `analysis`。
+
 可通过 `himan source init-docs` 为当前 default source 生成根目录文档模板；默认只创建缺失文件，`--force` 会覆盖已有 `README.md` / `CHANGELOG.md`，并把当前 source 中已有的 `rule`、`command`、`skill` 整理进 README 资源索引和 CHANGELOG 初始条目；资源引用会优先带上 Git tag 中的最新 semver 版本；对于尚未补齐 `himan.yaml` 的资源，会按默认入口识别，skill 还会读取 `skills/<name>/SKILL.md` front matter。`--dry-run` 可预览结果。有实际文件变更时，命令会提交并 push 到当前 Git source。
 
-`himan create` 和 `himan publish` 会自动维护 source 根目录文档：
+`himan create` 默认在当前项目 agent 目标目录创建资源脚手架，供用户直接验证；`himan publish` 会把项目目录中的资源同步回当前 default source，并自动维护 source 根目录文档：
 
 - `README.md`：只更新 `<!-- himan:resources:start -->` 和 `<!-- himan:resources:end -->` 之间的资源索引；如果没有 marker，会在文件末尾追加一个受控资源索引区。
-- `CHANGELOG.md`：向 `[Unreleased]` 下追加资源变更条目；`create` 记录 `Added`，`publish` 记录 `Changed` / published version。
+- `CHANGELOG.md`：`publish` 向 `[Unreleased]` 下追加 `Changed` / published version 条目。
+
+`himan rename` 也会维护 source 根目录文档：更新 README 资源索引，并向 CHANGELOG 的 `[Unreleased]` 追加 `Changed` 条目。
 
 仓库根目录的 `README.md` 和 `CHANGELOG.md` 不会被安装到 agent 目录；agent 只消费被安装的具体资源目录。当前安装实现会 materialize 资源目录本身，因此对 Cursor 这类要求特定单文件格式的 agent，资源目录内应避免放入会干扰识别的额外文件。
 
@@ -114,11 +153,13 @@ your-himan-source/
 
 | 命令                          | 说明                                             |
 | ----------------------------- | ------------------------------------------------ |
-| `init <git_url>`              | 初始化默认源（当前为 Git）并写入 `~/.himan/config.json` |
+| `init <git_url> [--agent a,b] [--install type/name[@version],...] [--mode link\|copy] [--json]` | 初始化默认源（当前为 Git）并写入 `~/.himan/config.json`；可同时写当前项目默认 agent 并安装选定资源 |
 | `source add <name> <git_url>` | 添加命名 Git 源                                    |
 | `source use <name>`           | 切换默认源                                          |
 | `source list [--json]`        | 查看已配置源（标记当前 default）                     |
 | `source init-docs [--force] [--dry-run] [--json]` | 为当前 default source 生成仓库级 README/CHANGELOG |
+| `source clone <from> <to> [--branch b] [--target-branch b] [--add-source name] [--use] [--dry-run] [--json]` | 将 Git source 分支和 himan 管理的资源 tag 复制到空目标 Git 仓库 |
+| `source sync <from> <to> [--target-branch b] [--add-source name] [--use] [--dry-run] [--json]` | 将最新资源快照同步到目标 Git 仓库并创建对应最新 tag |
 | `source init <git_url>`       | 与 `init` 等价，便于统一走 `himan source ...` 入口     |
 
 等价独立命令：
@@ -128,6 +169,8 @@ your-himan-source/
 - `himan-source use <name>`
 - `himan-source list [--json]`
 - `himan-source init-docs [--force] [--dry-run] [--json]`
+- `himan-source clone <from> <to> [...]`
+- `himan-source sync <from> <to> [...]`
 
 ### 2) resource（资源）
 
@@ -135,7 +178,8 @@ your-himan-source/
 | -------------------------------- | ----------------------------------------------------------------------------------- |
 | `list [type] [--agent a,b] [--brief] [--installed] [--json]` | 默认列出当前 default source 的资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源 |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
-| `create <type> <name>`           | 脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
+| `create <type> <name>`           | 在当前项目 agent 目录创建脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
+| `rename <type> <old-name> <new-name>` | 暂不推荐使用；重命名当前 default source 中的资源；常用选项：`--dry-run`、`--no-project`、`--json` |
 
 ### 3) project（当前项目）
 
@@ -143,9 +187,9 @@ your-himan-source/
 | --------------------------------- | --------------------------------------------------------- |
 | `list [type] [--agent a,b] [--json]` | 查看当前项目 `himan.lock` 中记录的已安装资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示 |
 | `install [type] [name[@version]] [--global] [--agent a,b] [--mode link\|copy]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；加 `--global` 时安装到用户级 agent 目录且不写项目 lock；可覆盖安装目标 agent 或安装模式 |
-| `dev <type> <name>`               | 切换到开发态，并按安装模式将项目目标指向或复制自 `.himan/dev/...` |
+| `dev <type> <name>`               | 切换到开发态；项目资源原地编辑，全局资源先复制到当前项目目标目录 |
 | `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
-| `publish <type> <name>`           | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个） |
+| `publish <type> <name> [--global]` | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个）；发布后默认安装到当前项目并更新 lock，`--global` 安装到用户级目录 |
 
 ### 4) agent（默认 Agent）
 
@@ -156,22 +200,31 @@ your-himan-source/
 | `agent current [--json]` | 查看当前项目、全局和最终生效的默认 agent |
 | `agent clear [--project\|--global] [--json]` | 清除当前项目或全局默认 agent；默认 `--project` |
 
+### 5) doctor（可用性检查）
+
+| 命令 | 说明 |
+|------|------|
+| `doctor [--json]` | 检查 Node/Git、Himan home、当前 source、资源扫描、默认 agent、项目 lock 和已安装目标；存在 error 时以非零状态退出 |
+
 也可使用分组命令（与上面等价）：
 
-- `himan resource list|history|create ...`
-- `himan-resource list|history|create ...`（兼容保留：也可执行 install/dev/uninstall/publish）
+- `himan resource list|history|create|rename ...`
+- `himan-resource list|history|create|rename ...`（兼容保留：也可执行 install/dev/uninstall/publish）
 - `himan project list|install|dev|uninstall|publish ...`
 - `himan-project list|install|dev|uninstall|publish ...`
 - `himan agent list|use|current|clear ...`
+- `himan doctor ...`
 
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
-若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
+若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用当前项目已有安装位置，找不到时再从用户级全局安装位置复制到当前项目。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
+
+`publish` 会展示 prepare、resolve-version、publish-source、sync-store、install、cleanup、done 等阶段日志。发布源优先使用旧版 `.himan/dev` 目录，其次使用当前项目 agent 目标目录，最后回退到 source 仓库对应资源目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。若待发布资源内容与最新已发布版本一致，则以 `E_PUBLISH_NO_CHANGES` 终止发布。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装；默认安装到当前项目并更新 `himan.lock`，传 `--global` 时安装到用户级目录且不写当前项目 lock。
 
-`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。若待发布资源内容与最新已发布版本一致，则以 `E_PUBLISH_NO_CHANGES` 终止发布。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录。
+`rename` 暂不推荐使用。该命令会移动 source 仓库里的资源目录并更新资源 metadata 名称、README 资源索引和 CHANGELOG。已有发布 tag 不会被改写；若旧资源已有历史版本，rename 会为新名字创建一个指向当前最新版本的 tag。默认会迁移当前项目中对应的安装目标、`.himan/dev` 副本和 lock 条目；传 `--no-project` 时只改 source。对于 skill，命令只自动更新 metadata / front matter 中的精确 `name` 字段，不会自动替换 `SKILL.md` 正文中的旧名称引用。
 
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 
-多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。
+多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish/rename`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。
 
 ## 当前范围
 

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

@@ -1,7 +1,9 @@
 import { promises as fs } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { simpleGit } from "simple-git";
 import { HimanError, errorCodes } from "../../utils/errors.js";
+const MANAGED_TAG_PATTERNS = ["rule/*@*", "command/*@*", "skill/*@*"];
 export class RepoManager {
     async cloneOrFetch(repo, targetDir) {
         const gitDir = path.join(targetDir, ".git");
@@ -61,6 +63,124 @@ export class RepoManager {
         await this.pushCurrentBranch(git, branch);
         return true;
     }
+    async cloneManagedSourceRefs(sourceRepoDir, targetRepo, options = {}) {
+        const sourceGit = simpleGit(sourceRepoDir);
+        await sourceGit.fetch(["--tags", "--prune"]);
+        const branch = options.branch ?? (await this.getCurrentBranch(sourceGit));
+        const sourceBranchRef = await this.resolveSourceBranchRef(sourceGit, branch);
+        const targetBranch = options.targetBranch ?? branch;
+        const targetRefs = await this.listRemoteRefs(targetRepo);
+        if (targetRefs.length > 0) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, "Target source repository is not empty.", { targetRepo, refs: targetRefs.map((item) => item.ref) });
+        }
+        const tags = await this.listManagedResourceTags(sourceRepoDir);
+        if (options.dryRun) {
+            return {
+                branch,
+                targetBranch,
+                tags,
+                dryRun: true,
+                pushed: false,
+            };
+        }
+        const refspecs = [
+            `${sourceBranchRef}:refs/heads/${targetBranch}`,
+            ...tags.map((tag) => `refs/tags/${tag}:refs/tags/${tag}`),
+        ];
+        await sourceGit.raw(["push", "--atomic", targetRepo, ...refspecs]);
+        return {
+            branch,
+            targetBranch,
+            tags,
+            dryRun: false,
+            pushed: true,
+        };
+    }
+    async syncLatestSourceSnapshot(sourceRepoDir, targetRepo, resources, options = {}) {
+        if (resources.length === 0) {
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, "No versioned resources found to sync.");
+        }
+        const targetBranch = options.targetBranch ?? "main";
+        const targetRefs = await this.listRemoteRefs(targetRepo);
+        const existingTagRefs = new Set(targetRefs
+            .filter((item) => item.ref.startsWith("refs/tags/"))
+            .map((item) => item.ref.slice("refs/tags/".length)));
+        const targetDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-source-sync-"));
+        const snapshotsDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-source-snapshots-"));
+        try {
+            const targetGit = await this.prepareTargetWorktree(targetRepo, targetDir, targetBranch, targetRefs);
+            const results = [];
+            for (const resource of resources) {
+                const sourceSnapshotDir = path.join(snapshotsDir, resource.type, resource.name);
+                await this.materializeSourceResourceSnapshot(sourceRepoDir, resource, sourceSnapshotDir);
+                if (existingTagRefs.has(resource.tag)) {
+                    await this.ensureExistingTagMatchesResource(targetDir, resource, sourceSnapshotDir);
+                    results.push({
+                        type: resource.type,
+                        name: resource.name,
+                        version: resource.version,
+                        tag: resource.tag,
+                        action: "skipped",
+                    });
+                }
+                else {
+                    results.push({
+                        type: resource.type,
+                        name: resource.name,
+                        version: resource.version,
+                        tag: resource.tag,
+                        action: "created",
+                    });
+                }
+                if (!options.dryRun) {
+                    const targetResourceDir = path.join(targetDir, this.getResourcePath(resource));
+                    await fs.rm(targetResourceDir, { recursive: true, force: true });
+                    await fs.mkdir(path.dirname(targetResourceDir), { recursive: true });
+                    await fs.cp(sourceSnapshotDir, targetResourceDir, { recursive: true });
+                }
+            }
+            if (options.dryRun) {
+                return {
+                    targetBranch,
+                    resources: results,
+                    dryRun: true,
+                    committed: false,
+                    pushed: false,
+                };
+            }
+            const changedPaths = [
+                ...new Set(resources.map((resource) => `${resource.type}s`)),
+            ];
+            const committed = await this.commitChanges(targetGit, "sync latest himan source resources", changedPaths, false);
+            const createdTags = results
+                .filter((result) => result.action === "created")
+                .map((result) => result.tag);
+            for (const tag of createdTags) {
+                await targetGit.addTag(tag);
+            }
+            const shouldPush = committed || createdTags.length > 0;
+            if (shouldPush) {
+                await targetGit.raw([
+                    "push",
+                    "--atomic",
+                    "origin",
+                    `${targetBranch}:refs/heads/${targetBranch}`,
+                    ...createdTags.map((tag) => `refs/tags/${tag}:refs/tags/${tag}`),
+                ]);
+            }
+            return {
+                targetBranch,
+                resources: results,
+                dryRun: false,
+                committed,
+                pushed: shouldPush,
+            };
+        }
+        finally {
+            await fs.rm(targetDir, { recursive: true, force: true });
+            await fs.rm(snapshotsDir, { recursive: true, force: true });
+        }
+    }
     async commitChanges(git, message, paths, requireChanges) {
         const pathspecs = paths.length > 0 ? paths : ["."];
         await git.add(pathspecs);
@@ -80,6 +200,132 @@ export class RepoManager {
         await git.commit(message, pathspecs);
         return true;
     }
+    async prepareTargetWorktree(targetRepo, targetDir, targetBranch, targetRefs) {
+        const hasTargetBranch = targetRefs.some((item) => item.ref === `refs/heads/${targetBranch}`);
+        if (hasTargetBranch) {
+            await simpleGit().clone(targetRepo, targetDir, ["--branch", targetBranch]);
+            const git = simpleGit(targetDir);
+            await git.fetch(["--tags", "--prune"]);
+            return git;
+        }
+        const git = simpleGit(targetDir);
+        await git.raw(["init", `--initial-branch=${targetBranch}`]);
+        await git.addRemote("origin", targetRepo);
+        if (targetRefs.some((item) => item.ref.startsWith("refs/tags/"))) {
+            await git.raw(["fetch", "origin", "+refs/tags/*:refs/tags/*"]);
+        }
+        return git;
+    }
+    async materializeSourceResourceSnapshot(sourceRepoDir, resource, targetDir) {
+        if (resource.sourceRef) {
+            await this.archiveResource(sourceRepoDir, resource.sourceRef, this.getResourcePath(resource), targetDir);
+            return;
+        }
+        if (!resource.sourcePath) {
+            throw new HimanError(errorCodes.VERSION_NOT_FOUND, `Version source not found for ${resource.type}/${resource.name}@${resource.version}.`);
+        }
+        await fs.rm(targetDir, { recursive: true, force: true });
+        await fs.mkdir(path.dirname(targetDir), { recursive: true });
+        await fs.cp(resource.sourcePath, targetDir, { recursive: true });
+    }
+    async ensureExistingTagMatchesResource(targetRepoDir, resource, sourceSnapshotDir) {
+        const previousDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-source-tag-"));
+        try {
+            await this.archiveResource(targetRepoDir, resource.tag, this.getResourcePath(resource), previousDir);
+            const [sourceSnapshot, previousSnapshot] = await Promise.all([
+                this.readDirectorySnapshot(sourceSnapshotDir),
+                this.readDirectorySnapshot(previousDir),
+            ]);
+            if (!this.snapshotsEqual(sourceSnapshot, previousSnapshot)) {
+                throw new HimanError(errorCodes.RESOURCE_EXISTS, `Target tag already exists with different content: ${resource.tag}`);
+            }
+        }
+        finally {
+            await fs.rm(previousDir, { recursive: true, force: true });
+        }
+    }
+    async listManagedResourceTags(repoDir) {
+        const tags = new Set();
+        for (const pattern of MANAGED_TAG_PATTERNS) {
+            for (const tag of await this.listTags(repoDir, pattern)) {
+                tags.add(tag);
+            }
+        }
+        return [...tags].sort((a, b) => a.localeCompare(b));
+    }
+    async listRemoteRefs(repo) {
+        const output = await simpleGit().raw(["ls-remote", "--heads", "--tags", repo]);
+        return output
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            const [hash, ref] = line.split(/\s+/);
+            return { hash, ref };
+        })
+            .filter((item) => item.hash && item.ref && !item.ref.endsWith("^{}"));
+    }
+    async getCurrentBranch(git) {
+        const branch = (await git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+        if (!branch || branch === "HEAD") {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Source repository is not on a named branch.");
+        }
+        return branch;
+    }
+    async resolveSourceBranchRef(git, branch) {
+        if (await this.hasGitRef(git, `refs/heads/${branch}`)) {
+            return branch;
+        }
+        const remoteRef = `refs/remotes/origin/${branch}`;
+        if (await this.hasGitRef(git, remoteRef)) {
+            return remoteRef;
+        }
+        throw new HimanError(errorCodes.INVALID_INPUT, `Source branch not found: ${branch}`);
+    }
+    async hasGitRef(git, ref) {
+        try {
+            await git.raw(["rev-parse", "--verify", ref]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async readDirectorySnapshot(targetDir) {
+        const files = await this.listFiles(targetDir);
+        const snapshot = new Map();
+        for (const file of files) {
+            const relative = path.relative(targetDir, file).split(path.sep).join("/");
+            snapshot.set(relative, await fs.readFile(file, "utf8"));
+        }
+        return snapshot;
+    }
+    async listFiles(targetDir) {
+        const entries = await fs.readdir(targetDir, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const fullPath = path.join(targetDir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(await this.listFiles(fullPath)));
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+            }
+        }
+        return files.sort((a, b) => a.localeCompare(b));
+    }
+    snapshotsEqual(a, b) {
+        if (a.size !== b.size)
+            return false;
+        for (const [file, content] of a) {
+            if (b.get(file) !== content)
+                return false;
+        }
+        return true;
+    }
+    getResourcePath(resource) {
+        return `${resource.type}s/${resource.name}`;
+    }
     async pushCurrentBranch(git, branch) {
         const currentBranch = (await git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
         const targetBranch = branch ?? currentBranch;

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

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+const TOKENIZER = "approx-char-v1";
+const TOKEN_ESTIMATOR = "ceil(chars/4)";
+export function buildResourceAnalysisMetadata(input) {
+    const measuredAt = input.measuredAt ?? new Date();
+    const packageFiles = input.packageFiles?.length
+        ? input.packageFiles
+        : [{ path: input.entry, content: input.entryContent }];
+    return {
+        content: {
+            tokenizer: TOKENIZER,
+            tokenEstimator: TOKEN_ESTIMATOR,
+            entryTokens: estimateTokens(input.entryContent),
+            packageTokens: estimateTokens(packageFiles.map((file) => file.content).join("\n")),
+            contentHash: hashPackageFiles(packageFiles),
+            measuredAt: measuredAt.toISOString(),
+            measuredBy: input.measuredBy,
+        },
+        dependencies: {
+            skills: [],
+            scripts: [],
+            mcpTools: [],
+        },
+        generation: {
+            generatedBy: input.generatedBy,
+            generatedAt: measuredAt.toISOString(),
+        },
+    };
+}
+function estimateTokens(content) {
+    return Math.ceil(content.length / 4);
+}
+function hashPackageFiles(files) {
+    const hash = createHash("sha256");
+    for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+        hash.update(file.path);
+        hash.update("\0");
+        hash.update(file.content);
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}