localql 1.0.0__tar.gz

localql-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug report
+description: Report a reproducible LocalQL problem
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for helping improve LocalQL. Please include a small local CSV example when possible."
+  - type: textarea
+    id: command
+    attributes:
+      label: Command
+      description: Paste the exact command you ran.
+      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 output.
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: LocalQL version
+      description: Run `csvql --version`.
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Run `python --version`.
+    validations:
+      required: false
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+    validations:
+      required: true

localql-1.0.0/.github/ISSUE_TEMPLATE/docs_issue.yml

@@ -0,0 +1,25 @@
+name: Documentation issue
+description: Report confusing, stale, or missing docs
+title: "[Docs]: "
+labels: ["documentation"]
+body:
+  - type: input
+    id: page
+    attributes:
+      label: Page or section
+      description: Link or name the page.
+    validations:
+      required: true
+  - type: textarea
+    id: issue
+    attributes:
+      label: What is confusing or missing?
+    validations:
+      required: true
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested wording
+      description: Optional exact replacement text.
+    validations:
+      required: false

localql-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature request
+description: Suggest a focused LocalQL improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: "LocalQL is local-first: CSV files, DuckDB SQL, CLI/TUI workflow, explicit exports, and project catalogs."
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What local CSV workflow problem would this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+    validations:
+      required: true
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This stays within local CSV, DuckDB SQL, CLI/TUI workflow, explicit exports, or project catalogs.
+          required: true
+        - label: This does not require a web app, cloud connector, NLP execution, hidden cache, or sandbox-safe SQL claim.
+          required: true

localql-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+## Scope Check
+
+- [ ] This change stays within LocalQL's local CSV, DuckDB, CLI/TUI, explicit export, project catalog, docs, or test scope.
+- [ ] This change does not add web app, cloud connector, NLP execution, hidden cache, sandbox-safe SQL, or production-readiness claims.
+- [ ] Public examples use installed `csvql ...` commands unless the section is specifically for source-checkout development.
+
+## Verification
+
+- [ ] `uv run ruff format --check .`
+- [ ] `uv run ruff check .`
+- [ ] `uv run --all-extras mypy src`
+- [ ] `uv run --all-extras pytest`
+
+## Notes

localql-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: ubuntu-latest
+            python-version: "3.14"
+          - os: macos-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+      - name: Baseline truth
+        run: |
+          pwd -P
+          git status --short --branch
+          git log -1 --oneline
+          git remote -v
+          git tag --points-at HEAD
+          uv --version
+          uv run python --version
+          uv run --all-extras csvql --version
+      - name: Check formatting
+        run: uv run ruff format --check .
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run --all-extras mypy src
+      - name: Test
+        run: uv run --all-extras pytest

