@nijaru/tk 0.0.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,229 @@
+# tk
+
+Task tracker for AI agents. Simple, fast, git-friendly.
+
+**Requires [Bun](https://bun.sh) runtime.**
+
+## Install
+
+```bash
+# Install Bun first (if not installed)
+curl -fsSL https://bun.sh/install | bash
+
+# Then install tk globally
+bun add -g @nijaru/tk
+
+# Or run from source
+git clone https://github.com/nijaru/tk.git
+cd tk && bun install
+bun run src/cli.ts --help
+```
+
+## Quick Start
+
+```bash
+$ cd myapp
+$ tk init                               # project auto-derived from directory
+Initialized: .tasks
+
+$ tk add "Implement auth" -p 1
+myapp-a7b3
+
+$ tk add "Write tests" -p 2
+myapp-x9k2
+
+$ tk block x9k2 a7b3                # tests blocked by auth (just use ref)
+
+$ tk ready                          # what can I work on?
+ID           PRI STATUS     TITLE
+------------------------------------------------------------
+myapp-a7b3   p1  open       Implement auth
+
+$ tk start a7b3                     # just the ref works everywhere
+Started: myapp-a7b3
+
+$ tk log a7b3 "Using JWT approach"
+Logged: myapp-a7b3
+
+$ tk done a7b3
+Completed: myapp-a7b3
+
+$ tk ready                          # tests now unblocked
+ID           PRI STATUS     TITLE
+------------------------------------------------------------
+myapp-x9k2   p2  open       Write tests
+```
+
+## Commands
+
+| Command                     | Description                                |
+| --------------------------- | ------------------------------------------ |
+| `tk init`                   | Initialize (project name from directory)   |
+| `tk add <title>`            | Create task                                |
+| `tk ls` / `tk list`         | List tasks                                 |
+| `tk ready`                  | List open + unblocked tasks                |
+| `tk show <id>`              | Show task details                          |
+| `tk start <id>`             | Start working (open → active)              |
+| `tk done <id>`              | Complete task                              |
+| `tk reopen <id>`            | Reopen task                                |
+| `tk edit <id>`              | Edit task                                  |
+| `tk log <id> <msg>`         | Add log entry                              |
+| `tk block <id> <blocker>`   | Add dependency (id blocked by blocker)     |
+| `tk unblock <id> <blocker>` | Remove dependency                          |
+| `tk rm` / `tk remove <id>`  | Delete task                                |
+| `tk clean`                  | Remove old done tasks (default: 7d)        |
+| `tk config`                 | Show/set configuration                     |
+| `tk completions <shell>`    | Output shell completions (bash, zsh, fish) |
+| `tk help [command]`         | Show help (or command-specific help)       |
+
+## Add Options
+
+```bash
+tk add "Title" -p 2                  # Priority (0-4)
+tk add "Title" -P api                # Project prefix
+tk add "Title" -d "Description"      # Description
+tk add "Title" -l bug,urgent         # Labels (CSV)
+tk add "Title" -A nick,alice         # Assignees (CSV, @me for git user)
+tk add "Title" --parent a7b3         # Parent task (ref works)
+tk add "Title" --estimate 3          # Estimate (user-defined units)
+tk add "Title" --due 2026-01-15      # Due date (YYYY-MM-DD)
+tk add "Title" --due +7d             # Relative due date (+Nh/+Nd/+Nw/+Nm)
+```
+
+## List Options
+
+```bash
+tk ls                          # List tasks (limit 20)
+tk ls -a                       # Show all (no limit)
+tk ls -s active                # Filter by status
+tk ls -p 1                     # Filter by priority
+tk ls -P api                   # Filter by project
+tk ls -l bug                   # Filter by label
+tk ls --assignee nick          # Filter by assignee
+tk ls --parent a7b3            # Filter by parent (ref works)
+tk ls --roots                  # Top-level tasks only
+tk ls --overdue                # Overdue tasks only
+tk ls -n 10                    # Limit results
+```
+
+## Edit Options
+
+```bash
+tk edit a7b3 -t "New title"    # Update title
+tk edit a7b3 -p 1              # Update priority
+tk edit a7b3 -l +urgent        # Add label
+tk edit a7b3 -l -bug           # Remove label (use --labels=-bug)
+tk edit a7b3 --due -           # Clear due date
+tk edit a7b3 --parent -        # Clear parent
+```
+
+## Clean Options
+
+```bash
+tk clean                       # Remove done tasks older than 7 days
+tk clean --older-than 30d      # Custom retention (Nd/Nw/Nm/Nh)
+tk clean -a                    # Remove all done tasks (ignore age)
+```
+
+## Config
+
+```bash
+tk config                                       # Show all config
+tk config project                               # Show default project
+tk config project api                           # Set default project
+tk config project lsmvec --rename cloudlsmvec   # Rename all cloudlsmvec-* → lsmvec-*
+tk config alias                                 # List aliases
+tk config alias web src/web                     # Add alias
+tk config alias --rm web                        # Remove alias
+```
+
+## Task IDs
+
+Format: `project-ref` (e.g., `myapp-a7b3`, `api-x9k2`, `web-3m8p`)
+
+- **Just use the ref** - `a7b3` works everywhere, no need to type `myapp-a7b3`
+- Project prefix auto-derived from directory name on init (or use `-P` flag)
+- Random 4-char alphanumeric ref (a-z, 0-9)
+- Prefix matching: `a7` resolves to `myapp-a7b3` if unambiguous
+- Random IDs prevent merge conflicts in team workflows
+
+## Priority
+
+| Value | Name   | Description      |
+| ----- | ------ | ---------------- |
+| 0     | none   | No priority set  |
+| 1     | urgent | Drop everything  |
+| 2     | high   | Important        |
+| 3     | medium | Normal (default) |
+| 4     | low    | Nice to have     |
+
+Accepts: `0-4`, `p0-p4`, or `none/urgent/high/medium/low`
+
+## Status Flow
+
+```
+open → active → done
+```
+
+## Storage
+
+```
+.tasks/
+  config.json     # Project config
+  tk-a7b3.json    # Task files
+  api-x9k2.json
+```
+
+Each task file:
+
+```json
+{
+  "project": "tk",
+  "ref": "a7b3",
+  "title": "Implement auth",
+  "description": "Use JWT approach",
+  "status": "open",
+  "priority": 3,
+  "labels": ["bug"],
+  "assignees": ["nick"],
+  "parent": null,
+  "blocked_by": [],
+  "estimate": 3,
+  "due_date": "2026-01-15",
+  "logs": [{ "ts": "2026-01-05T10:00:00Z", "msg": "Started research" }],
+  "created_at": "2026-01-05T09:00:00Z",
+  "updated_at": "2026-01-05T10:00:00Z",
+  "completed_at": null,
+  "external": {}
+}
+```
+
+## Global Options
+
+- `-C <dir>` - Run in different directory (`tk -C ../other-repo ls`)
+- `--json` - Output as JSON (works anywhere: `tk ls --json` or `tk --json ls`)
+- `-h, --help` - Show help (`tk add --help` or `tk help add` for command help)
+- `-V, --version` - Show version
+
+## Environment
+
+- `NO_COLOR` - Disable colored output (any non-empty value)
+
+Colors are also automatically disabled when output is piped.
+
+## Shell Completions
+
+```bash
+# Bash (add to ~/.bashrc)
+eval "$(tk completions bash)"
+
+# Zsh (add to ~/.zshrc)
+eval "$(tk completions zsh)"
+
+# Fish (add to ~/.config/fish/config.fish)
+tk completions fish | source
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@nijaru/tk",
+	"version": "0.0.1",
+	"description": "Task tracker for AI agents",
+	"type": "module",
+	"bin": {
+		"tk": "./src/cli.ts"
+	},
+	"files": [
+		"src",
+		"LICENSE",
+		"README.md"
+	],
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"scripts": {
+		"dev": "bun run src/cli.ts",
+		"build": "bun build src/cli.ts --compile --outfile tk",
+		"test": "bun test",
+		"lint": "bunx oxlint",
+		"format": "bunx oxfmt --write src"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.5"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"keywords": [
+		"task",
+		"todo",
+		"cli",
+		"agent",
+		"bun"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/nijaru/tk"
+	},
+	"author": "nijaru",
+	"homepage": "https://github.com/nijaru/tk#readme",
+	"bugs": {
+		"url": "https://github.com/nijaru/tk/issues"
+	}
+}