cli-consumption 0.0.1__tar.gz

cli_consumption-0.0.1/.agents/skills/add-cli-adapter/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: add-cli-adapter
+description: Add or update an AI coding CLI provider adapter for CLI Consumption. Use for provider discovery, local file or endpoint parsing, normalized conversation/turn/model/tool mapping, provider capability status, compatibility fixtures, and adapter documentation.
+---
+
+# Add a CLI adapter
+
+1. Verify the provider's current data sources and terms from primary documentation.
+2. Record which fields are stable, optional, inferred, or unavailable. Never invent a
+   cross-provider equivalence.
+3. Add synthetic fixtures covering the smallest supported format, malformed input, and
+   a realistic multi-turn conversation. Do not copy personal provider data.
+4. Implement the adapter contract under `src/cli_consumption/adapters/`. Keep all
+   provider-specific logic there and emit only the normalized snapshot fields.
+5. Apply `$audit-usage-privacy` to the input fields, transient parsing, errors, logs,
+   snapshot payload, SQL rows, CSV, and dashboard.
+6. Test stable IDs, duplicate copies, model attribution, token semantics, tool names,
+   partial records, and format changes.
+7. Register the adapter in the CLI only after its tests pass. Update
+   `docs/provider-support.md` with precise limitations.
+8. Run every quality gate in `AGENTS.md`.

cli_consumption-0.0.1/.agents/skills/add-cli-adapter/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Add CLI Adapter"
+  short_description: "Add a privacy-safe AI CLI ingestion adapter"
+  default_prompt: "Use $add-cli-adapter to implement the next AI CLI provider."

cli_consumption-0.0.1/.agents/skills/audit-usage-privacy/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: audit-usage-privacy
+description: Audit CLI Consumption changes for metadata minimization and sensitive-content leakage. Use for adapters, API payloads, storage, errors, logging, exports, dashboards, fixtures, documentation, or any change that handles provider files or conversation-derived data.
+---
+
+# Audit usage privacy
+
+1. Enumerate every input field read and every output surface changed: memory snapshot,
+   SQL, API, CSV, HTML, logs, errors, fixtures, and documentation examples.
+2. Require an explicit analytical purpose for each persisted field. Prefer derived
+   labels and counts over raw values.
+3. Reject prompts, responses, instructions, raw events, tool arguments or results,
+   commands, patches, environment values, credentials, original paths, and arbitrary
+   metadata blobs.
+4. Allow transient inspection only when required to derive an approved value, then
+   discard the source content immediately.
+5. Check malformed-input errors and debug paths for accidental raw-record output.
+6. Add a synthetic canary secret to fixtures and assert that it is absent from
+   snapshots, databases, API bodies, CSV files, dashboards, and logs.
+7. Re-read `docs/privacy.md` and update it if the approved boundary changes.
+8. Report each reviewed surface and any residual operational disclosure such as project
+   names or activity timestamps.

cli_consumption-0.0.1/.agents/skills/audit-usage-privacy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Audit Usage Privacy"
+  short_description: "Keep sensitive conversation content out of exports"
+  default_prompt: "Use $audit-usage-privacy to review this ingestion or export change."

cli_consumption-0.0.1/.agents/skills/evolve-storage-schema/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: evolve-storage-schema
+description: Evolve CLI Consumption persistence safely across SQLite and PostgreSQL. Use for tables, columns, indexes, constraints, migrations, retention, deduplication, stable identifiers, ingestion transactions, or storage compatibility changes.
+---
+
+# Evolve the storage schema
+
+1. Define the provider-neutral meaning, nullability, cardinality, and lifecycle of each
+   proposed field before editing the schema.
+2. Apply `$audit-usage-privacy`; reject fields that expose content or machine-private
+   paths without an explicit accepted design change.
+3. Specify upgrade, downgrade, and mixed-version behavior. Introduce a migration tool
+   before the first incompatible released schema change.
+4. Preserve provider-qualified stable IDs and atomic replacement of a conversation with
+   its child records.
+5. Test SQLite directly. Test PostgreSQL for SQL, types, constraints, indexes, and
+   transaction behavior whenever the change can differ by dialect.
+6. Cover repeated ingestion, less-complete duplicates, more-complete replacements,
+   partial failure, empty datasets, and concurrent writers as applicable.
+7. Update architecture, privacy, export, and API documentation together with the code.
+8. Run every quality gate in `AGENTS.md`.

cli_consumption-0.0.1/.agents/skills/evolve-storage-schema/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Evolve Storage Schema"
+  short_description: "Change SQLite and PostgreSQL schemas safely"
+  default_prompt: "Use $evolve-storage-schema to plan and implement this data model change."

