@kythin/stackydo 0.9.2

package/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kythin
+
+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,368 @@
+# stackydo
+
+**One person's entire workload, in one place.**
+
+Stackydo is a context-aware CLI task manager designed for individual engineers, leads, and makers who juggle work across many projects, teams, and responsibilities. Tasks are plain markdown files with YAML frontmatter — no database, no server, no vendor lock-in.
+
+The core idea: your work doesn't live in one project. You might be debugging a production incident, reviewing a teammate's PR, prepping a conference talk, and planning next sprint — all in the same afternoon. Stackydo uses **stacks** to separate these workstreams while keeping everything in a single, searchable task store.
+
+## Why This Exists
+
+Most task managers are built for teams or for single projects. Stackydo is built for **you** — the individual who needs to:
+
+- Track work across multiple projects, random ideas, ad-hoc tasks, team duties, and personal goals simultaneously
+- Create tasks from wherever you are — terminal, editor, scripts, or AI agents — so fast it becomes muscle memory to offload every stray thought
+- Search across everything at once ("what was that security thing last week?")
+- Let AI tools triage, summarize, and report on your workload via the built-in MCP server
+- Own your data as plain files you can grep, version, and back up
+
+## Features
+
+- **Headless CLI** — create, list, search, update, complete, delete from scripts and pipelines
+- **MCP server** — gives AI assistants (Claude Desktop, Claude Code, etc.) full access to your task store
+- **Stacks** — organize tasks into named workstreams (e.g. "work", "personal", "sprint-12")
+- **Short IDs** — human-friendly IDs like SD1, SD2 alongside ULIDs; all commands accept either
+- **Automatic context capture** — records git branch/commit, working directory, and project context on task creation
+- **Task graph** — subtasks, dependencies (blocked-by, blocks, related-to)
+- **AI-friendly storage** — plain markdown+YAML files that any LLM or script can read and write
+- **`.stackydo-context` files** — define project-level context that gets attached to new tasks automatically
+- **Session chaining** — tracks the last task ID created per shell session via `$STACKYDO_LAST_ID`
+- **Configurable storage** — set `dir` in `.stackydo-context` for per-project workspaces, or `$STACKYDO_DIR` for per-session overrides (defaults to `~/.stackydo/`)
+- **Multi-workspace** — discover, list, and migrate tasks across workspaces
+- **Doctor** — diagnose and auto-fix workspace issues (missing short IDs, orphan refs, corrupt files)
+
+## Install
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew tap kythin/homebrew-tap && brew install stackydo
+```
+
+### Shell (curl one-liner)
+
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/kythin/stackydo-cli/releases/latest/download/stackydo-installer.sh | sh
+```
+
+### PowerShell (Windows)
+
+```powershell
+powershell -c "irm https://github.com/kythin/stackydo-cli/releases/latest/download/stackydo-installer.ps1 | iex"
+```
+
+### From source
+
+```bash
+cargo install --git https://github.com/kythin/stackydo-cli
+```
+
+### Update
+
+```bash
+# Homebrew
+brew upgrade stackydo
+
+# Shell — re-run the curl installer, or use the built-in updater:
+stackydo-update
+```
+
+All methods install two binaries: `stackydo` (CLI) and `stackydo-mcp` (MCP server).
+
+## Quick Start
+
+```bash
+# Create a task
+stackydo create --title "Fix auth bug" --tags "backend,urgent" --priority high --stack work \
+  -- The login endpoint returns 500 when the token expires
+
+# List tasks
+stackydo list
+stackydo list --status todo --sort priority
+stackydo list --stack work
+stackydo list --overdue
+
+# Show task detail (prefix matching and short IDs work everywhere)
+stackydo show SD1
+stackydo show 01HQ
+
+# Update a task
+stackydo update SD1 --status in_progress --note "Investigating root cause"
+
+# Complete a task
+stackydo complete SD1
+
+# Search
+stackydo search "auth"
+
+# Add a comment
+stackydo comment SD1 "Turns out it was a timezone issue"
+
+# Check workspace health
+stackydo doctor
+stackydo doctor --fix
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `create` | Create a new task with title, tags, priority, stack, body, due date, dependencies |
+| `list` | List/filter tasks by status, stage, tag, priority, stack, due date; sort, group, paginate |
+| `show` | Show a task's full details |
+| `update` | Update fields, append body text, sed-style substitution, add timestamped notes |
+| `complete` | Mark task(s) as done (single or bulk with `--all`) |
+| `delete` | Permanently delete task(s) (single or bulk with `--all`) |
+| `search` | Search title and body (case-insensitive) with same filters as `list` |
+| `comment` | Add a comment to a task |
+| `stats` | Summary statistics: totals, overdue count, breakdowns by status/stack/tag |
+| `stacks` | All stacks with per-stack task counts and status breakdowns |
+| `context` | Preview what context would be captured for a new task |
+| `init` | Initialize a new workspace (optionally with `--here` and `--git`) |
+| `doctor` | Diagnose and optionally fix workspace issues |
+| `shuffle` | Randomise the order of tasks in a stack+status group |
+| `draw` | Draw the top task from one group and move it to another |
+| `list-workspaces` | Discover all stackydo workspaces on the system |
+| `migrate` | Move or copy tasks between workspaces |
+| `import` | Import tasks from stdin (JSON or YAML) |
+| `mcp-setup` | Register `stackydo-mcp` with Claude Code via `claude mcp add` |
+| `agent-setup` | Generate an AI agent playbook in your project's CLAUDE.md |
+
+## Stacks
+
+A task can belong to one **stack** — a named group like "work", "personal", or "sprint-12". Think of stacks as physical piles of tasks rather than flat database categories.
+
+```bash
+# Create a task on a stack
+stackydo create --title "Deploy v2" --stack work
+
+# Filter tasks by stack
+stackydo list --stack work
+stackydo list --stack personal --status todo
+
+# See all stacks with counts
+stackydo stacks
+```
+
+The manifest tracks known stack names. Tasks without a stack are unstacked and won't appear in stack-filtered results.
+
+## Workflows
+
+Workflows define the statuses available to tasks and how they map to lifecycle stages (backlog, active, archive). Each stack can use a different workflow.
+
+### Built-in Workflows
+
+**Kanban** (default) — traditional task board:
+
+| Stage | Statuses |
+|-------|----------|
+| Backlog | `todo`, `on_hold` |
+| Active | `in_progress`, `blocked`, `in_review` |
+| Archive | `done`, `cancelled` |
+
+**Deck** — card game metaphor for randomised/prioritised work:
+
+| Stage | Statuses |
+|-------|----------|
+| Backlog | `deck` |
+| Active | `hand`, `table` |
+| Archive | `discard` |
+
+### Per-Stack Assignment
+
+Set a stack's workflow in `manifest.json`:
+```json
+{
+  "stack_workflows": {
+    "ideas": "deck",
+    "work": "kanban"
+  }
+}
+```
+
+Stacks without a workflow inherit the workspace default (kanban).
+
+### Index Ordering
+
+Tasks within the same stack+status group have an `index` field for positional ordering. Indexes are maintained automatically when tasks are created, moved, or deleted. Use `shuffle` to randomise order, and `draw` to pull the top task from one group to another:
+
+```bash
+# Randomise the deck
+stackydo shuffle --stack ideas --status deck
+
+# Draw the top card into your hand
+stackydo draw --source ideas/deck --target ideas/hand
+```
+
+## MCP Server (Claude Desktop / Claude Code)
+
+Stackydo includes an MCP server that gives AI assistants full access to your task store.
+
+### Setup
+
+Install stackydo using any method from the [Install](#install) section. Both `stackydo` and `stackydo-mcp` are included.
+
+**Claude Code** (quickest):
+
+```bash
+stackydo mcp-setup
+```
+
+This runs `claude mcp add` to register the server. Use `--scope user` for global access or `--scope project` (default) for per-project.
+
+**Claude Desktop** — add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "stackydo": {
+      "command": "stackydo-mcp"
+    }
+  }
+}
+```
+
+To use a non-default storage directory, add an `env` key:
+
+```json
+{
+  "mcpServers": {
+    "stackydo": {
+      "command": "stackydo-mcp",
+      "env": {
+        "STACKYDO_DIR": "/path/to/your/tasks"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing the config.
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_tasks` | List/filter tasks by status, tag, priority, stack, due date; sort and group |
+| `get_task` | Get a single task by ID (prefix matching) |
+| `create_task` | Create a task with title, priority, tags, stack, body, due date |
+| `update_task` | Update fields, append timestamped notes, body editing |
+| `complete_task` | Mark a task as done |
+| `delete_task` | Permanently delete a task |
+| `search_tasks` | Search title and body (case-insensitive) |
+| `add_comment` | Add a comment to a task |
+| `get_stats` | Summary statistics: totals, overdue count, breakdowns by status/stack/tag |
+| `get_stacks` | All stacks with per-stack task counts and status breakdowns |
+| `list_workspaces` | Discover all stackydo workspaces on the system |
+| `migrate_tasks` | Move or copy tasks between workspaces |
+| `doctor` | Diagnose and optionally fix workspace issues |
+| `shuffle` | Randomise task order in a stack+status group |
+| `draw` | Draw top task from one group and move to another |
+
+The server also exposes a `stackydo://guide` resource with a full agent guide, and prompt templates for triage, planning, and task extraction.
+
+## AI Agent Setup
+
+Stackydo is designed to be used by AI coding agents (Claude Code, Cursor, etc.) as their own task tracker:
+
+```bash
+# Generate a CLAUDE.md playbook for your project
+stackydo agent-setup
+
+# Register the MCP server with Claude Code
+stackydo mcp-setup
+```
+
+`agent-setup` writes instructions into your project's CLAUDE.md so agents know how to create, update, and complete tasks as they work.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `STACKYDO_DIR` | Override the task storage directory (highest priority, overrides `.stackydo-context`; default: `~/.stackydo/`) |
+| `STACKYDO_LAST_ID` | Set automatically by `stackydo create`; chains tasks in a shell session |
+
+## Task Storage
+
+Each task is a markdown file at `<STACKYDO_DIR>/<ULID>.md`:
+
+```markdown
+---
+id: 01HQXYZ...
+short_id: SD1
+title: Fix auth bug
+status: todo
+priority: high
+tags: [backend, urgent]
+stack: work
+index: 0
+created: 2025-02-13T10:30:00Z
+modified: 2025-02-13T10:30:00Z
+context:
+  working_dir: /home/user/project
+  git_branch: main
+  git_commit: a3f7d92
+---
+
+The login endpoint returns 500 when the token expires.
+```
+
+A manifest at `<STACKYDO_DIR>/manifest.json` tracks tags, stacks, short ID counter, and settings.
+
+## Context Discovery
+
+On task creation, stackydo automatically captures:
+
+1. Current working directory
+2. Git branch, remote URL, and HEAD commit (if in a repo)
+3. Content from the nearest `.stackydo-context` file (walks up from CWD, falls back to `~/.stackydo-context`)
+4. `$STACKYDO_LAST_ID` — the ID of the previous task created in the same shell session
+
+Use `stackydo context` to preview what would be captured without creating a task.
+
+### Workspace Resolution
+
+The `.stackydo-context` file can set the task store location via a `dir` field. This lets a project root define a shared workspace without requiring every user to set an environment variable.
+
+Resolution priority:
+1. `$STACKYDO_DIR` env var (highest — per-session override)
+2. `dir` field in the nearest `.stackydo-context` (per-project)
+3. `~/.stackydo/` (default)
+
+Example `.stackydo-context`:
+
+```yaml
+dir: .stackydo-workspace
+project: my-app
+stack: dev
+description: Project-level context captured on new tasks
+```
+
+The `dir` path is resolved relative to the config file's location. Use `stackydo context` to see which source resolved the task store.
+
+To set up a project workspace:
+
+```bash
+stackydo init --here --dir .stackydo-workspace
+```
+
+## Contributing
+
+```bash
+# Build
+cargo build
+
+# Run tests
+cargo test                                     # unit tests
+cargo build && bash tests/smoke_test.sh        # CLI smoke tests
+bash tests/test_all.sh                         # full suite: clippy + unit + build + smoke + scenario + scale
+
+# Lint
+cargo clippy
+```
+
+Tests use `$STACKYDO_DIR` to write to a local `tests/.test-data/` directory — they never touch `~/.stackydo/`.
+
+## License
+
+MIT

