@devwithdavid/ledger 0.1.2 → 0.1.4

package/LEDGER.md

@@ -100,7 +100,13 @@ the code.
   code; all code change goes through dispatched agents. Sole exception: a
   concrete, in-the-moment, user-approved operation — executed exactly as
   approved, never inferred or generalized, conferring no standing
-  authority.
+  authority. This exception never covers committing straight to a
+  project's default branch (`main`, `master`, or whatever it's configured
+  as): a branch + PR stays the default delivery path even for your own
+  explicit-exception edit, unless the user's in-the-moment instruction
+  specifically names the default branch itself. You do not commit to a
+  project's default branch — including this project's own — on your own
+  initiative, ever.
 - **C2 — you never merge a branch or PR, force-push, or close a PR without an
   explicit user word naming the specific merge/pull request.** One explicit
   word at a time, in the moment, for that specific PR; there is no standing

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 David Kartik
+
+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

@@ -32,39 +32,57 @@ That's the whole install. The package ships pre-built, and the global
 install puts `ledger` on your PATH — no build step, no separate linking
 step: the `ledger` binary lands on PATH with the install itself.
 
-**Link the watcher plugin into herdr** — this is what keeps agent status
-current automatically as dispatched agents work, without any polling.
-`herdr-plugin.toml` ships inside the package, so point the link at the
-installed package's root:
+**Finish the setup with `ledger init`** — the single post-install step:
 
 ```sh
-herdr plugin link "$(npm root -g)/@devwithdavid/ledger"
+ledger init
 ```
 
