yakherder 0.1.79__tar.gz

yakherder-0.1.79/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

yakherder-0.1.79/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: yakherder
+Version: 0.1.79
+Summary: Filesystem-native task tracker for humans and AI agents
+Author: Joel
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/joelgwebber/yaks
+Project-URL: Repository, https://github.com/joelgwebber/yaks
+Project-URL: Issues, https://github.com/joelgwebber/yaks/issues
+Keywords: task-tracker,cli,tui,agents,productivity
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# Yaks
+
+[![skills.sh](https://skills.sh/b/joelgwebber/yaks)](https://skills.sh/joelgwebber/yaks)
+
+Filesystem-native task tracker for AI coding agents. Markdown files with YAML frontmatter, no database, no daemon.
+
+Yaks gives your AI coding assistant persistent task tracking across sessions. Tasks are stored as markdown files (with YAML frontmatter for metadata) in a `.yaks/` directory within your project — readable, diffable, and friendly to version control. Use it two ways: **commit `.yaks/`** to share a tracker with your team, or **gitignore it** to keep a private, local-only scratchpad. It ships as a plugin for Claude Code and OpenAI Codex, as an installable skill for Zed, and as a standalone CLI for any other agent.
+
+## Install
+
+### Claude Code
+
+```
+claude plugin add --from /path/to/yaks
+```
+
+The plugin bundles the `yak` and `yak-tracker` skills, which activate automatically when `.yaks/` exists in a project. The skills teach the agent to drive the `yaks` CLI directly (see [CLI tool](#cli-tool-any-agent) below to install it).
+
+### OpenAI Codex
+
+Yaks ships a `.codex-plugin/plugin.json` manifest. Install it from the Codex plugin browser, or point Codex at a local clone:
+
+```bash
+codex plugin marketplace add ./path/to/yaks
+```
+
+The `.claude-plugin/marketplace.json` legacy path also works if Codex picks it up automatically from a project root.
+
+### Zed
+
+Yaks ships a `skills/yak/` skill directory that follows the [Agent Skills spec](https://zed.dev/docs/ai/skills). Install via [skills.sh](https://skills.sh/joelgwebber/yaks):
+
+```bash
+# Global (available in all projects)
+npx skills add joelgwebber/yaks
+```
+
+Or copy manually from a local clone:
+
+```bash
+# Global
+cp -r /path/to/yaks/skills/yak ~/.agents/skills/yak
+cp -r /path/to/yaks/skills/yak-tracker ~/.agents/skills/yak-tracker
+
+# Project-local (inside your project, requires trusted worktree)
+cp -r /path/to/yaks/skills/yak  .agents/skills/yak
+cp -r /path/to/yaks/skills/yak-tracker  .agents/skills/yak-tracker
+```
+
+Once installed, the `yak` skill appears in Zed's skill catalog and activates automatically when the agent detects a `.yaks/` directory. You can also invoke it with `/yak` in the message editor. The `yak-tracker` skill relates yaks to external issue trackers as a one-way projection (rollup, import-once, outbound draft).
+
+The skills instruct Zed's agent to use the `yaks` CLI, so install that too (see [CLI tool](#cli-tool-any-agent) below).
+
+### CLI tool (any agent)
+
+The distribution is published on PyPI as **`yakherder`**; the command it installs is **`yaks`** (the name `yaks` was already taken on PyPI):
+
+```bash
+# From PyPI (recommended) — puts `yaks` on your $PATH
+uv tool install yakherder
+
+# Or straight from GitHub / a local clone
+uv tool install git+https://github.com/joelgwebber/yaks
+uv tool install /path/to/yaks
+```
+
+All subcommands work: `yaks list`, `yaks create`, `yaks tui`, etc. Upgrade with `uv tool upgrade yakherder`.
+
+Prefer not to install anything? Run it zero-install in an isolated environment:
+
+```bash
+uvx yakherder tui          # or any subcommand: uvx yakherder list, uvx yakherder next, ...
+```
+
+For agents that don't have a Yaks plugin (Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, etc.), the CLI is the integration point — see [Configuring your AI assistant](#configuring-your-ai-assistant-to-use-yaks) below.
+
+## Quick start
+
+Initialize task tracking in any project, from a terminal or via your agent:
+
+```bash
+yaks init
+```
+
+This creates a `.yaks/` directory with `hairy/`, `shaving/`, and `shorn/` subdirectories, plus a `config.yaml`. It also appends a workflow mandate to `CLAUDE.md` or `AGENTS.md` (defaults to `AGENTS.md`; use `--agents` to force it even when a `CLAUDE.md` exists).
+
+From there your coding assistant creates and manages tasks by calling the `yaks` CLI:
+
+```bash
+yaks create --title "Add retry logic to API client" --type feature --priority 1
+yaks list
+yaks next
+yaks shave yak-a1b2
+yaks shorn yak-a1b2
+```
+
+Agents drive these through shell/Bash tool access — there are no editor-specific slash commands to learn.
+
+## How it works
+
+- **Status is a directory.** A task in `.yaks/hairy/` needs shaving. Move it to `.yaks/shaving/` and it's in progress. Move it to `.yaks/shorn/` and it's done. No status field in the YAML — the filesystem is the source of truth.
+- **Tasks are markdown with frontmatter.** Every task is a single `.md` file. Structured metadata (ID, title, type, priority, timestamps, dependencies, labels) lives in YAML frontmatter. The markdown body is the description.
+- **Parent/child tasks.** Create subtasks with `--parent TASK_ID`. Children get dot-suffixed IDs (`yak-a1b2.1`, `yak-a1b2.2`). The relationship is implicit from the ID — no extra YAML field. `show` displays the hierarchy automatically.
+- **Dependencies are first-class.** Tasks can depend on other tasks. `yaks next` shows only tasks whose dependencies are all shorn. `yaks tangled` shows what's stuck.
+- **Artifacts.** Attach files or clipboard images to tasks with `attach`. They're stored in `.yaks/artifacts/{task-id}/` and linked from the task body.
+- **Git-friendly.** Task files are small, human-readable, and merge cleanly. Git history is your audit log.
+- **Local or team.** Commit `.yaks/` to share tasks with collaborators (team mode), or gitignore it for a private local-only scratchpad. In local-only mode, keep yak files — and their IDs — out of commits, PRs, and external trackers; the skill spells out the distinction so your agent doesn't leak private planning notes.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `yaks init` | Initialize `.yaks/` in the current project |
+| `yaks create` | Create a new task |
+| `yaks list` | List tasks with optional filters |
+| `yaks show` | Show full details of a task |
+| `yaks update` | Update a task's fields |
+| `yaks shave` | Start shaving a yak |
+| `yaks shorn` | Mark a yak as shorn |
+| `yaks regrow` | Regrow a shorn yak |
+| `yaks slaughter` | Slaughter a yak (move to hidden `dead/` state) |
+| `yaks revive` | Revive a dead yak back to hairy |
+| `yaks next` | Show yaks ready to shave (all deps met) |
+| `yaks tangled` | Show tangled yaks (unshorn dependencies) |
+| `yaks search` | Search tasks by keyword |
+| `yaks dep` | Add or remove dependencies between tasks |
+| `yaks reparent` | Move a task to a new parent or promote to top-level |
+| `yaks stats` | Show task statistics |
+| `yaks attach` / `yaks detach` | Attach or remove file/image artifacts on a task |
+| `yaks import-beads` | Import tasks from a beads JSONL export |
+
+Every command accepts `--json` where applicable for machine-readable output.
+
+## Filtering
+
+All query commands (`list`, `search`, `next`, `tangled`) share the same filter flags. Filters AND across dimensions; within a repeatable flag, values are OR'd:
+
+- `--status S` — filter by status (repeatable): `hairy`, `shaving`, `shorn`, `dead`
+- `--type T` — filter by type (repeatable): `bug`, `feature`, `task`, `idea`
+- `--priority P` — filter by priority (repeatable): `1`, `2`, `3`
+- `--label L` — match any listed label (repeatable)
+- `--search Q` — substring match on title, description, or id
+- `--ready` — only tasks whose dependencies are all resolved
+- `--tangled` — only tasks with at least one unresolved dependency
+- `--parent-of ID` — only descendants of a given task
+
+Examples:
+
+```bash
+yaks list --type bug --type feature --priority 1
+yaks list --label auth --search retry
+yaks next --type bug
+```
+
+## TUI
+
+Yaks includes a curses-based terminal UI for interactive task management:
+
+```
+yaks tui
+```
+
+The TUI provides:
+
+- **Tab-based status views** — switch between hairy, shaving, and shorn tabs
+- **Tree display** — parent/child tasks rendered as a collapsible tree
+- **Detail pane** — full task view with rendered markdown, metadata, dependencies, and artifacts
+- **Inline mutations** — change status, priority, type, title, labels, and dependencies without leaving the TUI
+- **Filter drawer** — drop-down filter panel (press `/` for search, `f` for full filter) with live preview as you type
+- **Help overlay** — press `?` for a full keybinding reference
+- **Vim-style editing** — optional vim keybindings in all text inputs (see Configuration below)
+
+## Task format
+
+Tasks are `.md` files with YAML frontmatter for metadata. The markdown body is the description.
+
+```markdown
+---
+id: yak-a1b2
+title: Fix the login crash
+type: bug
+priority: 2
+created: "2026-02-16T10:00:00Z"
+updated: "2026-02-16T10:30:00Z"
+depends_on:
+  - yak-c3d4
+labels:
+  - auth
+source: https://jira.example.com/browse/PROJ-123
+---
+
+Users see a crash on the login screen when
+submitting with an empty password field.
+```
+
+Frontmatter fields:
+
+- **id** — Auto-generated as `{prefix}-{4 hex chars}` (prefix from config), or `{parent-id}.N` for child tasks
+- **title** — Short description of the task
+- **type** — `bug`, `feature`, `task`, or `idea`
+- **priority** — `1` (highest) through `3` (lowest)
+- **created** / **updated** — ISO 8601 timestamps
+- **depends_on** — Optional list of task IDs that must be shorn first
+- **labels** — Optional list of string tags
+- **source** — Optional URL linking to an external issue (Jira, GitHub Issues, Linear, etc.). Many yaks can roll up to one external issue; `yaks rollup` groups them, and a yak with no `source:` inherits its nearest ancestor's.
+
+## Configuration
+
+Yaks reads configuration from two levels, with per-project values overriding user-global ones:
+
+1. **User-global** — `~/.config/yaks/config.yaml` (created by `yaks init` if it doesn't exist)
+2. **Per-project** — `.yaks/config.yaml`
+
+Available settings:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `prefix` | directory name | ID prefix for new tasks (e.g., `api` → `api-f3a1`) |
+| `vim_mode` | `false` | Vim-style insert/normal mode editing in TUI text inputs |
+
+## Configuring your AI assistant to use Yaks
+
+`yaks init` automatically appends a workflow mandate to your project's `AGENTS.md` (or an existing `CLAUDE.md`). Use `--agents` to force writing to `AGENTS.md` even when a `CLAUDE.md` is present.
+
+`AGENTS.md` is the most portable choice — it's recognized by Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Zed, Cursor, Windsurf, and Aider without any extra configuration.
+
+If you already have `.yaks/` set up and want to add the mandate manually, add this block to your context file:
+
+```markdown
+## Task tracking
+
+This project uses Yaks. The Yaks skill has the full workflow.
+
+1. Never start coding without a shaving yak. No exceptions.
+2. Shear a yak as soon as its work is done. If the project commits its yaks (`.yaks/` is tracked by git), commit the shorn yak alongside the code that completed it; if `.yaks/` is gitignored, keep yak files — and their IDs — out of commits, PRs, and anything external.
+3. Check existing yaks before creating new ones.
+4. Append progress notes to yak descriptions as you work.
+5. When unsure what's next, run `yaks next` — don't freelance.
+```
+
+### Platform-specific context files
+
+For agents that have their own context file convention, you can also create platform-specific files. Each file should contain the mandate above plus a note that the `yaks` CLI is available:
+
+| Platform | File | Notes |
+|----------|------|-------|
+| Claude Code | `CLAUDE.md` | Plugin handles skill injection automatically |
+| OpenAI Codex | `AGENTS.md` | Plugin handles skill injection automatically |
+| GitHub Copilot | `.github/copilot-instructions.md` | Highest-priority slot for Copilot |
+| Gemini CLI | `GEMINI.md` | Also read by Zed as a fallback |
+| Cursor | `.cursor/rules/yaks.mdc` | Use `alwaysApply: true` in frontmatter |
+| Windsurf | `.windsurfrules` | |
+| Zed | `AGENTS.md` or install the skill | Skill gives richer activation; see [Install](#install) |
+
+For Claude Code and Codex, the skill activates automatically when `.yaks/` exists and carries the full workflow details, command reference, and task format documentation. The mandate block above is what ensures your assistant actually follows the workflow.
+
+## Requirements
+
+- Python 3.10+
+- PyYAML (`pyyaml>=6.0`) and prompt-toolkit (`prompt-toolkit>=3.0.52`, for the TUI)
+
+Installing via `uv tool install yakherder` (or running `uvx yakherder`) pulls these in automatically into an isolated environment — nothing is added to your system or project Python.
+
+## License
+
+Apache 2.0