prizmkit 1.0.13 → 1.0.14

package/bundled/dev-pipeline/tests/test_utils.py

@@ -0,0 +1,141 @@
+"""Tests for utils.py."""
+
+import json
+import os
+import pytest
+
+from utils import load_json_file, write_json_file, pad_right, _build_progress_bar
+
+
+class TestLoadJsonFile:
+    def test_valid_json(self, tmp_path):
+        p = tmp_path / "valid.json"
+        p.write_text('{"key": "value"}', encoding="utf-8")
+        data, err = load_json_file(str(p))
+        assert err is None
+        assert data == {"key": "value"}
+
+    def test_invalid_json(self, tmp_path):
+        p = tmp_path / "invalid.json"
+        p.write_text("{not valid json", encoding="utf-8")
+        data, err = load_json_file(str(p))
+        assert data is None
+        assert "Invalid JSON" in err
+
+    def test_missing_file(self, tmp_path):
+        data, err = load_json_file(str(tmp_path / "missing.json"))
+        assert data is None
+        assert "File not found" in err
+
+    def test_empty_file(self, tmp_path):
+        p = tmp_path / "empty.json"
+        p.write_text("", encoding="utf-8")
+        data, err = load_json_file(str(p))
+        assert data is None
+        assert "Invalid JSON" in err
+
+    def test_unicode_content(self, tmp_path):
+        p = tmp_path / "unicode.json"
+        p.write_text('{"name": "hello"}', encoding="utf-8")
+        data, err = load_json_file(str(p))
+        assert err is None
+        assert data["name"] == "hello"
+
+    def test_nested_json(self, tmp_path):
+        nested = {"a": {"b": [1, 2, 3]}}
+        p = tmp_path / "nested.json"
+        p.write_text(json.dumps(nested), encoding="utf-8")
+        data, err = load_json_file(str(p))
+        assert err is None
+        assert data == nested
+
+
+class TestWriteJsonFile:
+    def test_write_and_read_back(self, tmp_path):
+        p = str(tmp_path / "output.json")
+        data = {"hello": "world", "num": 42}
+        err = write_json_file(p, data)
+        assert err is None
+        read_data, read_err = load_json_file(p)
+        assert read_err is None
+        assert read_data == data
+
+    def test_creates_parent_directories(self, tmp_path):
+        p = str(tmp_path / "a" / "b" / "c" / "output.json")
+        err = write_json_file(p, {"nested": True})
+        assert err is None
+        assert os.path.isfile(p)
+
+    def test_overwrites_existing(self, tmp_path):
+        p = str(tmp_path / "overwrite.json")
+        write_json_file(p, {"v": 1})
+        write_json_file(p, {"v": 2})
+        data, _ = load_json_file(p)
+        assert data["v"] == 2
+
+    def test_unicode_data(self, tmp_path):
+        p = str(tmp_path / "unicode.json")
+        err = write_json_file(p, {"name": "hello"})
+        assert err is None
+        data, _ = load_json_file(p)
+        assert data["name"] == "hello"
+
+
+class TestPadRight:
+    def test_shorter_than_width(self):
+        result = pad_right("abc", 10)
+        assert len(result) == 10
+        assert result == "abc       "
+
+    def test_exact_width(self):
+        result = pad_right("abcde", 5)
+        assert result == "abcde"
+
+    def test_longer_than_width(self):
+        result = pad_right("abcdefgh", 5)
+        assert result == "abcdefgh"
+
+    def test_empty_string(self):
+        result = pad_right("", 5)
+        assert result == "     "
+
+    def test_ansi_codes_ignored(self):
+        # ANSI escape should not count toward visible length
+        text = "\033[92mHi\033[0m"  # visible "Hi" = 2 chars
+        result = pad_right(text, 5)
+        # visible width is 2, so 3 spaces of padding
+        assert result.endswith("   ")
+
+    def test_zero_width(self):
+        result = pad_right("abc", 0)
+        assert result == "abc"
+
+
+class TestBuildProgressBar:
+    def test_zero_percent(self):
+        bar = _build_progress_bar(0)
+        assert "0%" in bar
+        assert "\u2591" in bar  # empty blocks
+        assert "\u2588" not in bar  # no filled blocks
+
+    def test_fifty_percent(self):
+        bar = _build_progress_bar(50, width=20)
+        assert "50%" in bar
+        assert bar.count("\u2588") == 10
+        assert bar.count("\u2591") == 10
+
+    def test_hundred_percent(self):
+        bar = _build_progress_bar(100, width=20)
+        assert "100%" in bar
+        assert bar.count("\u2588") == 20
+        assert bar.count("\u2591") == 0
+
+    def test_custom_width(self):
+        bar = _build_progress_bar(50, width=10)
+        assert bar.count("\u2588") == 5
+        assert bar.count("\u2591") == 5
+
+    def test_partial_percent(self):
+        bar = _build_progress_bar(33, width=10)
+        assert bar.count("\u2588") == 3
+        assert bar.count("\u2591") == 7

