ci: add e2e tests & readiness checks

.github/workflows/build.yml

@@ -34,33 +34,23 @@ jobs:
             os: ubuntu-latest
           - rid: win-x64
             name: officecli-win-x64.exe
-            os: ubuntu-latest
+            os: windows-latest
           - rid: win-arm64
             name: officecli-win-arm64.exe
-            os: ubuntu-latest
+            os: windows-latest
     runs-on: ${{ matrix.os }}
 
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Clone wiki for embedded help
-        run: git clone "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.wiki.git" src/officecli/wiki || echo "Wiki clone failed, using fallback help"
+    defaults:
+      run:
+        shell: bash
 
-      - name: Verify wiki version matches csproj version
-        run: |
-          CSPROJ_VERSION=$(grep '<Version>' src/officecli/officecli.csproj | sed 's/.*<Version>\(.*\)<\/Version>.*/\1/')
-          WIKI_VERSION=$(python3 -c "import json; print(json.load(open('src/officecli/wiki/version.json'))['version'])" 2>/dev/null || echo "unknown")
-          echo "csproj: $CSPROJ_VERSION, wiki: $WIKI_VERSION"
-          if [ "$WIKI_VERSION" != "$CSPROJ_VERSION" ]; then
-            echo "::error::Wiki version ($WIKI_VERSION) does not match csproj version ($CSPROJ_VERSION). Update wiki before building."
-            exit 1
-          fi
+    steps:
+      - uses: actions/checkout@v5
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v4
+        uses: actions/setup-dotnet@v5
         with:
           dotnet-version: '10.0.x'
-          dotnet-quality: 'preview'
 
       - name: Publish
         run: dotnet publish src/officecli/officecli.csproj -c Release -r ${{ matrix.rid }} -o publish --nologo
@@ -81,16 +71,85 @@ jobs:
         if: >-
           (matrix.rid == 'osx-arm64' && runner.arch == 'ARM64') ||
           (matrix.rid == 'osx-x64' && runner.arch == 'X64') ||
-          (matrix.rid == 'linux-x64' && runner.os == 'Linux')
+          (matrix.rid == 'linux-x64' && runner.os == 'Linux') ||
+          (matrix.rid == 'win-x64' && runner.os == 'Windows')
+        env:
+          # Disable Git Bash (MSYS) POSIX-to-Windows path conversion on
+          # windows-latest, which otherwise mangles `/body` into
+          # `C:/Program Files/Git/body` before it reaches the CLI.
+          MSYS_NO_PATHCONV: '1'
+          MSYS2_ARG_CONV_EXCL: '*'
         run: |
           chmod +x publish/${{ matrix.name }}
           publish/${{ matrix.name }} create test_smoke.docx
           publish/${{ matrix.name }} add test_smoke.docx /body --type paragraph --prop text="Hello from CI"
-          publish/${{ matrix.name }} get test_smoke.docx /body/p[1]
+          publish/${{ matrix.name }} get test_smoke.docx '/body/p[1]'
+          publish/${{ matrix.name }} close test_smoke.docx
           rm -f test_smoke.docx
 
