vault-tasks 0.4.0__tar.gz

vault_tasks-0.4.0/.gitignore

@@ -0,0 +1,19 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.DS_Store
+*.tgz
+.env*
+coverage/
+
+# Python wheel build artifacts (vault-tasks pip distribution).
+# python/README.md is regenerated from the repo-root README by
+# scripts/build-wheel.mjs so the PyPI page always shows the live doc.
+python/README.md
+python/vault_tasks/_bundle/
+python/dist/
+python/build/
+python/*.egg-info/
+__pycache__/
+*.pyc
+.venv/

vault_tasks-0.4.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: vault-tasks
+Version: 0.4.0
+Summary: Markdown-file task manager for solo devs building with Claude Code
+Project-URL: Homepage, https://github.com/adcoh/vault-tasks
+Project-URL: Repository, https://github.com/adcoh/vault-tasks
+Project-URL: Issues, https://github.com/adcoh/vault-tasks/issues
+Project-URL: Changelog, https://github.com/adcoh/vault-tasks/blob/main/CHANGELOG.md
+Author: Adam Cohn
+License: MIT
+Keywords: backlog,claude-code,markdown,obsidian,second-brain,tasks,zettelkasten
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# vault-tasks
+
+Markdown-file task manager for solo devs building with [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+Tasks are plain markdown files with YAML frontmatter. They live in your repo (or Obsidian vault), are version-controlled with git, and are readable by humans and LLMs alike. Zero runtime dependencies.
+
+## Install
+
+```bash
+npm install -g vault-tasks
+```
+
+Or use without installing:
+
+```bash
+npx vault-tasks <command>
+```
+
+Requires Node.js >= 20.
+
+### Python projects (pip / uv)
+
+If your project's lockfile is Python-based and you'd rather pin vault-tasks alongside your other dev dependencies:
+
+```bash
+pip install vault-tasks
+# or
+uv add --dev vault-tasks
+```
+
+The pip wheel is small (~100 KB) and bundles the same compiled JS that ships on npm. It still requires `node` (>= 20) on `PATH` — the wheel does not vendor a Node.js runtime.
+
+## Quick start
+
+```bash
+# Initialize in your repo/vault root
+vt init
+
+# Create a task
+vt new "Fix login redirect bug" --priority high --tags auth,bug
+
+# See what's open
+vt list
+
+# Start working on it
+vt start 1
+
+# Mark it done (auto-archives by default)
+vt done 1
+```
+
+`vt init` creates a `.vault-tasks.toml` config and a `backlog/` directory. Tasks are markdown files with ULID prefixes (e.g., `01HYX3KQPD7NG8RRGSSFQ9XNHY-fix-login-redirect-bug.md`). Sequential numeric IDs (`0001-...`) are also supported via config.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `vt new <title>` | Create a task. Options: `--priority`, `--tags`, `--source`, `--commit` |
+| `vt list` | List open tasks. Options: `--status`, `--priority`, `--tag`, `--all` |
+| `vt search <keyword>` | Search titles and body text. `--all` includes archived |
+| `vt show <id>` | Print full task file |
+| `vt start <id>` | Set status to `in-progress` |
+| `vt done <id>` | Set status to `done` (auto-archives) |
+| `vt edit <id>` | Update fields: `--status`, `--priority`, `--tags` |
+| `vt stale` | List open tasks older than 14 days. `--days` to customize |
+| `vt archive` | Move all completed tasks to the archive directory |
+| `vt tags` | List all tags and their counts |
+| `vt lint` | Audit the vault: broken wikilinks, orphan evergreens, stale refs, drift. `--only`, `--scope`, `--json`, `--quiet`, `--no-suggestions` |
+| `vt init` | Initialize config and backlog directory |
+| `vt install-skills` | Install Claude Code skills and rules. `--install`, `--list`, `--update` |
+
+Task lookup (`<id>`) accepts a ULID prefix (e.g., `vt done 01HYX`), a numeric ID for sequential vaults (e.g., `vt done 1`), or a substring match against the filename (e.g., `vt done login`).
+
+## Task format
+
+Each task is a markdown file with YAML frontmatter:
+
+```markdown
+---
+title: "Fix login redirect bug"
+status: open
+priority: high
+tags:
+  - auth
+  - bug
+created: 2026-04-02
+source: "[[2026-04-02 Session Log]]"
+---
+
+# Fix login redirect bug
+
+After OAuth callback, users are redirected to `/` instead of the page they came from.
+```
+
+- **Status**: `open`, `in-progress`, `done`, `wont-do`
+- **Priority**: `high`, `medium`, `low`
+- **Tags**: freeform, filterable via `vt list --tag`
+- **Source**: where the task was noticed (supports `[[wikilinks]]`)
+
+Extra frontmatter fields (e.g. `due`, `assignee`) are preserved through all operations.
+
+## Configuration
+
+`vt init` creates `.vault-tasks.toml` at your vault root:
+
+```toml
+[paths]
+backlog_dir = "backlog"           # where task files live
+archive_dir = "archive"           # relative to backlog_dir
+# journal_dir = "journal"         # build logs and session notes
+# projects_dir = "projects"       # project folders with CONTEXT.md
+# evergreen_dir = "evergreen"     # evergreen/zettelkasten notes
+
+[task]
+# statuses = ["open", "in-progress", "done", "wont-do"]
+# priorities = ["high", "medium", "low"]
+# default_priority = "medium"
+# default_status = "open"
+# archive_statuses = ["done", "wont-do"]
+# auto_archive = true
+
+[id]
+# strategy = "ulid"               # "ulid" | "sequential" | "timestamp"
+# pad_width = 4                   # zero-pad width (only used with sequential)
+
+[slugify]
+# max_length = 60
+```
+
+The config file is discovered by walking up from the current directory, so it works from any subdirectory.
+
+## Claude Code skills
+
+vault-tasks ships with skill templates that teach Claude Code how to work with your task backlog:
+
+```bash
+vt install-skills --install
+```
+
+This installs into `.claude/skills/` and `.claude/rules/`:
+
+| Skill | What it does |
+|---|---|
+| `/brief` | Pre-session briefing: open tasks, last session context, stale threads |
+| `/build-log` | End-of-session log: what was built, learned, decided. Extracts tasks |
+| `/weekly-review` | Consolidates journal entries, creates evergreen notes, triages backlog |
+| `/task` | Quick task creation/management from within a session |
+| `/lint` | Vault health check: broken wikilinks, orphans, stale refs, convention drift |
+
+Skills reference configurable vault paths (`journal_dir`, `projects_dir`, `evergreen_dir`) which are substituted from your `.vault-tasks.toml` at install time. Customize any skill by creating a `SKILL.local.md` next to the installed `SKILL.md` -- local files are never overwritten.
+
+An [Obsidian Bases](https://obsidian.md/blog/bases/) dashboard (`backlog.base`) is also installed for visual task management.
+
+## Library API
+
+vault-tasks also exports a programmatic API:
+
+```typescript
+import { loadConfig, TaskStore } from "vault-tasks";
+
+const config = loadConfig();
+const store = new TaskStore(config);
+
+// Create
+const task = store.create({ title: "My task", priority: "high", tags: ["api"] });
+
+// Query
+const all = store.loadAll();
+const results = store.search("login");
+const stale = store.stale(14);
+const tags = store.allTags();
+
+// Update
+store.update(task, { status: "done", priority: "low", tags: ["api", "shipped"] });
+store.archiveCompleted();
+```
+
+### Exports
+
+- `TaskStore` -- all CRUD operations
+- `loadConfig` / `findConfigFile` -- config discovery and parsing
+- `parseFrontmatter` / `writeFrontmatter` -- YAML frontmatter utilities
+- `slugify` -- title to kebab-case filename
+- `lintVault` -- run all lint checks; returns a `LintReport`
+- Lower-level lint primitives: `buildIndex`, `resolveTarget`,
+  `collectWikilinks`, `findBrokenLinks`, `findOrphanEvergreens`,
+  `findStaleReferences`, `findEvergreenDrift`, `attachSuggestions`
+- Types: `Task`, `CreateTaskOpts`, `Config`, `LintReport`, `LintOptions`,
+  `WikiLink`, `VaultFile`, `BrokenEntry`, `Suggestion`
+
+## License
+
+MIT

vault_tasks-0.4.0/README.md

@@ -0,0 +1,193 @@
+# vault-tasks
+
+Markdown-file task manager for solo devs building with [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+Tasks are plain markdown files with YAML frontmatter. They live in your repo (or Obsidian vault), are version-controlled with git, and are readable by humans and LLMs alike. Zero runtime dependencies.
+
+## Install
+
+```bash
+npm install -g vault-tasks
+```
+
+Or use without installing:
+
+```bash
+npx vault-tasks <command>
+```
+
+Requires Node.js >= 20.
+
+### Python projects (pip / uv)
+
+If your project's lockfile is Python-based and you'd rather pin vault-tasks alongside your other dev dependencies:
+
+```bash
+pip install vault-tasks
+# or
+uv add --dev vault-tasks
+```
+
+The pip wheel is small (~100 KB) and bundles the same compiled JS that ships on npm. It still requires `node` (>= 20) on `PATH` — the wheel does not vendor a Node.js runtime.
+
+## Quick start
+
+```bash
+# Initialize in your repo/vault root
+vt init
+
+# Create a task
+vt new "Fix login redirect bug" --priority high --tags auth,bug
+
+# See what's open
+vt list
+
+# Start working on it
+vt start 1
+
+# Mark it done (auto-archives by default)
+vt done 1
+```
+
+`vt init` creates a `.vault-tasks.toml` config and a `backlog/` directory. Tasks are markdown files with ULID prefixes (e.g., `01HYX3KQPD7NG8RRGSSFQ9XNHY-fix-login-redirect-bug.md`). Sequential numeric IDs (`0001-...`) are also supported via config.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `vt new <title>` | Create a task. Options: `--priority`, `--tags`, `--source`, `--commit` |
+| `vt list` | List open tasks. Options: `--status`, `--priority`, `--tag`, `--all` |
+| `vt search <keyword>` | Search titles and body text. `--all` includes archived |
+| `vt show <id>` | Print full task file |
+| `vt start <id>` | Set status to `in-progress` |
+| `vt done <id>` | Set status to `done` (auto-archives) |
+| `vt edit <id>` | Update fields: `--status`, `--priority`, `--tags` |
+| `vt stale` | List open tasks older than 14 days. `--days` to customize |
+| `vt archive` | Move all completed tasks to the archive directory |
+| `vt tags` | List all tags and their counts |
+| `vt lint` | Audit the vault: broken wikilinks, orphan evergreens, stale refs, drift. `--only`, `--scope`, `--json`, `--quiet`, `--no-suggestions` |
+| `vt init` | Initialize config and backlog directory |
+| `vt install-skills` | Install Claude Code skills and rules. `--install`, `--list`, `--update` |
+
+Task lookup (`<id>`) accepts a ULID prefix (e.g., `vt done 01HYX`), a numeric ID for sequential vaults (e.g., `vt done 1`), or a substring match against the filename (e.g., `vt done login`).
+
+## Task format
+
+Each task is a markdown file with YAML frontmatter:
+
+```markdown
+---
+title: "Fix login redirect bug"
+status: open
+priority: high
+tags:
+  - auth
+  - bug
+created: 2026-04-02
+source: "[[2026-04-02 Session Log]]"
+---
+
+# Fix login redirect bug
+
+After OAuth callback, users are redirected to `/` instead of the page they came from.
+```
+
+- **Status**: `open`, `in-progress`, `done`, `wont-do`
+- **Priority**: `high`, `medium`, `low`
+- **Tags**: freeform, filterable via `vt list --tag`
+- **Source**: where the task was noticed (supports `[[wikilinks]]`)
+
+Extra frontmatter fields (e.g. `due`, `assignee`) are preserved through all operations.
+
+## Configuration
+
+`vt init` creates `.vault-tasks.toml` at your vault root:
+
+```toml
+[paths]
+backlog_dir = "backlog"           # where task files live
+archive_dir = "archive"           # relative to backlog_dir
+# journal_dir = "journal"         # build logs and session notes
+# projects_dir = "projects"       # project folders with CONTEXT.md
+# evergreen_dir = "evergreen"     # evergreen/zettelkasten notes
+
+[task]
+# statuses = ["open", "in-progress", "done", "wont-do"]
+# priorities = ["high", "medium", "low"]
+# default_priority = "medium"
+# default_status = "open"
+# archive_statuses = ["done", "wont-do"]
+# auto_archive = true
+
+[id]
+# strategy = "ulid"               # "ulid" | "sequential" | "timestamp"
+# pad_width = 4                   # zero-pad width (only used with sequential)
+
+[slugify]
+# max_length = 60
+```
+
+The config file is discovered by walking up from the current directory, so it works from any subdirectory.
+
+## Claude Code skills
+
+vault-tasks ships with skill templates that teach Claude Code how to work with your task backlog:
+
+```bash
+vt install-skills --install
+```
+
+This installs into `.claude/skills/` and `.claude/rules/`:
+
+| Skill | What it does |
+|---|---|
+| `/brief` | Pre-session briefing: open tasks, last session context, stale threads |
+| `/build-log` | End-of-session log: what was built, learned, decided. Extracts tasks |
+| `/weekly-review` | Consolidates journal entries, creates evergreen notes, triages backlog |
+| `/task` | Quick task creation/management from within a session |
+| `/lint` | Vault health check: broken wikilinks, orphans, stale refs, convention drift |
+
+Skills reference configurable vault paths (`journal_dir`, `projects_dir`, `evergreen_dir`) which are substituted from your `.vault-tasks.toml` at install time. Customize any skill by creating a `SKILL.local.md` next to the installed `SKILL.md` -- local files are never overwritten.
+
+An [Obsidian Bases](https://obsidian.md/blog/bases/) dashboard (`backlog.base`) is also installed for visual task management.
+
+## Library API
+
+vault-tasks also exports a programmatic API:
+
+```typescript
+import { loadConfig, TaskStore } from "vault-tasks";
+
+const config = loadConfig();
+const store = new TaskStore(config);
+
+// Create
+const task = store.create({ title: "My task", priority: "high", tags: ["api"] });
+
+// Query
+const all = store.loadAll();
+const results = store.search("login");
+const stale = store.stale(14);
+const tags = store.allTags();
+
+// Update
+store.update(task, { status: "done", priority: "low", tags: ["api", "shipped"] });
+store.archiveCompleted();
+```
+
+### Exports
+
+- `TaskStore` -- all CRUD operations
+- `loadConfig` / `findConfigFile` -- config discovery and parsing
+- `parseFrontmatter` / `writeFrontmatter` -- YAML frontmatter utilities
+- `slugify` -- title to kebab-case filename
+- `lintVault` -- run all lint checks; returns a `LintReport`
+- Lower-level lint primitives: `buildIndex`, `resolveTarget`,
+  `collectWikilinks`, `findBrokenLinks`, `findOrphanEvergreens`,
+  `findStaleReferences`, `findEvergreenDrift`, `attachSuggestions`
+- Types: `Task`, `CreateTaskOpts`, `Config`, `LintReport`, `LintOptions`,
+  `WikiLink`, `VaultFile`, `BrokenEntry`, `Suggestion`
+
+## License
+
+MIT

vault_tasks-0.4.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vault-tasks"
+dynamic = ["version"]
+description = "Markdown-file task manager for solo devs building with Claude Code"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Adam Cohn" }]
+keywords = [
+  "tasks",
+  "backlog",
+  "obsidian",
+  "claude-code",
+  "markdown",
+  "zettelkasten",
+  "second-brain",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: JavaScript",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development",
+  "Topic :: Utilities",
+]
+
+[project.scripts]
+vault-tasks = "vault_tasks.__main__:main"
+vt = "vault_tasks.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/adcoh/vault-tasks"
+Repository = "https://github.com/adcoh/vault-tasks"
+Issues = "https://github.com/adcoh/vault-tasks/issues"
+Changelog = "https://github.com/adcoh/vault-tasks/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "vault_tasks/_version.py"
+
+[tool.hatch.build]
+# _bundle/ is gitignored (it is a build artifact staged by
+# scripts/build-wheel.mjs from package.json + dist/ + templates/). Without
+# this, hatchling honors .gitignore and silently drops the JS files from
+# the wheel. `artifacts` re-includes them.
+artifacts = [
+  "vault_tasks/_bundle/**",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["vault_tasks"]
+
+[tool.hatch.build.targets.sdist]
+# sdist must be self-contained: include the staged bundle so reproducing the
+# wheel from sdist does not require Node.js to be present on the builder.
+include = [
+  "vault_tasks/**",
+  "README.md",
+  "pyproject.toml",
+]

vault_tasks-0.4.0/vault_tasks/__init__.py

@@ -0,0 +1,3 @@
+from ._version import __version__
+
+__all__ = ["__version__"]

vault_tasks-0.4.0/vault_tasks/__main__.py

@@ -0,0 +1,82 @@
+"""Python entry point for the vault-tasks CLI.
+
+The pip wheel ships the compiled JS at vault_tasks/_bundle/dist/cli.js plus
+the templates tree at vault_tasks/_bundle/templates/. This shim:
+
+  1. Locates `node` on PATH (errors actionably if missing).
+  2. Sets VAULT_TASKS_TEMPLATES_DIR so install-skills finds the bundled
+     templates instead of walking up from __dirname.
+  3. Execs `node cli.js <forwarded argv>`. On POSIX we use os.execvpe so
+     signals (Ctrl-C) and exit codes pass through cleanly. On Windows we
+     fall back to subprocess.run because execvpe semantics there are
+     different enough to cause shell-related surprises.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+NODE_MISSING_MESSAGE = (
+    "vault-tasks: Node.js is required but was not found on PATH.\n"
+    "\n"
+    "vault-tasks ships as JavaScript and needs Node.js >= 20 to run.\n"
+    "Install Node from https://nodejs.org or via your package manager:\n"
+    "  macOS:    brew install node\n"
+    "  Ubuntu:   sudo apt install nodejs\n"
+    "  Windows:  winget install OpenJS.NodeJS.LTS\n"
+    "Then re-run this command.\n"
+)
+
+
+def _bundle_root() -> Path:
+    return Path(__file__).resolve().parent / "_bundle"
+
+
+def _find_node() -> str:
+    node = shutil.which("node")
+    if not node:
+        sys.stderr.write(NODE_MISSING_MESSAGE)
+        sys.exit(127)
+    return node
+
+
+def main() -> None:
+    node = _find_node()
+    bundle = _bundle_root()
+    cli_js = bundle / "dist" / "cli.js"
+    templates = bundle / "templates"
+
+    if not cli_js.is_file():
+        sys.stderr.write(
+            f"vault-tasks: bundle is missing cli.js at {cli_js}.\n"
+            "The pip wheel appears to be corrupt. Try `pip install --force-reinstall vault-tasks`.\n"
+        )
+        sys.exit(1)
+    if not templates.is_dir():
+        sys.stderr.write(
+            f"vault-tasks: bundle is missing templates at {templates}.\n"
+            "The pip wheel appears to be corrupt. Try `pip install --force-reinstall vault-tasks`.\n"
+        )
+        sys.exit(1)
+
+    env = os.environ.copy()
+    env["VAULT_TASKS_TEMPLATES_DIR"] = str(templates)
+
+    argv = [node, str(cli_js), *sys.argv[1:]]
+
+    if os.name == "nt":
+        # Windows: subprocess.run preserves stdio/exit-code semantics best.
+        # Pass argv as a list so the shell does not re-quote anything.
+        completed = subprocess.run(argv, env=env)
+        sys.exit(completed.returncode)
+
+    # POSIX: replace the Python process so signals and exit codes pass through.
+    os.execvpe(node, argv, env)
+
+
+if __name__ == "__main__":
+    main()

vault_tasks-0.4.0/vault_tasks/_bundle/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

vault_tasks-0.4.0/vault_tasks/_bundle/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}