localql-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,451 @@
+name: publish
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  EXPECTED_TAG: v1.0.0
+  EXPECTED_VERSION: "1.0.0"
+
+jobs:
+  build-and-verify:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Guard release tag
+        run: |
+          test "${GITHUB_REF}" = "refs/tags/${EXPECTED_TAG}"
+          test "${GITHUB_REF_TYPE}" = "tag"
+          test "${GITHUB_REF_NAME}" = "${EXPECTED_TAG}"
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+      - name: Check formatting
+        run: uv run ruff format --check .
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run --all-extras mypy src
+      - name: Test
+        run: uv run --all-extras pytest
+      - name: Build
+        run: uv build --sdist --wheel --out-dir dist
+      - name: Audit package contents
+        run: uv run python scripts/audit_package_contents.py dist
+      - name: Verify artifact identity and hashes
+        run: |
+          python - <<'PY'
+          from __future__ import annotations
+
+          import email.parser
+          import hashlib
+          import os
+          import tarfile
+          import zipfile
+          from pathlib import Path
+
+          dist = Path("dist")
+          expected_tag = os.environ["EXPECTED_TAG"]
+          expected_version = os.environ["EXPECTED_VERSION"]
+          if os.environ["GITHUB_REF"] != f"refs/tags/{expected_tag}":
+              raise SystemExit("publish workflow must run on the expected release tag")
+
+          wheels = sorted(dist.glob("localql-*.whl"))
+          sdists = sorted(dist.glob("localql-*.tar.gz"))
+          if len(wheels) != 1 or len(sdists) != 1:
+              raise SystemExit("expected exactly one localql wheel and one localql sdist")
+
+          def wheel_version(path: Path) -> str:
+              with zipfile.ZipFile(path) as archive:
+                  metadata_names = [
+                      name for name in archive.namelist() if name.endswith(".dist-info/METADATA")
+                  ]
+                  if len(metadata_names) != 1:
+                      raise SystemExit(f"{path}: expected exactly one wheel METADATA file")
+                  metadata = archive.read(metadata_names[0]).decode("utf-8")
+              return str(email.parser.Parser().parsestr(metadata)["Version"])
+
+          def sdist_version(path: Path) -> str:
+              with tarfile.open(path) as archive:
+                  members = [
+                      member for member in archive.getmembers() if member.name.endswith("/PKG-INFO")
+                  ]
+                  if len(members) != 1:
+                      raise SystemExit(f"{path}: expected exactly one sdist PKG-INFO file")
+                  extracted = archive.extractfile(members[0])
+                  if extracted is None:
+                      raise SystemExit(f"{path}: could not read sdist PKG-INFO")
+                  metadata = extracted.read().decode("utf-8")
+              return str(email.parser.Parser().parsestr(metadata)["Version"])
+
+          versions = {wheel_version(wheels[0]), sdist_version(sdists[0])}
+          if versions != {expected_version}:
+              raise SystemExit(f"artifact versions do not match {expected_version}: {versions}")
+
+          hash_lines = []
+          for path in [*wheels, *sdists]:
+              digest = hashlib.sha256(path.read_bytes()).hexdigest()
+              hash_lines.append(f"{digest}  {path.name}\n")
+          (dist / "SHA256SUMS.txt").write_text("".join(hash_lines), encoding="utf-8")
+          PY
+      - name: Installed wheel smoke
+        run: |
+          wheel="$(python - <<'PY'
+          from pathlib import Path
+
+          wheels = sorted(Path("dist").glob("localql-*.whl"))
+          if len(wheels) != 1:
+              raise SystemExit("expected exactly one localql wheel")
+          print(wheels[0].resolve())
+          PY
+          )"
+          smoke_root="$(mktemp -d)"
+          uv venv --seed "${smoke_root}/venv"
+          uv pip install --python "${smoke_root}/venv/bin/python" "${wheel}"
+          printf 'order_id,status\nORD-1,paid\n' > "${smoke_root}/orders.csv"
+          (
+            cd "${smoke_root}"
+            unset PYTHONPATH
+            "${smoke_root}/venv/bin/csvql" --version
+            "${smoke_root}/venv/bin/csvql" query "${smoke_root}/orders.csv" \
+              "SELECT COUNT(*) AS order_count FROM orders" --output json
+          )
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: localql-1.0.0-dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/SHA256SUMS.txt
+          if-no-files-found: error
+
+  publish:
+    needs: build-and-verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Guard release tag
+        run: |
+          test "${GITHUB_REF}" = "refs/tags/${EXPECTED_TAG}"
+          test "${GITHUB_REF_TYPE}" = "tag"
+          test "${GITHUB_REF_NAME}" = "${EXPECTED_TAG}"
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: localql-1.0.0-dist
+          path: release-artifacts
+      - name: Verify downloaded artifact hashes and metadata
+        run: |
+          cd release-artifacts
+          shasum -a 256 -c SHA256SUMS.txt
+          cd ..
+          python - <<'PY'
+          from __future__ import annotations
+
+          import email.parser
+          import os
+          import tarfile
+          import zipfile
+          from pathlib import Path
+
+          dist = Path("release-artifacts")
+          expected_version = os.environ["EXPECTED_VERSION"]
+          wheels = sorted(dist.glob("localql-*.whl"))
+          sdists = sorted(dist.glob("localql-*.tar.gz"))
+          if len(wheels) != 1 or len(sdists) != 1:
+              raise SystemExit("expected exactly one localql wheel and one localql sdist")
+
+          def wheel_version(path: Path) -> str:
+              with zipfile.ZipFile(path) as archive:
+                  metadata_names = [
+                      name for name in archive.namelist() if name.endswith(".dist-info/METADATA")
+                  ]
+                  if len(metadata_names) != 1:
+                      raise SystemExit(f"{path}: expected exactly one wheel METADATA file")
+                  metadata = archive.read(metadata_names[0]).decode("utf-8")
+              return str(email.parser.Parser().parsestr(metadata)["Version"])
+
+          def sdist_version(path: Path) -> str:
+              with tarfile.open(path) as archive:
+                  members = [
+                      member for member in archive.getmembers() if member.name.endswith("/PKG-INFO")
+                  ]
+                  if len(members) != 1:
+                      raise SystemExit(f"{path}: expected exactly one sdist PKG-INFO file")
+                  extracted = archive.extractfile(members[0])
+                  if extracted is None:
+                      raise SystemExit(f"{path}: could not read sdist PKG-INFO")
+                  metadata = extracted.read().decode("utf-8")
+              return str(email.parser.Parser().parsestr(metadata)["Version"])
+
+          versions = {wheel_version(wheels[0]), sdist_version(sdists[0])}
+          if versions != {expected_version}:
+              raise SystemExit(f"artifact versions do not match {expected_version}: {versions}")
+          PY
+          mkdir -p dist
+          cp release-artifacts/*.whl release-artifacts/*.tar.gz dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+        with:
+          packages-dir: dist/
+          print-hash: true
+          attestations: true
+
+  post-publish-verification:
+    needs: publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: localql-1.0.0-dist
+          path: release-artifacts
+      - name: Verify published artifacts and capture provenance
+        id: verify_pypi_release
+        timeout-minutes: 7
+        run: |
+          python - <<'PY'
+          from __future__ import annotations
+
+          import hashlib
+          import json
+          import os
+          import re
+          import time
+          from datetime import UTC, datetime
+          from pathlib import Path
+          from urllib.error import HTTPError, URLError
+          from urllib.parse import quote
+          from urllib.request import Request, urlopen
+
+          PROJECT = "localql"
+          VERSION = os.environ["EXPECTED_VERSION"]
+          ARTIFACT_DIR = Path("release-artifacts")
+          VERIFICATION_DIR = Path("pypi-verification")
+          MAX_ATTEMPTS = 8
+          POLL_SECONDS = 10
+          REQUEST_TIMEOUT_SECONDS = 10
+          INTEGRITY_ACCEPT = "application/vnd.pypi.integrity.v1+json"
+
+          VERIFICATION_DIR.mkdir(parents=True, exist_ok=True)
+          status_path = VERIFICATION_DIR / "verification-status.txt"
+          status_path.write_text("PyPI verification started.\n", encoding="utf-8")
+
+          def read_expected_digests() -> dict[str, str]:
+              manifest_path = ARTIFACT_DIR / "SHA256SUMS.txt"
+              digests: dict[str, str] = {}
+              for raw_line in manifest_path.read_text(encoding="utf-8").splitlines():
+                  if not raw_line.strip():
+                      continue
+                  parts = raw_line.split()
+                  if len(parts) != 2:
+                      raise SystemExit(f"invalid SHA256SUMS.txt line: {raw_line!r}")
+                  digest, filename = parts
+                  if not re.fullmatch(r"[0-9a-f]{64}", digest):
+                      raise SystemExit(f"invalid SHA-256 digest for {filename}")
+                  if filename in digests:
+                      raise SystemExit(f"duplicate SHA256SUMS.txt entry: {filename}")
+                  if Path(filename).name != filename:
+                      raise SystemExit(f"invalid artifact filename: {filename}")
+                  artifact_path = ARTIFACT_DIR / filename
+                  if not artifact_path.is_file():
+                      raise SystemExit(f"downloaded artifact is missing: {filename}")
+                  local_digest = hashlib.sha256(artifact_path.read_bytes()).hexdigest()
+                  if local_digest != digest:
+                      raise SystemExit(f"downloaded artifact digest mismatch: {filename}")
+                  digests[filename] = digest
+
+              wheel_names = [
+                  name
+                  for name in digests
+                  if name.startswith(f"{PROJECT}-{VERSION}-") and name.endswith(".whl")
+              ]
+              sdist_names = [name for name in digests if name == f"{PROJECT}-{VERSION}.tar.gz"]
+              if len(wheel_names) != 1 or len(sdist_names) != 1:
+                  raise SystemExit(
+                      f"expected one {PROJECT} {VERSION} wheel and one sdist in SHA256SUMS.txt"
+                  )
+              expected_names = {wheel_names[0], sdist_names[0]}
+              if set(digests) != expected_names:
+                  raise SystemExit(f"unexpected artifacts in SHA256SUMS.txt: {sorted(digests)}")
+              return digests
+
+          def fetch_json(url: str, *, accept: str) -> dict[str, object] | None:
+              request = Request(
+                  url,
+                  headers={
+                      "Accept": accept,
+                      "User-Agent": "localql-post-publish-verification/1.0",
+                  },
+              )
+              try:
+                  with urlopen(request, timeout=REQUEST_TIMEOUT_SECONDS) as response:
+                      payload = json.load(response)
+              except HTTPError as exc:
+                  if exc.code == 404 or exc.code == 429 or 500 <= exc.code < 600:
+                      return None
+                  raise
+              except (TimeoutError, URLError):
+                  return None
+              if not isinstance(payload, dict):
+                  raise SystemExit(f"expected a JSON object from {url}")
+              return payload
+
+          def write_receipt(path: Path, payload: dict[str, object]) -> None:
+              path.write_text(
+                  json.dumps(payload, indent=2, sort_keys=True) + "\n",
+                  encoding="utf-8",
+              )
+
+          def published_digests(entries: object) -> dict[str, str]:
+              if not isinstance(entries, list):
+                  return {}
+              digests: dict[str, str] = {}
+              for entry in entries:
+                  if not isinstance(entry, dict):
+                      continue
+                  filename = entry.get("filename")
+                  hashes = entry.get("digests")
+                  if not isinstance(filename, str) or not isinstance(hashes, dict):
+                      continue
+                  sha256 = hashes.get("sha256")
+                  if isinstance(sha256, str):
+                      digests[filename] = sha256
+              return digests
+
+          expected_digests = read_expected_digests()
+          project = PROJECT
+          version = VERSION
+          project_url = f"https://pypi.org/pypi/{project}/json"
+          release_url = f"https://pypi.org/pypi/{project}/{version}/json"
+          verified = False
+          last_issue = "PyPI metadata has not propagated"
+
+          for attempt in range(1, MAX_ATTEMPTS + 1):
+              project_metadata = fetch_json(project_url, accept="application/json")
+              release_metadata = fetch_json(release_url, accept="application/json")
+
+              if project_metadata is None or release_metadata is None:
+                  last_issue = "project or release JSON is not available"
+              else:
+                  write_receipt(VERIFICATION_DIR / "pypi-project.json", project_metadata)
+                  write_receipt(
+                      VERIFICATION_DIR / "pypi-release-1.0.0.json",
+                      release_metadata,
+                  )
+                  release_digests = published_digests(release_metadata.get("urls"))
+
+                  if release_digests != expected_digests:
+                      last_issue = "release JSON filenames or SHA-256 digests do not match"
+                  else:
+                      provenance_ready = True
+                      for filename in sorted(expected_digests):
+                          quoted_filename = quote(filename, safe="")
+                          integrity_base = f"https://pypi.org/integrity/{project}/{version}"
+                          provenance_url = f"{integrity_base}/{quoted_filename}/provenance"
+                          provenance = fetch_json(provenance_url, accept=INTEGRITY_ACCEPT)
+                          if provenance is None:
+                              provenance_ready = False
+                              last_issue = f"provenance is not available for {filename}"
+                              continue
+
+                          write_receipt(
+                              VERIFICATION_DIR / f"provenance-{filename}.json",
+                              provenance,
+                          )
+                          bundles = provenance.get("attestation_bundles")
+                          if not isinstance(bundles, list) or not bundles:
+                              provenance_ready = False
+                              last_issue = f"attestation bundles are missing for {filename}"
+                              continue
+                          if any(
+                              not isinstance(bundle, dict)
+                              or not isinstance(bundle.get("attestations"), list)
+                              or not bundle.get("attestations")
+                              for bundle in bundles
+                          ):
+                              provenance_ready = False
+                              last_issue = f"an attestation bundle is empty for {filename}"
+
+                      if provenance_ready:
+                          summary = {
+                              "project": PROJECT,
+                              "version": VERSION,
+                              "verified_at": datetime.now(UTC).isoformat(),
+                              "sha256": expected_digests,
+                              "release_metadata_and_digests_verified": True,
+                              "provenance_and_non_empty_attestation_receipts_captured": True,
+                              "cryptographic_attestation_verification_performed": False,
+                          }
+                          write_receipt(
+                              VERIFICATION_DIR / "verification-summary.json",
+                              summary,
+                          )
+                          status_path.write_text(
+                              "PyPI release metadata and digests verified; "
+                              "provenance and non-empty attestation receipts captured. "
+                              "No cryptographic attestation verification was performed.\n",
+                              encoding="utf-8",
+                          )
+                          verified = True
+                          break
+
+              if attempt < MAX_ATTEMPTS:
+                  print(
+                      f"PyPI verification attempt {attempt}/{MAX_ATTEMPTS} incomplete: "
+                      f"{last_issue}; retrying in {POLL_SECONDS}s"
+                  )
+                  time.sleep(POLL_SECONDS)
+
+          if not verified:
+              status_path.write_text(
+                  f"PyPI verification failed after {MAX_ATTEMPTS} attempts: {last_issue}.\n",
+                  encoding="utf-8",
+              )
+              raise SystemExit(status_path.read_text(encoding="utf-8").strip())
+          PY
+      - name: Record failed verification outcome
+        if: always() && steps.verify_pypi_release.outcome != 'success'
+        run: |
+          mkdir -p pypi-verification
+          printf '%s\n' \
+            'PyPI post-publish verification failed, timed out, or skipped before completion. Release metadata and digest verification did not complete; inspect workflow logs and captured partial receipts. No cryptographic attestation verification was performed.' \
+            > pypi-verification/verification-outcome.txt
+          if test ! -s pypi-verification/verification-status.txt || \
+            grep -Fqx 'PyPI verification started.' pypi-verification/verification-status.txt; then
+            cp pypi-verification/verification-outcome.txt \
+              pypi-verification/verification-status.txt
+          fi
+      - name: Upload PyPI verification receipts
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: localql-1.0.0-pypi-verification
+          path: pypi-verification
+          if-no-files-found: error

localql-1.0.0/.gitignore

@@ -0,0 +1,24 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.venv/
+dist/
+build/
+*.egg-info/
+
+.local/
+.superpowers/
+.worktrees/
+
+.csvql/
+output/
+keys.log
+
+csvql_project_pack/
+csvql_project_pack.zip

localql-1.0.0/.python-version

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