-This registers `herdr-plugin.toml`, so herdr invokes `dist/plugin/watcher.js`
-whenever a pane's detected agent state changes. It's local and reversible:
-`herdr plugin unlink ledger` removes it. herdr always runs whatever's
-currently in the installed package's `dist/`, so `npm update -g
-@devwithdavid/ledger` picks up new releases (including watcher changes) on
-the next event; re-run the link command if you want the registered version
-to track a new release.
+Run it once after installing. It does four things, printing a status line
+for each as it goes:
+
+1. **Verifies `herdr` and `treehouse` are on your PATH.** If either is
+   missing it exits without doing anything else, with an install pointer
+   for each missing tool (herdr: <https://herdr.dev>, treehouse:
+   <https://github.com/kunchenguid/treehouse>).
+2. **Creates the ledger database** at `$LEDGER_HOME/ledger.db` if it
+   doesn't exist yet. An existing store is never reset or rewritten.
+3. **Links the herdr watcher plugin**: runs `herdr plugin link` on the
+   installed package's root, where `herdr-plugin.toml` ships. That's what
+   keeps agent status current automatically as dispatched agents work,
+   without any polling — herdr invokes `dist/plugin/watcher.js` whenever a
+   pane's detected agent state changes.
+4. **Installs the clerk skill** at `~/.agents/skills/ledger/SKILL.md` from
+   the copy bundled with this install, symlinking it into
+   `~/.claude/skills/ledger` and `~/.pi/agent/skills/ledger` so either tool
+   picks it up. See "Starting a clerk session" below for what the skill
+   does.
+
+It's idempotent — re-running it (for example after `npm update -g
+@devwithdavid/ledger`) is safe: the store is only created if missing,
+re-linking the plugin leaves herdr's registration unchanged, the skill
+file is always re-synced from the bundled copy, and an existing symlink is
+only touched if it doesn't already point at the right place. The plugin
+link is local and reversible: `herdr plugin unlink ledger` removes it.
+herdr always runs whatever's currently in the installed package's `dist/`,
+so `npm update -g @devwithdavid/ledger` picks up new releases (including
+watcher changes) on the next event.
 
 ## Starting a clerk session
 
 You don't run `ledger` commands yourself day to day — you talk to **the
-clerk** (a Claude Code or Pi session), and it runs them on your behalf. A
-`ledger` skill is installed at `~/.agents/skills/ledger` (symlinked into
-both `~/.claude/skills/` and `~/.pi/agent/skills/`) so either tool can pick
-it up — it loads only when you actually ask for ledger-related work
-(register a project, dispatch an agent, check status, ...), not on every
-unrelated session.
+clerk** (a Claude Code or Pi session), and it runs them on your behalf.
+`ledger init` (step 4 above) installs a `ledger` skill so either Claude
+Code or Pi can pick it up — it loads only when you actually ask for
+ledger-related work (register a project, dispatch an agent, check status,
+...), not on every unrelated session.
 
 The skill itself carries no machine-specific path: it just tells the clerk
 to run `ledger docs`, which prints `LEDGER.md` by resolving it relative to
 wherever `ledger` is actually installed (works correctly through the
 `npm link` symlink too — proven live, see `DECISIONS.md`). That's what
-makes the skill portable to a fresh machine as-is: install `ledger` there
-per this README, and the skill works with no edits.
+makes the skill portable to a fresh machine as-is: run `ledger init` there
+and the skill works with no edits.
 
 ## Quick start (what the clerk actually runs)
 
@@ -136,3 +154,12 @@ with a high release cadence; some of the CLI/plugin behavior this repo
 depends on was reverse-engineered live (their docs don't fully match
 current behavior in places — see `DECISIONS.md`) and may need
 re-verification after either tool upgrades.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+Versions 0.1.0-0.1.2 were published to npm before this LICENSE file
+existed, so their tarballs don't contain it: published npm versions are
+immutable. As the sole author, the copyright holder grants those versions
+the same MIT license.

package/dist/cli/commands/init.js

@@ -0,0 +1,192 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, readlinkSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getDb, ledgerHome } from "../../db/client.js";
+// This file compiles to dist/cli/commands/init.js, three levels under the
+// package root — resolve the package root relative to *this running code's
+// own location* rather than the cwd (same approach as docs.ts), so it works
+// from any invocation directory, in a dev checkout and in an npm install.
+// The herdr plugin manifest (herdr-plugin.toml) lives at the package root,
+// so that directory is what gets linked.
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+// Step 4's bundled skill template: a hand-authored `~/.agents/skills/ledger`
+// (cross-agent skill tree; see DECISIONS.md "Clerk bootstrapping") existed
+// on one machine only and was never captured as a reproducible setup step —
+// a second machine's clerk session never loaded LEDGER.md as a result and
+// spent a whole session unaware of its own governance gates. This ships the
+// real skill content as a package asset instead, resolved the same way as
+// the herdr plugin root above, so `init` can (re-)install it anywhere.
+const SKILL_TEMPLATE_PATH = join(PACKAGE_ROOT, "skills/ledger/SKILL.md");
+const AGENTS_SKILL_DIR = join(homedir(), ".agents/skills/ledger");
+const AGENTS_SKILL_FILE = join(AGENTS_SKILL_DIR, "SKILL.md");
+// Deliberately outside this repo (same reasoning as the skill itself living
+// outside it) — per-tool skill directories are symlinks into the shared
+// `~/.agents/skills/<name>` tree, so any coding agent that understands that
+// convention picks it up with zero ledger-specific config of its own.
+const SKILL_SYMLINK_TARGETS = [join(homedir(), ".claude/skills/ledger"), join(homedir(), ".pi/agent/skills/ledger")];
+// Install pointers for the pre-check:
+//   herdr: derived from the tool's own npm package metadata, verified
+//   2026-09-03 — NOT guessed: npm view herdr homepage -> https://herdr.dev
+//   treehouse: npm's 'treehouse' is an unrelated React package (name
+//   squat); the required tool is kunchenguid's git-worktree tool
+//   (installed binary v2.3.0) — URL per user confirmation 2026-09-04,
+//   not npm metadata.
+// (The README's prerequisites section carries the same treehouse URL —
+// the two now agree; see DECISIONS.md for the resolution.)
+const DOCS = {
+    herdr: "https://herdr.dev",
+    treehouse: "https://github.com/kunchenguid/treehouse",
+};
+const REQUIRED_TOOLS = ["herdr", "treehouse"];
+/**
+ * PATH lookup for a required tool: the first $PATH directory that contains
+ * an executable FILE named <tool> wins. A plain lookup, deliberately not a
+ * version/capability probe — the pre-check's job is to fail fast with a
+ * per-tool install pointer, not to audit the tool (item 30).
+ */
+function findOnPath(tool) {
+    const dirs = (process.env["PATH"] ?? "").split(delimiter).filter((d) => d.length > 0);
+    for (const dir of dirs) {
+        const candidate = join(dir, tool);
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            // not here (or not executable) — keep looking
+        }
+    }
+    return undefined;
+}
+/**
+ * Step 4 helper: symlink one per-tool skill path to AGENTS_SKILL_DIR,
+ * creating its parent directory if needed. Idempotent: a symlink already
+ * pointing at the right place is a silent no-op; a pre-existing real
+ * file/directory (or a symlink to somewhere else) is left untouched with a
+ * warning rather than clobbered — this must never destroy something a user
+ * put there on purpose.
+ */
+function linkSkill(linkPath) {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    if (existsSync(linkPath)) {
+        let currentTarget;
+        try {
+            currentTarget = readlinkSync(linkPath);
+        }
+        catch {
+            // Exists but isn't a symlink at all.
+        }
+        if (currentTarget === AGENTS_SKILL_DIR) {
+            console.log(`✓ ${linkPath} already links to ${AGENTS_SKILL_DIR}`);
+        }
+        else {
+            console.log(`Warning: ${linkPath} already exists and is not a symlink to ${AGENTS_SKILL_DIR} ` +
+                `(${currentTarget ?? "a real file/directory"}) — left untouched. Remove it and ` +
+                `re-run 'ledger init' to relink.`);
+        }
+        return;
+    }
+    symlinkSync(AGENTS_SKILL_DIR, linkPath);
+    console.log(`✓ linked ${linkPath} -> ${AGENTS_SKILL_DIR}`);
+}
+/**
+ * The single post-install step (item 30, user-directed): the README's
+ * install section no longer tells users to hand-run `herdr plugin link
+ * <path>` — this command does that, transparently.
+ *
+ * Steps, in order:
+ *  1. Pre-check herdr AND treehouse on PATH before touching anything. If
+ *     one or both are missing, exit non-zero with a per-tool install
+ *     pointer (both in one error when both are missing) — no store is
+ *     created and no link is attempted.
+ *  2. Ensure the ledger store, reusing getDb() (it creates $LEDGER_HOME
+ *     and opens/migrates ledger.db; an existing store is only opened —
+ *     never reset or rewritten). Prints the path created or found.
+ *  3. Link the herdr plugin: `herdr plugin link <package root>`.
+ *     Verified live against herdr 0.7.5 (2026-09-03): re-linking a path
+ *     that's already linked exits 0, prints its `plugin_linked` JSON
+ *     result, and leaves herdr's plugin registry file byte-identical —
+ *     so this step is idempotent and the command is safe to re-run (e.g.
+ *     after `npm update -g @devwithdavid/ledger`). A non-zero exit (for
+ *     instance an already-linked different path) is surfaced: herdr's
+ *     own output is printed, the command fails, and the user resolves it
+ *     (`herdr plugin unlink ledger` first).
+ *  4. Install/update the clerk skill: write the bundled
+ *     `skills/ledger/SKILL.md` to `~/.agents/skills/ledger/SKILL.md`
+ *     (always overwritten from the bundled copy, so re-running `init`
+ *     after an upgrade re-syncs it), then symlink `~/.claude/skills/ledger`
+ *     and `~/.pi/agent/skills/ledger` to it if not already correctly
+ *     linked. Found missing on a second machine (see DECISIONS.md) —
+ *     the skill's *content* was portable, but nothing ever installed it.
+ *
+ * Every step prints an explicit status line (✓) naming what was done and
+ * the path/URL involved, so the user sees exactly what `ledger init` did.
+ */
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("one-time post-install setup: verify herdr and treehouse are on PATH, " +
+        "create the ledger store if missing, link the herdr watcher plugin, " +
+        "install the clerk skill (idempotent — safe to re-run)")
+        .action(() => {
+        // 1. Pre-check both required tools up front, before any side effect.
+        for (const tool of REQUIRED_TOOLS) {
+            if (findOnPath(tool)) {
+                console.log(`✓ ${tool} found on PATH`);
+            }
+        }
+        const missing = REQUIRED_TOOLS.filter((tool) => !findOnPath(tool));
+        if (missing.length > 0) {
+            // All missing tools are reported in one error, per the exact
+            // message format "<tool> not found on PATH - install it first:
+            // <docs URL>" (item 30). The CLI entry prints this as a single
+            // `Error:` line and exits non-zero.
+            throw new Error(missing.map((tool) => `${tool} not found on PATH - install it first: ${DOCS[tool]}`).join("; "));
+        }
+        // 2. Ensure the store — reuse the existing getDb() machinery (it
+        //    creates the home dir and migrates on open). Never resets or
+        //    rewrites an existing store.
+        const storePath = join(ledgerHome(), "ledger.db");
+        const alreadyThere = existsSync(storePath);
+        getDb();
+        console.log(`✓ ledger store ${alreadyThere ? "found at" : "created at"} ${storePath}`);
+        // 3. Link the herdr plugin from the package root.
+        const res = spawnSync("herdr", ["plugin", "link", PACKAGE_ROOT], { encoding: "utf8" });
+        if (res.error || res.status !== 0) {
+            const out = res.stdout ?? "";
+            const err = res.stderr ?? "";
+            if (out.trim())
+                process.stderr.write(`${out.trimEnd()}\n`);
+            if (err.trim())
+                process.stderr.write(`${err.trimEnd()}\n`);
+            const detail = res.error ? res.error.message : `exit ${res.status}`;
+            throw new Error(`herdr plugin link failed (${detail})`);
+        }
+        // Print herdr's own result so a fresh link and a no-op re-link are
+        // both visible, then our own status line naming the linked path.
+        const out = res.stdout ?? "";
+        if (out.trim())
+            console.log(out.trimEnd());
+        console.log(`✓ herdr plugin linked from ${PACKAGE_ROOT}`);
+        // 4. Install/update the clerk skill from the bundled template, then
+        //    link it into every known per-tool skill tree.
+        let skillTemplate;
+        try {
+            skillTemplate = readFileSync(SKILL_TEMPLATE_PATH, "utf8");
+        }
+        catch {
+            throw new Error(`couldn't read the bundled skill template at ${SKILL_TEMPLATE_PATH} ` +
+                `— is this a complete ledger install, not a partial copy?`);
+        }
+        const skillAlreadyThere = existsSync(AGENTS_SKILL_FILE);
+        mkdirSync(AGENTS_SKILL_DIR, { recursive: true });
+        writeFileSync(AGENTS_SKILL_FILE, skillTemplate);
+        console.log(`✓ clerk skill ${skillAlreadyThere ? "updated at" : "installed at"} ${AGENTS_SKILL_FILE}`);
+        for (const linkPath of SKILL_SYMLINK_TARGETS) {
+            linkSkill(linkPath);
+        }
+    });
+}

