firecube 0.1.4__tar.gz

firecube-0.1.4/.github/ISSUE_TEMPLATE/1-bug_report.yml

@@ -0,0 +1,101 @@
+name: Bug report
+description: Report incorrect behavior, a crash, or corrupted output in Firecube.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. Please give us enough detail to
+        reproduce it. Firecube requires **explicit product and storage flags** — include
+        the full command you ran so we can see them.
+
+        Do **not** paste credentials, tokens, or private data URIs. Redact them.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: A clear, one- or two-sentence description of the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: The exact command(s), including all product/storage flags. Redact secrets.
+      placeholder: |
+        1. uv run firecube <command> --product ... --storage ... <uri>
+        2. ...
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include the full error message and traceback if there is one.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Firecube version
+      description: Output of `uv run firecube --version`.
+      placeholder: "0.1.4"
+    validations:
+      required: true
+  - type: dropdown
+    id: install
+    attributes:
+      label: Install source
+      options:
+        - PyPI
+        - Git checkout (source)
+        - Container image
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, OS, and any relevant extras installed (obstore, tensogram, healpix, virtualzarr).
+      placeholder: |
+        - Python: 3.12.x
+        - OS: Linux / macOS / Windows (+ version)
+        - Extras: e.g. obstore
+        - Storage backend: local / S3 (endpoint type)
+    validations:
+      required: true
+  - type: input
+    id: plugin
+    attributes:
+      label: Plugin involved (if any)
+      description: Package name and version of the ingest plugin, if the bug is in an ingest run.
+      placeholder: "my-firecube-plugin==1.2.0"
+    validations:
+      required: false
+  - type: textarea
+    id: data
+    attributes:
+      label: Data / state impact
+      description: >-
+        Did this affect stored output (Zarr), the `.firecube/` control plane, or resume/append
+        state? Is any output store now corrupt or partially written?
+    validations:
+      required: false
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: I removed all credentials, tokens, and private URIs from this report.
+          required: true

firecube-0.1.4/.github/ISSUE_TEMPLATE/2-feature_request.yml

@@ -0,0 +1,73 @@
+name: Feature request
+description: Propose a new capability, integration, or improvement for Firecube.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing an improvement. Firecube favors small, explicit changes that
+        respect existing module boundaries (see `CONTRIBUTING.md` and `plans/DESIGN.md`).
+        Please describe the problem before the solution, and be concrete about scope.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What are you trying to do, and why is it hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should Firecube do? Sketch the CLI surface, config, or API if relevant.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of Firecube does this touch?
+      multiple: true
+      options:
+        - Output Formats
+        - CLI / UX
+        - Control plane (.firecube / ChunkManager)
+        - Storage / filesystem backends
+        - Plugin contracts / API
+        - Compute / array backend
+        - Observability
+        - Packaging / extras / dependencies
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches, existing workarounds, or why they fall short.
+    validations:
+      required: false
+  - type: textarea
+    id: compat
+    attributes:
+      label: Compatibility & scope
+      description: >-
+        Would this change public CLI flags, plugin contracts, config, or stored formats?
+        Should it be opt-in (e.g. an optional extra) to keep the default install lean?
+    validations:
+      required: false
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be willing to help implement this.
+          required: false
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true

firecube-0.1.4/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/eumetsat/firecube/discussions
+    about: Ask usage questions, propose ideas, or discuss plugin development here.
+  - name: Documentation
+    url: https://github.com/eumetsat/firecube/tree/main/docs
+    about: Check the docs before filing — many workflows and recovery steps are covered there.

firecube-0.1.4/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,50 @@
+<!--
+Thanks for contributing to Firecube. Please read CONTRIBUTING.md first.
+Keep pull requests focused: one logical change per PR.
+-->
+
+## What changed
+
+<!-- A clear description of the change. -->
+
+## Why
+
+<!-- The motivation. Link the issue this closes, e.g. "Closes #123". -->
+
+## Affected behavior
+
+<!-- Which user, operator, plugin, or maintainer behavior changes? -->
+
+- User / CLI:
+- Plugin authors:
+- Operators / production:
+- Stored formats or control-plane state:
+
+## Type of change
+
+- [ ] Bug fix (non-breaking)
+- [ ] New feature (non-breaking)
+- [ ] Breaking change (CLI flags, plugin contract, config, or stored format)
+- [ ] Documentation
+- [ ] CI / build / chore
+
+## Checks run
+
+<!-- Tick what you ran; paste anything notable. -->
+
+- [ ] `uv run ruff check .`
+- [ ] `uv run ruff format --check .`
+- [ ] `uv run pyright`
+- [ ] `uv run --with bandit bandit -c pyproject.toml -r src scripts -lll`
+- [ ] `uv run pytest --strict-deps -m "not slow and not s3" -q`
+- [ ] Docs build (if docs changed): `uv run mkdocs build --strict`
+
+## Follow-up work
+
+<!-- Known gaps or planned follow-ups, or "none". -->
+
+## Contributor certification
+
+- [ ] Commits are signed off (`git commit -s`) with my real name and a reachable email.
+- [ ] No credentials, generated products, caches, or virtualenvs are included in this PR.
+- [ ] If AI assistance materially shaped this change, I disclosed it here and added an `Assisted-by` trailer.

