@kevlns/xlmerge 1.2.1-beta.1 → 1.2.1-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -70,9 +70,12 @@ decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:
70
70
  ## 开发与测试
71
71
 
72
72
  ```bash
73
- # 单元测试(63 个,覆盖引擎与解析器全流程)
73
+ # 单元测试(72 个,覆盖引擎与解析器全流程)
74
74
  python -m unittest discover -s python/tests -v
75
75
 
76
+ # 校验 v-cli.plugin.json 与 CLI 解析器未漂移(命令/选项/副作用覆盖)
77
+ npm run check:manifest
78
+
76
79
  # 端到端(构造真实冲突仓库 -> detect -> launch -> API 决策 -> 写回提交)
77
80
  python e2e_test.py bin/xlmerge.js node
78
81
 
@@ -85,11 +88,12 @@ npm pack
85
88
  ```
86
89
  bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
87
90
  skill/SKILL.md # Agent Skill 文档
91
+ v-cli.plugin.json # Agent 插件清单(命令/选项/副作用),与 CLI 解析器做漂移校验
88
92
  python/
89
93
  ├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
90
94
  │ └── xlsx_git_merge_bridge.py
91
95
  ├── xlsx_resolver/ # 冲突解析器(detect/prepare/launch/apply + bottle UI)
