netbox-super-cli 1.0.0__tar.gz

netbox_super_cli-1.0.0/.github/workflows/agents-md-sync.yml

@@ -0,0 +1,35 @@
+name: agents-md-sync
+
+on:
+  pull_request:
+    paths:
+      - "CLAUDE.md"
+      - "AGENTS.md"
+      - "scripts/sync_agents_md.py"
+      - ".github/workflows/agents-md-sync.yml"
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Sync deps
+        run: uv sync --frozen
+
+      - name: Check AGENTS.md is in sync with CLAUDE.md
+        run: uv run python scripts/sync_agents_md.py --check

netbox_super_cli-1.0.0/.github/workflows/bench.yml

@@ -0,0 +1,23 @@
+name: bench
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  startup-time:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - name: Install
+        run: uv sync --all-extras --dev
+      - name: Benchmark
+        run: NSC_BENCH=1 uv run pytest tests/benchmarks/ -v -s
+        continue-on-error: true
+      - name: Step summary
+        if: always()
+        run: |
+          echo "Bench job ran. See the previous step's stdout for the median timing." >> "$GITHUB_STEP_SUMMARY"

netbox_super_cli-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: docs
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "scripts/gen_docs.py"
+      - ".github/workflows/docs.yml"
+  push:
+    tags:
+      - "v*"
+
+# Permissions for the deploy job (idempotent on the build-only PR job).
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Only one in-flight deploy at a time; cancel queued ones.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Sync deps (runtime + docs)
+        run: uv sync --frozen --group docs
+      - name: Build site (strict)
+        run: uv run mkdocs build --strict
+      - name: Upload Pages artifact
+        if: github.ref_type == 'tag'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

netbox_super_cli-1.0.0/.github/workflows/e2e.yml

@@ -0,0 +1,42 @@
+name: e2e
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - 'nsc/http/**'
+      - 'nsc/cli/handlers.py'
+      - 'nsc/cli/registration.py'
+      - 'nsc/cli/writes/**'
+      - 'nsc/output/explain.py'
+      - 'nsc/output/errors.py'
+      - 'tests/e2e/**'
+      - '.github/workflows/e2e.yml'
+  workflow_dispatch:
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Start NetBox
+        run: docker compose -f tests/e2e/docker-compose.yml up -d
+      - name: Wait for NetBox
+        run: tests/e2e/wait_for_netbox.sh
+      - name: Run e2e tests
+        env:
+          NSC_E2E: '1'
+          NSC_URL: http://127.0.0.1:8080
+          NSC_TOKEN: '0123456789abcdef0123456789abcdef01234567'
+        run: uv run pytest tests/e2e/ -v
+      - name: Dump container logs on failure
+        if: failure()
+        run: docker compose -f tests/e2e/docker-compose.yml logs
+      - name: Stop NetBox
+        if: always()
+        run: docker compose -f tests/e2e/docker-compose.yml down -v

netbox_super_cli-1.0.0/.github/workflows/lint.yml

@@ -0,0 +1,56 @@
+name: lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Ruff check
+        run: uv run ruff check nsc tests scripts
+      - name: Ruff format
+        run: uv run ruff format --check nsc tests scripts
+      - name: Mypy strict
+        run: uv run mypy --strict nsc scripts
+
+  docs-reference-fresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Sync deps (runtime + docs — gen_docs needs both)
+        run: uv sync --frozen --group docs
+      - name: Verify auto-generated reference pages are up to date
+        run: uv run python scripts/gen_docs.py --check
+
+  agents-md-fresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Check AGENTS.md is in sync with CLAUDE.md
+        run: uv run python scripts/sync_agents_md.py --check

