@hi-man/himan 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -6,10 +6,23 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.3.5] - 2026-05-12
+
+### Changed
+
+- Changed the CLI version shortcut from `-V` to `-v`; `--version` remains supported.
+- Changed the default install mode to `copy`; pass `--mode link` to install resources as symlinks.
+
+## [0.3.4] - 2026-05-11
+
 ### Changed
 
 - Changed project guidance to require changelog updates for user-visible CLI behavior changes.
 
+### Fixed
+
+- Fixed `himan publish` so publishing stops with `E_PUBLISH_NO_CHANGES` when the resource content matches the latest published version.
+
 ## [0.3.3] - 2026-05-11
 
 ### Added

package/README.md

@@ -66,7 +66,7 @@ himan publish rule my-rule --patch
   - `command` -> `.himan/dev/command/<name>`
   - `skill` -> `.himan/dev/skill/<name>`
 - lock 文件：项目安装 `install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。`--global` 安装不写当前项目的 `himan.lock`。
-- 安装模式：默认 `--mode link` 使用软链；也可用 `--mode copy` 将资源复制到目标 agent 目录，lock 会记录并复现该模式。
+- 安装模式：默认 `--mode copy` 将资源复制到目标 agent 目录；也可用 `--mode link` 使用软链，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)。
@@ -167,7 +167,7 @@ your-himan-source/
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
 若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
 
-`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录。
+`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>` 开发目录。
 
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 

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

@@ -4,6 +4,7 @@ import semver from "semver";
 import { HimanError, errorCodes } from "../../utils/errors.js";
 import { promises as fs } from "node:fs";
 import { createHash } from "node:crypto";
+import os from "node:os";
 import path from "node:path";
 import YAML from "yaml";
 import { IndexCacheStore } from "../../state/index-cache-store.js";
@@ -52,6 +53,7 @@ export class GitSourceAdapter {
         const repoDir = this.getRepoDir();
         const targetDir = path.join(repoDir, `${type}s`, name);
         const metadataResult = await this.validatePublishResource(type, name, sourceDir);
+        await this.ensurePublishHasContentChanges(type, name, sourceDir);
         const sameDir = await this.isSameDirectory(sourceDir, targetDir);
         if (!sameDir) {
             await fs.rm(targetDir, { recursive: true, force: true });
@@ -261,6 +263,76 @@ export class GitSourceAdapter {
             metadata.agents = agents;
         return metadata;
     }
+    async ensurePublishHasContentChanges(type, name, sourceDir) {
+        const latest = (await this.history(type, name))[0];
+        if (!latest)
+            return;
+        const previousDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-publish-"));
+        try {
+            await this.repoManager.archiveResource(this.getRepoDir(), latest.raw, `${type}s/${name}`, previousDir);
+            const [nextSnapshot, previousSnapshot] = await Promise.all([
+                this.readComparableResourceSnapshot(sourceDir),
+                this.readComparableResourceSnapshot(previousDir),
+            ]);
+            if (this.resourceSnapshotsEqual(nextSnapshot, previousSnapshot)) {
+                throw new HimanError(errorCodes.PUBLISH_NO_CHANGES, `No changes to publish for ${type}/${name}.`);
+            }
+        }
+        finally {
+            await fs.rm(previousDir, { recursive: true, force: true });
+        }
+    }
+    async readComparableResourceSnapshot(resourceDir) {
+        const files = await this.listResourceFiles(resourceDir);
+        const snapshot = new Map();
+        for (const file of files) {
+            const relative = this.toPosixPath(path.relative(resourceDir, file));
+            const content = await fs.readFile(file, "utf8");
+            snapshot.set(relative, relative === "himan.yaml"
+                ? this.normalizeComparableResourceMetadata(content)
+                : content);
+        }
+        return snapshot;
+    }
+    async listResourceFiles(resourceDir) {
+        const result = [];
+        const entries = await fs.readdir(resourceDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(resourceDir, entry.name);
+            if (entry.isDirectory()) {
+                result.push(...(await this.listResourceFiles(fullPath)));
+            }
+            else if (entry.isFile()) {
+                result.push(fullPath);
+            }
+        }
+        return result.sort((a, b) => a.localeCompare(b));
+    }
+    normalizeComparableResourceMetadata(content) {
+        try {
+            const parsed = YAML.parse(content);
+            if (!this.isRecord(parsed))
+                return content;
+            const normalized = { ...parsed };
+            delete normalized.version;
+            return YAML.stringify(normalized);
+        }
+        catch {
+            return content;
+        }
+    }
+    resourceSnapshotsEqual(a, b) {
+        if (a.size !== b.size)
+            return false;
+        for (const [file, content] of a) {
+            if (b.get(file) !== content)
+                return false;
+        }
+        return true;
+    }
+    toPosixPath(filePath) {
+        return filePath.split(path.sep).join("/");
+    }
     invalidResourceMetadata(type, name, message, details) {
         return new HimanError(errorCodes.INVALID_RESOURCE_METADATA, `Invalid metadata for ${type}/${name}: ${message}`, details);
     }

package/dist/cli/shared.js

@@ -12,7 +12,7 @@ export function createBaseProgram(name, description) {
             // Parse/usage errors are unified by writeCliError().
         },
     });