cli_consumption-0.0.1/.agents/skills/yeet-github/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: yeet-github
+description: Publish the current repository work in a draft GitHub pull request with gh.
+---
+
+# Yeet GitHub
+
+Run from the repository root. Publish the current work without merging the pull request. Use `$yolo` when the user explicitly requests publication, squash merge, and cleanup as one workflow.
+
+## 1. Verify context
+
+1. Read all repository instructions, including `AGENTS.md` and `CONTRIBUTING.md` when present.
+2. Read `docs/product-specification.md` when present and map the objective to relevant tickets and acceptance criteria without expanding scope.
+3. Summarize the objective and identify only the changes that belong to it.
+4. Inspect `git status --short --branch`, `git diff --check`, `git diff`, `git diff --stat`, and relevant untracked files.
+5. Verify `gh --version`, `gh auth status`, `git remote -v`, and the default branch with `gh repo view --json defaultBranchRef,nameWithOwner`.
+6. Require an authenticated `gh` session and an `origin` remote matching the expected GitHub repository. Stop before mutation if a prerequisite is missing.
+7. Preserve unrelated changes. Stop before staging if inclusion is ambiguous.
+
+Read the installed command help before relying on version-sensitive options:
+
+```bash
+gh pr create --help
+gh pr view --help
+gh pr merge --help
+```
+
+## 2. Select branches
+
+1. Capture the target branch from `defaultBranchRef`.
+2. If the current branch is the target, create a short `<type>/<issue>-<subject>` branch using the repository's allowed Conventional Commit types. Never include `codex`, an agent name, or an automation-tool name in the branch name.
+3. Keep an existing work branch only when it clearly matches the request.
+4. Capture exact source and target names. Reject an empty, identical, protected, or unexpected source branch.
+5. Check that proposed local and remote branches do not already exist in an ambiguous state.
+
+## 3. Validate and commit
+
+1. Run the canonical checks in `AGENTS.md` that apply to the changed domain. Never invent substitute commands.
+2. Review the final diff and run `git diff --check`.
+3. Present the branch, changed files, concise diff summary, checks, and known limitations; obtain explicit approval before any push or pull-request publication.
+4. After approval, stage only in-scope files. Run `git diff --cached --check` and inspect `git diff --cached --stat`.
+5. Commit using the repository convention, defaulting to an English Conventional Commit. Include a ticket reference only when one exists.
+6. Never bypass hooks. Capture the full SHA with `git rev-parse HEAD` and require a clean worktree apart from explicitly ignored local files.
+
+Never use `git clean`, `git reset --hard`, `git checkout --`, or hook bypasses.
+
+## 4. Push
+
+1. Push the captured source branch explicitly with `git push -u origin <source-branch>`.
+2. Stop on non-fast-forward. Never rebase, resolve conflicts, or force-push without explicit authorization.
+3. Verify that the remote source SHA equals the captured local SHA.
+
+## 5. Open the pull request
+
+1. Use `gh pr list --head <source-branch> --state all` to ensure no pull request already exists.
+2. Write an English title and body covering objective, tickets and acceptance criteria, changes, technical decisions, impacts, tests, documentation, limitations, both storage profiles, and references.
+3. Create a draft pull request with `gh pr create --draft --head <source-branch> --base <target-branch> --title '<title>' --body-file <temporary-file-outside-repository>`.
+4. Remove the temporary file after the command and never track it.
+5. Verify number, URL, draft state, branches, SHA, and state with `gh pr view`.
+6. If creation has an ambiguous result, look for an existing pull request immediately and do not retry until side effects are known.
+
+## Result
+
+Report the pull-request URL, number, and state; source and target branches; pushed SHA; checks and results; remaining limitations; and final `git status --short --branch`.
+
+Never merge the pull request, delete a branch, or modify GitHub protections in this skill.

cli_consumption-0.0.1/.agents/skills/yeet-github/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Yeet GitHub"
+  short_description: "Publish current work in a draft GitHub PR"
+  default_prompt: "Use $yeet-github to validate and publish the current work in a draft GitHub pull request."

