mad-cli 0.4.0__tar.gz

mad_cli-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,98 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality:
+    name: Lint + typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: ruff check + format
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: mypy (strict on mad_cli.core)
+        run: mypy
+
+  test:
+    name: Test + coverage
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: Unit tests + coverage on mad_cli.core
+        run: pytest -q tests/unit --cov=mad_cli.core --cov-report=term-missing --cov-fail-under=90
+
+      - name: Full suite
+        run: pytest -q
+
+  audit:
+    name: Dependency vulnerability audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: pip-audit
+        run: pip-audit --strict --skip-editable .
+
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    needs: [quality, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip build twine
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Verify artifacts with twine
+        run: python -m twine check dist/*

mad_cli-0.4.0/.github/workflows/docs-sync.yml

@@ -0,0 +1,21 @@
+name: Docs sync → mad-docs /raw
+
+# Thin caller for the shared reusable workflow in mad-core/.github.
+# After merge to main, mirrors this repo's /docs tree verbatim into
+# mad-core/mad-docs under raw/<service_slug>/ via a correlated PR.
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  docs-sync:
+    uses: mad-core/.github/.github/workflows/docs-sync.reusable.yml@main
+    with:
+      service_slug: mad-cli
+    secrets:
+      DOCS_SYNC_TOKEN: ${{ secrets.DOCS_SYNC_TOKEN }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

mad_cli-0.4.0/.github/workflows/docs-validate.yml

@@ -0,0 +1,19 @@
+name: Docs validate
+
+# Thin caller for the shared reusable workflow in mad-core/.github.
+# The trigger lives here; the docs structure linter lives in the reusable.
+# Lint-only gate — docs are NOT auto-generated in CI (update /docs locally
+# via the living-docs skill/commands).
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  docs-validate:
+    uses: mad-core/.github/.github/workflows/docs-validate.reusable.yml@main
+    with:
+      service_slug: mad-cli

mad_cli-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,129 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    # Path-gate the release trigger: bytes that never reach a PyPI consumer
+    # (docs, tests, CI workflows themselves, CLAUDE.md) must not move the
+    # version. See CLAUDE.md hard rule on package-centric versioning.
+    paths:
+      - "src/mad_cli/**"
+      - "pyproject.toml"
+      - "README.md"
+      - "LICENSE"
+  workflow_dispatch:
+    inputs:
+      manual_publish:
+        description: "Build current tree and publish to PyPI (skips semantic-release)"
+        type: boolean
+        default: false
+      release_kind:
+        description: "Bump kind for the semantic-release run (auto = derive from commits)"
+        type: choice
+        default: auto
+        options:
+          - auto
+          - minor
+          - major
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  manual-publish-pypi:
+    name: Manual publish to PyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.manual_publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mad-cli
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    name: Semantic release
+    # Run on every push to `main` that touches a version-relevant path (above),
+    # and on `workflow_dispatch` whenever the operator did NOT pick the
+    # `manual_publish` escape hatch (that path goes through `manual-publish-pypi`).
+    if: |
+      github.event_name == 'push'
+      || (github.event_name == 'workflow_dispatch' && !inputs.manual_publish)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.semrel.outputs.released }}
+      version: ${{ steps.semrel.outputs.version }}
+      tag: ${{ steps.semrel.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: Run pytest
+        run: pytest -q
+
+      - name: Python semantic release
+        id: semrel
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # `release_kind` only exists on `workflow_dispatch`; on `push` the
+          # expression evaluates to '' and `force` is a no-op (auto behavior).
+          # `auto` is also mapped to '' so the operator can pick it explicitly.
+          force: >-
+            ${{ (github.event_name == 'workflow_dispatch' && inputs.release_kind != 'auto')
+                && inputs.release_kind || '' }}
+
+      - name: Upload dist artifacts
+        if: steps.semrel.outputs.released == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mad-cli
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mad_cli-0.4.0/.github/workflows/testpypi-preview.yml

@@ -0,0 +1,195 @@
+name: TestPyPI preview
+
+# Publishes a pre-release (PEP 440 `.dev` version) of mad-cli to TestPyPI for
+# every PR against `main`, so the *exact built artifact* can be installed with
+# pip before it ever reaches the real index.
+#
+# Why a published round-trip and not just `pip install -e .`: packaging bugs
+# only manifest in the BUILT sdist/wheel — installing from an editable checkout
+# or `git+https://…@branch` rebuilds from the source tree and silently masks
+# them. The only faithful check is build → publish → install-from-index → import.
+#
+# ── One-time setup (until done, only `build` runs and it is always green) ──
+#   1. Create an account on https://test.pypi.org.
+#   2. Register a Trusted Publisher (a "pending publisher") for project
+#      `mad-cli` at https://test.pypi.org/manage/account/publishing/ with:
+#        Owner: mad-core   Repository: mad-cli
+#        Workflow name: testpypi-preview.yml   Environment: testpypi
+#   3. Create a GitHub Environment named `testpypi`
+#      (repo Settings → Environments → New environment).
+#   4. Set the repository variable TESTPYPI_ENABLED=true
+#      (Settings → Secrets and variables → Actions → Variables).
+#      Flip it to anything else to disable publishing without deleting the file.
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  # One in-flight preview per PR; a new push cancels the previous build so we
+  # don't waste a TestPyPI version number on a superseded commit.
+  group: testpypi-preview-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build preview (dev version)
+    # Trusted Publishing mints the publish token from the repo's own OIDC
+    # identity, which fork PRs never receive — and we would never want to hand
+    # publish rights to fork-authored code anyway. Skip the whole preview for
+    # forks; same-repo branches and manual runs proceed.
+    if: >-
+      github.event_name == 'workflow_dispatch'
+      || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Derive a unique PEP 440 dev version
+        id: version
+        # `<base>.dev<run_id>`: run_id is globally unique and monotonic, so
+        # re-runs and concurrent PRs never collide on TestPyPI's immutable
+        # version namespace. The edit is ephemeral (never committed).
+        run: |
+          python - <<'PY' >> "$GITHUB_OUTPUT"
+          import os, pathlib, re
+
+          run_id = os.environ["GITHUB_RUN_ID"]
+          pp = pathlib.Path("pyproject.toml")
+          text = pp.read_text()
+          base = re.search(r'^version = "([^"]+)"', text, re.M).group(1)
+          dev = f"{base}.dev{run_id}"
+          pp.write_text(
+              re.sub(r'^version = "[^"]+"', f'version = "{dev}"', text, count=1, flags=re.M)
+          )
+
+          init = pathlib.Path("src/mad_cli/__init__.py")
+          init.write_text(
+              re.sub(r'__version__ = "[^"]+"', f'__version__ = "{dev}"', init.read_text(), count=1)
+          )
+
+          print(f"version={dev}")
+          PY
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: testpypi-dist
+          path: dist/
+
+  publish:
+    name: Publish to TestPyPI
+    needs: build
+    # Gated on the operator opt-in variable so this PR (and any PR opened before
+    # the TestPyPI publisher is configured) stays green: no variable → no
+    # publish attempt, just the build above.
+    if: vars.TESTPYPI_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/mad-cli
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: testpypi-dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  verify:
+    name: Verify pip install from TestPyPI
+    needs: [build, publish]
+    if: vars.TESTPYPI_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install the published preview in a clean venv and import it
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        # Resolve the exact wheel URL from TestPyPI's JSON API and install THAT
+        # url, so pip pulls mad-cli from TestPyPI but every dependency from the
+        # default index (real PyPI). Pointing pip's --index-url at TestPyPI for
+        # the whole resolution is unsafe: TestPyPI hosts junk squats that shadow
+        # real deps by version number and break the install. Retry because
+        # TestPyPI indexing lags the upload.
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/v
+          wheel_url=""
+          for i in $(seq 1 12); do
+            wheel_url=$(curl -fsS "https://test.pypi.org/pypi/mad-cli/${VERSION}/json" 2>/dev/null \
+              | jq -r 'first(.urls[] | select(.packagetype=="bdist_wheel") | .url) // empty' || true)
+            [ -n "$wheel_url" ] && break
+            echo "attempt $i: ${VERSION} not on TestPyPI yet, waiting…"
+            sleep 15
+          done
+          if [ -z "$wheel_url" ]; then
+            echo "::error::wheel for mad-cli==${VERSION} never appeared on TestPyPI"
+            exit 1
+          fi
+          echo "Installing ${wheel_url} (dependencies resolve from real PyPI)"
+          /tmp/v/bin/pip install "$wheel_url"
+          # Smoke test: import the package and print its version. The console
+          # script's subcommands live on another branch, so we do NOT invoke it.
+          /tmp/v/bin/python -c "import mad_cli; print(mad_cli.__version__)"
+
+      - name: Upsert install instructions on the PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        with:
+          script: |
+            const version = process.env.VERSION;
+            const marker = '<!-- testpypi-preview -->';
+            const body = [
+              marker,
+              '📦 **TestPyPI preview published & verified**',
+              '',
+              "Install this PR's exact built artifact (deps resolve from real PyPI):",
+              '```bash',
+              'pip install "$(curl -s \\',
+              `  https://test.pypi.org/pypi/mad-cli/${version}/json \\`,
+              "  | jq -r 'first(.urls[] | select(.packagetype==\"bdist_wheel\") | .url)')\"",
+              '```',
+              '',
+              '_CI verified a clean-venv install imports `mad_cli` and reports its version._',
+            ].join('\n');
+            const { owner, repo } = context.repo;
+            const issue_number = context.issue.number;
+            // Upsert: update our previous comment if present, else create one,
+            // so repeated pushes refresh a single comment instead of spamming.
+            const existing = await github.paginate(github.rest.issues.listComments, {
+              owner, repo, issue_number,
+            });
+            const mine = existing.find((c) => c.body && c.body.includes(marker));
+            if (mine) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: mine.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+            }

mad_cli-0.4.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store