92
- └── tests/ # 引擎与解析器测试
96
+ └── tests/ # 引擎与解析器测试(不随 npm 包发布)
93
97
  ```
94
98
 
95
99
  > 注:为兼容嵌入式 Python 发行版(`._pth` 忽略 `PYTHONPATH`),模块内使用包内自举的 `sys.path` 注入而非纯包导入;这是有意为之。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kevlns/xlmerge",
3
- "version": "1.2.1-beta.1",
3
+ "version": "1.2.1-beta.2",
4
4
  "description": "Visual resolver for unresolved Git merge conflicts in .xlsx/.xlsm workbooks: three-way sheet/row/cell diff, local UI, write-back and commit.",
5
5
  "bin": {
6
6
  "xlmerge": "bin/xlmerge.js"
@@ -9,11 +9,16 @@
9
9
  "bin/",
10
10
  "skill/",
11
11
  "python/xlsx_merge_engine/",
12
- "python/xlsx_resolver/"
12
+ "python/xlsx_resolver/",
13
+ "v-cli.plugin.json"
13
14
  ],
15
+ "vCli": {
16
+ "manifest": "v-cli.plugin.json"
17
+ },
14
18
  "scripts": {
15
19
  "test": "node bin/xlmerge.js --selfcheck",
16
- "test:python": "python -m unittest discover -s python/tests -v"
20
+ "test:python": "python -m unittest discover -s python/tests -v",
21
+ "check:manifest": "python -m unittest discover -s python/tests -p test_v_cli_plugin_manifest.py -v"
17
22
  },
18
23
  "repository": {
19
24
  "type": "git",
@@ -85,7 +85,7 @@ def _launch_background(repo: Path, manifest: Path, *, open_browser: bool) -> dic
85
85
 
86
86
  def build_parser() -> argparse.ArgumentParser:
87
87
  parser = argparse.ArgumentParser(description="Resolve Git XLSX/XLSM conflicts in the sibling Debussy meta repository.")
88
- parser.add_argument("--repo", default=",", help="Git repository (default: current directory).")
88
+ parser.add_argument("--repo", default=".", help="Git repository (default: %(default)s; the current directory).")
89
89
  parser.add_argument("--runtime-dir", help="Optional directory for extracted Git stage workbooks and manifest.")
90
90
  subparsers = parser.add_subparsers(dest="command", required=True)
91
91
 
@@ -118,7 +118,10 @@ def build_parser() -> argparse.ArgumentParser:
118
118
  def main(argv: list[str] | None = None) -> int:
119
119
  args = build_parser().parse_args(argv)
120
120
  try:
121
- repo = find_repo_root(args.repo)
121
+ # serve/apply 仅依赖 manifest(其 repoRoot 在 apply_manifest 内部解析),
122
+ # 可在非 git 目录下运行;仅 detect/prepare/resolve/launch 需要前置解析仓库。
123
+ if args.command in ("detect", "prepare", "resolve", "launch"):
124
+ repo = find_repo_root(args.repo)
122
125
  if args.command == "detect":
123
126
  conflicts = detect_conflicts(repo)
124
127
  _print({"ok": True, "repo": str(repo), "count": len(conflicts), "conflicts": conflicts})
@@ -0,0 +1,167 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "package": "@kevlns/xlmerge",
4
+ "command": "xlmerge",
5
+ "bin": "xlmerge",
6
+ "description": "Visual resolver for Git merge conflicts in .xlsx/.xlsm planning tables: three-way sheet/row/cell diff, local UI, write-back and commit.",
7
+ "platforms": ["darwin", "linux", "win32"],
8
+ "runtime": {
9
+ "node": ">=16",
10
+ "python": ">=3.9",
11
+ "pythonDependencies": ["openpyxl==3.1.5", "bottle==0.13.4"]
12
+ },
13
+ "environment": [
14
+ {
15
+ "name": "XLMERGE_PYTHON",
16
+ "description": "Python interpreter path; highest precedence, bypasses automatic discovery."
17
+ },
18
+ {
19
+ "name": "XLMERGE_VENV",
20
+ "description": "Directory for the on-demand user-level virtualenv (default: ~/.xlmerge/venv)."
21
+ }
22
+ ],
23
+ "agent": {
24
+ "whenToUse": "When a user asks to resolve Git merge conflicts in .xlsx/.xlsm planning or configuration tables (策划表/配置表冲突): run detect first; when count > 0 run launch and give the returned url to the user. Do not inspect workbook cells or summarize diffs yourself; the resolver owns diff, choices, write-back and commit.",
25
+ "globalOptions": [
26
+ {
27
+ "flags": "--repo <path>",
28
+ "description": "Git repository (default: current directory; searches upward for the Git root)."
29
+ },
30
+ {
31
+ "flags": "--runtime-dir <dir>",
32
+ "description": "Optional directory for extracted Git stage workbooks and manifest (default: system temp). Used by prepare, resolve and launch."
33
+ }
34
+ ],
35
+ "commands": [
36
+ {
37
+ "path": ["detect"],
38
+ "usage": "xlmerge --repo <repo> detect",
39
+ "description": "List unresolved .xlsx/.xlsm files in the repository.",
40
+ "arguments": [],
41
+ "options": [],
42
+ "output": {
43
+ "format": "json",
44
+ "description": "Object with ok, repo (absolute path), count and conflicts (array of {path, stages})."
45
+ },
46
+ "exitCodes": {
47
+ "0": "success",
48
+ "1": "error (e.g. not a Git repository)",
49
+ "2": "usage error"
50
+ },
51
+ "safety": ["read-only", "no-worktree-modification"]
52
+ },
53
+ {
54
+ "path": ["prepare"],
55
+ "usage": "xlmerge --repo <repo> prepare [--path <file>]",
56
+ "description": "Extract base/ours/theirs stage versions from the Git index and build a sheet-aware manifest.",
57
+ "arguments": [],
58
+ "options": [
59
+ {
60
+ "flags": "--path <file>",
61
+ "description": "Only prepare this repository-relative .xlsx/.xlsm path."
62
+ }
63
+ ],
64
+ "output": {
65
+ "format": "json",
66
+ "description": "Object with ok and manifest (absolute path to the manifest JSON)."
67
+ },
68
+ "exitCodes": {
69
+ "0": "success",
70
+ "1": "error (no conflicts found, not a Git repository, git failure)",
71
+ "2": "usage error"
72
+ },
73
+ "safety": ["writes-runtime-dir", "no-worktree-modification", "no-commit"]
74
+ },
75
+ {
76
+ "path": ["resolve"],
77
+ "usage": "xlmerge --repo <repo> resolve [--path <file>] [--no-browser]",
78
+ "description": "Prepare conflicts and serve the local visual resolver in the foreground (blocking).",
79
+ "arguments": [],
80
+ "options": [
81
+ {
82
+ "flags": "--path <file>",
83
+ "description": "Only resolve this repository-relative .xlsx/.xlsm path."
84
+ },
85
+ {
86
+ "flags": "--no-browser",
87
+ "description": "Print the URL instead of opening a browser."
88
+ }
89
+ ],
90
+ "output": {
91
+ "format": "stdout",
92
+ "description": "Prints MERGE_SERVER_URL=http://127.0.0.1:<port> then serves the UI on loopback until a resolution is applied (write-back + commit) and the server shuts down."
93
+ },
94
+ "exitCodes": {
95
+ "0": "success (resolution applied; server shut down after write-back)",
96
+ "1": "error (prepare failure or server stopped before a resolution was applied)",
97
+ "2": "usage error"
98
+ },
99
+ "safety": ["blocking", "binds-loopback", "opens-browser-by-default", "no-push", "writes-runtime-dir", "writes-worktree-via-ui", "commits-by-default-via-ui"]
100
+ },
101
+ {
102
+ "path": ["launch"],
103
+ "usage": "xlmerge --repo <repo> launch [--path <file>] [--no-browser]",
104
+ "description": "Prepare conflicts, start the visual resolver in the background and return its URL.",
105
+ "arguments": [],
106
+ "options": [
107
+ {
108
+ "flags": "--path <file>",
109
+ "description": "Only resolve this repository-relative .xlsx/.xlsm path."
110
+ },
111
+ {
112
+ "flags": "--no-browser",
113
+ "description": "Start the server without opening a browser."
114
+ }
115
+ ],
116
+ "output": {
117
+ "format": "json",
118
+ "description": "Object with ok, pid, url (http://127.0.0.1:<port>), manifest and stdout/stderr log file paths."
119
+ },
120
+ "exitCodes": {
121
+ "0": "success",
122
+ "1": "error (prepare failure or server did not report a URL within 15 seconds)",
123
+ "2": "usage error"
124
+ },
125
+ "safety": ["starts-background-server", "binds-loopback", "opens-browser-by-default", "no-push", "writes-runtime-dir", "writes-worktree-via-ui", "commits-by-default-via-ui"]
126
+ },
127
+ {
128
+ "path": ["apply"],
129
+ "usage": "xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--push] [--message <text>]",
130
+ "description": "Write back decisions from a decisions JSON without launching the UI.",
131
+ "arguments": [],
132
+ "options": [
133
+ {
134
+ "flags": "--manifest <file>",
135
+ "description": "Required. Manifest JSON produced by prepare."
136
+ },
137
+ {
138
+ "flags": "--decisions <file>",
139
+ "description": "Required. Decisions JSON with per-file per-sheet cell, row, column, rename and macro choices keyed by logical IDs."
140
+ },
141
+ {
142
+ "flags": "--no-commit",
143
+ "description": "Skip git add/commit after writing merged workbooks."
144
+ },
145
+ {
146
+ "flags": "--push",
147
+ "description": "Push after committing (off by default)."
148
+ },
149
+ {
150
+ "flags": "--message <text>",
151
+ "description": "Override the auto-generated structured commit message."
152
+ }
153
+ ],
154
+ "output": {
155
+ "format": "json",
156
+ "description": "Result object with success and summary of written files and commit."
157
+ },
158
+ "exitCodes": {
159
+ "0": "success (including with --no-commit)",
160
+ "1": "error (invalid or incomplete decisions, git/OS failure)",
161
+ "2": "usage error"
162
+ },
163
+ "safety": ["writes-worktree", "commits-by-default", "pushes-only-with-flag"]
164
+ }
165
+ ]
166
+ }
167
+ }