cli_consumption-0.0.1/.agents/skills/yolo/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: yolo
+description: Publish the current Codex work in a GitHub pull request, squash-merge it, then clean up its local and remote branches. Use only when the user explicitly invokes `$yolo` or requests the full publish, merge, and cleanup sequence.
+---
+
+# Publish, merge, and clean up
+
+Run each phase in order from the repository root. The implicit pull request is the one for the current Codex work and current branch.
+
+## 1. Publish
+
+1. Read all repository instructions and the product specification referenced by `AGENTS.md`.
+2. Load and follow `$yeet-github` in full to inspect, validate, commit, push, and open a draft pull request.
+3. Retain the exact source and target branches, pushed SHA, pull-request number, and URL.
+4. Stop after any failure or ambiguous external result. Never merge or clean up after a partial failure.
+
+## 2. Merge
+
+1. Explicit `$yolo` invocation authorizes merging only the pull request for the current work. It never authorizes bypassing protections or merging another pull request.
+2. Verify with `gh pr view` that the pull request exactly matches the captured source branch and SHA. Reject ambiguity or a changed head.
+3. Inspect required checks, reviews, conversations, and protections with `gh pr checks` and `gh pr view --json mergeStateStatus,reviewDecision,statusCheckRollup`.
+4. Mark a ready draft with `gh pr ready <number>`.
+5. Watch pending checks with `gh pr checks <number> --watch --interval 10`; stop and report any failing check.
+6. Present the final state and obtain explicit approval immediately before merging and deleting branches.
+7. After approval, use `gh pr merge <number> --squash --delete-branch --match-head-commit <source-sha>`.
+8. If GitHub queues the merge, keep monitoring. Clean up only after `gh pr view <number> --json state,mergedAt,mergeCommit` reports `MERGED`.
+
+## 3. Clean up
+
+1. Reconfirm the merged state and capture the merge commit SHA.
+2. Refuse cleanup if new tracked, staged, or untracked work appeared after the source commit.
+3. Run `git fetch --prune origin`.
+4. Switch to the target branch and update it only by fast-forward with `git switch <target-branch>` and `git pull --ff-only origin <target-branch>`.
+5. Delete the exact local source branch if it remains. `git branch -D <source-branch>` is allowed only after verified squash merge.
+6. If the unprotected remote branch remains, obtain fresh explicit approval before `git push origin --delete <source-branch>`.
+7. Run `git status --short --branch` and report the final state.
+
+## Guardrails
+
+- Never use `git clean`, `git reset --hard`, or recursive deletion.
+- Never delete the target branch, a protected branch, or a branch whose exact name was not captured before merge.
+- Never clean another worktree.
+- Never confuse green checks, approval, or mergeability with an actual merge.
+- Never extend this authorization to a pull request unrelated to the current work.
+
+## Result
+
+Report the pull-request URL and state, merged SHA, deleted branches, current branch, and final `git status`.

cli_consumption-0.0.1/.agents/skills/yolo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Yolo GitHub"
+  short_description: "Publish, squash-merge, and clean up a PR"
+  default_prompt: "Use $yolo to publish, squash-merge, and clean up the current GitHub work."

cli_consumption-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: "3.14"
+      - run: uv sync --locked --all-groups
+      - run: uv run pre-commit run --all-files --show-diff-on-failure
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run ty check --output-format github
+      - run: uv run pytest --cov --cov-report=term-missing
+      - run: uv build

cli_consumption-0.0.1/.github/workflows/release.yaml