package/bundled/rules/USAGE.md

@@ -0,0 +1,153 @@
+# Rules 使用说明
+
+## 目录结构
+
+```
+core/rules/
+├── _rules-metadata.json     # 规则元数据 + preset 定义
+├── prizm/                   # PrizmKit 专属规则
+│   ├── prizm-documentation.md
+│   ├── prizm-commit-workflow.md
+│   └── prizm-progressive-loading.md
+└── general/                 # 通用 AI 行为规则
+    └── prefer-linux-commands.md
+```
+
+## 现有规则
+
+### PrizmKit 专属规则（`prizm/`）
+
+| 文件 | 说明 |
+|------|------|
+| `prizm-documentation.md` | 修改源文件时同步更新 `.prizm-docs/` |
+| `prizm-commit-workflow.md` | 提交前更新文档，遵循 Conventional Commits |
+| `prizm-progressive-loading.md` | 按需渐进加载 `.prizm-docs/`，禁止一次性全量读取 |
+
+### 通用规则（`general/`）
+
+| 文件 | 说明 |
+|------|------|
+| `prefer-linux-commands.md` | 优先使用 Linux/Unix 命令，避免平台特定语法 |
+
+---
+
+## 安装预设（Presets）
+
+安装时通过 `--rules` 选项选择预设，在 `_rules-metadata.json` 的 `presets` 字段定义：
+
+| Preset | 包含规则 |
+|--------|---------|
+| `recommended`（默认） | 全部 4 条规则 |
+| `minimal` | prizm-progressive-loading + prefer-linux-commands |
+| `none` | 不安装任何规则 |
+
+安装命令：
+```bash
+npx prizmkit install . --rules recommended
+npx prizmkit install . --rules minimal
+npx prizmkit install . --rules none
+```
+
+---
+
+## 安装后的文件位置
+
+| 平台 | 安装目录 | 格式 |
+|------|---------|------|
+| Claude Code | `.claude/rules/<name>.md` | Markdown + YAML frontmatter |
+| CodeBuddy | `.codebuddy/rules/<name>.mdc` | `.mdc` 格式（自动转换） |
+
+规则名使用 `category/filename` 路径格式（如 `prizm/prizm-documentation`），安装时取最后一段作为文件名（`prizm-documentation.md`）。
+
+---
+
+## 添加新规则
+
+### 1. 创建规则文件
+
+在对应子目录创建 `.md` 文件：
+
+```bash
+# PrizmKit 专属规则
+core/rules/prizm/my-new-rule.md
+
+# 通用规则
+core/rules/general/my-new-rule.md
+```
+
+规则文件格式：
+```markdown
+---
+description: "简短描述这条规则的作用"
+---
+
+规则正文，直接用自然语言描述 AI 应该遵守的行为。
+```
+
+如需限定文件类型（仅对特定文件触发），添加 `globs` 字段：
+```markdown
+---
+description: "仅对 TypeScript 文件生效的规则"
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+```
+
+### 2. 在 `_rules-metadata.json` 注册
+
+打开 `core/rules/_rules-metadata.json`，在 `rules` 对象中添加条目：
+
+```json
+{
+  "rules": {
+    "prizm/my-new-rule": {
+      "description": "一句话说明规则用途",
+      "tags": ["prizm", "custom"]
+    }
+  }
+}
+```
+
+规则名格式：`<category>/<filename>`（不含 `.md` 后缀）。
+
+### 3. 添加到 Preset（可选）
+
+如果希望新规则默认随 `recommended` 安装，在 `presets.recommended.rules` 数组中追加：
+
+```json
+{
+  "presets": {
+    "recommended": {
+      "rules": [
+        "prizm/prizm-documentation",
+        "prizm/prizm-commit-workflow",
+        "prizm/prizm-progressive-loading",
+        "general/prefer-linux-commands",
+        "prizm/my-new-rule"
+      ]
+    }
+  }
+}
+```
+
+也可以只添加到特定 preset，或不加入任何 preset（规则存在但不默认安装）。
+
+### 4. 重新打包
+
+修改 `core/rules/` 后，若需更新 npm 包的 `bundled/` 内容：
+
+```bash
+npm run bundle
+```
+
+---
+
+## CodeBuddy `.mdc` 格式转换说明
+
+安装到 CodeBuddy 时，`.md` 文件会由 `adapters/codebuddy/rules-adapter.js` 自动转换为 `.mdc` 格式：
+
+- 原始 `description` 字段保留
+- 自动添加 `alwaysApply: true`、`enabled: true`、`updatedAt` 字段
+- `globs` 字段（如有）保持不变
+- 规则正文内容不变