-    program.name(name).description(description).version(PACKAGE_VERSION);
+    program.name(name).description(description).version(PACKAGE_VERSION, "-v, --version");
     return program;
 }
 export async function runAction(action) {

package/dist/services/index.js

@@ -183,11 +183,11 @@ export class ServiceFactory {
         const source = await this.loadSourceFromConfig();
         return source.history(type, name);
     }
-    async install(type, name, version, projectDir, agents, mode = "link") {
+    async install(type, name, version, projectDir, agents, mode = "copy") {
         const { source, sourceInfo } = await this.loadSourceWithInfoFromConfig();
         return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode);
     }
-    async installGlobal(type, name, version, projectDir, agents, mode = "link") {
+    async installGlobal(type, name, version, projectDir, agents, mode = "copy") {
         const source = await this.loadSourceFromConfig();
         return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global");
     }
@@ -431,7 +431,7 @@ export class ServiceFactory {
         await fs.symlink(sourcePath, targetPath, "dir");
     }
     resolveInstallMode(mode) {
-        return mode === "copy" ? "copy" : "link";
+        return mode === "link" ? "link" : "copy";
     }
     async resolveInstalledResource(projectDir, type, name) {
         const locked = await this.getLockedResource(projectDir, type, name);

package/docs/development.md

@@ -13,7 +13,7 @@
 ```bash
 pnpm install
 pnpm run build
-pnpm run dev -- --help
+pnpm cli --help
 node dist/bin/himan.js --help
 ```
 
@@ -28,6 +28,7 @@ pnpm test
 | 命令 | 作用 |
 |------|------|
 | `pnpm run clean` | 删除 `dist/` |
+| `pnpm cli <subcommand>` | 从源码运行主 CLI |
 | `pnpm run build` | 清理并编译 TypeScript 到 `dist/` |
 | `pnpm run typecheck` | 运行 TypeScript 类型检查，不输出文件 |
 | `pnpm test` | 运行 Vitest 一次 |

package/docs/error-codes.md

@@ -116,7 +116,7 @@
 ### `E_PUBLISH_NO_CHANGES`
 
 - **含义**：发布时没有可提交的资源变更。
-- **常见触发**：重复发布已写入相同内容和版本的资源目录。
+- **常见触发**：重复发布与最新已发布版本内容一致的资源目录；`himan.yaml` 中仅版本字段不同也会视为无内容变化。
 - **建议处理**：确认资源内容或元数据已经变更，再重新执行 `publish`。
 
 ### `E_UNSUPPORTED_RESOURCE_TYPE`

package/docs/mvp/README.md

@@ -43,7 +43,7 @@
 - 也支持 `himan install`（无参数）按 `himan.lock` 批量复现安装。
 - 未指定版本则安装该资源最新 tag 对应版本。
 - 若本地 store 中已有该版本缓存，则复用、不重新从 Git 导出；否则导出到 store。
-- 在项目下按安装模式创建目标（默认 `--mode link` 软链；`--mode copy` 复制）。
+- 在项目下按安装模式创建目标（默认 `--mode copy` 复制；`--mode link` 软链）。
 - 目标路径由 agent 和资源类型共同决定：
   - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
   - `claude-code` -> `.claude/{rules|commands|skills}/<name>`
@@ -91,7 +91,7 @@
 - **领域**：资源类型、版本、路径约定
 - **适配**：Git 实现 + Registry 预留；扫描与解析元数据；版本计算；配置与全局路径
 
-**原则：** store 按版本目录追加、不覆盖已有缓存；开发目录与项目安装目标分离；项目侧默认以软链引用资源，也支持复制。
+**原则：** store 按版本目录追加、不覆盖已有缓存；开发目录与项目安装目标分离；项目侧默认复制资源，也支持软链引用。
 
 ### 3.2 目录与数据
 

package/docs/mvp/impl.md

@@ -44,7 +44,7 @@
 - 命令层接受 `rule|command|skill`
 - 无版本则取该资源历史中的最新 semver
 - 若本地 store 已有该版本目录则不再从 Git 导出；否则从对应 tag 导出资源树到 store
-- 在项目中按 agent 和资源类型创建/更新安装目标，例如 `cursor -> .cursor/{rules|commands|skills}`、`codex -> .agents/{rules|commands|skills}`；默认软链到 store 中该版本，也可通过 `--mode copy` 复制内容
+- 在项目中按 agent 和资源类型创建/更新安装目标，例如 `cursor -> .cursor/{rules|commands|skills}`、`codex -> .agents/{rules|commands|skills}`；默认复制 store 中该版本，也可通过 `--mode link` 软链引用
 
 ### 2.5 `dev <type> <name>`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hi-man/himan",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Prompt and agent asset management CLI",
   "keywords": [
     "ai",
@@ -51,7 +51,7 @@
     "clean": "rm -rf dist",
     "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/bin/himan.ts",
+    "cli": "tsx src/bin/himan.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",