@4-r-c-4-n-4/todo 0.1.5 → 0.1.6

package/BIBLE.md

@@ -140,6 +140,19 @@ git branch -d todo/<parent-id>
 
 If you need manual control instead of a loop, use `todo work --skip-branch <child-id>` to activate a child without a redundant checkout. Do NOT use plain `todo work` for subsequent children on a shared branch — it performs a no-op checkout and prints confusing resume output.
 
+### Branch Protection (recommended)
+
+The local-merge step above is convenient for solo work, but `todo` is built for agent-driven flows where unreviewed code shouldn't land on `main` silently. GitHub's branch-protection rules close that gap without adding any process inside the tool — turn them on once and the same `todo` workflow stops bypassing review.
+
+For `main`, enable:
+
+- **Require a pull request before merging** — the agent stops at the PR; you click Merge.
+- **Require status checks to pass** — your CI's `Lint, typecheck, test` job. Catches the kind of regression that this session's commit `b6709ed` (missing `pretest` hook) would have stopped on red.
+- **Require linear history** — enforces the skill's `--no-ff` rule. Squash merges would orphan the resolution-commit SHAs stored in `.todo/done/<id>.json`.
+- **Require approvals (optional)** — even for a solo repo, setting "1 approval" forces you to actually open the PR and skim the diff before clicking through. Cheap insurance against autopilot merges.
+
+Once protected, the closing step becomes `todo pr` (push branch + open PR + stop) instead of a local merge. The local-merge sequence in the previous sections remains valid for unprotected repos or quick solo work.
+
 ---
 
 ## Ticket Types

package/dist/branch-guard.d.ts

@@ -6,4 +6,13 @@ export interface BranchCheck {
 }
 export declare function checkOnExpectedBranch(ticket: Ticket, currentBranch: string): BranchCheck;
 export declare function checkBranchHasTodoCommit(ticket: Ticket, repoRoot: string, commitPrefix: string): BranchCheck;
+/**
+ * True iff the ticket has at least one child AND every child is in a
+ * terminal state (done/wontfix/duplicate). Parents in this shape carry no
+ * code commit of their own — the work lives in children whose commits use
+ * `todo:<child-id>` prefixes — so the commit-prefix branch guard should
+ * skip them. Children with missing files are treated as non-terminal so
+ * the guard stays conservative.
+ */
+export declare function isParentWithAllChildrenClosed(ticket: Ticket, repoRoot: string): boolean;
 export declare function checkWorkingTreeClean(repoRoot: string): BranchCheck;

package/dist/branch-guard.js

@@ -8,8 +8,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.expectedBranchFor = expectedBranchFor;
 exports.checkOnExpectedBranch = checkOnExpectedBranch;
 exports.checkBranchHasTodoCommit = checkBranchHasTodoCommit;
+exports.isParentWithAllChildrenClosed = isParentWithAllChildrenClosed;
 exports.checkWorkingTreeClean = checkWorkingTreeClean;
 const git_js_1 = require("./git.js");
+const ticket_js_1 = require("./ticket.js");
 function expectedBranchFor(ticket) {
     if (ticket.work?.branch)
         return ticket.work.branch;
@@ -42,6 +44,31 @@ function checkBranchHasTodoCommit(ticket, repoRoot, commitPrefix) {
             `if this ticket genuinely has no code change attached.`,
     };
 }