netbox_super_cli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,163 @@
+name: release
+
+# Tag-only trigger. NEVER on pull_request or branch push — the trusted
+# publisher is bound to this workflow filename + the v* tag pattern, so a
+# stray dispatch on main would either fail authentication (good) or, if
+# someone misconfigured PyPI, publish a bogus release (very bad).
+on:
+  push:
+    tags:
+      # Release versions: v<digit><anything>.<digit><anything>.<digit><anything>.
+      # GitHub's tag filter uses fnmatch (not regex), so the leading [0-9]
+      # excludes vfoobar / vNEXT entirely, but the unbounded `*` after each
+      # digit class also matches v1.0.0-rc1 and v1.0.0.1. Those slip through
+      # the trigger and are caught by the version-match step below — the
+      # filter narrows the obvious garbage; the version-match step is the
+      # actual gate.
+      - "v[0-9]*.[0-9]*.[0-9]*"
+
+# Trusted publishing requires id-token: write at the workflow level so the
+# OIDC token issued to pypa/gh-action-pypi-publish is signed.
+permissions:
+  contents: write   # gh release create
+  id-token: write   # PyPI trusted publishing OIDC
+
+# One in-flight release at a time; queue rather than cancel so a fast
+# re-tag never overlaps the previous publish.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # PyPI trusted publishing reads the workflow filename + repo + tag-ref
+    # from the OIDC claim. No environment is required for PyPI; we
+    # explicitly do NOT set an `environment:` block here — adding one would
+    # change the OIDC subject claim and break the trusted-publisher binding
+    # the user registered against the no-environment form (per §Pre-tag
+    # prerequisites).
+    steps:
+      - name: Checkout (full history for changelog notes)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag is on main
+        run: |
+          set -euo pipefail
+          # Trusted publishing's OIDC claim is bound to the workflow filename
+          # and tag ref — it does NOT enforce that the tagged commit is on
+          # main. Tags pushed from a topic branch (or any unmerged commit)
+          # would otherwise publish from un-reviewed code. This guard rejects
+          # any tag whose commit is not reachable from origin/main.
+          # actions/checkout@v4 with fetch-depth: 0 fetches the tag's full
+          # history but does not populate origin/main as a ref locally; we
+          # fetch it explicitly here.
+          git fetch origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "Tag $GITHUB_REF_NAME points at $GITHUB_SHA which is not reachable from main." >&2
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME ($GITHUB_SHA) is on main."
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Sync runtime deps (so the next step can import nsc._version)
+        run: uv sync --frozen
+
+      - name: Verify tag matches package version
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(uv run python -c 'from nsc._version import __version__; print(__version__)')"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "Tag $GITHUB_REF_NAME -> version $tag_version does not match nsc/_version.py $pkg_version" >&2
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME matches package version $pkg_version"
+
+      - name: Build sdist + wheel
+        run: |
+          rm -rf dist
+          uv build --out-dir dist
+          ls -la dist/
+
+      - name: Verify wheel filename matches tag
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          if ! ls "dist/netbox_super_cli-${tag_version}-py3-none-any.whl" >/dev/null 2>&1; then
+            echo "Wheel for ${tag_version} not found in dist/" >&2
+            ls dist/ >&2
+            exit 1
+          fi
+          if ! ls "dist/netbox_super_cli-${tag_version}.tar.gz" >/dev/null 2>&1; then
+            echo "Sdist for ${tag_version} not found in dist/" >&2
+            ls dist/ >&2
+            exit 1
+          fi
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # No `password:` — trusted publishing uses the OIDC token bound
+          # to id-token: write above. PyPI must have a Trusted Publisher
+          # registered for this repo + workflow + (no) environment before
+          # this step runs (see §Pre-tag prerequisites in the 5d plan).
+          packages-dir: dist
+          # Print which artifacts were uploaded; helps diagnose mismatches.
+          verbose: true
+          # Don't fail if a re-tag attempts to re-upload an existing
+          # filename: the action calls PyPI's filename-exists check and
+          # silently skips the upload (it does NOT compare byte content
+          # of the existing vs. would-be-uploaded artifact). PyPI itself
+          # treats version artifacts as immutable, so the file already on
+          # PyPI is the canonical bytes for that version. A re-tag that
+          # builds different bytes for the same version would publish
+          # those bytes only to the GitHub Release, not to PyPI — diverging
+          # the two. Avoid that by never re-tagging an already-published
+          # version; bump to the next patch version instead.
+          skip-existing: true
+
+      - name: Extract changelog section for release notes
+        id: notes
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          # Match `## v<ver><space>...` and capture until the next `## `
+          # heading. The trailing space after <ver> in the regex is what
+          # disambiguates `v1.0` from `v1.0.1`; what follows (typically an
+          # em-dash, date, sub-phase name) is intentionally unconstrained.
+          awk -v ver="$tag_version" '
+            $0 ~ "^## v" ver " " { capture=1; print; next }
+            capture && /^## / { exit }
+            capture { print }
+          ' CHANGELOG.md > /tmp/release-notes.md
+          if [ ! -s /tmp/release-notes.md ]; then
+            echo "Release notes for v${tag_version} not found in CHANGELOG.md" >&2
+            exit 1
+          fi
+          echo "Extracted $(wc -l < /tmp/release-notes.md) lines of release notes."
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          # Use exact filenames (the verify-wheel-filename step proved both
+          # exist) rather than glob-expanding `dist/*.whl dist/*.tar.gz` —
+          # that glob would silently attach any stray artifact a future
+          # build step might drop into dist/.
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file /tmp/release-notes.md \
+            "dist/netbox_super_cli-${tag_version}-py3-none-any.whl" \
+            "dist/netbox_super_cli-${tag_version}.tar.gz"

