apmw 0.1.0__tar.gz

apmw-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,119 @@
+name: Publish apmw
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  determine-version:
+    name: Determine Version
+    runs-on: ubuntu-latest
+    outputs:
+      semver: ${{ steps.version.outputs.semver }}
+      python-version: ${{ steps.version.outputs.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Determine version
+        id: version
+        uses: GravionLabs/ci/versioning/determine-version@main
+        with:
+          gitversion-config-file: GitVersion.yml
+
+  build-test:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    needs: determine-version
+    steps:
+      - name: Build
+        uses: GravionLabs/ci/python/build@main
+        with:
+          version: ${{ needs.determine-version.outputs.python-version }}
+
+      - name: Test
+        uses: GravionLabs/ci/python/test@main
+
+  build-executables:
+    name: Build executable (${{ matrix.suffix }})
+    runs-on: ${{ matrix.os }}
+    needs: determine-version
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            suffix: linux
+          - os: macos-latest
+            suffix: macos-arm64
+          - os: windows-latest
+            suffix: windows.exe
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python (uv)
+        uses: GravionLabs/ci/python/setup@main
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build executable
+        run: uv run --with pyinstaller pyinstaller --onefile --name apmw-${{ matrix.suffix }} scripts/apmw_entrypoint.py
+
+      - name: Upload executable artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: apmw-${{ matrix.suffix }}
+          path: dist/apmw-${{ matrix.suffix }}
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    needs:
+      - determine-version
+      - build-test
+    steps:
+      - name: Publish Python package
+        uses: GravionLabs/ci/python/pypi/publish@main
+        with:
+          download-artifact: 'true'
+
+  release:
+    name: Release
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    needs:
+      - determine-version
+      - publish
+      - build-executables
+    permissions:
+      contents: write
+    steps:
+      - name: Create GitHub Release
+        uses: GravionLabs/ci/versioning/gh-release@main
+        with:
+          version: ${{ needs.determine-version.outputs.semver }}
+          tag-prefix: v
+
+      - name: Download executable artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: apmw-*
+          path: executables
+          merge-multiple: true
+
+      - name: Attach executables to release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="v${{ needs.determine-version.outputs.semver }}"
+          gh release upload "$TAG" executables/* --clobber

apmw-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.spec
+.venv/
+.pytest_cache/
+.coverage
+coverage.xml

apmw-0.1.0/AGENTS.md

@@ -0,0 +1,50 @@
+# apmw
+
+Cross-platform wrapper CLI for [apm](https://github.com/GravionLabs). `apm install`/`apm update`
+deploy platform-neutral skills cleanly, but agent files carry platform-specific frontmatter
+(`permission`, `mode`, `tools`, `model`, etc.) that each target — Claude Code, OpenCode, GitHub
+Copilot, Cursor, Codex — interprets differently. `apmw` runs the real `apm` command and then
+strips/rewrites the installed agent frontmatter for the target platform. `apmw sanitize` exposes
+the stripping step standalone, for re-sanitizing an already-installed agent directory without
+invoking `apm` at all.
+
+## Repo layout
+
+- `src/apmw/__init__.py` — the entire package: argument parsing, sanitization logic, and `apm`
+  subprocess invocation all live in this single file.
+- `src/apmw/data/agent-strip-fields.json` — per-platform list of frontmatter fields to strip.
+  **Must be kept in sync with `apm-hub`'s `config/agent-strip-fields.json`** (used by
+  `src/generators/agent-target-generator.ts` there) — there is no automated sync, update both by
+  hand when the set of fields per platform changes.
+- `tests/test_sanitize.py` — unit tests for the frontmatter-stripping logic (`sanitize_installed`,
+  `strip_fields`, `add_permission_block`).
+- `tests/test_cli.py` — CLI-level tests: argument parsing and `main()` dispatch.
+
+## Key concepts
+
+- `TARGET_DIRS` — local (CWD-relative) agent install dir per platform, e.g. `claude` → `.claude`.
+- `GLOBAL_PATHS` — per-OS global agent install dirs per platform, used when `-g/--global` is passed.
+- `TARGET_STRIP_FIELDS` — loaded from `agent-strip-fields.json`; which frontmatter keys to drop
+  per platform.
+- `do_sanitize(platform, global_, source)` — the core operation: sanitizes either the local or
+  global agent dir for a platform, optionally also sanitizing source files under `packages/`.
+- `sanitize_installed` / `sanitize_source` — the actual file-rewriting functions `do_sanitize`
+  calls.
+- Subcommands (`build_parser()` in `src/apmw/__init__.py`): `install` and `update` run the real
+  `apm` binary via `run_apm()` and then call `do_sanitize()`; `sanitize` calls `do_sanitize()`
+  directly with no `apm` invocation.
+
+## Dev workflow
+
+```bash
+uv sync
+uv run pytest
+```
+
+No linter or formatter is configured in `pyproject.toml` — don't introduce one speculatively.
+
+## Style
+
+The codebase has no docstrings and minimal comments (only where a non-obvious rationale needs
+capturing, e.g. the `claude` strip-fields comment). Keep additions flat and terse — match what's
+already there rather than adding documentation blocks.

apmw-0.1.0/GitVersion.yml

@@ -0,0 +1,2 @@
+mode: ContinuousDeployment
+next-version: 0.1.0

apmw-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.5
+Name: apmw
+Version: 0.1.0
+Summary: Cross-platform wrapper for the apm CLI — sanitizes agent frontmatter per target
+Requires-Python: >=3.10

apmw-0.1.0/README.md

@@ -0,0 +1,308 @@
+# apmw
+
+Cross-platform wrapper for the [apm](https://github.com/GravionLabs) CLI.
+
+`apm install` and `apm update` deploy platform-neutral skills cleanly, but
+agent files carry platform-specific frontmatter (`permission`, `mode`,
+`tools`, etc.) that each target — Claude Code, OpenCode, GitHub Copilot,
+Cursor, Codex — interprets differently. `apmw` runs the real `apm` command
+and then sanitizes the installed agent frontmatter for the target platform
+you specify.
+
+---
+
+## Install
+
+```bash
+pipx install apmw
+# or
+uvx apmw install -p claude
+```
+
+Prebuilt single-file executables (linux, macOS-arm64, windows) that need no Python environment
+are attached to each [GitHub Release](https://github.com/GravionLabs/apmw/releases).
+
+### Local development install
+
+To install the local checkout (editable — picks up source edits immediately):
+
+```bash
+./install.sh       # Linux / macOS
+.\install.ps1      # Windows
+```
+
+Uses `uv tool install` if `uv` is on `PATH`, falling back to `pipx`.
+
+---
+
+## Usage
+
+```bash
+apmw install -p claude      # apm install + sanitize for Claude Code
+apmw install -p opencode    # apm install + sanitize for OpenCode
+apmw update  -p copilot     # apm update + sanitize for GitHub Copilot
+apmw sanitize -p claude     # sanitize an already-installed local agent dir (no apm call)
+apmw sanitize -g -p claude  # sanitize the global Claude Code agent dir
+apmw sanitize               # sanitize for every known platform
+```
+
+**Flags:**
+
+| Flag | Description |
+| :--- | :---------- |
+| `-p, --platform` | Target: `opencode`, `copilot`, `claude`, `cursor`, `codex`; omit to run for all |
+| `-g, --global` | Sanitize the platform's global agent install directory instead of the project dir |
+| `-s, --source` | Also inject `permission:` blocks into source agent files under `packages/` |
+| `-y, --yes` | (`update` only) Skip consent prompt |
+| `--dry-run` | (`update` only) Preview changes without writing |
+
+`apmw install`/`update` require `apm` to be installed and on `PATH`.  
+`apmw sanitize` operates only on local files and does not invoke `apm`.
+
+---
+
+## Global install — all packages
+
+Install the full apm-hub skill set into the global agent directories so every
+repository on the machine benefits without a per-project `apm install`:
+
+```bash
+# 1. Register the marketplace (once per machine)
+apm marketplace add GravionLabs/apm-hub
+
+# 2. Install the meta-package globally
+apmw install all@apm-hub -g -p opencode
+apmw install all@apm-hub -g -p claude
+apmw install all@apm-hub -g -p copilot
+```
+
+`apmw install` calls `apm install -g` (which deploys to global paths) and then
+sanitizes all agent files in those paths for the target platform.
+
+**Global agent paths per platform:**
+
+| Platform       | Linux / macOS                                    | Windows                                     |
+| :------------- | :----------------------------------------------- | :------------------------------------------ |
+| OpenCode       | `~/.config/opencode/agents/`                     | `%APPDATA%\opencode\agents\`                |
+| Claude Code    | `~/.claude/agents/` · `~/.config/claude/agents/` | `%APPDATA%\Claude\agents\`                  |
+| GitHub Copilot | `~/.config/github-copilot/agents/`               | `%APPDATA%\GitHub Copilot\agents\`          |
+| Cursor         | `~/.cursor/agents/`                              | `%APPDATA%\Cursor\agents\`                  |
+| Codex          | `~/.codex/agents/`                               | `%APPDATA%\Codex\agents\`                   |
+
+### Transitive MCP server definitions
+
+When a package declares MCP server entries in its `apm.yml`, `apm install`
+propagates those definitions to consuming projects transitively. For example,
+the `github` package may ship an MCP server configuration for the GitHub API:
+
+```yaml
+# packages/github/apm.yml
+name: github
+version: 1.0.0
+mcp:
+  servers:
+    - name: github
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-github"]
+      env:
+        GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
+```
+
+When you run `apmw install all@apm-hub -g -p opencode`, the `all` meta-package
+pulls in `github` (and every other package) transitively. `apm` writes the MCP
+server entries to the platform's agent config file (e.g.
+`~/.config/opencode/mcp.json`) so every project on the machine can use GitHub
+MCP tools without any per-project setup.
+
+---
+
+## Multi-target agent authoring
+
+Agent source files (`*.agent.md`) are written in **GitHub Copilot style** as
+the primary format. Each platform understands only a subset of frontmatter
+fields — `apmw` strips the incompatible ones and can also inject
+platform-specific additions via a reserved `metadata:` key.
+
+### Field compatibility
+
+| Field            | Copilot | OpenCode | Claude Code | Cursor / Codex |
+| :--------------- | :-----: | :------: | :---------: | :------------: |
+| `name`           |    ✅    |    ✅     |      ✅      |       ✅        |
+| `description`    |    ✅    |    ✅     |      ✅      |       ✅        |
+| `tools`          |    ✅    |    ❌     |      ✅ *    |       ✅        |
+| `mode`           |    ✅    |    ❌     |      ❌      |       ❌        |
+| `steps`          |    ✅    |    ❌     |      ❌      |       ❌        |
+| `color`          |    ✅    |    ❌     |      ❌      |       ❌        |
+| `permission`     |    ❌    |    ✅     |      ❌      |       ❌        |
+| `user-invocable` |    ✅    |    ❌     |      ❌      |       ❌        |
+| `model`          |    ✅    |    ✅     |      ❌      |       ✅        |
+| `agents`         |    ✅    |    ❌     |      ❌      |       ✅        |
+
+*Claude Code uses different tool identifiers than Copilot (`Bash` vs `run_in_terminal`, etc.).
+
+### `metadata:` — platform-specific overrides
+
+Add a `metadata:` block to supply fields that only apply to a specific
+platform. `apmw` extracts the block for the target platform, injects the
+lines into the sanitized frontmatter, and strips `metadata:` itself from all
+outputs. **Metadata wins on conflict** — if both the top level and
+`metadata.opencode` define `permission:`, the metadata version is used.
+
+```yaml
+---
+name: dev-workflow
+description: "Dev workflow orchestrator."
+# Copilot-native fields — kept as-is in the Copilot output
+mode: all
+steps: 40
+color: primary
+tools: ['agent', 'read', 'search']
+user-invocable: true
+# Platform-specific overrides (never appear in any output file)
+metadata:
+  opencode:
+    permission:
+      read: allow
+      edit: deny
+      glob: allow
+      grep: allow
+      bash:
+        "*": deny
+      task: allow
+      skill: allow
+      webfetch: allow
+      question: allow
+  claude:
+    tools:
+      - Bash
+      - Read
+      - Glob
+      - Grep
+      - WebFetch
+      - Task
+---
+
+Agent body — unchanged across all platforms.
+```
+
+### What each platform receives
+
+**`.github/agents/dev-workflow.agent.md`** — Copilot output (`metadata:` stripped, all else kept):
+```yaml
+---
+name: dev-workflow
+description: "Dev workflow orchestrator."
+mode: all
+steps: 40
+color: primary
+tools: ['agent', 'read', 'search']
+user-invocable: true
+---
+```
+
+**`.opencode/agents/dev-workflow.md`** — `permission:` injected from `metadata.opencode`; Copilot-only fields stripped by default:
+```yaml
+---
+name: dev-workflow
+description: "Dev workflow orchestrator."
+mode: all
+steps: 40
+color: primary
+permission:
+  read: allow
+  edit: deny
+  glob: allow
+  grep: allow
+  bash:
+    "*": deny
+  task: allow
+  skill: allow
+  webfetch: allow
+  question: allow
+---
+```
+
+**`.claude/agents/dev-workflow.md`** — Claude-native `tools:` injected from `metadata.claude`; all incompatible fields stripped:
+```yaml
+---
+name: dev-workflow
+description: "Dev workflow orchestrator."
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - WebFetch
+  - Task
+---
+```
+
+### Strip rules
+
+The strip rules are loaded from `src/apmw/data/agent-strip-fields.json` and
+must be kept in sync with `apm-hub`'s `config/agent-strip-fields.json`:
+
+```json
+{
+  "opencode":  ["tools", "user-invocable", "agents", "metadata"],
+  "copilot":   ["mode", "steps", "color", "permission", "task", "metadata"],
+  "claude":    ["mode", "steps", "color", "tools", "permission", "user-invocable", "agents", "model", "metadata"],
+  "cursor":    ["mode", "steps", "color", "permission", "metadata"],
+  "codex":     ["mode", "steps", "color", "permission", "metadata"]
+}
+```
+
+`metadata` appears in every platform's list — it is always stripped after extraction.
+
+### Processing pipeline
+
+For each `*.md` file in the target agent directory, `apmw` runs:
+
+1. **Extract** — find `metadata.<platform>` and de-indent its content lines.
+2. **Strip** — remove fields in the platform's strip list (including `metadata`).
+3. **Inject** — if step 1 produced lines: strip any conflicting top-level fields, then append the extracted lines. Metadata wins.
+4. **Rewrite** — write the file only if the frontmatter changed.
+
+### OpenCode `permission:` reference
+
+```yaml
+permission:
+  read: allow          # file read
+  edit: deny           # file write/edit
+  glob: allow          # file glob search
+  grep: allow          # content search
+  bash:
+    "*": deny          # deny all shell commands by default
+    "git *": allow     # allow specific patterns
+    "gh *": allow
+  task: allow          # spawn sub-agents
+  skill: allow         # load skills
+  webfetch: allow      # HTTP fetch
+  question: allow      # interactive prompts
+```
+
+### Claude Code `tools:` reference
+
+```yaml
+tools:
+  - Bash        # shell commands
+  - Read        # read files
+  - Write       # create/overwrite files
+  - Edit        # patch existing files
+  - Glob        # file pattern search
+  - Grep        # content search
+  - WebFetch    # HTTP fetch
+  - Task        # spawn sub-agents
+  - TodoWrite   # task list management
+```
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+No linter or formatter is configured — don't introduce one speculatively.

apmw-0.1.0/install.ps1

@@ -0,0 +1,13 @@
+$ErrorActionPreference = "Stop"
+$ScriptDir = $PSScriptRoot
+
+if (Get-Command uv -ErrorAction SilentlyContinue) {
+    uv tool install --editable $ScriptDir --force
+} elseif (Get-Command pipx -ErrorAction SilentlyContinue) {
+    pipx install --editable $ScriptDir --force
+} else {
+    Write-Error "neither 'uv' nor 'pipx' found on PATH"
+    exit 1
+}
+
+Write-Host "apmw installed — run 'apmw --help' to verify."

apmw-0.1.0/install.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if command -v uv >/dev/null 2>&1; then
+    uv tool install --editable "$SCRIPT_DIR" --force
+elif command -v pipx >/dev/null 2>&1; then
+    pipx install --editable "$SCRIPT_DIR" --force
+else
+    echo "error: neither 'uv' nor 'pipx' found on PATH" >&2
+    exit 1
+fi
+
+echo "apmw installed — run 'apmw --help' to verify."

apmw-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "apmw"
+version = "0.1.0"
+description = "Cross-platform wrapper for the apm CLI — sanitizes agent frontmatter per target"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+apmw = "apmw:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-cov>=5"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

apmw-0.1.0/scripts/apmw_entrypoint.py

@@ -0,0 +1,4 @@
+from apmw import main
+
+if __name__ == "__main__":
+    main()