carrel 0.1.1__tar.gz

carrel-0.1.1/.claude/agents/design-artist.md

@@ -0,0 +1,15 @@
+---
+name: design-artist
+description: Creates carrel's visual identity — hand-authored SVG logo, banner, social preview, palette — and applies it to README and the TUI theme.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+You are the design artist for the carrel project.
+
+Rules:
+1. Everything is original, hand-authored SVG — no copyrighted or trademarked imagery, no traced logos, no external fonts fetched at runtime (system font stacks or outlined shapes only).
+2. Palette and typography are defined once in `docs/BRAND.md` and used everywhere (README badges/hero, SVG assets, TUI CSS). Derive, don't improvise per-file.
+3. Validate every SVG: well-formed XML (`python -c "import xml.etree.ElementTree as ET; ET.parse(...)"`), renders at intended sizes (rasterize a check PNG via ImageMagick if available).
+4. Keep SVGs lean: no editor cruft, viewBox set, dark/light considerations documented.
+
+Completion report format: files created · validation commands + output · palette summary.

carrel-0.1.1/.claude/agents/doc-smith.md

@@ -0,0 +1,15 @@
+---
+name: doc-smith
+description: Writes carrel documentation — reference pages, cookbook recipes, guides — grounded in actual command output, never invented flags.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+You are the documentation writer for the carrel project.
+
+Rules:
+1. Ground every documented flag/behavior in reality: run `uv run carrel <cmd> --help` and real invocations; paste real output into docs (trim noise). Never document a flag you didn't see.
+2. Follow the voice: practical, example-first, second person, no marketing fluff inside reference docs.
+3. Cookbook recipes must be runnable as-is from repo root and state expected output; you must run each one before writing it down.
+4. Cross-link docs (relative links). Product name comes from product.json — write "Carrel"/"carrel" in prose but never hardcode it in generated snippets where a variable exists.
+
+Completion report format: files touched · every recipe/command you executed with output tail · gaps or doc debt you noticed.

carrel-0.1.1/.claude/agents/integration-reviewer.md

@@ -0,0 +1,13 @@
+---
+name: integration-reviewer
+description: Adversarial reviewer that verifies cross-module consistency and hunts real bugs in carrel by executing commands, not by reading reports.
+tools: Read, Bash, Grep, Glob
+---
+
+You are the integration reviewer for the carrel project. You do not trust completion reports — you verify by execution.
+
+Process:
+1. Run the full suite: `uv run pytest -q`. Any failure is a finding.
+2. Exercise the contracts: for each command under review run `--help`, a real fixture invocation, its `--json` mode (must be parseable: pipe to `python -m json.tool`), and a failure path (missing file → exit 4; you can fake a missing binary with PATH surgery → exit 3).
+3. Check cross-module drift: exit codes match CLAUDE.md; JSON shapes match specs; no module bypasses the adapter layer (`grep -rn "subprocess" src/carrel/commands/` should only show adapter imports).
+4. Report findings ranked by severity with exact reproduction commands and observed vs expected output. Do NOT fix anything — report only.

carrel-0.1.1/.claude/agents/module-builder.md

@@ -0,0 +1,17 @@
+---
+name: module-builder
+description: Implements one carrel module from its spec in specs/, including its tests. Use for building CLI command modules against the core library contracts.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+You are a module builder for the carrel project. You implement exactly one spec per dispatch.
+
+Rules:
+1. Read your assigned spec in `specs/`, plus `docs/ARCHITECTURE.md` (Global contracts) and `CLAUDE.md` before writing code.
+2. Respect your write boundary exactly — touch only the paths your spec's **Owns** line lists.
+3. Use the core library: `carrel.core.adapters` (never subprocess directly), `carrel.core.output.emit/CarrelInputError/ExitCode`, `carrel.core.filetypes`, `carrel.core.textextract`, `carrel.core.db`. Command modules export a click command named `cmd`.
+4. Write real tests (pytest) alongside the code and RUN them: `uv run pytest tests/test_<yours>.py -q`. Tests needing optional binaries use the `needs()` skip helper from conftest.
+5. No stubs, no TODOs. If a spec item can't be finished, implement the rest, and report the cut explicitly.
+6. Verify `uv run carrel <yourcmd> --help` and one real invocation on a fixture before reporting.
+
+Completion report format (required): files touched · tests written + pass/fail output (paste the pytest tail) · deviations from spec · open issues.