+/**
+ * True iff the ticket has at least one child AND every child is in a
+ * terminal state (done/wontfix/duplicate). Parents in this shape carry no
+ * code commit of their own — the work lives in children whose commits use
+ * `todo:<child-id>` prefixes — so the commit-prefix branch guard should
+ * skip them. Children with missing files are treated as non-terminal so
+ * the guard stays conservative.
+ */
+function isParentWithAllChildrenClosed(ticket, repoRoot) {
+    const children = ticket.relationships?.children ?? [];
+    if (children.length === 0)
+        return false;
+    for (const childId of children) {
+        let child;
+        try {
+            child = (0, ticket_js_1.readTicket)(repoRoot, childId);
+        }
+        catch {
+            return false;
+        }
+        if (!ticket_js_1.TERMINAL_STATES.includes(child.state))
+            return false;
+    }
+    return true;
+}
 function checkWorkingTreeClean(repoRoot) {
     if (!(0, git_js_1.hasUncommittedChanges)(repoRoot))
         return { ok: true };

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const commander_1 = require("commander");
 const analyze_js_1 = require("./commands/analyze.js");
 const close_js_1 = require("./commands/close.js");
@@ -13,16 +15,20 @@ const link_js_1 = require("./commands/link.js");
 const list_js_1 = require("./commands/list.js");
 const new_js_1 = require("./commands/new.js");
 const next_js_1 = require("./commands/next.js");
+const pr_js_1 = require("./commands/pr.js");
 const scan_js_1 = require("./commands/scan.js");
 const show_js_1 = require("./commands/show.js");
 const sync_js_1 = require("./commands/sync.js");
 const transition_js_1 = require("./commands/transition.js");
 const work_js_1 = require("./commands/work.js");
+// Read version from the package.json shipped alongside dist/. Avoids drift
+// between the published npm version and what `todo --version` prints.
+const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf8"));
 const program = new commander_1.Command();
 program
     .name("todo")
     .description("Git-native work tracking for coding agents")
-    .version("1.0.0");
+    .version(pkg.version);
 (0, init_js_1.registerInit)(program);
 (0, new_js_1.registerNew)(program);
 (0, list_js_1.registerList)(program);
@@ -39,4 +45,5 @@ program
 (0, dedup_js_1.registerDedup)(program);
 (0, install_hooks_js_1.registerInstallHooks)(program);
 (0, sync_js_1.registerSync)(program);
+(0, pr_js_1.registerPr)(program);
 program.parse(process.argv);

package/dist/commands/close.js

@@ -36,10 +36,15 @@ function registerClose(program) {
                     console.error(`Error: ${branchCheck.message}`);
                     process.exit(1);
                 }
-                const commitCheck = (0, branch_guard_js_1.checkBranchHasTodoCommit)(ticket, repoRoot, (0, config_js_1.getCommitPrefix)(config));
-                if (!commitCheck.ok) {
-                    console.error(`Error: ${commitCheck.message}`);
-                    process.exit(1);
+                // Parents with all-terminal children carry no code commit of
+                // their own — skip the commit-prefix check for them. The
+                // branch-match check above still fires.
+                if (!(0, branch_guard_js_1.isParentWithAllChildrenClosed)(ticket, repoRoot)) {
+                    const commitCheck = (0, branch_guard_js_1.checkBranchHasTodoCommit)(ticket, repoRoot, (0, config_js_1.getCommitPrefix)(config));
+                    if (!commitCheck.ok) {
+                        console.error(`Error: ${commitCheck.message}`);
+                        process.exit(1);
+                    }
                 }
             }
             else {

package/dist/commands/pr.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerPr(program: Command): void;

package/dist/commands/pr.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPr = registerPr;
+const context_js_1 = require("../context.js");
+const errors_js_1 = require("../errors.js");
+const git_js_1 = require("../git.js");
+const pr_js_1 = require("../pr.js");
+const ticket_js_1 = require("../ticket.js");
+function registerPr(program) {
+    program
+        .command("pr")
+        .description("Push the current todo/<id> branch and open (or update) a GitHub PR")
+        .option("--base <branch>", "PR base branch (default: repo default)")
+        .option("--draft", "open the PR as a draft")
+        .action((opts) => {
+        const ctx = (0, context_js_1.getContext)(true);
+        const { repoRoot } = ctx;
+        try {
+            let branch;
+            try {
+                branch = (0, git_js_1.getCurrentBranch)(repoRoot);
+            }
+            catch {
+                console.error("Error: could not resolve current branch (detached HEAD?).");
+                process.exit(1);
+            }
+            const id = (0, pr_js_1.branchToTicketId)(branch);
+            if (!id) {
+                console.error(`Error: not on a todo/<id> branch (HEAD is on '${branch}').\n` +
+                    "  Run `todo work <id>` first.");
+                process.exit(1);
+            }
+            let ticket;
+            try {
+                ticket = (0, ticket_js_1.readTicket)(repoRoot, id);
+            }
+            catch {
+                console.error(`Error: branch '${branch}' references ticket '${id}' but no .todo/ ` +
+                    "file exists for it. Was it deleted?");
+                process.exit(1);
+            }
+            const outcome = (0, pr_js_1.runPr)(repoRoot, branch, ticket, { base: opts.base, draft: !!opts.draft }, (0, pr_js_1.defaultPrEnv)(repoRoot));
+            if (outcome.kind === "error") {
+                console.error(`Error: ${outcome.message}`);
+                process.exit(1);
+            }
+            console.log(outcome.kind === "created"
+                ? `Opened PR: ${outcome.url}`
+                : `Updated PR: ${outcome.url}`);
+        }
+        catch (err) {
+            (0, errors_js_1.handleError)(err);
+        }
+    });
+}

package/dist/pr.d.ts

@@ -0,0 +1,35 @@
+import type { Ticket } from "./types.js";
+/** Extract the ticket id from a `todo/<id>` branch name. */
+export declare function branchToTicketId(branch: string): string | null;
+/**
+ * Truncate a one-line title to MAX_TITLE_CHARS, ending with an ellipsis
+ * when truncated. Single-line input only — strips newlines.
+ */
+export declare function makeTitle(summary: string): string;
+/**
+ * Render the PR body for a given root ticket. For parents, includes a
+ * "Children" section with each terminal child's resolution. For single
+ * tickets, includes the description and resolution.
+ */
+export declare function makeBody(ticket: Ticket, repoRoot: string): string;
+export interface PrEnv {
+    gh: (args: string[], input?: string) => string;
+    git: (args: string[]) => string;
+    hasGh: () => boolean;
+}
+export declare function defaultPrEnv(cwd: string): PrEnv;
+export interface PrOptions {
+    base?: string;
+    draft?: boolean;
+}
+export type PrOutcome = {
+    kind: "created";
+    url: string;
+} | {
+    kind: "updated";
+    url: string;
+} | {
+    kind: "error";
+    message: string;
+};
+export declare function runPr(repoRoot: string, currentBranch: string, ticket: Ticket, opts: PrOptions, env: PrEnv): PrOutcome;

package/dist/pr.js

@@ -0,0 +1,174 @@
+"use strict";
+// Pull-request creation helpers used by `todo pr`.
+//
+// The CLI command is a thin wrapper around the `gh` binary plus `git push`,
+// with title and body auto-generated from the ticket(s) on the current
+// todo/<id> branch. Keeping the formatting and decision logic in this
+// module so it can be unit-tested without touching the network.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.branchToTicketId = branchToTicketId;
+exports.makeTitle = makeTitle;
+exports.makeBody = makeBody;
+exports.defaultPrEnv = defaultPrEnv;
+exports.runPr = runPr;
+const node_child_process_1 = require("node:child_process");
+const ticket_js_1 = require("./ticket.js");
+const MAX_TITLE_CHARS = 70;
+/** Extract the ticket id from a `todo/<id>` branch name. */
+function branchToTicketId(branch) {
+    const m = branch.match(/^todo\/(.+)$/);
+    return m ? (m[1] ?? null) : null;
+}
+/**
+ * Truncate a one-line title to MAX_TITLE_CHARS, ending with an ellipsis
+ * when truncated. Single-line input only — strips newlines.
+ */
+function makeTitle(summary) {
+    const oneLine = summary.replace(/\s+/g, " ").trim();
+    if (oneLine.length <= MAX_TITLE_CHARS)
+        return oneLine;
+    return `${oneLine.slice(0, MAX_TITLE_CHARS - 1)}…`;
+}
+function shortSha(sha) {
+    if (!sha)
+        return "";
+    return sha.length > 7 ? sha.slice(0, 7) : sha;
+}
+/**
+ * Render the PR body for a given root ticket. For parents, includes a
+ * "Children" section with each terminal child's resolution. For single
+ * tickets, includes the description and resolution.
+ */
+function makeBody(ticket, repoRoot) {
+    const lines = [];
+    if (ticket.description) {
+        lines.push(ticket.description.trim());
+        lines.push("");
+    }
+    const children = ticket.relationships?.children ?? [];
+    if (children.length > 0) {
+        lines.push("## Children");
+        lines.push("");
+        for (const childId of children) {
+            let child;
+            try {
+                child = (0, ticket_js_1.readTicket)(repoRoot, childId);
+            }
+            catch {
+                lines.push(`- ${childId} — _ticket file missing_`);
+                continue;
+            }
+            const status = ticket_js_1.TERMINAL_STATES.includes(child.state)
+                ? child.state
+                : `**${child.state}**`;
+            const note = child.resolution?.note ?? "_no note_";
+            const sha = shortSha(child.resolution?.commit);
+            lines.push(`- **${child.id}** (${status}) — ${child.summary}` +
+                (sha ? ` _(${sha})_` : "") +
+                `\n  ${note}`);
+        }
+        lines.push("");
+    }
+    if (ticket.resolution?.note) {
+        lines.push("## Resolution");
+        lines.push("");
+        lines.push(ticket.resolution.note);
+        if (ticket.resolution.commit) {
+            lines.push("");
+            lines.push(`Commit: \`${shortSha(ticket.resolution.commit)}\``);
+        }
+        lines.push("");
+    }
+    lines.push("---");
+    lines.push(`<sub>Generated by \`todo pr\` from ticket ${ticket.id}.</sub>`);
+    return lines.join("\n").trim() + "\n";
+}
+function defaultPrEnv(cwd) {
+    return {
+        gh: (args, input) => {
+            return (0, node_child_process_1.execFileSync)("gh", args, {
+                cwd,
+                encoding: "utf8",
+                input,
+                stdio: input ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"],
+            }).trim();
+        },
+        git: (args) => (0, node_child_process_1.execFileSync)("git", args, { cwd, encoding: "utf8" }).trim(),
+        hasGh: () => {
+            try {
+                (0, node_child_process_1.execFileSync)("gh", ["--version"], { stdio: "ignore" });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+function findExistingPrUrl(env, branch) {
+    try {
+        const out = env.gh(["pr", "view", branch, "--json", "url", "-q", ".url"]);
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+function runPr(repoRoot, currentBranch, ticket, opts, env) {
+    if (!env.hasGh()) {
+        return {
+            kind: "error",
+            message: "`gh` CLI not found in PATH. Install from https://cli.github.com/ " +
+                "and run `gh auth login` once, or use the local-merge fallback " +
+                "documented in /todo-implement step 8.",
+        };
+    }
+    // Push branch first (idempotent; -u sets upstream if not set).
+    try {
+        env.git(["push", "-u", "origin", currentBranch]);
+    }
+    catch (err) {
+        return {
+            kind: "error",
+            message: `failed to push '${currentBranch}' to origin: ${err.message}\n` +
+                "  Confirm a git remote is configured and you have push access.",
+        };
+    }
+    const title = makeTitle(ticket.summary);
+    const body = makeBody(ticket, repoRoot);
+    const existingUrl = findExistingPrUrl(env, currentBranch);
+    if (existingUrl) {
+        try {
+            env.gh(["pr", "edit", currentBranch, "--title", title, "--body-file", "-"], body);
+            return { kind: "updated", url: existingUrl };
+        }
+        catch (err) {
+            return {
+                kind: "error",
+                message: `failed to update existing PR: ${err.message}`,
+            };
+        }
+    }
+    const createArgs = ["pr", "create", "--title", title, "--body-file", "-"];
+    if (opts.base)
+        createArgs.push("--base", opts.base);
+    if (opts.draft)
+        createArgs.push("--draft");
+    let url;
+    try {
+        url = env.gh(createArgs, body);
+    }
+    catch (err) {
+        return {
+            kind: "error",
+            message: `gh pr create failed: ${err.message}`,
+        };
+    }
+    // gh prints the URL as the last non-empty line.
+    const lines = url
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const lastLine = lines[lines.length - 1] ?? "";
+    return { kind: "created", url: lastLine };
+}

package/dist/state.js

@@ -34,6 +34,28 @@ function validateTransition(ticket, targetState, params, repoRoot) {
             if (!params.note) {
                 throw new Error(`Parent ticket requires a resolution note when closing as done`);
             }
+            // Every child must be in a terminal state. Belt-and-suspenders to
+            // the branch-guard check in close.ts — that one only fires when
+            // the commit-prefix needle is missing on the branch.
+            const openChildren = [];
+            const missingChildren = [];
+            for (const childId of ticket.relationships?.children ?? []) {
+                try {
+                    const child = (0, ticket_js_1.readTicket)(repoRoot, childId);
+                    if (!ticket_js_1.TERMINAL_STATES.includes(child.state)) {
+                        openChildren.push(`${childId} (${child.state})`);
+                    }
+                }
+                catch {
+                    missingChildren.push(childId);
+                }
+            }
+            if (missingChildren.length > 0) {
+                throw new Error(`Cannot close parent ${ticket.id}: child ticket(s) not found in .todo/: ${missingChildren.join(", ")}`);
+            }
+            if (openChildren.length > 0) {
+                throw new Error(`Cannot close parent ${ticket.id}: ${openChildren.length} child ticket(s) still open: ${openChildren.join(", ")}. Close them first.`);
+            }
             // commit is optional for parent (defaults to HEAD — caller handles HEAD resolution)
         }
         else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4-r-c-4-n-4/todo",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Git-native work tracking for coding agents",
   "main": "dist/cli.js",
   "bin": {