clinear 0.2.0__tar.gz

clinear-0.2.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# SECURITY — these are forbidden everywhere (also enforced by pre-commit hook)
+*.log
+.env
+.env.*
+.secrets/
+vault/
+secrets.toml
+*.pem
+*.key
+id_rsa*
+id_ed25519*
+
+# Project-specific
+schema/linear-schema.json
+clinear-debug.log

clinear-0.2.0/.python-version

@@ -0,0 +1 @@
+3.10

clinear-0.2.0/AGENTS.md

@@ -0,0 +1,317 @@
+# AGENTS.md — Contributing to clinear
+
+> Guide for humans and AI agents who modify this codebase.
+
+---
+
+## TL;DR (the rules)
+
+1. **Every change bumps the version.** Patch for bugfixes (0.2.0 → 0.2.1), minor for features (0.2.x → 0.3.0), major for breaking changes.
+2. **Every change updates `CHANGELOG.md`** under a new version heading.
+3. **Every change is tested.** Run `bash scripts/e2e-test.sh` before commit. All 36+ tests must pass.
+4. **Every commit goes through the pre-commit hook.** No secrets, no `.log`, no `.env`, no `schema/linear-schema.json`.
+5. **Every release gets a git tag (`vX.Y.Z`) and a GitHub release.** No exceptions.
+
+---
+
+## Architecture
+
+```
+clinear/
+├── VERSION                    Source of truth for __version__
+├── pyproject.toml             Build metadata (must match VERSION)
+├── CHANGELOG.md               Keep-a-Changelog format
+│
+├── clinear/                   Package
+│   ├── __init__.py            Reads VERSION
+│   ├── cli.py                 Root Typer app, global flags, error wrapper
+│   ├── cli_state.py           Per-invocation state container
+│   ├── config.py              TOML config + token resolution
+│   ├── client.py              Async httpx GraphQL client
+│   ├── auth.py                Viewer caching
+│   ├── filters.py             Filter DSL → IssueFilter GraphQL input
+│   ├── output.py              Six output formatters
+│   ├── errors.py              Typed exit codes
+│   ├── models/                Pydantic v2 models (User, Team, Issue, ...)
+│   ├── graphql/               Query/mutation strings + fragments
+│   └── commands/              One file per command group
+│
+├── schema/
+│   ├── linear-schema.json     2.3 MB introspection result (GITIGNORED)
+│   └── schema-summary.json    Categorized summary (committed)
+│
+├── scripts/
+│   ├── e2e-test.sh            Live API E2E test suite
+│   ├── pre-commit.sh          Secret-blocking pre-commit hook
+│   └── install-hooks.sh       Install pre-commit hook
+│
+└── tests/                     (TODO: pytest unit tests for v0.3)
+```
+
+### Data flow for any command
+
+```
+User CLI input
+  └─► clinear.cli.app (Typer)
+        └─► global flags resolved → cli_state.CLIState
+              └─► subcommand handler (clinear/commands/*.py)
+                    └─► clinear.client.LinearClient.execute_as()
+                          ├─► httpx POST to api.linear.app/graphql
+                          ├─► JSON → dict
+                          └─► dict → Pydantic model (validation)
+                                └─► clinear.output.render(model, fmt)
+                                      └─► stdout
+```
+
+### Adding a new command
+
+1. Pick the right file in `clinear/commands/` (or create one).
+2. Add a Typer command with rich `--help` text.
+3. Write the GraphQL string in `clinear/graphql/queries.py` or `mutations.py`. Use fragments from `fragments.py`.
+4. If the response shape is new, add or extend a Pydantic model in `clinear/models/`.
+5. Register the new command group in `clinear/cli.py` via `app.add_typer(...)`.
+6. Add an E2E test case in `scripts/e2e-test.sh`.
+7. Bump version. Update CHANGELOG.
+
+### Adding a new model
+
+```python
+# clinear/models/your_entity.py
+from clinear.models.base import Timestamped
+
+class YourEntity(Timestamped):
+    id: str
+    name: str
+    # use Field(alias="camelCase") for GraphQL → snake_case mapping
+```
+
+### Adding GraphQL fragments
+
+Keep fragments **DRY** and **small**. One fragment per entity "view":
+- `YourEntityCore` → fields included in lists
+- `YourEntityFull` → extra fields included on detail views
+
+```python
+# clinear/graphql/fragments.py
+YOUR_ENTITY_CORE = """
+fragment YourEntityCore on YourEntity {
+  id
+  name
+  createdAt
+}
+"""
+```
+
+---
+
+## Development Workflow
+
+### Setup
+
+```bash
+git clone https://github.com/rinadelph/clinear.git
+cd clinear
+bash scripts/install-hooks.sh        # MANDATORY — installs the secret-blocking pre-commit hook
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+### Day-to-day
+
+```bash
+# 1. Set your token (one-time per shell)
+export LINEAR_TOKEN="lin_api_..."
+
+# 2. Edit code
+
+# 3. Smoke test live API
+.venv/bin/clinear me
+
+# 4. Full E2E suite (takes ~30s)
+bash scripts/e2e-test.sh
+
+# 5. Lint + type check
+uv run ruff check clinear/
+uv run mypy clinear/
+
+# 6. Bump version (see "Versioning" below)
+
+# 7. Commit (hook will refuse if you touch secrets)
+git add -A
+git commit -m "fix(issue): handle null state in IssueSearchResult"
+```
+
+---
+
+## Testing
+
+### E2E (live API — primary suite)
+
+`scripts/e2e-test.sh` exercises every command against the real Linear API.
+
+```bash
+export LINEAR_TOKEN="lin_api_..."
+bash scripts/e2e-test.sh
+```
+
+The script reads `LINEAR_TOKEN` from your env. **It does not contain any hardcoded tokens.** If you find one, that's a bug — fix it immediately and rotate the leaked credential.
+
+Pass condition: `SUMMARY: N passed, 0 failed`.
+
+### Unit tests (TODO — v0.3)
+
+`tests/` is empty as of v0.2.0. Planned with `pytest` + `respx` (mocks httpx) + Pydantic fixture data.
+
+---
+
+## Versioning
+
+We follow [Semantic Versioning](https://semver.org/):
+
+| Bump | When |
+|------|------|
+| **Patch** `0.2.0 → 0.2.1` | Bugfixes, typo corrections, internal refactors with no behavior change. |
+| **Minor** `0.2.x → 0.3.0` | New commands, new flags, new output formats. Backward-compatible. |
+| **Major** `0.x → 1.0` (then `1 → 2`) | Removed/renamed commands, changed exit codes, changed default output. |
+
+### Version bump checklist (every change)
+
+1. Edit `VERSION` to the new number.
+2. Edit `pyproject.toml` → `version = "X.Y.Z"` (must match `VERSION`).
+3. Add a new section to `CHANGELOG.md`:
+   ```markdown
+   ## [X.Y.Z] — YYYY-MM-DD
+
+   ### Added
+   - ...
+
+   ### Changed
+   - ...
+
+   ### Fixed
+   - ...
+   ```
+4. Run the E2E suite. Must pass.
+5. Commit with message: `release: vX.Y.Z`.
+6. Tag: `git tag -a vX.Y.Z -m "vX.Y.Z"` and push: `git push origin vX.Y.Z`.
+7. Create GitHub release (see Release Process).
+8. Publish to PyPI (see Release Process).
+
+---
+
+## Release Process
+
+### 1. Pre-flight
+
+```bash
+# Tests pass?
+bash scripts/e2e-test.sh
+
+# Lint passes?
+uv run ruff check clinear/
+
+# Version is bumped in BOTH places?
+cat VERSION
+grep '^version =' pyproject.toml
+
+# CHANGELOG has the new section?
+head -20 CHANGELOG.md
+```
+
+### 2. Tag and push
+
+```bash
+git add -A
+git commit -m "release: v0.3.0"
+git push origin main
+
+git tag -a v0.3.0 -m "v0.3.0"
+git push origin v0.3.0
+```
+
+### 3. Build with uv
+
+```bash
+rm -rf dist/
+uv build
+# → dist/clinear-0.3.0-py3-none-any.whl
+# → dist/clinear-0.3.0.tar.gz
+```
+
+### 4. Publish to PyPI
+
+```bash
+# Token MUST come from environment — never paste into a shell that gets logged.
+export UV_PUBLISH_TOKEN="pypi-..."
+uv publish
+```
+
+### 5. Create GitHub release
+
+```bash
+gh release create v0.3.0 \
+    --title "v0.3.0" \
+    --notes-file <(awk '/^## \[0.3.0\]/,/^## \[/{if (!/^## \[/) print; if (/^## \[/ && !found) found=1; else if (/^## \[/) exit}' CHANGELOG.md) \
+    dist/clinear-0.3.0-py3-none-any.whl \
+    dist/clinear-0.3.0.tar.gz
+```
+
+### 6. Verify
+
+```bash
+# Wait ~60s for PyPI to propagate, then:
+uv tool install --refresh clinear
+clinear --version  # should print the new version
+```
+
+---
+
+## Pre-commit Hook
+
+`scripts/pre-commit.sh` is installed via `bash scripts/install-hooks.sh`. It runs on `git commit` and **refuses** to commit any staged file that contains:
+
+- Linear API tokens (`lin_api_...`)
+- PyPI API tokens (`pypi-...`)
+- AWS access keys (`AKIA...`)
+- GitHub PATs (`ghp_`, `ghs_`, `gho_`, `ghu_`, `ghr_`)
+- Google service account JSON
+- SSH/PGP private keys
+- Slack tokens
+
+It also blocks these file types entirely:
+- `*.log`
+- `.env`, `.env.*`
+- `schema/linear-schema.json` (regenerable; it's 2 MB)
+- Anything under `.secrets/` or `vault/`
+
+**Bypassing:** `git commit --no-verify` (use only for vetted false positives; audit first).
+
+---
+
+## House Rules
+
+1. **No new runtime dependencies without a security review.** Every dep is a supply-chain attack vector. The dependency tree is currently: `pydantic + pydantic-core (Rust binary) + httpx + httpcore + h11 + idna + certifi + sniffio + anyio + typer + click + shellingham + rich + markdown-it-py + mdurl + pygments + typing-extensions + annotated-types + annotated-doc + exceptiongroup + tomli (py<3.11)`. Don't add to it without justification.
+2. **No `dict[str, Any]` leaks** out of `clinear.client`. Everything that hits a command handler must be a Pydantic model.
+3. **No silent failures.** If something can't be done, raise a `ClinearError` subclass with a helpful `hint`.
+4. **No print statements** outside `clinear/output.py` and a couple of init-related scripts. All output goes through the formatter.
+5. **No `--insecure` flag, ever.** TLS verification is non-negotiable.
+
+---
+
+## When something breaks
+
+1. Re-run `bash scripts/e2e-test.sh -v` (verbose flag prints full output).
+2. Linear API errors will be in the error message verbatim — look for `GRAPHQL_VALIDATION_FAILED` (your query is wrong) vs. `AUTHENTICATION_ERROR` (token issue).
+3. Pydantic validation errors mean the response shape changed or the model is wrong. Run with `--verbose` to see the raw response.
+4. `clinear raw query 'query { ... }'` is your friend — bypass our models, talk directly to Linear's GraphQL.
+5. Re-fetch the schema: `curl -X POST https://api.linear.app/graphql -H "Authorization: $LINEAR_TOKEN" -d '<introspection query>'`. Update fragments/models as needed.
+
+---
+
+## Roadmap
+
+- v0.3 — pytest unit tests, hash-pinned `requirements.txt`, `docs/COMMANDS.md`, `clinear completions` for shell completion install
+- v0.4 — `clinear initiative`, `clinear document`, `clinear customer` (next-tier domains)
+- v0.5 — config-defined views (`--view my-bugs`), aliases
+- v1.0 — stable command surface, full integration with the 8 priority domains

