mars-agents 0.0.3__tar.gz

mars_agents-0.0.3/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check:
+    name: Check (${{ matrix.rust }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        rust: [stable, nightly]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.rust }}
+          components: rustfmt, clippy
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Build
+        run: cargo build
+
+      - name: Test
+        run: cargo test
+
+      - name: Clippy
+        run: cargo clippy -- -D warnings
+
+      - name: Format check
+        run: cargo fmt --check

mars_agents-0.0.3/.github/workflows/release.yml

@@ -0,0 +1,270 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: Build (${{ matrix.target }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            runner: ubuntu-latest
+            artifact: mars-linux-x64
+          - target: aarch64-unknown-linux-gnu
+            runner: ubuntu-latest
+            artifact: mars-linux-arm64
+          - target: aarch64-apple-darwin
+            runner: macos-latest
+            artifact: mars-darwin-arm64
+          - target: x86_64-apple-darwin
+            runner: macos-15-intel
+            artifact: mars-darwin-x64
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.target }}
+
+      - name: Install Linux ARM64 cross toolchain
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu
+
+      - name: Build
+        if: matrix.target != 'aarch64-unknown-linux-gnu'
+        run: cargo build --release --target ${{ matrix.target }}
+
+      - name: Build (Linux ARM64)
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+        run: cargo build --release --target ${{ matrix.target }}
+
+      - name: Strip binary
+        if: matrix.target != 'aarch64-unknown-linux-gnu'
+        run: strip target/${{ matrix.target }}/release/mars
+
+      - name: Strip binary (Linux ARM64)
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        run: aarch64-linux-gnu-strip target/${{ matrix.target }}/release/mars
+
+      - name: Rename binary
+        run: cp target/${{ matrix.target }}/release/mars ${{ matrix.artifact }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: ${{ matrix.artifact }}
+
+  pypi-wheels:
+    name: Build PyPI wheels (${{ matrix.target }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            runner: ubuntu-latest
+            artifact: wheels-linux-x64
+          - target: aarch64-unknown-linux-gnu
+            runner: ubuntu-24.04-arm
+            artifact: wheels-linux-arm64
+          - target: aarch64-apple-darwin
+            runner: macos-latest
+            artifact: wheels-darwin-arm64
+          - target: x86_64-apple-darwin
+            runner: macos-15-intel
+            artifact: wheels-darwin-x64
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          target: ${{ matrix.target }}
+          manylinux: auto
+          args: --release --out dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/*.whl
+
+  pypi-sdist:
+    name: Build PyPI sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  pypi-publish:
+    name: Publish PyPI
+    needs: [pypi-wheels, pypi-sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: wheels-*
+          merge-multiple: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          name: sdist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+  github-release:
+    name: GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts/
+          merge-multiple: true
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: artifacts/mars-*
+
+  npm-publish:
+    name: Publish npm packages
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Ensure npm supports trusted publishing
+        run: npm install -g npm@latest
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts/
+          pattern: mars-*
+          merge-multiple: true
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify tag matches Cargo.toml
+        run: |
+          CARGO_VERSION=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          TAG_VERSION=${{ steps.version.outputs.version }}
+          if [ "$CARGO_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match Cargo.toml ($CARGO_VERSION)"
+            exit 1
+          fi
+
+      - name: Prepare and publish platform packages
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+
+          publish_platform() {
+            local pkg_dir=$1
+            local binary=$2
+            local pkg_name
+            pkg_name=$(node -e "console.log(require('./$pkg_dir/package.json').name)")
+
+            # Skip if already published (idempotent on re-run)
+            if npm view "$pkg_name@$VERSION" version >/dev/null 2>&1; then
+              echo "Skipping $pkg_name@$VERSION — already published"
+              return 0
+            fi
+
+            (
+              cd "$pkg_dir"
+              npm version "$VERSION" --no-git-tag-version --allow-same-version
+              cp "$GITHUB_WORKSPACE/artifacts/$binary" mars
+              chmod +x mars
+              npm publish --provenance --access public
+            )
+          }
+
+          publish_platform npm/@haowjy/mars-agents-linux-x64 mars-linux-x64
+          publish_platform npm/@haowjy/mars-agents-linux-arm64 mars-linux-arm64
+          publish_platform npm/@haowjy/mars-agents-darwin-arm64 mars-darwin-arm64
+          publish_platform npm/@haowjy/mars-agents-darwin-x64 mars-darwin-x64
+
+      - name: Publish CLI stub package
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+
+          # Skip if already published
+          if npm view "@haowjy/mars-agents@$VERSION" version >/dev/null 2>&1; then
+            echo "Skipping @haowjy/mars-agents@$VERSION — already published"
+            exit 0
+          fi
+
+          (
+            cd npm/@haowjy/mars-agents
+            node -e "
+              const pkg = require('./package.json');
+              pkg.version = '$VERSION';
+              for (const dep of Object.keys(pkg.optionalDependencies || {})) {
+                pkg.optionalDependencies[dep] = '$VERSION';
+              }
+              require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+            "
+            npm publish --provenance --access public
+          )
+
+  cargo-publish:
+    name: Publish crate
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Publish to crates.io
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish || true

mars_agents-0.0.3/.gitignore

@@ -0,0 +1,6 @@
+# Rust build artifacts
+/target/
+
+# Project-local directories (managed by other tools)
+.meridian/
+.agents/

mars_agents-0.0.3/AGENTS.md

@@ -0,0 +1,152 @@
+# Development Guide: mars-agents
+
+Mars is an agent package manager for `.agents/` directories. It installs agent profiles and skills from git/local sources, tracks ownership in `mars.lock`, and links managed content into tool directories like `.claude/`.
+
+## Core Principles
+
+1. **Resolve first, then act.** Validate + build full desired state before mutating files. If any conflict or error is detected during resolution, zero mutations occur.
+   - *Why*: Partial failures leave users in states that are hard to diagnose. A user who sees "3 conflicts" can fix all three and retry. A user whose command half-completed has to figure out what happened first.
+
+2. **Atomic writes.** Config, lock, and installed files use temp + rename. Crash mid-write leaves the old file intact.
+   - *Why*: Mars manages files that agents and tools read continuously. A half-written mars.toml breaks every tool that reads it. tmp + rename is atomic on POSIX — no recovery logic needed.
+
+3. **Lock file is authority.** `mars.lock` defines managed ownership and checksums. If it's not in the lock, it's not managed.
+   - *Why*: Without a single authority, mars can't distinguish "user added this manually" from "mars installed this." The lock makes ownership explicit — safe coexistence with unmanaged files.
+
+4. **No heuristics.** User intent is expressed through explicit flags and arguments, not inferred from string patterns.
+   - *Why*: The dot-prefix heuristic (`starts_with('.')`) classified `./my-project` as a target dir — a real bug caught by reviewers. Explicit arguments are boring but predictable, and predictable tools earn trust.
+
+## Managed Layout
+
+```text
+project/
+  .agents/                   # managed root (default)
+    mars.toml               # desired sources + settings
+    mars.lock               # generated lock/ownership/provenance
+    mars.local.toml         # local overrides (gitignored)
+    .mars/                  # internal state (sync.lock, cache)
+    agents/                 # installed agent profiles
+    skills/                 # installed skills
+  .claude/                   # optional linked tool dir
+    agents -> ../.agents/agents
+    skills -> ../.agents/skills
+```
+
+## MarsContext Invariant
+
+`src/cli/mod.rs` defines:
+
+- `MarsContext { managed_root, project_root }`
+- Invariant enforced by `MarsContext::new`: managed root must be a subdirectory and therefore has a parent.
+- `project_root` is always `managed_root.parent()` (canonicalized when possible).
+
+This invariant is relied on by local-path resolution and link-target resolution.
+
+## CLI Surface
+
+### Global flags
+
+| Flag | Meaning |
+|---|---|
+| `--root <PATH>` | Use this managed root instead of auto-discovery. |
+| `--json` | Machine-readable output. |
+
+### Commands
+
+| Command | Purpose |
+|---|---|
+| `mars init [TARGET]` | Initialize managed root with `mars.toml` (optional `--link`). |
+| `mars add <source>` | Add/update source, then sync. |
+| `mars remove <source>` | Remove source, then prune managed items. |
+| `mars sync` | Resolve + install to match config (`--force`, `--diff`, `--frozen`). |
+| `mars upgrade [sources...]` | Maximize versions for all or selected sources. |
+| `mars outdated` | Show available updates without applying changes. |
+| `mars list` | List managed agents/skills (`--status` for checksum state). |
+| `mars why <name>` | Explain source/provenance for an installed item. |
+| `mars rename <from> <to>` | Add rename rule and sync to apply it. |
+| `mars resolve [file]` | Mark conflicts resolved by updating installed checksums. |
+| `mars override <source> --path <PATH>` | Set local dev override in `mars.local.toml`. |
+| `mars link <target>` | Link managed `agents/` + `skills/` into tool dir (`--unlink`, `--force`). |
+| `mars check [path]` | Validate a source package (structure/frontmatter/deps). |
+| `mars doctor` | Validate config/lock/filesystem/link/dependency health. |
+| `mars repair` | Force rebuild from config/sources (corrupt-lock recovery path). |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success (or clean report). |
+| `1` | Action needed: unresolved conflicts (sync) or validation errors (check). |
+| `2` | User/config/resolution/validation/link/frozen errors. |
+| `3` | Source fetch, I/O, HTTP, or git command errors. |
+
+## Sync Pipeline
+
+Sync is orchestrated in `src/sync/mod.rs` under `.mars/sync.lock`:
+
+1. Load config + local overrides; apply optional mutation.
+2. Resolve graph (versions, deps, source identities).
+3. Build target state.
+4. Compute diff.
+5. Create plan.
+6. Apply plan.
+7. Write new `mars.lock`.
+
+Core apply chain: `target -> diff -> plan -> apply`.
+
+## Source Fetching
+
+- GitHub HTTPS sources: archive download (`/archive/<sha>.tar.gz`) into global cache.
+- SSH / non-GitHub HTTPS git sources: `git clone`/`git fetch` + checkout.
+- Local path sources: canonicalized filesystem paths, read directly (no copy cache).
+
+Global cache root: `~/.mars/cache` (override with `MARS_CACHE_DIR`).
+
+## Key Modules
+
+| Module | Responsibility |
+|---|---|
+| `src/cli/` | Clap args, root discovery, command dispatch, output formatting. |
+| `src/config/` | `mars.toml` + `mars.local.toml` schemas, load/save, merge to effective config. |
+| `src/lock/` | `mars.lock` schema, load/write, lock rebuild from apply outcomes. |
+| `src/sync/` | End-to-end sync orchestration + `target/diff/plan/apply`. |
+| `src/resolve/` | Dependency + version resolution and graph ordering. |
+| `src/source/` | Source parsing/fetching (git + path) and global cache handling. |
+| `src/discover/` | Discover agents/skills by filesystem conventions. |
+| `src/validate/` | Agent-to-skill dependency validation. |
+| `src/merge/` | Three-way merge/conflict handling. |
+| `src/fs/` | Atomic writes/installs and advisory file lock (`flock`). |
+| `src/frontmatter/` | YAML frontmatter parsing for agent/skill metadata. |
+| `src/manifest/` | Optional per-source `mars.toml` manifest loading. |
+| `src/hash/` | SHA-256 hashing for files/directories. |
+| `src/types.rs` | Typed identifiers/newtypes used across modules. |
+
+## Dev Workflow
+
+```bash
+cargo build
+cargo test
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+```
+
+Notes:
+
+- Integration coverage is under `tests/` (CLI-level behavior).
+- Prefer keeping changes localized to one module/command path when adding features.
+
+## Releasing
+
+```bash
+./scripts/release.sh patch --push    # 0.0.1 → 0.0.2, push to trigger CI
+./scripts/release.sh minor --push    # 0.0.2 → 0.1.0
+./scripts/release.sh 1.0.0 --push    # explicit version
+./scripts/release.sh patch --dry     # run checks only, don't tag
+```
+
+The release script runs pre-release checks (fmt, clippy, tests, release build, version consistency between Cargo.toml and pyproject.toml), bumps both files, commits, tags, and optionally pushes. The `v*` tag triggers GitHub Actions to build platform wheels and publish to PyPI, npm, and crates.io.
+
+Prerequisites for first release:
+- Set up trusted publisher on PyPI (repo: `haowjy/mars-agents`, workflow: `release.yml`, environment: `pypi`)
+- Create `pypi` environment in GitHub repo settings
+- `NPM_TOKEN` and `CARGO_REGISTRY_TOKEN` secrets already configured

mars_agents-0.0.3/CLAUDE.md

@@ -0,0 +1,152 @@
+# Development Guide: mars-agents
+
+Mars is an agent package manager for `.agents/` directories. It installs agent profiles and skills from git/local sources, tracks ownership in `mars.lock`, and links managed content into tool directories like `.claude/`.
+
+## Core Principles
+
+1. **Resolve first, then act.** Validate + build full desired state before mutating files. If any conflict or error is detected during resolution, zero mutations occur.
+   - *Why*: Partial failures leave users in states that are hard to diagnose. A user who sees "3 conflicts" can fix all three and retry. A user whose command half-completed has to figure out what happened first.
+
+2. **Atomic writes.** Config, lock, and installed files use temp + rename. Crash mid-write leaves the old file intact.
+   - *Why*: Mars manages files that agents and tools read continuously. A half-written mars.toml breaks every tool that reads it. tmp + rename is atomic on POSIX — no recovery logic needed.
+
+3. **Lock file is authority.** `mars.lock` defines managed ownership and checksums. If it's not in the lock, it's not managed.
+   - *Why*: Without a single authority, mars can't distinguish "user added this manually" from "mars installed this." The lock makes ownership explicit — safe coexistence with unmanaged files.
+
+4. **No heuristics.** User intent is expressed through explicit flags and arguments, not inferred from string patterns.
+   - *Why*: The dot-prefix heuristic (`starts_with('.')`) classified `./my-project` as a target dir — a real bug caught by reviewers. Explicit arguments are boring but predictable, and predictable tools earn trust.
+
+## Managed Layout
+
+```text
+project/
+  .agents/                   # managed root (default)
+    mars.toml               # desired sources + settings
+    mars.lock               # generated lock/ownership/provenance
+    mars.local.toml         # local overrides (gitignored)
+    .mars/                  # internal state (sync.lock, cache)
+    agents/                 # installed agent profiles
+    skills/                 # installed skills
+  .claude/                   # optional linked tool dir
+    agents -> ../.agents/agents
+    skills -> ../.agents/skills
+```
+
+## MarsContext Invariant
+
+`src/cli/mod.rs` defines:
+
+- `MarsContext { managed_root, project_root }`
+- Invariant enforced by `MarsContext::new`: managed root must be a subdirectory and therefore has a parent.
+- `project_root` is always `managed_root.parent()` (canonicalized when possible).
+
+This invariant is relied on by local-path resolution and link-target resolution.
+
+## CLI Surface
+
+### Global flags
+
+| Flag | Meaning |
+|---|---|
+| `--root <PATH>` | Use this managed root instead of auto-discovery. |
+| `--json` | Machine-readable output. |
+
+### Commands
+
+| Command | Purpose |
+|---|---|
+| `mars init [TARGET]` | Initialize managed root with `mars.toml` (optional `--link`). |
+| `mars add <source>` | Add/update source, then sync. |
+| `mars remove <source>` | Remove source, then prune managed items. |
+| `mars sync` | Resolve + install to match config (`--force`, `--diff`, `--frozen`). |
+| `mars upgrade [sources...]` | Maximize versions for all or selected sources. |
+| `mars outdated` | Show available updates without applying changes. |
+| `mars list` | List managed agents/skills (`--status` for checksum state). |
+| `mars why <name>` | Explain source/provenance for an installed item. |
+| `mars rename <from> <to>` | Add rename rule and sync to apply it. |
+| `mars resolve [file]` | Mark conflicts resolved by updating installed checksums. |
+| `mars override <source> --path <PATH>` | Set local dev override in `mars.local.toml`. |
+| `mars link <target>` | Link managed `agents/` + `skills/` into tool dir (`--unlink`, `--force`). |
+| `mars check [path]` | Validate a source package (structure/frontmatter/deps). |
+| `mars doctor` | Validate config/lock/filesystem/link/dependency health. |
+| `mars repair` | Force rebuild from config/sources (corrupt-lock recovery path). |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success (or clean report). |
+| `1` | Action needed: unresolved conflicts (sync) or validation errors (check). |
+| `2` | User/config/resolution/validation/link/frozen errors. |
+| `3` | Source fetch, I/O, HTTP, or git command errors. |
+
+## Sync Pipeline
+
+Sync is orchestrated in `src/sync/mod.rs` under `.mars/sync.lock`:
+
+1. Load config + local overrides; apply optional mutation.
+2. Resolve graph (versions, deps, source identities).
+3. Build target state.
+4. Compute diff.
+5. Create plan.
+6. Apply plan.
+7. Write new `mars.lock`.
+
+Core apply chain: `target -> diff -> plan -> apply`.
+
+## Source Fetching
+
+- GitHub HTTPS sources: archive download (`/archive/<sha>.tar.gz`) into global cache.
+- SSH / non-GitHub HTTPS git sources: `git clone`/`git fetch` + checkout.
+- Local path sources: canonicalized filesystem paths, read directly (no copy cache).
+
+Global cache root: `~/.mars/cache` (override with `MARS_CACHE_DIR`).
+
+## Key Modules
+
+| Module | Responsibility |
+|---|---|
+| `src/cli/` | Clap args, root discovery, command dispatch, output formatting. |
+| `src/config/` | `mars.toml` + `mars.local.toml` schemas, load/save, merge to effective config. |
+| `src/lock/` | `mars.lock` schema, load/write, lock rebuild from apply outcomes. |
+| `src/sync/` | End-to-end sync orchestration + `target/diff/plan/apply`. |
+| `src/resolve/` | Dependency + version resolution and graph ordering. |
+| `src/source/` | Source parsing/fetching (git + path) and global cache handling. |
+| `src/discover/` | Discover agents/skills by filesystem conventions. |
+| `src/validate/` | Agent-to-skill dependency validation. |
+| `src/merge/` | Three-way merge/conflict handling. |
+| `src/fs/` | Atomic writes/installs and advisory file lock (`flock`). |
+| `src/frontmatter/` | YAML frontmatter parsing for agent/skill metadata. |
+| `src/manifest/` | Optional per-source `mars.toml` manifest loading. |
+| `src/hash/` | SHA-256 hashing for files/directories. |
+| `src/types.rs` | Typed identifiers/newtypes used across modules. |
+
+## Dev Workflow
+
+```bash
+cargo build
+cargo test
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+```
+
+Notes:
+
+- Integration coverage is under `tests/` (CLI-level behavior).
+- Prefer keeping changes localized to one module/command path when adding features.
+
+## Releasing
+
+```bash
+./scripts/release.sh patch --push    # 0.0.1 → 0.0.2, push to trigger CI
+./scripts/release.sh minor --push    # 0.0.2 → 0.1.0
+./scripts/release.sh 1.0.0 --push    # explicit version
+./scripts/release.sh patch --dry     # run checks only, don't tag
+```
+
+The release script runs pre-release checks (fmt, clippy, tests, release build, version consistency between Cargo.toml and pyproject.toml), bumps both files, commits, tags, and optionally pushes. The `v*` tag triggers GitHub Actions to build platform wheels and publish to PyPI, npm, and crates.io.
+
+Prerequisites for first release:
+- Set up trusted publisher on PyPI (repo: `haowjy/mars-agents`, workflow: `release.yml`, environment: `pypi`)
+- Create `pypi` environment in GitHub repo settings
+- `NPM_TOKEN` and `CARGO_REGISTRY_TOKEN` secrets already configured