carrel-0.1.1/.claude/agents/test-engineer.md

@@ -0,0 +1,16 @@
+---
+name: test-engineer
+description: Builds fixtures, integration tests, and end-to-end cookbook validation for carrel. Use when tests span modules or need real file fixtures.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+You are the test engineer for the carrel project.
+
+Rules:
+1. Read `specs/14-fixtures.md`, `docs/ARCHITECTURE.md` §Testing, and `CLAUDE.md` first.
+2. Fixtures are generated programmatically (`tests/fixtures/generate.py`) — idempotent, deterministic where possible, committed outputs. Never hand-craft binary files.
+3. Integration tests drive the real CLI (`uv run carrel ...` via subprocess or CliRunner) on real fixtures — no mocking of the filesystem.
+4. Tests that need an optional binary skip with a reason when it's missing; on THIS machine most binaries exist, so verify they actually run here.
+5. Every claim in your report must come from executed pytest output. Paste the tail.
+
+Completion report format: files touched · commands run + real output tails · coverage gaps you noticed · open issues.

carrel-0.1.1/.claude-plugin/marketplace.json

@@ -0,0 +1,57 @@
+{
+  "name": "carrel",
+  "owner": {
+    "name": "Colton Bearden"
+  },
+  "metadata": {
+    "description": "Carrel — a library desk for your files, and your agents. Local file toolkit plugins: convert, OCR, inspect, index/search, pack for LLM context, organize, watch, and agent workflows.",
+    "pluginRoot": "./plugins"
+  },
+  "plugins": [
+    {
+      "name": "carrel-convert",
+      "source": "./plugins/carrel-convert",
+      "description": "Convert, OCR, thumbnail, and narrate local files with the carrel CLI: /convert, /ocr, /thumb, /audiobook, plus a doc-converter batch agent.",
+      "version": "0.1.0",
+      "author": { "name": "Colton Bearden" },
+      "license": "MIT",
+      "keywords": ["files", "convert", "pdf", "ocr", "thumbnails", "audiobook", "tts"]
+    },
+    {
+      "name": "carrel-inspect",
+      "source": "./plugins/carrel-inspect",
+      "description": "Inspect, diff, search, and pack local files for LLM context with the carrel CLI: /inspect, /diff, /search, /pack, plus a context-packing skill.",
+      "version": "0.1.0",
+      "author": { "name": "Colton Bearden" },
+      "license": "MIT",
+      "keywords": ["files", "inspect", "diff", "search", "fts5", "pack", "llm-context"]
+    },
+    {
+      "name": "carrel-organize",
+      "source": "./plugins/carrel-organize",
+      "description": "Organize, dedupe, tag, and annotate local files with the carrel CLI: /organize, /dedupe, /tag, /note-file.",
+      "version": "0.1.0",
+      "author": { "name": "Colton Bearden" },
+      "license": "MIT",
+      "keywords": ["files", "organize", "dedupe", "tags", "notes"]
+    },
+    {
+      "name": "carrel-watch",
+      "source": "./plugins/carrel-watch",
+      "description": "Watch folders and run carrel actions on file events: /watch-folder plus a watch-automation recipe skill.",
+      "version": "0.1.0",
+      "author": { "name": "Colton Bearden" },
+      "license": "MIT",
+      "keywords": ["files", "watch", "automation", "watchdog", "folder-actions"]
+    },
+    {
+      "name": "carrel-agent",
+      "source": "./plugins/carrel-agent",
+      "description": "Agentic file librarian for carrel desks: file-librarian agent, agent-workflows skill, carrel MCP server (search/pack/inspect), and a PostToolUse hook that re-indexes files Claude writes.",
+      "version": "0.1.0",
+      "author": { "name": "Colton Bearden" },
+      "license": "MIT",
+      "keywords": ["agent", "mcp", "index", "search", "hooks", "librarian"]
+    }
+  ]
+}