clinear-0.2.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to clinear will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.2.0] — 2026-05-14
+
+### Added
+- `clinear init` — scaffold the config file at `~/.config/clinear/config.toml`.
+- `clinear comment` group: `list`, `add`, `edit`, `delete`.
+- `clinear label` group: `list`, `create`, `delete`.
+- Label resolution in `issue create` and `issue update` — accept label names
+  (comma-separated) and resolve to UUIDs server-side per team.
+- `VERSION` file at the repo root; `__version__` now reads from it.
+- `CHANGELOG.md`.
+
+### Changed
+- `cycle current` now exits 0 with `{ "active_cycle": null }` (JSON) or
+  a friendly message (human) instead of crashing with NotFoundError when
+  a team has no active cycle.
+- `issue search` results now render a full table with priority, state,
+  assignee, and identifier columns.
+- Bumped version to 0.2.0.
+
+### Fixed
+- 4 issues from the v0.1 smoke test:
+  - `Issue.labels` / `Issue.subscribers` now flatten the GraphQL
+    `{nodes: [...]}` connection wrapper automatically.
+  - `searchIssues` no longer spreads the `Issue` fragment on
+    `IssueSearchResult` (different GraphQL type).
+  - YAML formatter no longer collapses nested object indentation.
+  - Error exit codes propagate correctly through the typer entrypoint.
+
+---
+
+## [0.1.0] — 2026-05-14
+
+Initial release.
+
+### Added
+- Core commands: `me`, `auth status/whoami`, `team list/get/states/members`,
+  `issue list/get/create/update/state/assign/prio/url/search`,
+  `project list/get`, `cycle current/list`, `raw query`.
+- Pydantic v2 models for User, Team, Issue, Project, Cycle, WorkflowState.
+- Async httpx GraphQL client with auth, retry, error handling, rate-limit
+  awareness, and pagination helper.
+- Six output formats: `human` (Rich tables), `json`, `yaml`, `md` (markdown),
+  `plain` (TSV), `ids` (one identifier per line).
+- Filter DSL for `issue list` covering team/state/assignee/project/cycle/
+  label/priority/free-text/date filters.
+- Token resolution from `--token` flag, `LINEAR_TOKEN` env var, or
+  `config.toml`.
+- Typed exit codes (0–8) for scriptable error handling.
+- `--dry-run` for safe mutation previews.
+- 28/29 passing E2E tests against the live Linear API.