firecube-0.1.4/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

firecube-0.1.4/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install 3.12
+      - run: uv sync --locked --extra test --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install 3.12
+      - run: uv sync --locked --extra test --group dev
+      - name: Install test fixture plugins
+        run: |
+          uv pip install -e tests/fixtures/cli_test_plugin
+          uv pip install -e tests/fixtures/direct_zarr_capable_test_plugin
+          uv pip install -e tests/fixtures/direct_zarr_non_capable_test_plugin
+          uv pip install -e tests/fixtures/multi_group_capable_test_plugin
+          uv pip install -e tests/fixtures/cf_time_dim_test_plugin
+          uv pip install -e tests/fixtures/slot_shape_test_plugin
+      - run: uv run pyright
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install 3.12
+      - run: uv sync --locked --extra test --group dev
+      - name: Install test fixture plugins
+        run: |
+          uv pip install -e tests/fixtures/cli_test_plugin
+          uv pip install -e tests/fixtures/direct_zarr_capable_test_plugin
+          uv pip install -e tests/fixtures/direct_zarr_non_capable_test_plugin
+          uv pip install -e tests/fixtures/multi_group_capable_test_plugin
+          uv pip install -e tests/fixtures/cf_time_dim_test_plugin
+          uv pip install -e tests/fixtures/slot_shape_test_plugin
+      - run: uv run pytest --strict-deps -m "not slow and not s3" -n auto --cov=firecube --cov-report=term-missing -q
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install 3.12
+      - run: uv sync --locked --extra test --group docs
+      - run: uv run mkdocs build --strict --site-dir /tmp/firecube-mkdocs-check