package/binary-install.js

@@ -0,0 +1,212 @@
+const { createWriteStream, existsSync, mkdirSync, mkdtemp } = require("fs");
+const { join, sep } = require("path");
+const { spawnSync } = require("child_process");
+const { tmpdir } = require("os");
+
+const axios = require("axios");
+const rimraf = require("rimraf");
+const tmpDir = tmpdir();
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+class Package {
+  constructor(platform, name, url, filename, zipExt, binaries) {
+    let errors = [];
+    if (typeof url !== "string") {
+      errors.push("url must be a string");
+    } else {
+      try {
+        new URL(url);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    if (name && typeof name !== "string") {
+      errors.push("package name must be a string");
+    }
+    if (!name) {
+      errors.push("You must specify the name of your package");
+    }
+    if (binaries && typeof binaries !== "object") {
+      errors.push("binaries must be a string => string map");
+    }
+    if (!binaries) {
+      errors.push("You must specify the binaries in the package");
+    }
+
+    if (errors.length > 0) {
+      let errorMsg =
+        "One or more of the parameters you passed to the Binary constructor are invalid:\n";
+      errors.forEach((error) => {
+        errorMsg += error;
+      });
+      errorMsg +=
+        '\n\nCorrect usage: new Package("my-binary", "https://example.com/binary/download.tar.gz", {"my-binary": "my-binary"})';
+      error(errorMsg);
+    }
+
+    this.platform = platform;
+    this.url = url;
+    this.name = name;
+    this.filename = filename;
+    this.zipExt = zipExt;
+    this.installDirectory = join(__dirname, "node_modules", ".bin_real");
+    this.binaries = binaries;
+
+    if (!existsSync(this.installDirectory)) {
+      mkdirSync(this.installDirectory, { recursive: true });
+    }
+  }
+
+  exists() {
+    for (const binaryName in this.binaries) {
+      const binRelPath = this.binaries[binaryName];
+      const binPath = join(this.installDirectory, binRelPath);
+      if (!existsSync(binPath)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  install(fetchOptions, suppressLogs = false) {
+    if (this.exists()) {
+      if (!suppressLogs) {
+        console.error(
+          `${this.name} is already installed, skipping installation.`,
+        );
+      }
+      return Promise.resolve();
+    }
+
+    if (existsSync(this.installDirectory)) {
+      rimraf.sync(this.installDirectory);
+    }
+
+    mkdirSync(this.installDirectory, { recursive: true });
+
+    if (!suppressLogs) {
+      console.error(`Downloading release from ${this.url}`);
+    }
+
+    return axios({ ...fetchOptions, url: this.url, responseType: "stream" })
+      .then((res) => {
+        return new Promise((resolve, reject) => {
+          mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
+            let tempFile = join(directory, this.filename);
+            const sink = res.data.pipe(createWriteStream(tempFile));
+            sink.on("error", (err) => reject(err));
+            sink.on("close", () => {
+              if (/\.tar\.*/.test(this.zipExt)) {
+                const result = spawnSync("tar", [
+                  "xf",
+                  tempFile,
+                  // The tarballs are stored with a leading directory
+                  // component; we strip one component in the
+                  // shell installers too.
+                  "--strip-components",
+                  "1",
+                  "-C",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred untarring the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else if (this.zipExt == ".zip") {
+                let result;
+                if (this.platform.artifactName.includes("windows")) {
+                  // Windows does not have "unzip" by default on many installations, instead
+                  // we use Expand-Archive from powershell
+                  result = spawnSync("powershell.exe", [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    `& {
+                        param([string]$LiteralPath, [string]$DestinationPath)
+                        Expand-Archive -LiteralPath $LiteralPath -DestinationPath $DestinationPath -Force
+                    }`,
+                    tempFile,
+                    this.installDirectory,
+                  ]);
+                } else {
+                  result = spawnSync("unzip", [
+                    "-q",
+                    tempFile,
+                    "-d",
+                    this.installDirectory,
+                  ]);
+                }
+
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred unzipping the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else {
+                reject(
+                  new Error(`Unrecognized file extension: ${this.zipExt}`),
+                );
+              }
+            });
+          });
+        });
+      })
+      .then(() => {
+        if (!suppressLogs) {
+          console.error(`${this.name} has been installed!`);
+        }
+      })
+      .catch((e) => {
+        error(`Error fetching release: ${e.message}`);
+      });
+  }
+
+  run(binaryName, fetchOptions) {
+    const promise = !this.exists()
+      ? this.install(fetchOptions, true)
+      : Promise.resolve();
+
+    promise
+      .then(() => {
+        const [, , ...args] = process.argv;
+
+        const options = { cwd: process.cwd(), stdio: "inherit" };
+
+        const binRelPath = this.binaries[binaryName];
+        if (!binRelPath) {
+          error(`${binaryName} is not a known binary in ${this.name}`);
+        }
+        const binPath = join(this.installDirectory, binRelPath);
+        const result = spawnSync(binPath, args, options);
+
+        if (result.error) {
+          error(result.error);
+        }
+
+        process.exit(result.status);
+      })
+      .catch((e) => {
+        error(e.message);
+        process.exit(1);
+      });
+  }
+}
+
+module.exports.Package = Package;