clinear-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clover
+
+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.

clinear-0.2.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: clinear
+Version: 0.2.0
+Summary: Type-safe Linear CLI built on Pydantic v2
+Project-URL: Homepage, https://github.com/Clover/clinear
+Project-URL: Documentation, https://github.com/Clover/clinear/blob/main/docs/DESIGN.md
+Project-URL: Issues, https://github.com/Clover/clinear/issues
+Author-email: Clover <rnadales@cloverve.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,graphql,issue-tracker,linear,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.10
+Requires-Dist: rich<15.0,>=13.9
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer<1.0,>=0.15
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clinear
+
+> Type-safe Linear CLI built on Pydantic v2 + httpx + Typer.
+
+A Linear command-line interface designed for **humans, agents, and CI/CD pipelines**. Every API response is a validated Pydantic model. Every command works in shell pipelines. JSON output is the canonical contract; the pretty human tables sit on top of it.
+
+```
+clinear me                          # who am I?
+clinear team list                   # all teams in workspace
+clinear issue list --assignee me    # my issues
+clinear issue create --team ENG --title "Fix login bug" --priority 1
+clinear -o json issue list | jq '.[].title'    # pipe into anything
+```
+
+---
+
+## Why clinear?
+
+- **Type-safe.** Every response validated through Pydantic v2. No silent schema drift.
+- **Agent-first.** Stable JSON contracts; pipe-friendly `-o ids` / `-o md` / `-o yaml`.
+- **Tiny attack surface.** Only Pydantic + httpx + Typer + Rich. No npm chaos, no `postinstall` hooks.
+- **Honest errors.** Linear API errors surfaced verbatim with proper POSIX exit codes.
+- **Built for automation.** `--dry-run` for safe mutation previews, `raw query` escape hatch for any GraphQL.
+
+---
+
+## Install
+
+```bash
+# From PyPI (recommended)
+pip install clinear
+# or
+uv tool install clinear
+```
+
+```bash
+# From source
+git clone https://github.com/rinadelph/clinear.git
+cd clinear
+uv venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Get a token
+
+Generate a personal API key at <https://linear.app/settings/api>.
+
+### 2. Set it up
+
+```bash
+export LINEAR_TOKEN="lin_api_..."
+# Or persist a config:
+clinear init
+```
+
+### 3. Verify
+
+```bash
+clinear me
+```
+
+### 4. Use it
+
+```bash
+# Read
+clinear team list
+clinear issue get ENG-123
+clinear issue list --assignee me --state Todo
+
+# Write
+clinear issue create --team ENG --title "Fix login bug" --priority 1
+clinear issue assign ENG-123 me
+clinear issue state ENG-123 "In Progress"
+clinear issue prio ENG-123 1
+clinear comment add ENG-123 "Started on this — investigating now"
+
+# Pipe
+clinear -o ids issue list --assignee me | xargs -I{} clinear issue url {}
+clinear -o json issue list --state Todo | jq '.[] | "\(.identifier): \(.title)"'
+
+# Safety net
+clinear --dry-run issue update ENG-123 --priority 2
+```
+
+---
+
+## Output Formats
+
+Set with `-o` / `--output` **before** the subcommand:
+
+| Format | Flag | What you get |
+|---|---|---|
+| **human** | default | Pretty Rich tables with colors |
+| **json** | `-o json` | Compact JSON, null-pruned |
+| **yaml** | `-o yaml` | Hand-rolled minimal YAML |
+| **md** | `-o md` | Markdown tables for PRs / reports |
+| **plain** | `-o plain` | TSV — `id<TAB>state<TAB>...` |
+| **ids** | `-o ids` | Just identifiers, one per line — great for `xargs` |
+
+---
+
+## Command Reference
+
+```
+clinear
+├── me / auth status / auth whoami
+├── init                          Create ~/.config/clinear/config.toml
+├── team list / get / states / members
+├── issue
+│   ├── list   --team --state --assignee --label --priority --contains ...
+│   ├── get <id>
+│   ├── create --team --title [--description --priority --assignee --label ...]
+│   ├── update <id> [--title --state --assignee --priority --label ...]
+│   ├── state <id> <state-name>
+│   ├── assign <id> <user>
+│   ├── prio <id> <0-4>
+│   ├── url <id>
+│   └── search <query>
+├── project list / get
+├── cycle current <team> / list <team>
+├── comment list / add / edit / delete
+├── label list / create / delete
+└── raw query <graphql>           Escape hatch — arbitrary GraphQL
+```
+
+Run `clinear <command> --help` for full flags on any subcommand.
+
+---
+
+## Configuration
+
+Default location: `~/.config/clinear/config.toml`. Override with `$CLINEAR_CONFIG`.
+
+```toml
+[auth]
+token_env = "LINEAR_TOKEN"  # read from this env var
+
+[defaults]
+team = "ENG"
+output = "human"
+
+[display]
+color = true
+table_max_width = 120
+```
+
+Run `clinear init` to scaffold the file.
+
+---
+
+## Exit Codes (stable across versions)
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic error |
+| 2 | Usage error (bad flags) |
+| 3 | Auth error (missing/invalid token) |
+| 4 | Not found |
+| 5 | Validation error (response didn't match model) |
+| 6 | API error (Linear returned errors) |
+| 7 | Network error (timeout, DNS, TLS) |
+| 8 | Rate limited |
+
+---
+
+## Security
+
+- Token read from `$LINEAR_TOKEN`, `--token` flag, or `config.toml`. Never logged in plaintext.
+- HTTPS-only. TLS verification mandatory.
+- No telemetry. Zero outbound calls except to `api.linear.app`.
+- Pre-commit hook blocks committing tokens, `.log` files, `.env` files. See `scripts/pre-commit.sh`.
+
+---
+
+## Development
+
+See [AGENTS.md](./AGENTS.md) for the contributor guide — architecture, testing, version bumping, and release process.
+
+```bash
+git clone https://github.com/rinadelph/clinear.git
+cd clinear
+bash scripts/install-hooks.sh    # install pre-commit hook
+uv venv && uv pip install -e ".[dev]"
+export LINEAR_TOKEN="lin_api_..."
+bash scripts/e2e-test.sh         # 36/36 should pass
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).