superset-cli 0.1.0__tar.gz

superset_cli-0.1.0/.envrc

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+eval "$(devenv direnvrc)"
+use devenv

superset_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+"on":
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install project dependencies
+        run: uv sync --locked --group dev
+
+      - name: Run test suite
+        run: uv run pytest -v
+
+      - name: Smoke-test CLI help
+        run: uv run superset-cli --help
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test built wheel
+        run: uv run --isolated --no-project --with dist/*.whl superset-cli --help

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

@@ -0,0 +1,79 @@
+name: Build and publish
+
+"on":
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - name: Check release version
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          tag = os.environ["RELEASE_TAG"]
+          if tag != f"v{version}":
+              raise SystemExit(f"Release tag {tag!r} does not match package version {version!r}; expected v{version}")
+          PY
+      - name: Install project dependencies
+        run: uv sync --locked --group dev
+      - name: Run test suite
+        run: uv run pytest -v
+      - name: Build distributions
+        run: uv build
+      - name: Smoke-test built wheel and source distribution
+        run: |
+          uv run --isolated --no-project --with dist/*.whl superset-cli --help
+          uv run --isolated --no-project --with dist/*.tar.gz superset-cli --help
+      - name: Store distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/superset-cli
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

superset_cli-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Devenv
+.devenv*
+devenv.local.nix
+devenv.local.yaml
+
+# direnv
+.direnv
+
+# pre-commit
+.pre-commit-config.yaml

superset_cli-0.1.0/AGENTS.md

@@ -0,0 +1,235 @@
+# AGENTS.md
+
+## Mission
+
+This repository builds `superset-cli`, a CLI for self-hosted Apache Superset.
+
+Current product scope is **read-only**:
+- local instance config management
+- Playwright-based browser login scaffold
+- saved auth-state inspection and validation
+- read-only Superset REST access for dashboards, charts, datasets, and databases
+
+Do not expand the product beyond read-only behavior unless the user explicitly asks for it.
+
+## Instruction priority
+
+Follow instructions in this order:
+1. explicit user request
+2. this file
+3. README and nearby docs
+4. existing code patterns
+
+If instructions conflict or the safest path is unclear, stop and ask.
+
+## Project map
+
+- `src/superset_cli/` — application code
+- `tests/` — pytest suite; treat tests as executable spec
+- `docs/index.md` — top-level map of repository documentation
+- `docs/glossary.md` — repository-specific terminology used in docs, plans, and architecture notes
+- `docs/templates/` — reusable templates for plans, decision records, and final reports
+- `docs/plans/` — written plans and design notes
+- `docs/tickets/` — lightweight Markdown ticket system for repo work tracking
+- `docs/decisions/` — durable decision log; this is the primary "why" memory for future agents
+- `docs/architecture/` — structural map of the codebase; use this for module responsibilities and command-to-code entry points
+- `README.md` — human-oriented project overview and commands
+- `pyproject.toml` — dependencies, packaging, Python version
+- `devenv.nix` / `devenv.yaml` — local development environment
+
+## Environment and working commands
+
+Prefer these commands:
+
+```bash
+devenv shell
+uv sync --group dev
+uv run pytest -v
+uv run pytest tests/test_cli.py -v
+uv run superset-cli --help
+uv build
+```
+
+The CLI reads Superset session cookies directly from an installed browser via `browser-cookie3` — no extra browser install step is required.
+
+Use `uv` to run Python commands. Prefer `devenv shell` before development work.
+
+## Golden workflow (mandatory)
+
+For any task beyond a tiny docs edit:
+
+1. **Research first.** Check relevant docs, APIs, libraries, and existing repo patterns before changing code.
+2. **Read first.** Read all relevant files immediately before referencing or editing them. Read nearby tests before implementation. Read relevant files in `docs/decisions/` before planning or changing behavior. Read `docs/index.md` when you need the top-level documentation map. Read `docs/glossary.md` when repository-specific terminology is unclear. Read `docs/templates/README.md` when you need repository-approved doc templates. Read `docs/architecture/README.md` when you need the current structural map of modules, commands, and tests.
+3. **Plan first.** Write a short plan to `docs/plans/YYYY-MM-DD-<topic>.md` before any non-trivial change. Every plan must end with a `Decision follow-up` section that says either `Decision record update required:` with the target file(s), or `No durable decision change.`
+4. **TDD always.** Write or update a failing test first.
+5. **Implement minimally.** Make the smallest change that satisfies the test and the request.
+6. **Verify incrementally.** Run focused tests first, then broader verification.
+7. **Capture durable reasoning.** If you made or changed a lasting technical decision, add or update a record in `docs/decisions/` and link it from the plan.
+8. **Report evidence only.** Never claim success without command output or other concrete evidence.
+
+## TDD rules
+
+TDD is required for all code changes.
+
+- Start by adding or updating tests in `tests/`.
+- Confirm the new or changed test fails for the expected reason.
+- Implement the minimum code needed to make it pass.
+- Re-run the targeted test, then the broader suite.
+- Never remove, weaken, or bypass a test just to get green results.
+
+For CLI changes:
+- test both human-readable output and `--json` output when applicable
+- preserve existing JSON output shape unless the contract is intentionally changed
+- when changing the contract, update tests and docs in the same task
+
+## Decision memory rules
+
+- Treat `docs/decisions/` as the canonical long-term memory for why this repository works the way it does.
+- Before planning or implementation, read the most relevant decision record(s) for the area you are changing.
+- Use `docs/plans/` for proposed work and temporary reasoning.
+- Every non-trivial plan must include a final `Decision follow-up` section with one of two outcomes: `Decision record update required:` or `No durable decision change.`
+- Promote any durable outcome from a plan into `docs/decisions/`.
+- Keep one decision per file with stable headings such as `Status`, `Context`, `Decision`, `Consequences`, and `Alternatives considered`.
+- Cross-link decision records to relevant plans, code paths, and tests when possible.
+- Do not bury important rationale only in chat, commit messages, or code comments.
+
+## Markdown ticket system
+
+- Use `docs/tickets/` for lightweight repo work tracking.
+- Ticket folders are the primary workflow state:
+  - `docs/tickets/todo/`
+  - `docs/tickets/in-progress/`
+  - `docs/tickets/done/`
+- Every ticket must also include a `Status:` field that matches its folder.
+- Agents may create tickets proactively for code, docs, plans, decisions, cleanup, research, and follow-up work.
+- Before creating a ticket, check `docs/tickets/` for an obvious duplicate.
+- If an existing ticket clearly covers the same work, update that ticket instead of creating a new one.
+- If overlap is uncertain, create a new ticket and cross-link related tickets.
+- Keep tickets small and actionable; split broad work into multiple tickets.
+- Starting work on a ticket should move it to `in-progress/`.
+- Finishing work on a ticket should move it to `done/`.
+- Tickets capture what should be done. They do not replace `docs/plans/` for non-trivial implementation planning or `docs/decisions/` for durable rationale.
+
+## Coding rules
+
+- Prefer extending existing patterns in `cli.py`, `client.py`, `config.py`, `auth.py`, and `models.py`.
+- Keep diffs small and focused.
+- Avoid speculative abstractions and broad refactors.
+- Do not mix unrelated fixes in one change.
+- Preserve current read-only posture unless explicitly asked to change it.
+- If command behavior, UX, or examples change, update `README.md`.
+- If a new top-level documentation area is added, or an existing documentation layer changes role, update `docs/index.md` in the same workstream.
+- If repository-specific terminology changes or important new local terms appear, update `docs/glossary.md` in the same workstream.
+- If repository documentation templates change or new canonical templates are added, update `docs/templates/README.md` in the same workstream.
+- If command-to-code mappings, major module responsibilities, or common structural entry points change, update `docs/architecture/README.md` in the same workstream.
+
+## Verification checklist
+
+Before declaring a code task complete, run the relevant checks.
+
+Minimum expected verification for most code changes:
+
+```bash
+uv run pytest -v
+uv run superset-cli --help
+uv build
+```
+
+Also run the most specific targeted test(s) for the area you changed, for example:
+
+```bash
+uv run pytest tests/test_cli.py -v
+uv run pytest tests/test_auth.py -v
+```
+
+If you changed CLI behavior, include at least one manual command smoke check.
+
+## Live Superset, auth, and browser safety
+
+Live verification is allowed, but guarded.
+
+- Prefer local tests, mocks, and fixtures first.
+- Use a real Superset instance only when needed for validation.
+- Keep all live-instance actions read-only unless the user explicitly authorizes otherwise.
+- Log the exact commands used for live verification.
+- Announce browser-based login before launching it.
+- Treat browser profiles, cookies, and `storage-state.json` as sensitive.
+- Never commit credentials, auth state, browser profiles, or secrets.
+- Use `/tmp` for temporary files and scratch artifacts.
+
+## Public repository content
+
+This repository and its source distribution are public. Everything committed, including docs, plans, tickets, tests, fixtures, commit messages, and PR descriptions, must be free of employer- or customer-specific details.
+
+- Use the example company `Example Corp` and reserved example domains (`example.com`, `superset.example.com`, `superset-staging.example.com`) instead of real company names, hostnames, or SSO setups.
+- Do not quote real instance data: dashboard, chart, dataset, or database names, IDs, user names, or emails taken from a live Superset. Replace them with neutral examples before committing.
+- Redact cookie values, tokens, and other credentials in captured command output (for example `session=<redacted>`).
+- When live verification against a real instance informs a doc or ticket, describe the behavior, not the instance.
+
+## Ask-first boundaries
+
+Ask before:
+- adding or changing dependencies
+- changing CLI defaults or JSON output contracts
+- changing packaging, build, or `devenv` behavior
+- expanding from read-only into write-capable Superset operations
+- making broad architectural refactors
+- running live verification that goes beyond minimal read-only checks
+
+## Write-command contract
+
+Every CLI command that mutates Superset state (create, update, delete via the API) must require an explicit `--allow-write` flag on every invocation. Default off.
+
+Rules:
+- `--allow-write` is per-invocation. It is never persisted in the config file, never read from an environment variable, and never defaulted on.
+- Without the flag, the command exits non-zero with a message naming the missing flag and the mutation it would have performed (for example: `"This would delete dashboard 7. Re-run with --allow-write to perform the write."`).
+- The check lives in a shared helper in `src/superset_cli/cli.py` so individual commands cannot forget it.
+- Help text for every write command must state "Required to actually perform the write. Without it the command is a dry-run."
+- The check applies to every write command, including ones that look idempotent (for example setting a tag).
+- `--allow-write` is never granted by a confirmation prompt, a config flag, or a parent command — only by the literal CLI argument on the same invocation.
+
+This rule exists so that unintended write calls (typos, copy-paste mistakes, agent overshoot) fail safe, human and agent operators see the same friction, and the read-only product posture remains visible in every write surface that ever gets added.
+
+See [`docs/decisions/0009-write-command-explicit-opt-in.md`](docs/decisions/0009-write-command-explicit-opt-in.md) for the full rationale and alternatives considered.
+
+## Never do these things
+
+- never fabricate results
+- never claim tests passed without running them
+- never claim a file contains something you did not re-read
+- never remove tests or checks to make the suite pass
+- never commit secrets, auth state, or browser profile data
+- never use `git push`
+- never create a pull request or merge request
+- never perform destructive or write actions against Superset without explicit user instruction
+
+## Definition of done
+
+A task is not done until all relevant items below are true:
+
+- a written plan exists for any non-trivial change
+- the plan ends with a `Decision follow-up` section
+- failing tests were written first
+- implementation is minimal and scoped
+- targeted tests pass
+- `uv run pytest -v` passes for code changes
+- relevant smoke checks were run
+- docs were updated if behavior or workflow changed
+- `docs/index.md` was updated if top-level documentation areas or doc roles changed
+- `docs/architecture/README.md` was updated if structural mappings or module responsibilities changed
+- decision records were added or updated if durable technical choices changed
+- the final report includes:
+  - files changed
+  - commands run
+  - actual verification results
+  - consulted decision records, or an explicit statement that none were relevant
+  - any remaining risks or unverified areas
+
+## When stuck
+
+If progress stalls:
+- stop and summarize what is known
+- identify the exact uncertainty
+- research or inspect the narrow missing piece
+- prefer a smaller verified change over a larger speculative one
+- ask the user when a decision affects scope, contract, or risk

superset_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Rittsteiger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.