carrel-0.1.1/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# Renders the Sponsor button once the account is enrolled in GitHub Sponsors.
+github: [coltonbearden]

carrel-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,53 @@
+name: Bug Report
+description: File a bug report to help us improve
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the sections below.
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: What version of carrel are you running?
+      placeholder: "v1.2.0"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run '...'
+        2. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: false
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: "OS, Python/Node version, Docker version, etc."
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      render: shell
+    validations:
+      required: false

carrel-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussions / Q&A
+    url: https://github.com/FirstCastSolutions423/carrel/discussions
+    about: Ask questions and discuss ideas here rather than filing an issue.

carrel-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the pain point this feature would address.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd be willing to submit a PR for this

carrel-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+{{What does this PR do, in 1-2 sentences?}}
+
+## Related issue
+Closes #{{issue_number}}
+
+## Changes
+- {{change 1}}
+- {{change 2}}
+
+## Testing
+{{How was this tested? Include commands run.}}
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] Docs updated
+- [ ] Changelog entry added
+- [ ] No unrelated changes

carrel-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install docs dependencies
+        run: uv sync --group docs --no-dev
+      - name: Build site
+        run: uv run mkdocs build --strict
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

carrel-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+# Publishes carrel to PyPI via Trusted Publishing (OIDC — no API token).
+# Fires only when a GitHub Release is published (release timing is the
+# operator's). Requires the pending-publisher entry on pypi.org:
+#   project: carrel · owner: FirstCastSolutions423 · repo: carrel
+#   workflow: publish.yml · environment: pypi
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist and wheel
+        run: pipx run build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

carrel-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,50 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install external tools (full-capability run)
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y -q --no-install-recommends \
+            pandoc poppler-utils qpdf ghostscript weasyprint \
+            tesseract-ocr ocrmypdf imagemagick libimage-exiftool-perl \
+            ffmpeg pngquant icoutils jq miller ripgrep espeak-ng gnupg
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Regenerate fixtures (idempotence check)
+        run: uv run python tests/fixtures/generate.py
+
+      - name: Run test suite
+        run: uv run pytest -q
+
+      - name: CLI smoke
+        run: |
+          uv run carrel --version
+          uv run carrel doctor
+          uv run carrel --json pack src/carrel/core --tree-only > /dev/null
+
+  test-minimal:
+    # degradation guard: no optional binaries installed at all
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+      - run: uv sync
+      - name: Suite must pass via skips, never crashes
+        run: uv run pytest -q
+      - name: doctor reports missing tools without failing
+        run: uv run carrel doctor

carrel-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+node_modules/
+.carrel/
+carrel-out/
+site/

carrel-0.1.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## v0.1.1 — 2026-08-12
+
+First PyPI release: `pip install carrel`, published from CI via PyPI Trusted
+Publishing (.github/workflows/publish.yml, OIDC — no token). Repo-side
+discoverability round: CODE_OF_CONDUCT, issue forms + PR template,
+CITATION.cff, FUNDING.yml, Related-projects README section, repo homepage +
+Discussions + social preview. No CLI behavior changes.
+
+## v0.1.0 — 2026-07-16
+
+Initial release: carrel CLI (23 commands), desk TUI, Claude Code plugin
+marketplace (5 plugins), MCP server, docs package. Built 2026-07-16.

