@anhvupt/tito 0.1.3 → 0.2.0

package/README.md

@@ -3,12 +3,13 @@
 **Quiet orchestration. Trusted continuity.**
 
 Tito is a chat-first engineering coordinator for solo builders. You talk to one
-coordinator; Tito explores the repository, chooses the right working mode,
-turns larger work into reviewable slices, and keeps implementation inside the
-scope you approved.
+coordinator. Tito confirms what you want, writes the plan as the spec, and
+sends only the approved slice to a sub-agent.
 
-It is local-first, Git-friendly, and designed to add coordination without
-replacing your project documentation, rules, or specialists.
+The spec records the decisions and the conventions behind them, the test cases
+you review before they are written, and the docs that must change. Tito is
+local-first and Git-friendly. It coordinates your documentation, rules, and
+specialists, and it updates the docs named in the plan before a pull request.
 
 ## What Tito helps with
 
@@ -17,9 +18,16 @@ replacing your project documentation, rules, or specialists.
 - **The right amount of process:** Tito recommends Ask for discovery, Plan for
   uncertain or critical work, and Agent only for an approved implementation
   slice.
-- **Plans that make decisions:** the planner owns technical choices, records
-  important trade-offs, and includes signatures, schemas, pseudocode, or
-  guidance code when that makes implementation clearer.
+- **Plans that make decisions:** Tito confirms the goal and what is out of
+  scope, then asks one batch of clarifying questions, lighter on `solo-fast`.
+  One obvious reading continues after a one-line confirmation. Tito still asks
+  before locking a technical decision or a product-vision change. The plan
+  records that decision and includes signatures, schemas, pseudocode, or
+  guidance code when that makes implementation clearer. Decisions name the
+  convention they follow. Test cases carry a layer tag: `[unit]`,
+  `[integration]`, or `[e2e]`. The plan also lists its docs impact.
+- **A light joke, sometimes:** after `Hola, Tito here!`, Tito may add one short
+  joke. It does not replace the answer, and it stays out of the CLI.
 - **Smaller reviews:** work is split into bounded slices with acceptance
   criteria, tests, forbidden changes, risks, and a stop condition.
 - **Safer changes:** Tito preserves uncommitted work, refuses silent overwrites,
@@ -52,11 +60,15 @@ mode decides whether it may change anything:
 | Tech docs writer | — | Update technical documentation |
 | User docs writer | — | Update user documentation |
 
-Several read-only specialists may work together. Only one mutating mode may be
-active. Backend and frontend work is split into sequential slices. After a
-module is finished, Tito schedules the tech docs writer and then the user docs
-writer, one at a time, before calling that module done. Skip that handoff only
-when you explicitly waive it for that module. Each specialist carries triggers,
+Several read-only specialists may work together. Coding sub-agents follow the
+profile cap: `client-careful` 3, `solo-balanced` 6, and `solo-fast` 12. Each
+has its own plan and branch. Tito does not code in the chat. Every change,
+including a small one, goes to a sub-agent, and Tito returns to the user.
+Backend and frontend work can run together inside that cap. Docs named in
+the plan are updated, or you waive them, before Tito offers a pull request.
+After a module is finished, Tito still schedules the tech docs writer and then
+the user docs writer, one at a time, before calling that module done. Skip
+that handoff only when you explicitly waive it for that module. Each specialist carries triggers,
 knowledge references, handoffs, and a stop condition. The detailed prompt stays
 lean and loads knowledge only when that mode needs it.
 
@@ -103,10 +115,11 @@ npx tito upgrade --confirm
 agents, skills, and the Tito section of `AGENTS.md`. Consumer rules, consumer
 agents, and other project skills stay untouched.
 
-Tito is installed in each project. It is not a required global command, and
-there is no global configuration yet. A future personal default would be
-overridden by that project's `tito.yaml`. The safety floor still cannot be
-weakened.
+Tito is installed in each project. It is not a required global command.
+An opt-in local admin index (`tito admin add|list|remove|refresh`) can register
+repos under `~/.config/tito/admin/` and store recent commit subjects, dates, and
+touched paths — never diffs. A project `tito.yaml` still overrides any personal
+default. The safety floor cannot be weakened.
 
 ## What works today
 
