gfly 0.1.0__tar.gz

gfly-0.1.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{md,yml,yaml,json,toml,tape}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

gfly-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Default owner for everything in this repo.
+* @rnwolfe
+
+# The agent-CLI contract surface — review with extra care.
+/src/gfly/output.py   @rnwolfe
+/src/gfly/errors.py   @rnwolfe
+/tests/test_schema_snapshot.py @rnwolfe

gfly-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug report
+description: Something in gfly behaves incorrectly.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! For **security** issues do NOT use this form — see SECURITY.md.
+        Please **redact any secrets** (SerpApi keys, cookies) before pasting output.
+  - type: input
+    id: version
+    attributes:
+      label: gfly version
+      description: Output of `gfly --version`.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Backend
+      options: ["google (default)", "serpapi"]
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS / Python
+      placeholder: "Ubuntu 24.04 / Python 3.12 (uv)"
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command
+      description: The exact command you ran (redact secrets).
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected vs. what happened
+    validations:
+      required: true
+  - type: textarea
+    id: error
+    attributes:
+      label: Structured error / exit code
+      description: Paste the JSON error from stderr and the exit code (`echo $?`).
+      render: json
+    validations:
+      required: false
+  - type: textarea
+    id: schema
+    attributes:
+      label: gfly doctor output
+      description: Output of `gfly doctor --json` (secrets are redacted automatically).
+      render: json
+    validations:
+      required: false

gfly-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔒 Security vulnerability
+    url: https://github.com/rnwolfe/gfly/security/advisories/new
+    about: Report security issues privately — never via a public issue. See SECURITY.md.
+  - name: 💬 Questions & ideas
+    url: https://github.com/rnwolfe/gfly/discussions
+    about: Ask questions, share recipes, or discuss before filing a feature request.

gfly-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Suggest a capability or improvement for gfly.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        gfly is **read-only by design** (it searches; it does not book) and **agent-first**
+        (stable JSON, structured errors, bounded output). Requests that respect those
+        constraints are most likely to land.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / use case
+      description: What are you trying to do, and what's blocking you today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Command surface, flags, and the output fields you'd expect.
+    validations:
+      required: true
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Which backend(s)?
+      multiple: true
+      options: ["google", "serpapi", "both / new backend"]
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

gfly-0.1.0/.github/PUBLISH_CHECKLIST.md

