task-notes 0.1.0__tar.gz

task_notes-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# macOS
+.DS_Store
+
+# Python bytecode/cache
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Local task data (if using repo-local custom dir)
+.task-notes/
+tasks/

task_notes-0.1.0/.mise.toml

@@ -0,0 +1,15 @@
+[tools]
+python = "3.13"
+uv = "latest"
+
+[tasks.install]
+description = "Install project dependencies with uv"
+run = "uv sync"
+
+[tasks.test]
+description = "Run full test suite"
+run = "uv run python -m unittest discover -s tests -v"
+
+[tasks.task-help]
+description = "Show task CLI help"
+run = "uv run task --help"

task_notes-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

task_notes-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: task-notes
+Version: 0.1.0
+Summary: LLM-friendly Markdown task notes CLI
+Keywords: agent,cli,llm,markdown,tasks
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: rich>=14.1.0
+Description-Content-Type: text/markdown
+
+# task-notes
+
+一个面向 LLM/Agent 的任务管理 CLI。  
+用 Markdown checklist 保存任务，支持多级子任务、稳定 selector（如 `1.2.3`）、文本/JSON 双输出，以及 Rich 终端展示。
+
+## 功能
+
+- 单项目单文件：`<project>.md`
+- 多级树状任务
+- selector 定位：`1`、`1.2`、`2.1.3`
+- 原子写入 + 文件锁（并发安全）
+- Rich 展示（`ls` 表格、`show` 树）
+- `edit` 支持交互选择（方向键/jk + Space + Enter）
+- `--json` 机读输出
+
+## 安装与运行
+
+### 使用 uv（推荐）
+
+在项目目录内：
+
+```bash
+uv run task --help
+```
+
+临时执行（不安装到全局）：
+
+```bash
+uvx --from . task --help
+```
+
+安装为全局工具：
+
+```bash
+uv tool install --editable .
+task --help
+```
+
+### 使用 pip
+
+```bash
+pip install .
+task --help
+```
+
+## 默认数据目录与安全策略
+
+- 默认目录：`~/.task-notes`
+- 可自定义目录：`--tasks-dir <path>`
+- 安全限制：默认禁止写入非 `~/.task-notes` 目录；若要使用其他目录，必须显式加：
+
+```bash
+--unsafe-external-dir
+```
+
+示例：
+
+```bash
+task --unsafe-external-dir --tasks-dir ./tasks ls
+```
+
+## 快速开始
+
+```bash
+task new app-redesign "梳理需求" "实现功能" "验收发布"
+task add app-redesign --parent 2 "实现 task ls/show"
+task show app-redesign
+task next app-redesign
+task check app-redesign --path 1
+task edit app-redesign --path 2.1 "实现 ls/show/tree 输出"
+```
+
+## 命令概览
+
+```bash
+task ls [--json]
+task show <project> [--json]
+task next <project> [--json]
+task new <project> <content...> [--json]
+task add <project> [--parent <selector>] <content...> [--json]
+task edit <project> --path <selector> <content> [--json]
+task edit <project> -i [--json]
+task del <project> --path <selector> [--json]
+task rm <project> [--json]
+task check <project> --path <selector> [--json]
+task uncheck <project> --path <selector> [--json]
+task toggle <project> --path <selector> [--json]
+```
+
+## 交互式编辑
+
+```bash
+task edit <project> -i
+```
+
+按键：
+
+- `↑/↓` 或 `j/k`：移动光标
+- `Space`：选择当前任务
+- `Enter`：确认并编辑文本
+- `q` / `Esc`：取消
+
+## JSON 输出
+
+适合 tools/LLM 集成：
+
+```bash
+task show app-redesign --json
+```
+
+错误时返回非 0，并输出：
+
+- `ok: false`
+- `error_code`
+- `error_message`
+
+## 开发
+
+运行测试：
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py' -v
+```
+
+## 发布到 PyPI（建议流程）
+
+```bash
+uv build
+uvx twine check dist/*
+# uvx twine upload dist/*
+```

task_notes-0.1.0/README.md

@@ -0,0 +1,131 @@
+# task-notes
+
+一个面向 LLM/Agent 的任务管理 CLI。  
+用 Markdown checklist 保存任务，支持多级子任务、稳定 selector（如 `1.2.3`）、文本/JSON 双输出，以及 Rich 终端展示。
+
+## 功能
+
+- 单项目单文件：`<project>.md`
+- 多级树状任务
+- selector 定位：`1`、`1.2`、`2.1.3`
+- 原子写入 + 文件锁（并发安全）
+- Rich 展示（`ls` 表格、`show` 树）
+- `edit` 支持交互选择（方向键/jk + Space + Enter）
+- `--json` 机读输出
+
+## 安装与运行
+
+### 使用 uv（推荐）
+
+在项目目录内：
+
+```bash
+uv run task --help
+```
+
+临时执行（不安装到全局）：
+
+```bash
+uvx --from . task --help
+```
+
+安装为全局工具：
+
+```bash
+uv tool install --editable .
+task --help
+```
+
+### 使用 pip
+
+```bash
+pip install .
+task --help
+```
+
+## 默认数据目录与安全策略
+
+- 默认目录：`~/.task-notes`
+- 可自定义目录：`--tasks-dir <path>`
+- 安全限制：默认禁止写入非 `~/.task-notes` 目录；若要使用其他目录，必须显式加：
+
+```bash
+--unsafe-external-dir
+```
+
+示例：
+
+```bash
+task --unsafe-external-dir --tasks-dir ./tasks ls
+```
+
+## 快速开始
+
+```bash
+task new app-redesign "梳理需求" "实现功能" "验收发布"
+task add app-redesign --parent 2 "实现 task ls/show"
+task show app-redesign
+task next app-redesign
+task check app-redesign --path 1
+task edit app-redesign --path 2.1 "实现 ls/show/tree 输出"
+```
+
+## 命令概览
+
+```bash
+task ls [--json]
+task show <project> [--json]
+task next <project> [--json]
+task new <project> <content...> [--json]
+task add <project> [--parent <selector>] <content...> [--json]
+task edit <project> --path <selector> <content> [--json]
+task edit <project> -i [--json]
+task del <project> --path <selector> [--json]
+task rm <project> [--json]
+task check <project> --path <selector> [--json]
+task uncheck <project> --path <selector> [--json]
+task toggle <project> --path <selector> [--json]
+```
+
+## 交互式编辑
+
+```bash
+task edit <project> -i
+```
+
+按键：
+
+- `↑/↓` 或 `j/k`：移动光标
+- `Space`：选择当前任务
+- `Enter`：确认并编辑文本
+- `q` / `Esc`：取消
+
+## JSON 输出
+
+适合 tools/LLM 集成：
+
+```bash
+task show app-redesign --json
+```
+
+错误时返回非 0，并输出：
+
+- `ok: false`
+- `error_code`
+- `error_message`
+
+## 开发
+
+运行测试：
+
+```bash
+uv run python -m unittest discover -s tests -p 'test_*.py' -v
+```
+
+## 发布到 PyPI（建议流程）
+
+```bash
+uv build
+uvx twine check dist/*
+# uvx twine upload dist/*
+```

task_notes-0.1.0/docs/requirements.md

@@ -0,0 +1,181 @@
+# Task Notes CLI 需求文档（v2，参考 tdx + nb）
+
+## 1. 产品定位
+
+一个面向 LLM agent 的纯 CLI 任务管理工具：
+- 使用 Markdown 作为唯一存储介质
+- 使用 checklist 表达任务状态
+- 支持单文件多层嵌套任务树
+- 所有操作均可通过稳定编号选择器完成
+
+目标不是替代通用任务系统，而是提供“可脚本化、可追踪、可回放”的任务控制层。
+
+## 2. 参考设计与取舍
+
+参考 `tdx`：
+- 采用 Markdown + checklist + 嵌套树模型
+- 采用路径式选择器（如 `1.2.3`）定位节点
+
+参考 `nb`：
+- 输出中默认提供可复用编号
+- 命令保持简短，适配自动化调用
+
+本项目差异化：
+- 更强调 LLM 调度场景
+- 要求所有关键命令可稳定机读（`--json`）
+- 默认按“项目文件”组织，而不是全局扁平任务池
+
+## 3. 核心场景
+
+LLM 在执行复杂项目时需要：
+- 将项目拆分为多级子任务
+- 随时查询“当前做到哪一步”
+- 对某个子树进行增删改查，不依赖人工打开编辑器
+
+## 4. 数据模型
+
+- `Project`：一个项目对应一个 Markdown 文件
+- `TaskNode`：一条 checklist 项，可包含子节点
+- `Selector`：节点定位符，使用层级路径（如 `2.1.3`）
+
+节点最小字段：
+- 文本内容（必填）
+- 完成状态（`todo`/`done`）
+- 子节点列表
+
+## 5. 文件与目录规范
+
+### 5.1 目录
+
+- 默认目录：`~/.task-notes`（使用当前用户主目录，跨系统兼容）
+- 可通过 `--tasks-dir` 指定其他目录
+- 安全策略：当目录不是 `~/.task-notes` 时，必须额外传 `--unsafe-external-dir`
+- 文件命名：`<project-name>.md`
+- `project-name` 需做 slug 化，避免非法字符
+
+### 5.2 Markdown 结构
+
+```md
+# project-alpha
+
+- [ ] 需求澄清
+  - [x] 收集输入
+  - [ ] 输出接口定义
+- [ ] 开发实现
+  - [ ] CLI 参数解析
+  - [ ] 文件读写与原子更新
+```
+
+约束：
+- 编码：UTF-8
+- 缩进：2 个空格表示一级嵌套
+- 仅使用 `- [ ]` 和 `- [x]`
+
+### 5.3 选择器规则
+
+- 顶层按显示顺序编号：`1`、`2`、`3`
+- 子节点编号：`1.1`、`1.2`、`2.1.3`
+- CLI 必须接受 `1.2.3` 形式；可选兼容 `[1.2.3]`
+- 任何会修改节点的命令都必须支持基于选择器定位
+
+## 6. 命令设计（MVP）
+
+说明：所有命令默认非交互式，适合 LLM 直接调用。
+
+### 6.1 查询类
+
+`task ls`
+- 列出所有项目文件
+- 每行必须包含：顺序标号、项目名、完成数/总数、文件路径
+
+`task show <project>`
+- 展示项目任务树
+- 每行必须包含层级选择器（如 `1.2`）和勾选状态
+
+`task next <project>`
+- 返回“下一个可执行任务”
+- 默认规则：第一个未完成叶子节点
+- 用于让 LLM 快速判断下一步行动
+
+### 6.2 新增类
+
+`task new <project> <content1> <content2> ...`
+- 创建项目文件并写入顶层任务
+- 项目已存在时报错，不覆盖
+
+`task add <project> <content1> <content2> ...`
+- 在顶层末尾追加任务
+
+`task add <project> --parent <selector> <content1> <content2> ...`
+- 在指定父节点下追加子任务
+
+### 6.3 编辑与删除类
+
+`task edit <project> --path <selector> <content>`
+- 仅修改文本，不改变勾选状态
+- 也支持交互式：`task edit <project> -i`
+- 交互式支持：`↑/↓`（或 `j/k`）移动，`Space` 选择，`Enter` 确认
+
+`task del <project> --path <selector>`
+- 删除目标节点及其整个子树
+
+`task rm <project>`
+- 删除整个项目文件
+
+### 6.4 状态类
+
+`task check <project> --path <selector>`
+- 将目标节点置为完成
+
+`task uncheck <project> --path <selector>`
+- 将目标节点置为未完成
+
+`task toggle <project> --path <selector>`（可选）
+- 在完成/未完成间切换
+
+## 7. 输出规范（LLM 友好）
+
+### 7.1 文本模式（默认）
+
+- 成功：`OK <action>: <target>`
+- 失败：`ERR <reason>: <target>`
+- 列表输出默认带顺序编号
+- `task show` 默认带层级选择器编号
+
+### 7.2 JSON 模式
+
+所有核心命令建议支持 `--json`：
+- 至少包含：`ok`、`action`、`project`、`selector`（如有）、`message`
+- 出错时包含：`error_code`、`error_message`
+
+## 8. 一致性与安全
+
+- 文件写入采用原子替换（tmp + rename）
+- 并发写同一文件时不出现半写入内容
+- 默认仅允许写入 `~/.task-notes`，防止误写任意目录
+- 错误返回非 0 退出码
+- 命令执行应幂等可预期（同输入得同结果）
+
+## 9. 验收标准（MVP）
+
+- 能创建项目并生成 Markdown checklist
+- 能展示项目列表与任务树，且默认带编号
+- 能基于 `--path` 对任意层级节点增删改查
+- 能正确处理嵌套任务
+- `task next` 能返回第一个未完成叶子节点
+- 任务不存在、路径不存在、重名创建均有明确错误和非 0 退出码
+- 核心命令在 `--json` 下可被程序稳定解析
+
+## 10. 示例流程（LLM 调度）
+
+```bash
+task new app-redesign "梳理需求" "实现功能" "验收发布"
+task add app-redesign --parent 2 "实现 task ls/show"
+task add app-redesign --parent 2 "实现 task add/edit/del"
+task show app-redesign
+task next app-redesign
+task check app-redesign --path 1
+task edit app-redesign --path 2.1 "实现 ls/show/tree 输出"
+task del app-redesign --path 2.2
+task show app-redesign --json
+```

task_notes-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "task-notes"
+version = "0.1.0"
+description = "LLM-friendly Markdown task notes CLI"
+readme = "README.md"
+requires-python = ">=3.13"
+keywords = ["cli", "tasks", "markdown", "agent", "llm"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "rich>=14.1.0",
+]
+
+[project.scripts]
+task = "task_notes.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/task_notes"]

task_notes-0.1.0/skills/task_skills/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: task-notes-cli
+description: Use this skill when working with the task-notes CLI to create, inspect, update, and automate Markdown task trees, especially for selector-based edits and JSON-safe tool integration.
+metadata:
+  short-description: Operate task-notes CLI safely and consistently
+---
+
+# Task Notes CLI Skill
+
+## When To Use
+
+Use this skill when the user asks to:
+
+- manage project tasks with `task` commands
+- create or update nested task trees
+- operate tasks by selector path (`1`, `1.2`, `2.1.3`)
+- integrate task output with tools/LLM pipelines
+
+Do not use this skill for unrelated generic to-do apps or external SaaS task systems.
+
+## Key Rules
+
+1. Default data directory is `~/.task-notes`.
+2. Non-default directories require explicit opt-in:
+   `--unsafe-external-dir --tasks-dir <path>`.
+3. Prefer `--json` for machine parsing and tool-to-LLM handoff.
+4. Use `task show <project>` to get selectors before mutating.
+5. Keep slug-safe project names; CLI normalizes project names internally.
+
+## Command Patterns
+
+### Query
+
+```bash
+task ls
+task show <project>
+task next <project>
+```
+
+Machine-safe:
+
+```bash
+task show <project> --json
+```
+
+### Create / Add
+
+```bash
+task new <project> "<task1>" "<task2>"
+task add <project> "<task>"
+task add <project> --parent <selector> "<child-task>"
+```
+
+### Update / Remove
+
+```bash
+task edit <project> --path <selector> "<new-text>"
+task edit <project> -i
+task del <project> --path <selector>
+task rm <project>
+```
+
+### Status
+
+```bash
+task check <project> --path <selector>
+task uncheck <project> --path <selector>
+task toggle <project> --path <selector>
+```
+
+## Interactive Edit Mode
+
+Use when user wants terminal UI editing:
+
+```bash
+task edit <project> -i
+```
+
+Keys:
+
+- `↑/↓` or `j/k`: move cursor
+- `Space`: select item
+- `Enter`: confirm
+- `q`/`Esc`: cancel
+
+Interactive edit requires a TTY. In non-interactive subprocess environments, use `--path`.
+
+## Recommended Workflow For Agents
+
+1. `task ls --json` to inspect projects.
+2. `task show <project> --json` to fetch selectors and status.
+3. Pick exact selector target.
+4. Run mutation command (`add/edit/del/check/...`).
+5. Re-run `task show <project> --json` to verify.
+
+## Error Handling
+
+- Any failure returns non-zero exit code.
+- In text mode: `ERR <ErrorClass>: <message>`
+- In JSON mode: parse `ok`, `error_code`, `error_message`
+
+On path safety errors, user must explicitly approve and add `--unsafe-external-dir`.