package/dist/cli/index.js

@@ -1,21 +1,47 @@
 #!/usr/bin/env node
 // Must come first — see the comment in suppress-experimental-warnings.ts.
 import "./suppress-experimental-warnings.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { registerAgentCommands } from "./commands/agents.js";
 import { registerCatchupCommand } from "./commands/catchup.js";
 import { registerClerkCommands } from "./commands/clerk.js";
 import { registerDocsCommand } from "./commands/docs.js";
 import { registerEventCommands } from "./commands/events.js";
+import { registerInitCommand } from "./commands/init.js";
 import { registerProjectCommands } from "./commands/projects.js";
 import { registerRoadmapCommands } from "./commands/roadmap.js";
 import { touchClerkHeartbeat } from "../db/client.js";
+// The version is derived from the package's own package.json at runtime —
+// package.json is the ONLY source of it. This entry compiles to
+// dist/cli/index.js, two levels below the package root, so resolve the
+// file relative to *this running code's own location* rather than the cwd
+// (same approach as docs.ts): that works from any invocation directory, in
+// a dev checkout, and in an npm install (the npm tarball carries
+// package.json at its root — verified in the 0.1.2 tarball). Publishing
+// bumps package.json, and since this reads package.json, the two can never
+// desync — a literal here is a second copy and is forbidden.
+// Graceful degradation: if the file can't be read or parsed (a corrupt
+// install), report "unknown" instead of throwing — a version query must
+// never crash the CLI (item 30, DECISIONS.md).
+function packageVersion() {
+    const pkgJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    try {
+        const parsed = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+        return parsed.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 const program = new Command();
 program
     .name("ledger")
     .description("Durable state store for a personal agent-orchestration workflow " +
     "(projects, roadmap, dispatched agents, events).")
-    .version("0.1.0");
+    .version(packageVersion());
 registerProjectCommands(program);
 registerRoadmapCommands(program);
 registerAgentCommands(program);
@@ -23,6 +49,7 @@ registerEventCommands(program);
 registerClerkCommands(program);
 registerCatchupCommand(program);
 registerDocsCommand(program);
+registerInitCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync(process.argv);

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@devwithdavid/ledger",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Personal agent-orchestration ledger: SQLite state store, CLI, and herdr watcher plugin.",
+  "license": "MIT",
+  "repository": "https://yggdrasil.thekartiks.com/chewbakartik/ledger.git",
   "type": "module",
   "bin": {
     "ledger": "dist/cli/index.js"
   },
   "files": [
+    "LICENSE",
     "dist",
     "LEDGER.md",
     "README.md",
-    "herdr-plugin.toml"
+    "herdr-plugin.toml",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/skills/ledger/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: ledger
+description: Act as the first clerk for `ledger`, a personal SQLite-backed agent-orchestration tool (herdr + treehouse). Use when asked to register a ledger project, break work into a roadmap, dispatch a coding agent via ledger, check on dispatched agents, run a ledger catch-up, or otherwise manage state via the `ledger` CLI.
+---
+
+Run `ledger docs` and read its full output before doing anything else in
+this role — that prints the complete clerk/agent reference (CLI surface,
+what the first clerk is responsible for, what a dispatched agent is told).
+
+This skill is intentionally just a pointer, not a copy of that content, so
+it can't drift out of sync with the real CLI, and carries no machine-
+specific path — `ledger docs` resolves its own reference doc relative to
+wherever the `ledger` package is actually installed on this machine.
+
+If `ledger` isn't found on PATH, either it isn't installed here yet
+(`npm install -g @devwithdavid/ledger`, then `ledger init` — see the
+project's README for prerequisites), or it's installed but npm's global
+bin directory isn't on PATH (`npm config get prefix`, then confirm
+`<that prefix>/bin` is in `$PATH` — common after switching Node
+versions/managers).