@@ -0,0 +1,47 @@
+# Publish checklist (manual operator steps)
+
+The repo, README, demo, hygiene, landing page, and release pipeline are ready. These steps require
+your credentials / a browser and can't be automated from here.
+
+## 1. Create the GitHub repo & push
+```bash
+gh repo create rnwolfe/gfly --public --source=. --remote=origin --push \
+  --description "Google Flights for agents — a read-only, JSON-first flight-search CLI an LLM can drive (no API key)."
+```
+
+## 2. Repo settings (Settings → …)
+- **Topics** (≤20, lowercase-hyphen): `cli` `google-flights` `flight-search` `agent` `llm`
+  `agentic` `python` `uv` `travel` `json` `read-only` `serpapi`.
+- **About → website**: the docs/landing URL once hosted.
+- **Social preview**: upload a 1280×640 card (reuse the split-flap board aesthetic from `site/`).
+- **Security → enable Private Vulnerability Reporting** (required for SECURITY.md's flow).
+- **Discussions**: enable (SUPPORT.md and the issue `config.yml` link to it).
+- **Branches → protect `main`**: require PR + status checks (`ci`) + **require review from Code Owners**.
+
+## 3. PyPI Trusted Publishing (no stored secrets)
+- Register the project on PyPI, then add a **Trusted Publisher**: owner `rnwolfe`, repo `gfly`,
+  workflow `release.yml`, environment `pypi`. Must match the workflow exactly.
+- Create a repo **Environment** named `pypi`.
+
+## 4. First release (delegate to the `release` skill)
+- Run `/release` to: bump version from Conventional Commits, finalize `CHANGELOG.md`, and create an
+  **SSH-signed annotated tag** (→ "Verified" badge). Push the tag → `release.yml` builds, attests
+  provenance, publishes to PyPI (OIDC), and creates the GitHub Release with `SHA256SUMS`.
+- Verify: `gh attestation verify <wheel> -R rnwolfe/gfly`.
+
+## 5. Docs site (delegate)
+- `/starlight-docs` — scaffold the Astro Starlight site (Diátaxis IA, `llms.txt`, Pagefind search,
+  GitHub Pages deploy + base-path config, AGENTS.md freshness wiring).
+- `/harvest-docs` — fill it from the code (multi-agent: scavenge → IA → per-page writers → reviewers).
+- Auto-generate the Reference quadrant from Click; add the CI freshness gate (regenerate + `git diff --exit-code`).
+
+## 6. Host the landing page
+- `site/index.html` is self-contained (only `gfly.gif` alongside it). Serve via GitHub Pages, or
+  `expose` for a quick LAN review. Optionally reserve `gfly.sh`.
+
+## 7. Discoverability (after a tag + >20 stars where required)
+- **awesome-cli-apps** (one app/PR, format `[gfly](url) - Description.`).
+- **awesome-agent-clis** (ComposioHQ) — folder + the bundled `SKILL.md`.
+- **clis.dev** `/submit`; terminaltrove.com.
+- Launch: **Show HN** (`Show HN: gfly – Google Flights for agents (no API key)`, link the repo, be
+  present the first 30–60 min); r/commandline; Product Hunt 12:01 PT.

gfly-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+<!-- Title must follow Conventional Commits, e.g. `feat: add --max-price filter` -->
+
+## What & why
+
+<!-- What does this change and why? Link any issue: Closes #123 -->
+
+## Checklist
+
+- [ ] Title uses [Conventional Commits](https://www.conventionalcommits.org/) (`feat:` / `fix:` / `docs:` / …)
+- [ ] `uv run pytest -q` passes locally
+- [ ] Output contract respected: **append-only** fields; stdout=data / stderr=chatter
+- [ ] If the agent-facing schema changed: `SCHEMA_VERSION` bumped + `tests/test_schema_snapshot.py` updated
+- [ ] No secrets via argv; read-only invariant preserved (no new mutations)
+- [ ] `CHANGELOG.md` (Unreleased) and docs / `SKILL.md` updated if behavior changed
+- [ ] Commits signed off (`git commit -s`, DCO)

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

@@ -0,0 +1,25 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync
+        run: uv sync --extra dev
+      - name: Test (contract gate)
+        run: uv run pytest -q
+      - name: Schema smoke
+        run: uv run gfly schema > /dev/null

gfly-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: release
+
+# Tag-driven release: build → checksums → build-provenance attestation (SLSA L2) →
+# PyPI Trusted Publishing (OIDC) → GitHub Release with artifacts + SHA256SUMS.
+# Prereqs (one-time, manual): configure PyPI Trusted Publishing for owner=rnwolfe,
+# repo=gfly, workflow=release.yml, environment=pypi.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write        # create the GitHub Release
+  id-token: write        # PyPI OIDC + provenance signing (no stored secrets)
+  attestations: write    # actions/attest-build-provenance
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Generate checksums
+        run: cd dist && sha256sum * > SHA256SUMS && cat SHA256SUMS
+
+      # SLSA L2 build provenance. Skipped on private user-owned repos (the action
+      # fails there and would block the publish).
+      - name: Attest build provenance
+        if: ${{ !github.event.repository.private }}
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: "dist/*.whl, dist/*.tar.gz"
+
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        run: uv publish
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            dist/*.whl dist/*.tar.gz dist/SHA256SUMS \
+            --title "${GITHUB_REF_NAME}" \
+            --notes "See [CHANGELOG.md](https://github.com/rnwolfe/gfly/blob/main/CHANGELOG.md). Verify provenance: \`gh attestation verify <artifact> -R rnwolfe/gfly\`."

gfly-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv/
+.env
+.env.*
+
+# uv
+# (uv.lock IS committed — do not ignore it)
+.vercel

gfly-0.1.0/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md — gfly
+
+Conventions for agents editing this repo. (End users driving the CLI want `gfly agent` /
+`src/gfly/SKILL.md` instead.)
+
+## What this is
+`gfly` is an agent-first, **read-only** CLI for searching Google Flights. Scaffolded by
+agent-cli-factory from the Python (Click) template. `spec.md` is the single source of truth.
+
+## Build / test / run
+```bash
+uv sync --extra dev          # install (uv-managed; Python >=3.10)
+uv run pytest -q             # contract + behavior tests (must stay green)
+uv run gfly schema           # machine-readable command tree
+uv run gfly search JFK LHR --depart 2026-08-01 --json
+python -m gfly --help        # module entry also works
+```
+
+## Layout
+- `src/gfly/cli.py` — Click grammar, `Runtime`, global-flag merge, exit-code mapping. **Contract
+  surface; edit deliberately.** Global flags must work in any position (the `_resolve` walk).
+- `src/gfly/output.py` — stdout=data / stderr=chatter, `--format`, `--select`, `--limit`. **Do not edit.**
+- `src/gfly/errors.py` — exit-code table + structured `AppError` (incl. `BLOCKED` 20, `SCHEMA_DRIFT` 21).
+- `src/gfly/throttle.py` — persistent cross-process politeness/circuit-breaker (real infra).
+- `src/gfly/backend.py` — **PLACEHOLDER** stub data. `cli-implement` replaces with fast-flights
+  (google) + SerpApi (serpapi), behind the same normalized shapes.
+- `src/gfly/auth.py` — **PLACEHOLDER** credential resolution (env only today; keyring later).
+- `src/gfly/SKILL.md` — embedded; printed by `gfly agent`. Regenerate when the surface changes.
+
+## Rules
+- **Read-only tool.** No command mutates. The `--allow-mutations` gate + `Runtime.guard` are kept
+  for contract uniformity but unused; don't add mutations without revisiting `spec.md`.
+- **Output contract is append-only** (contract §10). New fields OK; never rename/remove. Bump
+  `SCHEMA_VERSION` (in `backend.py`) on any breaking shape change and update the snapshot test.
+- **Secrets via stdin/env, never argv** (contract §7).
+- **Heavy imports stay lazy** — inside backend functions, never at module top (keeps `--help`/`schema` fast).
+- Keep `uv run pytest -q` green before every commit; the `schema` test is the contract gate.
+
+## Handoff state
+This is a **scaffold**: it compiles, runs on stub data, and passes contract tests. Next stage is
+`cli-implement` — wire the real engines + auth, replacing `backend.py` / `auth.py`.

gfly-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-23
+
+First public release.
+
+### Added
+- `search` (one-way / round-trip), `dates` (price calendar), `multi` (multi-city), and
+  `airports search` (offline IATA resolution) commands.
+- Swappable backends: `google` (reverse-engineered, zero-auth, default) and `serpapi` (live JSON, keyed).
+- Agent-CLI contract: stable versioned JSON envelope (`schemaVersion`), `schema` self-description,
+  embedded `agent` SKILL.md, `--select`/`--limit`/`--offset` token bounding, `--format json|plain|tsv`.
+- Semantic exit codes incl. `BLOCKED` (20) and `SCHEMA_DRIFT` (21); structured errors with
+  `retryAfterSeconds` on throttle/block.
+- Persistent, cross-process politeness throttle (min-interval + circuit breaker) with fail-fast
+  default and `--wait` opt-in.
+- `auth login|status|logout` (OS keyring + `0600` file fallback, stdin-only secrets); real `doctor`.
+- Prompt-injection hardening: third-party text sanitized and fenced as untrusted by default.
+
+[Unreleased]: https://github.com/rnwolfe/gfly/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rnwolfe/gfly/releases/tag/v0.1.0

gfly-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use gfly, please cite it using these metadata."
+title: "gfly: an agent-first, read-only Google Flights CLI"
+abstract: >-
+  gfly is a read-only, JSON-first command-line tool for searching Google Flights,
+  engineered to be driven by LLM agents: stable versioned output schema, machine-readable
+  self-description, semantic exit codes, token-bounded output, a persistent politeness
+  throttle, and a swappable backend (reverse-engineered Google Flights or SerpApi).
+type: software
+authors:
+  - family-names: Wolfe
+    given-names: Ryan
+license: "MIT OR Apache-2.0"
+repository-code: "https://github.com/rnwolfe/gfly"
+url: "https://github.com/rnwolfe/gfly"
+keywords:
+  - google-flights
+  - cli
+  - agent
+  - llm
+  - flight-search
+  - travel

gfly-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,99 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or
+sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and
+healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the
+  experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit
+  permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and
+will take appropriate and fair corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code,
+wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will
+communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community
+leaders responsible for enforcement at **rn.wolfe@gmail.com**. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any
+incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any
+action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact:** Use of inappropriate language or other behavior deemed unprofessional or unwelcome.
+
+**Consequence:** A private, written warning from community leaders, providing clarity around the nature
+of the violation and an explanation of why the behavior was inappropriate. A public apology may be
+requested.
+
+### 2. Warning
+
+**Community Impact:** A violation through a single incident or series of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No interaction with the people
+involved for a specified period of time. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact:** A serious violation of community standards, including sustained inappropriate
+behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public communication with the
+community for a specified period of time. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact:** Demonstrating a pattern of violation of community standards, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 3.0, available at
+<https://www.contributor-covenant.org/version/3/0/code_of_conduct/>. Contributor Covenant is stewarded
+by the Organization for Ethical Source and licensed under CC BY-SA 4.0.
+
+[homepage]: https://www.contributor-covenant.org

gfly-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to gfly
+
+Thanks for helping! gfly is an agent-first, read-only Google Flights CLI. `spec.md` is the source
+of truth for what it is; the **agent-CLI contract** (read-only, stable JSON, structured errors,
+bounded output) is non-negotiable — keep it intact.
+
+## Setup
+
+```bash
+uv sync --extra dev          # Python >= 3.10, uv-managed
+uv run pytest -q             # tests must stay green
+uv run gfly schema           # machine-readable command tree
+```
+
+## Develop
+
+- **Layout:** `src/gfly/cli.py` (Click grammar + runtime), `backend.py` (google/serpapi engines),
+  `throttle.py` (persistent politeness), `auth.py` (keyring), `output.py` (output discipline —
+  don't break stdout=data/stderr=chatter), `errors.py` (exit-code table). See `AGENTS.md`.
+- **Heavy imports stay lazy** (inside the functions that use them) so `--help`/`schema` stay fast.
+- **Read-only:** no command may mutate remote state. Don't add mutations without revisiting `spec.md`.
+- **Output contract is append-only:** add fields freely; never rename/remove. A breaking shape change
+  means bumping `SCHEMA_VERSION` and updating `tests/test_schema_snapshot.py` in the same PR.
+- **Secrets:** stdin/env only, never argv (contract §7).
+
+## Tests
+
+```bash
+uv run pytest -q
+```
+
+Network is mocked in tests (`tests/conftest.py` monkeypatches the two backend entry points). The
+**schema-snapshot test is the CI gate** — if it fails, you changed the agent-facing contract; make
+that a deliberate, reviewed diff.
+
+## Pull requests
+
+- Use **[Conventional Commits](https://www.conventionalcommits.org/)** (`feat:`, `fix:`, `docs:`,
+  `refactor:`, `test:`, `chore:`) — they drive the changelog and semver bump.
+- Sign off your commits (**DCO**): `git commit -s`. No CLA.
+- Keep PRs focused; update `CHANGELOG.md` (Unreleased) and docs/`SKILL.md` when behavior changes.
+- Green CI required: tests + `gfly schema` smoke.
+
+## Reporting bugs / security
+
+- Bugs: open an issue (the form asks for `gfly --version`, OS, backend, repro, and the JSON error).
+- Security: **do not** open a public issue — see [SECURITY.md](SECURITY.md).