@@ -142,6 +155,11 @@ node dist/cli.js inspect
 node dist/cli.js inspect --root .
 node dist/cli.js apply --dry-run --profile solo-balanced
 node dist/cli.js init --profile solo-balanced
+node dist/cli.js admin add
+node dist/cli.js admin list
+node dist/cli.js admin refresh
+node dist/cli.js admin remove --root /path/to/repo
+node dist/cli.js admin retro --week 2026-W40
 ```
 
 `inspect` reads `tito.yaml` when it exists and checks whether `AGENTS.md` is
@@ -155,6 +173,15 @@ specialist agent files. It writes those files only with `--confirm`, and it
 refuses when an existing file would be overwritten. In chat, `/tito-init` runs
 this same command.
 
+`admin` is opt-in. `add` registers the current repo (or `--root`), `list` prints
+registered paths, `remove` drops one path, and `refresh` writes local branch plus
+the last 50 commit subjects, dates, and file paths (secrets like `.env` skipped;
+no diffs) for chat and CLI to share.
+
+`retro` builds that week's report from local git and saves `retros/<week>.json`
+and `retros/<week>.md` under the admin root. Review-fix counts, docs-blank, and
+merge duration say unavailable until GitHub data is added.
+
 ## How work moves
 
 The normal careful path is:
@@ -165,6 +192,39 @@ A small, obvious change can move from discovery directly to an explicitly
 approved slice. Review feedback can return an in-scope slice to implementation.
 Other lifecycle skips are rejected.
 
+## Git flow
+
+Tito suggests the branch before checkout, for example `Suggested branch: feat/short-slug from develop`. You accept it or name another base or type. The base is `dev`, `develop`, `main`, or `master`. `dev` and `develop` are interchangeable. `main` and `master` are interchangeable. The type is `feat`, `fix`, `hot-fix`, `chores`, `refactor`, or `debug`.
+
+`tito.yaml` may set the default base:
+
+```yaml
+schemaVersion: 1
+profile: client-careful
+git:
+  defaultBase: develop
+```
+
+`product.screenLanguage` is optional and accepts only `vi` or `en`. A missing product block is valid. A missing `screenLanguage` is valid. Unknown product fields are rejected. `product.tenancy` is optional (`single` or `multi`). `product.surfaces` is an optional list of `{ id }` entries. Missing `tenancy` and missing `surfaces` stay valid.
+
+```yaml
+product:
+  screenLanguage: vi
+  tenancy: single
+  surfaces:
+    - id: admin
+```
+
+- 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.
+
+A commit subject is `<type>: <sentence>`. The type is the same token as the branch type: `feat`, `fix`, `hot-fix`, `chores`, `refactor`, or `debug`. Examples: `feat: add commit message rule`, `fix: reject a duplicate surface id`, `chores: record the commit prefix rule`, and `hot-fix: stop a bad release build`. 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. When you review a plan, Tito saves that plan and your edit as separate files under `.tito/feedback/<slug>/`. `review.md` starts with front matter `outcome: accepted | edited | expanded`. Tito indexes only the plan name. The plan body stays in Cursor's plan file. After an approved slice is coded, every review fix goes into one plan named `review/<slug>` on the same branch. Tito asks before opening a pull request only after that plan is coded, or when you accept the code with no changes. The 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. Init creates `.github/pull_request_template.md` from Tito's template when it is missing. Upgrade replaces that file with Tito's template. Tito does not approve a pull request. Tito merges only when you call for the merge and the pull request already has an approval. After a pull request is merged, Tito asks before the next slice. Tito switches back to the base branch only when you say so clearly. Tito pushes directly to the base branch only when you clearly instruct that push.
+
 ## Development
 
 Requirements:

package/dist/cli.js

@@ -9,6 +9,8 @@ import { InspectionError, formatInspection, inspectRepository, } from "./core/in
 import { PlanError, formatAdoptionPlan, planAdoption } from "./core/plan.js";
 import { InitError, applyInitialization, formatInitialization, planInitialization, promptForProfile, } from "./core/init.js";
 import { applyUpgrade, formatUpgrade, planUpgrade, titoOwnedFiles, } from "./core/upgrade.js";
+import { AdminError, addRepo, formatContexts, formatRepos, listRepos, refreshRepos, removeRepo, resolveAdminRoot, } from "./core/admin.js";
+import { RetroError, buildRetro, formatRetro, retroJson, saveRetro, } from "./core/retro.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const help = `Tito — quiet orchestration for solo builders
 