+      - name: Smoke test - .NET 8-only runtime (linux-x64)
+        if: matrix.rid == 'linux-x64' && runner.os == 'Linux'
+        run: |
+          chmod +x publish/${{ matrix.name }}
+          mkdir -p smoke_net8
+          docker run --rm \
+            -v "$PWD/publish:/app:ro" \
+            -v "$PWD/smoke_net8:/work" \
+            -w /work \
+            mcr.microsoft.com/dotnet/runtime:8.0 \
+            bash -c "set -e; \
+              /app/${{ matrix.name }} create issue115.docx; \
+              /app/${{ matrix.name }} add issue115.docx /body --type paragraph --prop text='net8 smoke'; \
+              /app/${{ matrix.name }} close issue115.docx; \
+              /app/${{ matrix.name }} view issue115.docx text --json"
+
+      - name: Smoke test - install
+        if: >-
+          (matrix.rid == 'osx-arm64' && runner.arch == 'ARM64') ||
+          (matrix.rid == 'osx-x64' && runner.arch == 'X64') ||
+          (matrix.rid == 'linux-x64' && runner.os == 'Linux') ||
+          (matrix.rid == 'win-x64' && runner.os == 'Windows')
+        env:
+          MSYS_NO_PATHCONV: '1'
+          MSYS2_ARG_CONV_EXCL: '*'
+        run: |
+          publish/${{ matrix.name }} install
+          if [ "$RUNNER_OS" == "Windows" ]; then
+            test -f "$LOCALAPPDATA/OfficeCLI/officecli.exe" || { echo "FAIL: officecli.exe not found in %LOCALAPPDATA%\\OfficeCLI"; exit 1; }
+            "$LOCALAPPDATA/OfficeCLI/officecli.exe" --version
+          else
+            test -f "$HOME/.local/bin/officecli" || { echo "FAIL: officecli not found in ~/.local/bin"; exit 1; }
+            "$HOME/.local/bin/officecli" --version
+          fi
+
+      - name: Smoke test - install.sh / install.ps1
+        # Exercises the shell installers themselves (separate from the CLI's
+        # own `install` subcommand tested above). Downloads from
+        # d.officecli.ai with github fallback — validates the production
+        # mirror is reachable AND the in-repo script is syntactically and
+        # logically correct on each platform.
+        if: >-
+          (matrix.rid == 'osx-arm64' && runner.arch == 'ARM64') ||
+          (matrix.rid == 'osx-x64' && runner.arch == 'X64') ||
+          (matrix.rid == 'linux-x64' && runner.os == 'Linux') ||
+          (matrix.rid == 'win-x64' && runner.os == 'Windows')
+        shell: bash
+        env:
+          MSYS_NO_PATHCONV: '1'
+          MSYS2_ARG_CONV_EXCL: '*'
+        run: |
+          if [ "$RUNNER_OS" == "Windows" ]; then
+            pwsh -NoProfile -ExecutionPolicy Bypass -File ./install.ps1
+            test -f "$LOCALAPPDATA/OfficeCLI/officecli.exe" || { echo "FAIL: officecli.exe not installed"; exit 1; }
+            "$LOCALAPPDATA/OfficeCLI/officecli.exe" --version
+          else
+            bash install.sh
+            test -f "$HOME/.local/bin/officecli" || { echo "FAIL: officecli not installed at ~/.local/bin"; exit 1; }
+            "$HOME/.local/bin/officecli" --version
+          fi
+
       - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: ${{ matrix.name }}
           path: publish/${{ matrix.name }}
@@ -103,7 +162,7 @@ jobs:
       contents: write
     steps:
       - name: Download all artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: artifacts
 
@@ -119,7 +178,7 @@ jobs:
           cat SHA256SUMS
 
       - name: Create Draft Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           files: artifacts/**/*
           generate_release_notes: true

.github/workflows/skill-parity.yml

@@ -0,0 +1,41 @@
+name: Skill parity
+
+# Root SKILL.md is the file the public URL serves
+# (https://d.officecli.ai/SKILL.md, raw GitHub URL) and is what
+# `curl ... | bash` consumers fetch. skills/officecli/SKILL.md is a
+# symlink to it — the spec-conforming location that `gh skill install`
+# and `npx skills add` discover, and what the binary embeds.
+#
+# On macOS / Linux the symlink resolves transparently and this diff
+# always passes. The check exists for the Windows case: git on Windows
+# without core.symlinks=true checks out symlinks as plain text files
+# containing the link target path (e.g. literal "../../SKILL.md"), so
+# diff catches that corruption before it ships in a release build.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - 'SKILL.md'
+      - 'skills/officecli/SKILL.md'
+      - '.github/workflows/skill-parity.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Diff root SKILL.md vs skills/officecli/SKILL.md
+        run: |
+          if ! diff -q SKILL.md skills/officecli/SKILL.md; then
+            echo "::error::SKILL.md and skills/officecli/SKILL.md are out of sync."
+            echo "The two files must be byte-identical. The binary embeds skills/officecli/SKILL.md;"
+            echo "the public URL (d.officecli.ai/SKILL.md, raw GitHub) serves the root copy."
+            echo "Fix: cp SKILL.md skills/officecli/SKILL.md (or the reverse) and commit."
+            exit 1
+          fi
+          echo "OK: SKILL.md == skills/officecli/SKILL.md"

CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to OfficeCLI
+
+> 中文版 / Chinese version: [CONTRIBUTING.zh.md](./CONTRIBUTING.zh.md)
+
+> You must follow the two rules below. Code style, dependencies, tests, and
+> docs are handled by the maintainer in post-merge cleanup — do not worry
+> about them.
+
+## Rule 1: One PR = one atomic change
+
+A PR must contain exactly one feature or one bug fix that cannot be further
+decomposed. If your change can be split into multiple pieces that each have
+standalone value, submit each piece as a separate PR.
+
+### Self-check
+
+Before opening the PR, ask your AI tool:
+
+> "Analyze this diff. Can it be decomposed into multiple PRs where each
+> could be merged or reverted independently? If yes, list them."
+
+If the answer is "yes, N PRs", split into N PRs before submitting.
+
+### Examples
+
+**✅ Single-PR bugs** — one root cause, one fix
+- `Picture added with only 'width' specified gets wrong default height`
+- `Body-level find: anchor throws ArgumentException`
+- `AddParagraph --index N is off-by-one when the body contains a table`
+
+**✅ Single-PR features** — one coherent capability
+- `query ole: list embedded OLE objects with ProgID and dimensions`
+- `set wrap/hposition/vposition on floating pictures`
+
+**❌ Must split** — multiple independent changes bundled together
+- `Fix picture index bug + add OLE detection + add HTML heading numbering`
+  → 3 PRs, zero shared code
+- `Add OLE object detection + add EMF→PNG conversion`
+  → 2 PRs, two independent layers
+- `Add auto aspect ratio + fix index off-by-one + fix line spacing clipping`
+  → 3 PRs, three unrelated root causes
+
+**🤔 Judgment calls** — default to splitting
+- `Add helper function + its first consumer`
+  → 1 or 2 PRs; split if the helper has standalone reuse potential
+- `Add read support + add write support for the same property`
+  → 1 or 2 PRs; split if you want read to land before write is vetted
+
+## Rule 2: Every PR must include a verifiable validation method
+
+State in the PR description (or a linked issue) how a reviewer can confirm
+your change actually works.
+
+### For bug-fix PRs — pick one (in order of preference)
+
+1. **officecli command sequence** showing broken output before and fixed
+   output after
+2. **Shell or Python script** that reproduces the bug and runs clean after
+   the fix
+3. **Authoritative reference** showing what the correct behavior should be
+   (OOXML spec, Microsoft / ECMA docs, etc.)
+4. **Screenshot** — only when the bug is purely visual
+
+### For feature PRs — include at minimum
+
+- **A screenshot** of the feature in action (Word / Excel / PowerPoint
+  window, HTML preview, or terminal output)
+- Optionally a command sequence showing how to trigger it
+
+### Examples
+
+**Bug fix — command sequence (ideal):**
+
+```bash
+# Before my fix:
+officecli blank test.docx
+officecli add test.docx picture --prop "path=photo-2x1.png" --prop "width=10cm"
+officecli query test.docx picture
+# → height: "10.2cm"  ❌ WRONG (hardcoded 4-inch default)
+
+# After my fix:
+officecli blank test.docx
+officecli add test.docx picture --prop "path=photo-2x1.png" --prop "width=10cm"
+officecli query test.docx picture
+# → height: "5.0cm"   ✓ CORRECT (auto-computed from 2:1 pixel ratio)
+```
+
+**Feature — screenshot (ideal):**
+
+> **Heading auto-numbering from style chain**
+>
+> Before: ![heading-before.png] (plain "Chapter One" with no number)
+> After:  ![heading-after.png]  ("1. Chapter One" with auto-numbering span)
+>
+> How to trigger:
+> ```bash
+> officecli blank demo.docx
+> officecli add demo.docx paragraph --prop "style=Heading1" --prop "text=Chapter One"
+> officecli watch demo.docx
+> ```
+
+## If you don't follow these rules
+
+The maintainer reserves two options.
+
+### Option A — Reject and ask for resubmission (preferred)
+
+The maintainer closes the PR with a link to this guide and asks you to
+resubmit as properly decomposed PRs with validation methods.
+
+**Your credit:** the PR is entirely yours, including the **"Merged"** badge
+after resubmission.
+
+### Option B — Cherry-pick the valuable parts (last resort)
+
+If part of your PR is clearly valuable and worth saving, the maintainer runs
+`git cherry-pick` on those commits into `main` directly and closes the
+original PR.
+
+**Your credit:**
+- `git cherry-pick` preserves the original author, so `git log` and
+  `git blame` still show you as author of those lines.
+- The maintainer's reconcile commit message carries a
+  `Co-authored-by: <you> <your-email>` trailer, which counts toward your
+  GitHub contribution graph.
+- **However, the original PR shows as "Closed" instead of "Merged"**.