carrel-0.1.1/CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "carrel"
+version: "0.1.0"
+date-released: "2026-07-16"
+authors:
+  - family-names: "Bearden"
+    given-names: "Colton"
+repository-code: "https://github.com/FirstCastSolutions423/carrel"
+url: "https://github.com/FirstCastSolutions423/carrel"
+license: "MIT"
+keywords:
+  - "claude-code"
+  - "claude-code-plugins"
+  - "cli"
+  - "file-management"
+  - "mcp"

carrel-0.1.1/CLAUDE.md

@@ -0,0 +1,44 @@
+# Project CLAUDE.md — Local File Toolkit + Plugin Marketplace
+
+**Resume from disk:** read `STATE.md` first — it always says what's done, what's in flight, and what's next. Decisions live in `docs/DECISIONS.md`.
+
+## Product name — single source of truth
+
+The product name, tagline, and version live ONLY in `product.json` at the repo root. Never hardcode the name in code. Docs/manifests may use the name in prose, but anything generated (CLI banner, `--version`, asset text) must read `product.json`. `scripts/finalize.sh` performs renames by updating `product.json` and regenerating derived references.
+
+## Stack & layout
+
+- Python ≥3.12 (dev box: 3.14), managed by **uv** (`pyproject.toml`, `uv run`, `uv sync`).
+- Core library in `src/<pkg>/`; umbrella CLI entry in `pyproject.toml [project.scripts]`.
+- All external binaries are called through the single adapter layer `src/<pkg>/adapters.py` — never `subprocess` directly from command modules. Adapters do capability detection.
+- Repo root doubles as a Claude Code plugin marketplace: `.claude-plugin/marketplace.json` + `plugins/<name>/`.
+
+## Coding standards
+
+- Python: type hints on public functions, `pathlib.Path` over strings, no global state, f-strings, stdlib `argparse`-free — we use the CLI framework chosen in Phase 2 (see docs/ARCHITECTURE.md).
+- Every CLI command MUST have: working `--help`, `--json` flag when output is data, ≥1 test, graceful degradation when an optional binary is missing (actionable message + install hint, exit code 3 — never a traceback, never a silent no-op).
+- No stubs/TODO/placeholder code in shipped commands. Cut and document in `docs/FEATURES.md` instead.
+- Wrap, don't rewrite: prefer proven libraries/binaries via the adapter layer; attribute in docs/LICENSES section.
+
+## Exit code convention
+
+- `0` success
+- `1` general/unexpected error (message to stderr, no traceback unless `--debug`)
+- `2` bad usage/arguments (argparse-style)
+- `3` missing optional dependency (message names the binary + install hint)
+- `4` input file not found / unreadable / unsupported type
+- `5` operation produced no result (e.g., search with no hits when `--fail-empty`)
+
+## Testing
+
+- `uv run pytest` from repo root runs everything. Fixtures in `tests/fixtures/` (generated by `tests/fixtures/generate.py`; never hand-edit binaries).
+- Tests that need an optional binary must skip (with reason) when it's absent, not fail.
+
+## Subagent rules
+
+Subagents: read your spec in `specs/`, respect your write boundary exactly, and report: files touched, tests written+run (with real output), deviations from spec, open issues. Claims are verified by execution — write tests that actually run.
+
+## Git
+
+- Branch `main`. Commits at phase gates `phase(N): ...` and waves `wave(N): ...`.
+- Never commit generated junk (see .gitignore); fixtures ARE committed once generated.

carrel-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,21 @@
+# Code of Conduct
+
+## Our Pledge
+We as members, contributors, and maintainers pledge to make participation in carrel a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity/expression, experience level, nationality, personal appearance, race, religion, or sexual identity/orientation.
+
+## Our Standards
+Examples of behavior that contributes to a positive environment:
+- Using welcoming and inclusive language
+- Respecting differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+- Harassment, insults, or derogatory comments
+- Public or private harassment
+- Publishing others' private information without consent
+
+## Enforcement
+Instances of abusive behavior may be reported to inbox@coltonbearden.com. All complaints will be reviewed and investigated promptly and fairly.
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

carrel-0.1.1/LICENSE

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