firecube-0.1.4/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  quality-gate:
+    name: quality gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install 3.12
+      - run: uv sync --locked --extra test --group dev
+      - name: Install test fixture plugins
+        run: |
+          uv pip install -e tests/fixtures/cli_test_plugin
+          uv pip install -e tests/fixtures/direct_zarr_capable_test_plugin
+          uv pip install -e tests/fixtures/direct_zarr_non_capable_test_plugin
+          uv pip install -e tests/fixtures/multi_group_capable_test_plugin
+          uv pip install -e tests/fixtures/cf_time_dim_test_plugin
+          uv pip install -e tests/fixtures/slot_shape_test_plugin
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - run: uv run pytest --strict-deps -m "not slow and not s3" -n auto --cov=firecube -q
+
+  publish:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    needs: quality-gate
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install 3.12
+
+      - name: Verify release tag matches pyproject version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version="$(python3 -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          if [ "$RELEASE_TAG" != "v$version" ]; then
+            echo "Release tag $RELEASE_TAG does not match pyproject version v$version" >&2
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distributions
+        run: uvx twine check dist/*
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

firecube-0.1.4/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.ipynb_checkpoints
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg-info/
+.eggs/
+.*
+!.gitignore
+!.prompts/
+!.prompts/*.md
+!.github/
+
+# Environments
+.venv/
+.env/
+
+# MkDocs
+site/
+
+# Plugin Development
+plugins_dev/
+
+# Build artifacts
+build/
+dist/
+
+# Project outputs
+artifacts/
+outputs/
+data/
+*.zarr
+*.parquet
+
+# Logs
+*.log
+
+# OS / Editor
+.DS_Store
+.idea/
+.vscode/
+
+# Coverage / testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.python-version
+.ruff_cache
+
+# Generated SBOM / dependency-license reports (regenerate locally)
+reports/

firecube-0.1.4/.prompts/address-pr-comments.md

@@ -0,0 +1,84 @@
+---
+description: Review and resolve unresolved pull request comments
+agent: build
+---
+
+# Address Review Comments
+
+Review and resolve all actionable feedback on a pull request.
+
+## Arguments
+
+Provide the MR/PR number or URL as `$ARGUMENTS`. If no argument is given, detect
+the current branch's open review if possible.
+
+## 1. Fetch Review Feedback
+
+Use the available hosting CLI:
+
+```bash
+glab mr view "$ARGUMENTS" --comments
+```
+
+or:
+
+```bash
+gh pr view "$ARGUMENTS" --comments
+gh pr diff "$ARGUMENTS"
+```
+
+If threaded inline comments are not visible, use the host API to fetch unresolved
+threads/comments directly. Report if authentication or network access prevents
+fetching review comments.
+
+## 2. Analyze Each Comment
+
+For each unresolved comment:
+
+- Read the full file and surrounding context, not just the commented line.
+- Identify whether the comment is about correctness, API design, tests, docs, security, performance, or style.
+- Check the concern against Firecube's local rules in `AGENTS.md`, `plans/STYLE.md`, `plans/TEST.md`, and `.prompts/docs-policy.md` when documentation is involved.
+- If the requested fix conflicts with repo architecture or user intent, propose the safer alternative with concrete reasoning.
+- If the intent is ambiguous, ask for clarification before making risky changes.
+
+## 3. Address Actionable Issues
+
+For each actionable comment:
+
+- Fix the underlying issue, not only the symptom.
+- Update tests when the feedback identifies missing coverage or changed behavior.
+- Update public docs when behavior, flags, config, or SDK surfaces change.
+- Keep edits scoped to the reviewed change unless a small adjacent cleanup is required.
+
+Do not resolve comments, commit, or push unless the user explicitly asks.
+
+## 4. Verify
+
+Run the smallest relevant verification first, then broaden as needed:
+
+```bash
+uv run ruff check .
+uv run pyright
+uv run pytest <focused tests>
+uv run mkdocs build --strict --site-dir /tmp/firecube-mkdocs-check
+```
+
+For broad changes, run:
+
+```bash
+uv run pytest --strict-deps -q --tb=short
+uv run pytest --strict-deps -q --tb=short -W error::DeprecationWarning
+```
+
+## 5. Report
+
+Provide a mapping from each review comment to the action taken:
+
+```text
+Comment:
+Action:
+Verification:
+Residual risk:
+```
+
+List unresolved comments separately with the blocker or question.

firecube-0.1.4/.prompts/doc-fact-check.md

@@ -0,0 +1,97 @@
+---
+description: Run Firecube docs code examples and verify prose claims against the codebase
+agent: build
+---
+
+# Documentation Fact-Check
+
+Run code examples in the docs and verify prose claims against the actual codebase.
+
+## Arguments
+
+`$ARGUMENTS` — optional file paths relative to `docs/` to narrow the scope.
+
+Examples:
+
+- `/doc-fact-check quickstart/ingestion.md`
+- `/doc-fact-check concepts/`
+- `/doc-fact-check`
+
+If no arguments are given, check all `.md` files under `docs/`.
+
+## Setup
+
+```bash
+uv sync --extra test --group docs
+uv pip install -e tests/fixtures/cli_test_plugin
+uv pip install -e tests/fixtures/direct_zarr_capable_test_plugin
+uv pip install -e tests/fixtures/direct_zarr_non_capable_test_plugin
+uv pip install -e tests/fixtures/multi_group_capable_test_plugin
+uv pip install -e tests/fixtures/cf_time_dim_test_plugin
+uv run firecube --help
+```
+
+If any setup step fails, report it and continue with the checks that can still run.
+Blocks that fail because of missing credentials, missing private plugins, or missing
+external services are setup problems, not documentation bugs.
+
+## 1. Run Code Examples
+
+For each fenced code block in the selected docs:
+
+### Classify Each Block
+
+- **Runnable**: self-contained Python or Bash with no placeholders, no ellipsis, and no user-specific files.
+- **Continuation**: follows a runnable block on the same page and reuses its variables; concatenate with its predecessor.
+- **Skip**: partial snippets, signatures-only snippets, output samples, unlabeled blocks, install commands, destructive commands, cloud/S3 commands without local fixtures, or commands requiring private data/plugins.
+
+### Execute Runnable Blocks
+
+- **Python**: write to a temp `.py` file and run with `uv run python`.
+- **Bash**: run only commands that are safe locally and can complete without credentials.
+- **CLI help**: run documented `firecube ... --help` commands and verify exit code 0.
+
+Never invent missing imports, variables, files, credentials, or plugin names. Record
+pass/fail/skip for every block.
+
+## 2. Check Claims Against Code
+
+Read each selected doc file and find verifiable factual claims. Focus on inline
+code spans, command flags, config keys, table cells, defaults, feature names, and
+numbers.
+
+Check:
+
+- **CLI flags and subcommands**: run `uv run firecube ... --help`.
+- **Config keys**: verify against config parsing and documented examples.
+- **Public SDK imports**: verify names are exported from `firecube.ingestor.api` or `firecube.core.api`.
+- **Plugin entry points**: verify entry point group names and loading behavior.
+- **Default values**: verify against dataclasses/config classes.
+- **Metric names and environment variables**: verify against source.
+- **Test counts or marker claims**: verify by running or inspecting pytest config.
+
+Do not check subjective claims such as "fast", "simple", or "production-ready"
+unless the doc attaches a measurable value.
+
+## 3. Report
+
+For each finding:
+
+```text
+[ERROR|STALE|DRIFT] docs/path.md:LINE — Summary
+Docs say:
+Code says:
+Suggested fix:
+```
+
+- **ERROR**: code example fails, command is invalid, API does not exist, or documented behavior is wrong.
+- **STALE**: outdated value, renamed API, removed flag, or old config.
+- **DRIFT**: minor mismatch such as wording, count, default, or incomplete example.
+
+End with a summary:
+
+- files checked
+- blocks run/passed/failed/skipped
+- claim issues found
+
+For findings, propose fixes but do not apply them unless the user asked for edits.