netbox_super_cli-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install ${{ matrix.python }}
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Run tests
+        run: uv run pytest -v

netbox_super_cli-1.0.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg
+
+# venv
+.venv/
+venv/
+
+# uv
+# (uv.lock IS committed)
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# nsc local state (must never be committed)
+.nsc/
+
+# Secrets
+.env
+.env.*
+*.env
+
+# Local-only design notes (kept out of git history)
+docs/superpowers/
+
+# mkdocs
+site/

netbox_super_cli-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        # 2 MB is enough now that bundled schemas are gzipped.
+        args: [--maxkb=2048]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.20.2
+    hooks:
+      - id: mypy
+        # Keep this list in sync with [project.dependencies] in pyproject.toml,
+        # plus type stubs for any third-party packages used in scripts/.
+        additional_dependencies:
+          - pydantic>=2.7
+          - typer>=0.12
+          - rich>=13.7
+          - httpx>=0.27
+          - "ruamel.yaml>=0.18"
+          - structlog>=24.1
+          - platformdirs>=4.2
+          - types-PyYAML>=6.0
+        args: [--strict]
+        files: ^(nsc|scripts)/

netbox_super_cli-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

netbox_super_cli-1.0.0/AGENTS.md

@@ -0,0 +1,45 @@
+<!--
+  AGENTS.md is auto-generated from CLAUDE.md by scripts/sync_agents_md.py.
+  Do NOT edit this file directly — edit CLAUDE.md and run
+  `uv run python scripts/sync_agents_md.py` to regenerate. CI fails the PR
+  if this file drifts from CLAUDE.md (see .github/workflows/lint.yml).
+-->
+
+# Working on netbox-super-cli (for AI agents)
+
+This is the contributor guide for AI agents (and humans!) modifying this repo. The end-user-facing AI guide is the bundled Skill at `skills/netbox-super-cli/SKILL.md` (added in Phase 5).
+
+## Architecture cheat sheet
+
+- `nsc/schema/` — parses an OpenAPI document into Pydantic models. Knows nothing about CLIs.
+- `nsc/model/` — the normalized command tree (data only, framework-free). The "brain".
+- `nsc/builder/` — converts a parsed schema into a `CommandModel`.
+- `nsc/cli/` — the Typer app; consumes a `CommandModel`.
+- `nsc/http/` — thin httpx wrapper (Phase 2+).
+- `nsc/output/` — formatters (Phase 2+).
+- `nsc/config/` — config loader + Pydantic models (Phase 1 has a minimal version).
+- `nsc/cache/` — disk cache for generated command-models.
+- `nsc/schemas/bundled/` — versioned NetBox OpenAPI snapshots, fallback when offline.
+
+The hard rule: **`nsc/model/` imports nothing from `nsc/cli/`, `nsc/http/`, or any framework.** If you need to add a dependency to `model/`, you're probably solving the wrong problem.
+
+## Common commands
+
+- `just sync` — install/refresh deps.
+- `just test` — run all tests.
+- `just lint` — ruff + mypy --strict.
+- `just fix` — auto-fix ruff issues.
+- `just nsc <args>` — run the local CLI.
+
+## Conventions
+
+- Python 3.12+, full type annotations, `mypy --strict`.
+- Pydantic v2 for all structured data.
+- Conventional Commits.
+- TDD: write the failing test first.
+- No comments on what code does; only on non-obvious *why*.
+
+## Where the design lives
+
+- `docs/superpowers/specs/2026-04-30-netbox-super-cli-design.md` — the full design.
+- `docs/superpowers/plans/` — implementation plans, one per phase.