@anhvupt/tito 0.3.1 → 0.3.3

package/dist/core/worktree.js

@@ -0,0 +1,295 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ConfigValidationError, parseConfig } from "./config.js";
+import { BRANCH_BASES } from "./git-flow.js";
+export class WorktreeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorktreeError";
+        this.code = code;
+    }
+}
+const BASE_BRANCHES = new Set(BRANCH_BASES);
+function errno(error) {
+    if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") {
+        return error.code;
+    }
+    return null;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isMainCheckout(path) {
+    try {
+        return statSync(join(path, ".git")).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function spawnGit(cwd, args) {
+    const result = spawnSync("git", [...args], { cwd, encoding: "utf8" });
+    if (result.error)
+        throw new WorktreeError("git", result.error.message);
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+function gitOk(cwd, args) {
+    const result = spawnGit(cwd, args);
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "git command failed").trim();
+        throw new WorktreeError("git", detail);
+    }
+    return result.stdout;
+}
+function parseCount(stdout) {
+    const count = Number(stdout.trim());
+    if (!Number.isInteger(count) || count < 0) {
+        throw new WorktreeError("git", `Unexpected rev-list count: ${stdout.trim()}`);
+    }
+    return count;
+}
+function revCount(cwd, range) {
+    return parseCount(gitOk(cwd, ["rev-list", "--count", range]));
+}
+function parsePorcelain(text) {
+    const entries = [];
+    let path = null;
+    let branch = null;
+    let prunable = false;
+    let saw = false;
+    const flush = () => {
+        if (!saw || path === null)
+            return;
+        entries.push({ path, branch, prunable });
+        path = null;
+        branch = null;
+        prunable = false;
+        saw = false;
+    };
+    for (const line of text.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            flush();
+            path = line.slice("worktree ".length);
+            saw = true;
+            continue;
+        }
+        if (!saw)
+            continue;
+        if (line.startsWith("branch ")) {
+            const ref = line.slice("branch ".length);
+            branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+            continue;
+        }
+        if (line === "detached" || line.startsWith("detached ")) {
+            branch = null;
+            continue;
+        }
+        if (line.startsWith("prunable")) {
+            prunable = true;
+            continue;
+        }
+        if (line.length === 0)
+            flush();
+    }
+    flush();
+    return entries;
+}
+function parseMergedBranches(stdout) {
+    const names = new Set();
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        names.add(trimmed.replace(/^[*+]\s+/, ""));
+    }
+    return names;
+}
+function readDefaultBase(root) {
+    const path = join(root, "tito.yaml");
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (errno(error) === "ENOENT")
+            return undefined;
+        throw new WorktreeError("config", `Cannot read ${path}.`);
+    }
+    try {
+        return parseConfig(text).git?.defaultBase;
+    }
+    catch (error) {
+        if (error instanceof ConfigValidationError)
+            throw new WorktreeError("config", error.message);
+        throw error;
+    }
+}
+function resolveBase(root) {
+    const configured = readDefaultBase(root);
+    if (configured !== undefined)
+        return configured;
+    const existing = new Set();
+    for (const name of BRANCH_BASES) {
+        if (spawnGit(root, ["rev-list", "--count", name]).status === 0)
+            existing.add(name);
+    }
+    return BRANCH_BASES.find((name) => existing.has(name)) ?? "main";
+}
+function unpushedCount(worktreePath) {
+    const result = spawnGit(worktreePath, ["rev-list", "--count", "@{upstream}..HEAD"]);
+    if (result.status !== 0)
+        return null;
+    return parseCount(result.stdout);
+}
+function mergedPullRequestListed(stdout) {
+    const text = stdout.trim();
+    if (text.length === 0 || text === "[]")
+        return false;
+    try {
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) && parsed.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultGhMerged(root) {
+    let available;
+    return (branch) => {
+        if (available === undefined) {
+            const probe = spawnSync("gh", ["--version"], { encoding: "utf8" });
+            available = probe.error === undefined && probe.status === 0;
+        }
+        if (!available)
+            return null;
+        const result = spawnSync("gh", ["pr", "list", "--state", "merged", "--head", branch, "--json", "number"], { cwd: root, encoding: "utf8", timeout: 15000 });
+        if (result.error || result.status !== 0)
+            return false;
+        return mergedPullRequestListed(result.stdout ?? "");
+    };
+}
+function cherryMerged(root, base, branch) {
+    const lines = gitOk(root, ["cherry", base, branch])
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    return lines.length > 0 && lines.every((line) => line.startsWith("-"));
+}
+function branchMoved(root, branch) {
+    return spawnGit(root, ["rev-parse", "--verify", "--quiet", `${branch}@{1}`]).status === 0;
+}
+function row(input) {
+    return input;
+}
+function classifyEntry(input) {
+    const { entry } = input;
+    const missing = entry.prunable || !isDirectory(entry.path);
+    const behind = entry.branch === null ? 0 : revCount(input.root, `${entry.branch}..${input.base}`);
+    const baseFields = {
+        path: entry.path,
+        branch: entry.branch,
+        behind,
+        squashMerged: false,
+    };
+    if (missing)
+        return row({ ...baseFields, status: "missing", removable: false });
+    const protectedCheckout = isMainCheckout(entry.path) || entry.branch === null || BASE_BRANCHES.has(entry.branch);
+    if (protectedCheckout)
+        return row({ ...baseFields, status: "protected", removable: false });
+    if (gitOk(entry.path, ["status", "--porcelain"]).trim().length > 0) {
+        return row({ ...baseFields, status: "dirty", removable: false });
+    }
+    const unpushed = unpushedCount(entry.path);
+    if (unpushed !== null && unpushed > 0) {
+        return row({ ...baseFields, status: "unmerged", removable: false });
+    }
+    const branch = entry.branch;
+    if (branch === null)
+        return row({ ...baseFields, status: "unmerged", removable: false });
+    const contained = input.merged.has(branch);
+    if (contained && behind > 0) {
+        return row({ ...baseFields, status: "merged-clean", removable: true });
+    }
+    const pullRequest = input.ghMerged(branch);
+    if (pullRequest === true) {
+        return row({ ...baseFields, status: "merged-clean", removable: true, squashMerged: true });
+    }
+    if (pullRequest === null && cherryMerged(input.root, input.base, branch)) {
+        return row({ ...baseFields, status: "merged-clean", removable: true });
+    }
+    if (contained && behind === 0) {
+        if (branchMoved(input.root, branch)) {
+            return row({ ...baseFields, status: "merged-clean", removable: true });
+        }
+        return row({ ...baseFields, status: "fresh", removable: false });
+    }
+    if (behind > 0)
+        return row({ ...baseFields, status: "behind", removable: false });
+    return row({ ...baseFields, status: "unmerged", removable: false });
+}
+function deleteLocalBranch(root, branch, squashMerged) {
+    if (BASE_BRANCHES.has(branch)) {
+        throw new WorktreeError("git", `Refusing to delete base branch ${branch}.`);
+    }
+    const soft = spawnGit(root, ["branch", "-d", branch]);
+    if (soft.status === 0)
+        return;
+    if (!squashMerged) {
+        const detail = (soft.stderr || soft.stdout || "git branch -d failed").trim();
+        throw new WorktreeError("git", detail);
+    }
+    gitOk(root, ["branch", "-D", branch]);
+}
+export function tidyWorktrees(input) {
+    const root = resolve(input.root);
+    if (!isDirectory(root))
+        throw new WorktreeError("not-a-directory", `${root} is not a directory.`);
+    const base = resolveBase(root);
+    const merged = parseMergedBranches(gitOk(root, ["branch", "--merged", base]));
+    const ghMerged = input.ghMerged ?? defaultGhMerged(root);
+    const rows = parsePorcelain(gitOk(root, ["worktree", "list", "--porcelain"])).map((entry) => classifyEntry({ root, base, entry, merged, ghMerged }));
+    const removed = [];
+    const deletedBranches = [];
+    let pruned = false;
+    if (input.confirm === true) {
+        for (const item of rows) {
+            if (!item.removable || item.branch === null || BASE_BRANCHES.has(item.branch))
+                continue;
+            if (isMainCheckout(item.path))
+                continue;
+            gitOk(root, ["worktree", "remove", item.path]);
+            removed.push(item.path);
+            deleteLocalBranch(root, item.branch, item.squashMerged);
+            deletedBranches.push(item.branch);
+        }
+        if (rows.some((item) => item.status === "missing")) {
+            gitOk(root, ["worktree", "prune"]);
+            pruned = true;
+        }
+    }
+    return { root, base, rows, removed, deletedBranches, pruned };
+}
+export function formatTidyReport(report) {
+    const lines = [`base: ${report.base}`];
+    for (const item of report.rows) {
+        lines.push(`worktree: ${item.path}`, `branch: ${item.branch ?? "detached"}`, `status: ${item.status}`, `behind: ${item.behind}`, `removable: ${item.removable ? "yes" : "no"}`);
+    }
+    for (const path of report.removed)
+        lines.push(`removed: ${path}`);
+    for (const branch of report.deletedBranches)
+        lines.push(`deleted-branch: ${branch}`);
+    if (report.pruned)
+        lines.push("pruned: yes");
+    return `${lines.join("\n")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhvupt/tito",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Chat-first engineering coordinator for solo builders. The plan is the spec: decisions, test cases, and docs.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test"
+    "test": "npm run build && node --test test/"
   },
   "engines": {
     "node": ">=20"

package/templates/cursor/AGENTS.md

@@ -0,0 +1,41 @@
+# Tito bootstrap
+
+This project uses Tito as its root engineering coordinator.
+
+- Start every Tito-coordinated chat response exactly with `Hola, Tito here!`
+  The marker is for chat only, never CLI or machine-readable output.
+- Sometimes add one short joke after that greeting. The joke does not replace the answer. Skip it when the user is blocked, when the news is bad, and in CLI or machine-readable output.
+- Treat ordinary user requests as Tito-coordinated work by default.
+- Read `TITO-INITIAL-BRIEF.md` when planning, editing, or resolving policy.
+- Recommend Ask for read-only discovery, Plan for ambiguous or critical work,
+  and Agent only for one approved implementation slice.
+- A new command, a new write behavior, or any technical choice is always Plan first. That response is the plan only. No source edits.
+- Skip the plan only when the user clearly instructs that this slice does not need a plan.
+- Implementation starts only after that plan is approved.
+- Confirm intent before clarifying. Questions are only for large decisions; zero is fine.
+- Tito decides small and medium choices and reports them. `client-careful` still asks for medium decisions. `solo-balanced` and `solo-fast` decide both.
+- Tito asks only for large or irreversible choices: product vision or scope, a new command or write behavior, a new dependency, a public CLI or API contract, a data or schema migration, security or permissions, premium-model fan-out, push, a pull request when auto-create is off, merge, deploy, delete, `--confirm` cleanups, and the safety floor.
+- Every update that follows a Tito decision carries one `Decided:` line listing those decisions.
+- Research current official sources and judge them before trusting; adopt maintained tools before building our own; show options with pros and cons for this project.
+- Plans open with Domain (business impact first), then Decisions, Test cases, Docs impact, and Slices and branch. Decisions name conventions, and test cases are tagged AAA.
+- Suggest the git branch and change type, then check out only after the user accepts.
+- Never approve a pull request. Never merge unless the user calls for the merge and the pull request already has an approval.
+- Do not merge a slice branch into `main`, `master`, `dev`, or `develop`, on the machine or on the remote, unless the user calls for that merge and the pull request already has an approval. Finishing a slice leaves the branch as it is.
+- Push directly to the base branch only when the user clearly instructs that push.
+- Tito does not code in this chat. Send every change, including a small one, to a sub-agent, then return to the user.
+- Before writing an approved slice, list installed skills, read only each name and description, and name in the handoff the ones the writer must read.
+- The implementation handoff names the skills it will read.
+- Every sub-agent launch names the model slug from the live catalog.
+- Coding sub-agents follow the profile cap: `client-careful` 3, `solo-balanced` 6, `solo-fast` 12. Each has its own plan and branch. Documentation writers stay one at a time. Check out each branch only after the user accepts that branch.
+- When two or more slices are independent, send those sub-agents together, each on its own branch, up to that cap. Do not line them up one after another when they can run together. After the handoff, return to the user.
+- Preserve uncommitted work.
+- Select specialist advisers and reviewers only when the task needs them. They stay read-only.
+- Stop for human approval between reviewable slices.
+- Never commit, push, publish, deploy, or perform irreversible external actions
+  without explicit approval.
+- Use the `/tito` skill when the user invokes it explicitly.
+- Ask before locking a large decision or a product-vision change. One obvious reading continues after a one-line confirmation. After the user answers, the plan records that decision and includes guidance code when it removes implementation ambiguity. Coding agents follow the approved approach.
+- Plans own technical decisions and include guidance code when useful.
+
+Keep this bootstrap compact. Load detailed workflow policy from the brief and
+scoped project surfaces only when relevant.

package/templates/cursor/rules/commit-branch.mdc

@@ -0,0 +1,8 @@
+---
+description: Commit subjects and branch names.
+alwaysApply: false
+---
+
+- Bases are `dev`, `develop`, `main`, and `master`. `dev` and `develop` are interchangeable. `main` and `master` are interchangeable.
+- A commit subject is `<type>: <sentence>`. The type is the same token as the branch type: `feat`, `fix`, `hot-fix`, `chores`, `refactor`, or `debug`.
+- The words after the colon are one finished sentence of at most 70 words. The type is not counted in those 70 words. The body is a separate description.

package/templates/cursor/rules/init-upgrade-admin.mdc

@@ -0,0 +1,15 @@
+---
+description: Tito init, upgrade, and the opt-in admin index.
+alwaysApply: false
+---
+
+- Init creates `.github/pull_request_template.md` from Tito's template when it is missing. Upgrade replaces that file with Tito's template.
+- In a terminal, `tito init --confirm` asks for the git base, screen language, tenancy, surfaces, and whether to auto-create a pull request after implementation. The auto-pull-request question defaults to yes. Upgrade asks only for settings missing from `tito.yaml`. Storing that answer does not open a pull request.
+- Chat is the primary interface. Implement each operation once, then expose the same behavior as `tito <command>` and `/tito-<command>`.
+- Multi-tenant or multi-surface work includes isolation, consistency, propagation, and permission cases.
+
+Per-project Tito install stays. Opt-in `tito admin add|list|remove|refresh`
+registers repos under `~/.config/tito/admin/` and stores commit subject, date,
+and paths — not diffs. A weekly retro stores counts only, never review text.
+A project `tito.yaml` overrides a personal default; do
+not weaken the safety floor.

package/templates/cursor/rules/pull-request.mdc

@@ -0,0 +1,13 @@
+---
+description: Pull request descriptions, review-fix plans, and feedback files.
+globs: .github/pull_request_template.md,.tito/feedback/**/*.md
+alwaysApply: false
+---
+
+- When the user reviews a plan, save Tito's plan and the user's edit as separate files under `.tito/feedback/<slug>/`. `review.md` starts with front matter `outcome: accepted | edited | expanded`.
+- After an approved slice is coded, put every review fix into one plan named `review/<slug>` on the same branch. Ask before opening a pull request only after that plan is coded, or when the user accepts the code with no changes.
+- A pull request description has four parts within 2 to 50 lines: a one-line problem, what changed, review fixes, and checks for lint, code quality, conventions, tests, build, and docs.
+- When the user comments on an open pull request, Tito updates that pull request's description in the same turn. Review fixes lists every comment, including the earlier ones. A thread reply does not replace that update.
+- After a pull request is merged, ask before the next slice. Switch back to the base branch only when the user says so clearly.
+- Docs from the plan are updated or waived before a pull request.
+- The module-end docs writers still run.

package/templates/cursor/rules/screen-language.mdc

@@ -0,0 +1,12 @@
+---
+description: Vietnamese routes and screen text, English screen text, and UTC timestamps.
+alwaysApply: false
+---
+
+- Code stays English.
+- In a Vietnamese app (`screenLanguage: vi`), routes and slugs are Vietnamese first. The public path is native Vietnamese, for example `/tien-ich/ca-phe`. Do not invent that Vietnamese by translating an English slug word for word. If the product is bilingual, the English route comes second.
+- An English app (`screenLanguage: en`) keeps English routes and slugs.
+- In a Vietnamese app (`screenLanguage: vi`), every string a person reads is Vietnamese: tables, labels, buttons, headings, and messages. Write native Vietnamese first. Do not invent it by translating English word for word. English may exist as a second field only when the product is bilingual, and it comes after the Vietnamese.
+- An English app (`screenLanguage: en`) stays English on screen.
+- When `screenLanguage` is missing and the screen language is unclear, Tito asks once. One obvious reading continues without a question.
+- Globalized apps store timestamps in UTC and show them in the user's timezone. There is no switch to turn that off.

package/templates/cursor/skills/tito/SKILL.md

@@ -40,7 +40,7 @@ For Plan work, prefer a Reasoning-tier model unless the plan is obvious and
 bounded or the user chose another model. The implementation agent follows the approved decision and does not invent a new one. Include concise guidance code,
 signatures, schemas, or pseudocode where it removes ambiguity.
 
-Discover restates the goal and what is out of scope in one or two sentences, then asks whether that is what the user wants, and waits. After the user confirms, ask one batch of 3 to 5 clarifying questions. Each question offers options and a recommended default. `solo-fast` does only the intent check, plus questions about real ambiguity. `client-careful` and `solo-balanced` use the full batch. One obvious reading still continues, after a one-line confirmation. Ask before locking a technical decision or a product-vision change. After the user answers, the plan records that decision and includes guidance code when it removes implementation ambiguity.
+Discover runs the intent check only when the goal is unclear: restate the goal and what is out of scope in one or two sentences, ask whether that is what the user wants, and wait. One obvious reading continues without stopping. Ask clarifying questions only for large decisions, such as product vision or scope, a new dependency, a public contract, a migration, security, or anything irreversible. Each question offers options and a recommended default. Zero questions is fine. Tito decides small and medium choices itself and reports them on one `Decided:` line so the user can overrule them. `client-careful` still asks for medium decisions. After the user answers, the plan records that decision and includes guidance code when it removes implementation ambiguity.
 
 The workflow is Discover → Plan → Human Approval → Code → Verify → Docs gate → Review. Every plan has five sections in this order: Domain (opens with one Business impact line, then terms, rules, invariants, and who uses it), Decisions (each names the principle and the project convention it follows, with where that convention lives), Test cases (each has an ID and a layer tag `[unit]`, `[integration]`, or `[e2e]`; behavior tests use Arrange / Act / Assert; edge cases are one line each), Docs impact, and Slices and branch. The approved plan is the spec. For a single slice, the user may say "skip test discussion" or "skip docs", in the same spirit as skipping the plan.
 
@@ -75,9 +75,9 @@ A plan that touches shared data includes only the kinds that apply:
 ## Execute
 
 1. Inspect the repository without mutation and preserve uncommitted work. When a Tito command exists, use that same core behavior in chat instead of sending the person to the terminal.
-2. Discover: restate the goal and what is out of scope, confirm that reading, then ask the clarifying batch the risk profile calls for. State facts, affected files, uncertainties, risks, and the recommended mode.
+2. Discover: restate the goal and what is out of scope, confirm that reading only when the goal is unclear, then ask only the large questions the risk profile calls for. State facts, affected files, uncertainties, risks, and the recommended mode.
 3. For Plan work, produce one plan with Domain, Decisions, Test cases, Docs impact, and Slices and branch, then stop for approval. The approved plan is the spec.
-4. Before Agent work, provide the implementation handoff required by the brief.
+4. Before Agent work, provide the implementation handoff required by the brief. List installed skills, read only each name and description, and name the ones the writer must read without loading the whole set.
 5. Tito does not code in this chat. Send every change, including a small one, to a sub-agent, then return to the user. When two or more slices are independent, send those sub-agents together, each on its own branch, up to the profile cap. Do not line them up one after another when they can run together. `client-careful` may run 3 coding sub-agents, `solo-balanced` 6, and `solo-fast` 12. Each has its own plan and branch. Check out each branch only after the user accepts that branch. Documentation writers stay one at a time. Specialist advisers and reviewers stay read-only.
 6. Code the approved slice by writing the spec doc named in Docs impact first, then the failing tests, then the code. Confirm they fail before implementing until they pass. A test beyond the approved list is flagged as new. A bug fix starts with a test that reproduces the bug. Writing is not committing. Waive the spec doc when the slice changes no behavior.
 7. Verify: report each approved test ID as passing or failing, plus lint and build.

package/templates/cursor/skills/tito-worktree-tidy/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: tito-worktree-tidy
+description: Report stale git worktrees and remove merged clean ones when confirmed. Invoke explicitly with /tito-worktree-tidy. Uses the same report as tito worktree tidy.
+disable-model-invocation: true
+---
+
+# Tito worktree tidy
+
+Chat adapter for `npx tito worktree tidy`. Run that command and show its stdout unchanged.
+Start the chat response exactly with `Hola, Tito here!` The greeting is not part of the command output.
+
+Add `--root <path>` only when the user names another directory. Add `--confirm` only when the user asks to remove merged clean worktrees. Do not reimplement tidy by running git yourself. Do not delete remote branches. Do not rebase. Do not remove the main checkout, a base branch, or a worktree with uncommitted or unpushed work.
+
+After a pull request is merged, Tito first runs `tito worktree tidy` report-only, then asks before the next slice.