@@ -0,0 +1,122 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    paths: [pyproject.toml]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  detect-version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      changed: ${{ steps.version.outputs.changed }}
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - name: Detect project version change
+        id: version
+        env:
+          BEFORE_SHA: ${{ github.event.before }}
+        run: |
+          set -euo pipefail
+
+          current_version="$(uv version --short)"
+          previous_version=""
+          if git cat-file -e "${BEFORE_SHA}:pyproject.toml" 2>/dev/null; then
+            previous_version="$(
+              git show "${BEFORE_SHA}:pyproject.toml" |
+                python -c 'import sys, tomllib; print(tomllib.load(sys.stdin.buffer)["project"]["version"])'
+            )"
+          fi
+
+          echo "version=${current_version}" >> "${GITHUB_OUTPUT}"
+          if [[ "${current_version}" == "${previous_version}" ]]; then
+            echo "changed=false" >> "${GITHUB_OUTPUT}"
+          else
+            echo "changed=true" >> "${GITHUB_OUTPUT}"
+          fi
+
+  build:
+    needs: detect-version
+    if: needs.detect-version.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: "3.14"
+      - run: uv sync --locked --all-groups
+      - run: uv run pre-commit run --all-files --show-diff-on-failure
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run ty check --output-format github
+      - run: uv run pytest --cov --cov-report=term-missing
+      - run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          overwrite: true
+
+  tag:
+    needs: [detect-version, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Tag version commit
+        env:
+          RELEASE_VERSION: ${{ needs.detect-version.outputs.version }}
+        run: |
+          set -euo pipefail
+
+          tag="v${RELEASE_VERSION}"
+          git fetch --tags origin
+          if git rev-parse --verify --quiet "refs/tags/${tag}" >/dev/null; then
+            tagged_commit="$(git rev-list -n 1 "${tag}")"
+            if [[ "${tagged_commit}" != "${GITHUB_SHA}" ]]; then
+              echo "Tag ${tag} already points to ${tagged_commit}, not ${GITHUB_SHA}." >&2
+              exit 1
+            fi
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git tag --annotate "${tag}" --message "Release ${RELEASE_VERSION}" "${GITHUB_SHA}"
+            git push origin "refs/tags/${tag}"
+          fi
+
+  publish:
+    needs: [detect-version, tag]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cli-consumption
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cli_consumption-0.0.1/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.py[cod]
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+reports/
+*.sqlite
+*.sqlite3
+.env
+
+# Machine-specific orchestration context. These files must never be committed.
+.agents/orchestrator.md
+.agents/local-environment.md

cli_consumption-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+minimum_pre_commit_version: "4.6.2"
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.4
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty
+        entry: uv run ty check
+        language: system
+        pass_filenames: false
+        require_serial: true
+      - id: pytest
+        name: pytest
+        entry: uv run pytest -W error::ResourceWarning --cov --cov-report=term-missing
+        language: system
+        pass_filenames: false
+        require_serial: true
+        stages: [pre-push]

cli_consumption-0.0.1/.python-version

@@ -0,0 +1 @@
+3.14

cli_consumption-0.0.1/AGENTS.md

@@ -0,0 +1,67 @@
+# Repository instructions
+
+## Authority and scope
+
+Read this file, `README.md`, `CONTRIBUTING.md`, and the relevant documents under
+`docs/` before changing the repository. Keep changes scoped to one short-lived branch
+and one coherent pull request.
+
+The project is a Python 3.14+ package managed exclusively with `uv`. Do not introduce
+another package manager, task runner, ORM, web framework, or migration tool without an
+accepted architecture decision.
+
+## Product invariants
+
+- Never collect or persist prompts, responses, tool arguments, environment values,
+  credentials, or raw rollout events.
+- Treat every provider file and API payload as untrusted input.
+- Keep the normalized model provider-neutral; provider-specific parsing belongs in
+  `src/cli_consumption/adapters/`.
+- Support SQLite and PostgreSQL for every persisted schema change.
+- Make ingestion idempotent and safe to repeat after partial failures.
+- Preserve stable conversation IDs and prefer the most complete duplicate copy.
+- Keep generated dashboards self-contained and free of network requests.
+- Do not claim that local token events represent billing data.
+
+## Required skills
+
+- Use `.agents/skills/add-cli-adapter` for a new provider or provider format change.
+- Use `.agents/skills/evolve-storage-schema` for tables, columns, indexes, migrations,
+  retention, or compatibility changes.
+- Use `.agents/skills/audit-usage-privacy` for collectors, API payloads, exports,
+  dashboards, logging, or changes that can cross the privacy boundary.
+- Use `.agents/skills/yeet-github` only when explicitly asked to publish a draft pull
+  request. Use `.agents/skills/yolo` only when explicitly invoked for the full publish,
+  squash-merge, and cleanup workflow.
+
+## Quality gates
+
+Run all of the following before requesting review:
+
+```bash
+uv run pre-commit run --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest --cov --cov-report=term-missing
+uv build
+```
+
+Add tests for every behavioral change. Include malformed and adversarial provider data
+for parsers, idempotency cases for ingestion, authentication cases for the API, and
+privacy assertions for every new exported field.
+
+## Trunk-based workflow
+
+- Branch from current `main` using a short-lived `feat/`, `fix/`, `docs/`, or `chore/`
+  branch.
+- Never push directly to `main`, force-push shared history, or bypass required checks.
+- Prefer one focused commit before review and squash-merge the pull request.
+- Rebase or merge current `main` before final validation when the branch is stale.
+- Delete the source branch only after the pull request is verified as merged.
+
+## Local orchestration files
+
+`.agents/orchestrator.md` and `.agents/local-environment.md` are machine-specific and
+ignored deliberately. Keep durable, portable decisions in tracked documentation or
+architecture decision records instead.

cli_consumption-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Set up the project
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c feat/short-description
+uv sync --all-groups
+uv run pre-commit install
+```
+
+Use `uv add`, `uv remove`, and `uv lock` for dependency changes. Do not edit the lock
+file manually.
+
+## Make a change
+
+Keep provider parsing behind the adapter interface and normalized persistence behind
+the storage module. A new field must have a documented meaning across providers or be
+explicitly namespaced as provider-specific.
+
+Do not add telemetry. Test fixtures must be synthetic and must not contain copied user
+conversations or credentials.
+
+## Validate and review
+
+Run the quality gates documented in `AGENTS.md`, inspect the complete diff, then open a
+pull request. The pull request must explain the behavior, privacy impact, storage
+compatibility, tests, and any remaining limitation. Merge by squash after required
+checks pass and review is complete.
+
+## Release
+
+Update the project version with `uv version <version>` and include the resulting
+`pyproject.toml` and `uv.lock` changes in a pull request. When that version change is
+squash-merged into `main`, the release workflow reruns the quality gates, builds the
+distributions, tags the merge commit as `v<version>`, and publishes to PyPI through
+Trusted Publishing. Do not create the release tag manually.