package/bundled/rules/_rules-metadata.json

@@ -0,0 +1,43 @@
+{
+  "version": "1.0.0",
+  "rules": {
+    "prizm/prizm-documentation": {
+      "description": "PrizmKit documentation update protocol",
+      "tags": ["prizm", "docs"]
+    },
+    "prizm/prizm-commit-workflow": {
+      "description": "Conventional commits + prizm-docs update before commit",
+      "tags": ["prizm", "git"]
+    },
+    "prizm/prizm-progressive-loading": {
+      "description": "Progressive .prizm-docs context loading protocol",
+      "tags": ["prizm", "context"]
+    },
+    "general/prefer-linux-commands": {
+      "description": "Prefer Linux/Unix shell commands",
+      "tags": ["general", "shell"]
+    }
+  },
+  "presets": {
+    "recommended": {
+      "description": "All PrizmKit rules + general rules (recommended)",
+      "rules": [
+        "prizm/prizm-documentation",
+        "prizm/prizm-commit-workflow",
+        "prizm/prizm-progressive-loading",
+        "general/prefer-linux-commands"
+      ]
+    },
+    "minimal": {
+      "description": "Minimal: progressive loading + general rules only",
+      "rules": [
+        "prizm/prizm-progressive-loading",
+        "general/prefer-linux-commands"
+      ]
+    },
+    "none": {
+      "description": "No rules installed",
+      "rules": []
+    }
+  }
+}

package/bundled/rules/general/prefer-linux-commands.md

@@ -0,0 +1,9 @@
+---
+description: "Prefer Linux/Unix commands for shell operations"
+---
+
+When writing or suggesting shell commands:
+1. Prefer standard Linux/Unix commands (ls, grep, find, cat, sed, awk, etc.)
+2. Avoid PowerShell, Windows CMD, or macOS-specific commands unless the target is explicitly Windows
+3. Use POSIX-compliant syntax when possible for cross-platform compatibility
+4. For file operations, prefer: cp, mv, rm, mkdir, chmod over GUI or platform-specific tools

package/bundled/rules/prizm/prizm-commit-workflow.md

@@ -0,0 +1,10 @@
+---
+description: "PrizmKit commit workflow rules"
+---
+
+Before any git commit in this project:
+1. Update `.prizm-docs/` for affected modules
+2. Use Conventional Commits format: type(scope): description
+3. Bug fixes use `fix()` prefix, not `feat()`
+4. Do NOT create REGISTRY.md entries for bug fixes
+5. Use `/prizmkit-committer` command for the complete commit workflow

package/bundled/rules/prizm/prizm-documentation.md

@@ -0,0 +1,19 @@
+---
+description: "PrizmKit documentation rules"
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.java"
+---
+
+When modifying source files in this project:
+1. Check if `.prizm-docs/root.prizm` exists
+2. If it does, read it before making changes to understand project structure
+3. After making changes, update affected `.prizm-docs/` files
+4. Follow the Prizm doc format (KEY: value, not prose)
+5. Size limits: L0 = 4KB, L1 = 3KB, L2 = 5KB

package/bundled/rules/prizm/prizm-progressive-loading.md

@@ -0,0 +1,11 @@
+---
+description: "PrizmKit progressive context loading protocol"
+---
+
+This project uses PrizmKit's progressive loading protocol:
+- ON SESSION START: Read `.prizm-docs/root.prizm` (L0 — project map)
+- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules
+- ON FILE EDIT: Read L2 (`.prizm-docs/<module>/<submodule>.prizm`) before modifying
+- NEVER load all .prizm docs at once
+- Arrow notation (->) in .prizm files indicates load pointers
+- DECISIONS and CHANGELOG in .prizm files are append-only