@@ -18,6 +20,11 @@ Usage:
   tito apply --dry-run --profile <id> [--root <path>]
   tito init [--profile <id>] [--root <path>] [--confirm]
   tito upgrade [--root <path>] [--confirm]
+  tito admin add [--root <path>] [--admin-root <path>]
+  tito admin list [--admin-root <path>]
+  tito admin remove --root <path> [--admin-root <path>]
+  tito admin refresh [--admin-root <path>]
+  tito admin retro [--week <YYYY-Www>] [--timezone <IANA>] [--json] [--alerts] [--admin-root <path>]
 
 Options:
   -h, --help     Show help
@@ -28,6 +35,7 @@ Commands:
   apply          Dry-run an adoption plan. Writes are not available.
   init           Install Tito files and specialist agents. Confirm before writing.
   upgrade        Install the latest Tito and replace Tito-owned files only.
+  admin          Opt-in local repo index: add, list, remove, refresh, retro.
 `;
 function fail(message) {
     process.stderr.write(`${message}\n`);
@@ -238,6 +246,130 @@ function isTitoSource(root) {
         return false;
     }
 }
+function runAdmin(args) {
+    if (args.includes("-h") || args.includes("--help") || args.length === 0) {
+        process.stdout.write(help);
+        return;
+    }
+    const action = args[0];
+    const rest = args.slice(1);
+    if (action === "retro") {
+        runRetro(rest);
+        return;
+    }
+    if (action !== "add" &&
+        action !== "list" &&
+        action !== "remove" &&
+        action !== "refresh") {
+        fail(`Unknown admin action: ${action}`);
+        return;
+    }
+    let root = process.cwd();
+    let adminRoot = resolveAdminRoot();
+    let rootProvided = false;
+    try {
+        const { values } = parseArgs({
+            args: rest,
+            options: {
+                root: { type: "string" },
+                "admin-root": { type: "string" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        if (values.root !== undefined) {
+            root = values.root;
+            rootProvided = true;
+        }
+        if (values["admin-root"] !== undefined) {
+            adminRoot = resolveAdminRoot(values["admin-root"]);
+        }
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Invalid admin arguments.");
+        return;
+    }
+    try {
+        if (action === "add") {
+            const result = addRepo(adminRoot, root);
+            process.stdout.write(result.created
+                ? `added: ${result.repo.path}\n`
+                : `kept: ${result.repo.path}\n`);
+            return;
+        }
+        if (action === "list") {
+            process.stdout.write(formatRepos(listRepos(adminRoot)));
+            return;
+        }
+        if (action === "remove") {
+            if (!rootProvided) {
+                fail("Missing required option --root.");
+                return;
+            }
+            const removed = removeRepo(adminRoot, root);
+            process.stdout.write(`removed: ${removed.path}\n`);
+            return;
+        }
+        process.stdout.write(formatContexts(refreshRepos(adminRoot)));
+    }
+    catch (error) {
+        if (error instanceof AdminError) {
+            fail(`${error.code}: ${error.message}`);
+            return;
+        }
+        throw error;
+    }
+}
+function runRetro(args) {
+    let week;
+    let timezone;
+    let json = false;
+    let alerts = false;
+    let adminRoot = resolveAdminRoot();
+    try {
+        const { values } = parseArgs({
+            args,
+            options: {
+                week: { type: "string" },
+                timezone: { type: "string" },
+                json: { type: "boolean" },
+                alerts: { type: "boolean" },
+                "admin-root": { type: "string" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        if (values.week !== undefined)
+            week = values.week;
+        if (values.timezone !== undefined)
+            timezone = values.timezone;
+        json = values.json === true;
+        alerts = values.alerts === true;
+        if (values["admin-root"] !== undefined) {
+            adminRoot = resolveAdminRoot(values["admin-root"]);
+        }
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Invalid admin arguments.");
+        return;
+    }
+    try {
+        const report = buildRetro({
+            adminRoot,
+            ...(week !== undefined ? { week } : {}),
+            ...(timezone !== undefined ? { timezone } : {}),
+        });
+        saveRetro(adminRoot, report);
+        process.stdout.write(json ? retroJson(report) : formatRetro(report, { alerts }));
+    }
+    catch (error) {
+        if (error instanceof RetroError || error instanceof AdminError) {
+            fail(`${error.code}: ${error.message}`);
+            return;
+        }
+        throw error;
+    }
+}
 async function run(args) {
     if (args[0] === "inspect") {
         runInspect(args.slice(1));
@@ -253,6 +385,10 @@ async function run(args) {
     if (args[0] === "upgrade") {
         return runUpgrade(args.slice(1));
     }
+    if (args[0] === "admin") {
+        runAdmin(args.slice(1));
+        return;
+    }
     let helpRequested = false;
     let versionRequested = false;
     try {

package/dist/core/admin.js

@@ -0,0 +1,241 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+export class AdminError extends Error {
+    code;
+    path;
+    constructor(code, path, message) {
+        super(message);
+        this.name = "AdminError";
+        this.code = code;
+        this.path = path;
+    }
+}
+const SECRET_BASENAMES = new Set([".env", "credentials.json", "id_rsa"]);
+export function isSecretFilename(filePath) {
+    const name = basename(filePath);
+    if (SECRET_BASENAMES.has(name))
+        return true;
+    return name.startsWith(".env.");
+}
+export function resolveAdminRoot(explicit) {
+    if (explicit !== undefined)
+        return resolve(explicit);
+    return join(homedir(), ".config", "tito", "admin");
+}
+export function reposFilePath(adminRoot) {
+    return join(resolve(adminRoot), "repos.json");
+}
+export function contextFilePath(adminRoot) {
+    return join(resolve(adminRoot), "context.json");
+}
+function errno(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string") {
+        return error.code;
+    }
+    return null;
+}
+function assertDirectory(path) {
+    const resolved = resolve(path);
+    try {
+        if (!statSync(resolved).isDirectory()) {
+            throw new AdminError("not-a-directory", resolved, `${resolved} is not a directory.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof AdminError)
+            throw error;
+        const code = errno(error);
+        if (code === "ENOENT") {
+            throw new AdminError("not-a-directory", resolved, `${resolved} is not a directory.`);
+        }
+        throw new AdminError("filesystem", resolved, `Cannot inspect ${resolved}.`);
+    }
+    return resolved;
+}
+function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        throw new AdminError("filesystem", path, error instanceof Error ? error.message : `Cannot write ${path}.`);
+    }
+}
+function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        const code = errno(error);
+        if (code === "ENOENT")
+            return null;
+        throw new AdminError("filesystem", path, error instanceof Error ? error.message : `Cannot read ${path}.`);
+    }
+}
+function isAdminRepo(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return typeof record.path === "string" && typeof record.addedAt === "string";
+}
+export function loadRepos(adminRoot) {
+    const path = reposFilePath(adminRoot);
+    if (!existsSync(path))
+        return [];
+    const raw = readJsonFile(path);
+    if (!Array.isArray(raw)) {
+        throw new AdminError("filesystem", path, `${path} must contain a JSON array.`);
+    }
+    const repos = [];
+    for (const item of raw) {
+        if (!isAdminRepo(item)) {
+            throw new AdminError("filesystem", path, `${path} has an invalid repo entry.`);
+        }
+        repos.push({ path: item.path, addedAt: item.addedAt });
+    }
+    return repos;
+}
+export function saveRepos(adminRoot, repos) {
+    writeJsonAtomic(reposFilePath(adminRoot), repos);
+}
+export function loadContexts(adminRoot) {
+    const path = contextFilePath(adminRoot);
+    if (!existsSync(path))
+        return [];
+    const raw = readJsonFile(path);
+    if (!Array.isArray(raw)) {
+        throw new AdminError("filesystem", path, `${path} must contain a JSON array.`);
+    }
+    return raw;
+}
+export function saveContexts(adminRoot, contexts) {
+    writeJsonAtomic(contextFilePath(adminRoot), contexts);
+}
+const defaultClock = () => new Date().toISOString();
+export function defaultGitRunner(cwd, args) {
+    const result = spawnSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (result.error) {
+        throw new AdminError("git", cwd, result.error.message);
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "git command failed").trim();
+        throw new AdminError("git", cwd, detail);
+    }
+    return result.stdout ?? "";
+}
+export function addRepo(adminRoot, repoPath, options = {}) {
+    const path = assertDirectory(repoPath);
+    const repos = loadRepos(adminRoot);
+    const existing = repos.find((repo) => repo.path === path);
+    if (existing !== undefined) {
+        return { repo: existing, created: false };
+    }
+    const clock = options.clock ?? defaultClock;
+    const repo = { path, addedAt: clock() };
+    repos.push(repo);
+    saveRepos(adminRoot, repos);
+    return { repo, created: true };
+}
+export function listRepos(adminRoot) {
+    return loadRepos(adminRoot);
+}
+export function removeRepo(adminRoot, repoPath) {
+    const path = resolve(repoPath);
+    const repos = loadRepos(adminRoot);
+    const index = repos.findIndex((repo) => repo.path === path);
+    if (index < 0) {
+        throw new AdminError("not-registered", path, `${path} is not registered.`);
+    }
+    const [removed] = repos.splice(index, 1);
+    if (removed === undefined) {
+        throw new AdminError("not-registered", path, `${path} is not registered.`);
+    }
+    saveRepos(adminRoot, repos);
+    return removed;
+}
+function parseCommitLog(stdout) {
+    const commits = [];
+    const blocks = stdout.split(/\n(?=◆)/);
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (trimmed.length === 0)
+            continue;
+        const lines = trimmed.split("\n");
+        const header = lines[0];
+        if (header === undefined || !header.startsWith("◆"))
+            continue;
+        const parts = header.slice(1).split("\0");
+        const subject = parts[0] ?? "";
+        const date = parts[1] ?? "";
+        const files = [];
+        for (const line of lines.slice(1)) {
+            const file = line.trim();
+            if (file.length === 0)
+                continue;
+            if (isSecretFilename(file))
+                continue;
+            files.push(file);
+        }
+        commits.push({ subject, date, files });
+    }
+    return commits;
+}
+export function readRepoContext(repoPath, options = {}) {
+    const path = assertDirectory(repoPath);
+    const git = options.git ?? defaultGitRunner;
+    const branch = git(path, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    const log = git(path, [
+        "log",
+        "-n",
+        "50",
+        "--pretty=format:◆%s%x00%cI",
+        "--name-only",
+    ]);
+    return {
+        path,
+        branch,
+        recentCommits: parseCommitLog(log),
+    };
+}
+export function refreshRepos(adminRoot, options = {}) {
+    const repos = loadRepos(adminRoot);
+    const contexts = [];
+    for (const repo of repos) {
+        contexts.push(readRepoContext(repo.path, options));
+    }
+    saveContexts(adminRoot, contexts);
+    return contexts;
+}
+export function formatRepos(repos) {
+    if (repos.length === 0)
+        return "No registered repositories.\n";
+    return `${repos.map((repo) => `${repo.path}\t${repo.addedAt}`).join("\n")}\n`;
+}
+export function formatContexts(contexts) {
+    if (contexts.length === 0)
+        return "No repository context.\n";
+    const lines = [];
+    for (const context of contexts) {
+        lines.push(`path: ${context.path}`);
+        lines.push(`branch: ${context.branch}`);
+        lines.push(`commits: ${context.recentCommits.length}`);
+        for (const commit of context.recentCommits) {
+            lines.push(`- ${commit.date}\t${commit.subject}`);
+            for (const file of commit.files) {
+                lines.push(`  ${file}`);
+            }
+        }
+        lines.push("");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}