@anhvupt/tito 0.1.1 → 0.1.3

package/README.md

@@ -87,9 +87,21 @@ npx tito init --profile client-careful --confirm
 The first `init` prints the plan and writes nothing. In a terminal, omitting
 `--profile` asks you to choose `client-careful`, `solo-balanced`, or
 `solo-fast`. A script or piped command must still pass `--profile`.
-`--confirm` creates the missing Tito files and specialist agents. It keeps an
-existing `AGENTS.md` and refuses to overwrite a file that is already there.
-Open a new Cursor chat, then start with `/tito`.
+`--confirm` creates the missing `tito.yaml`, specialist agents, and `/tito`
+skills. If `AGENTS.md` already exists, Tito appends its bootstrap and leaves
+the existing guidance in place. It refuses to overwrite a Tito file that is
+already there. Open a new Cursor chat, then start with `/tito`.
+
+Upgrade an existing project after installing a newer Tito:
+
+```sh
+npx tito upgrade
+npx tito upgrade --confirm
+```
+
+`--confirm` installs the latest `@anhvupt/tito` and replaces Tito-owned
+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

package/dist/cli.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { InspectionError, formatInspection, inspectRepository, } from "./core/inspect.js";
 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";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const help = `Tito — quiet orchestration for solo builders
 
@@ -14,6 +17,7 @@ Usage:
   tito inspect [--root <path>]
   tito apply --dry-run --profile <id> [--root <path>]
   tito init [--profile <id>] [--root <path>] [--confirm]
+  tito upgrade [--root <path>] [--confirm]
 
 Options:
   -h, --help     Show help
@@ -23,6 +27,7 @@ Commands:
   inspect        Report tito.yaml and AGENTS.md. Reads only.
   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.
 `;
 function fail(message) {
     process.stderr.write(`${message}\n`);
@@ -174,6 +179,65 @@ async function runInit(args) {
         throw error;
     }
 }
+async function runUpgrade(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        process.stdout.write(help);
+        return;
+    }
+    let root = process.cwd();
+    let confirm = false;
+    let filesOnly = false;
+    try {
+        const { values } = parseArgs({
+            args,
+            options: {
+                confirm: { type: "boolean" },
+                root: { type: "string" },
+                "files-only": { type: "boolean" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        confirm = values.confirm === true;
+        filesOnly = values["files-only"] === true;
+        if (values.root !== undefined)
+            root = values.root;
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Invalid upgrade arguments.");
+        return;
+    }
+    const files = planUpgrade(root, titoOwnedFiles());
+    if (!confirm) {
+        process.stdout.write(formatUpgrade(root, files));
+        return;
+    }
+    if (!filesOnly && !isTitoSource(root)) {
+        const install = spawnSync("npm", ["install", "-D", "@anhvupt/tito@latest"], { cwd: root, encoding: "utf8" });
+        if (install.status !== 0) {
+            fail(install.stderr || "Could not install the latest Tito.");
+            return;
+        }
+        const installed = join(root, "node_modules/@anhvupt/tito/dist/cli.js");
+        const child = spawnSync(process.execPath, [installed, "upgrade", "--confirm", "--files-only", "--root", root], { encoding: "utf8" });
+        process.stdout.write(child.stdout ?? "");
+        if (child.stderr)
+            process.stderr.write(child.stderr);
+        process.exitCode = child.status ?? 1;
+        return;
+    }
+    applyUpgrade(root, files);
+    process.stdout.write(formatUpgrade(root, files));
+}
+function isTitoSource(root) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return manifest.name === "@anhvupt/tito";
+    }
+    catch {
+        return false;
+    }
+}
 async function run(args) {
     if (args[0] === "inspect") {
         runInspect(args.slice(1));
@@ -186,6 +250,9 @@ async function run(args) {
     if (args[0] === "init") {
         return runInit(args.slice(1));
     }
+    if (args[0] === "upgrade") {
+        return runUpgrade(args.slice(1));
+    }
     let helpRequested = false;
     let versionRequested = false;
     try {

package/dist/core/init.js

@@ -1,8 +1,9 @@
-import { mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { compiledCursorAgents } from "./agents.js";
 import { ACTIVE_RISK_PROFILE_IDS } from "./profiles.js";
-import { PlanError, planAdoption, } from "./plan.js";
+import { PlanError, TITO_BOOTSTRAP_START, planAdoption, titoBootstrapBlock, } from "./plan.js";
 export class InitError extends Error {
     code;
     constructor(message) {
@@ -30,19 +31,48 @@ function exists(root, path) {
         return false;
     }
 }
+export function shippedSkills() {
+    const root = join(dirname(fileURLToPath(import.meta.url)), "../../templates/cursor/skills");
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({
+        path: `.cursor/skills/${entry.name}/SKILL.md`,
+        body: readFileSync(join(root, entry.name, "SKILL.md"), "utf8"),
+    }));
+}
+function agentsBootstrap(report) {
+    if (report.agentsMd === "absent") {
+        return { path: "AGENTS.md", action: "create", body: titoBootstrapBlock() };
+    }
+    const current = readFileSync(join(report.root, "AGENTS.md"), "utf8");
+    if (current.includes(TITO_BOOTSTRAP_START) ||
+        current.includes("Hola, Tito here!")) {
+        return { path: "AGENTS.md", action: "keep" };
+    }
+    return {
+        path: "AGENTS.md",
+        action: "append",
+        body: `\n${titoBootstrapBlock()}`,
+    };
+}
 export function planInitialization(report, profile) {
     const adoption = planAdoption(report, profile);
+    const files = adoption.files.map((file) => file.path === "AGENTS.md" ? agentsBootstrap(report) : file);
     const agents = compiledCursorAgents().map((agent) => exists(report.root, agent.path)
         ? { path: agent.path, action: "conflict" }
         : { path: agent.path, action: "create", body: agent.body });
-    return { root: adoption.root, profile: adoption.profile, files: [...adoption.files, ...agents] };
+    const skills = shippedSkills().map((skill) => exists(report.root, skill.path)
+        ? { path: skill.path, action: "keep" }
+        : { path: skill.path, action: "create", body: skill.body });
+    return { root: adoption.root, profile: adoption.profile, files: [...files, ...agents, ...skills] };
 }
 export function formatInitialization(plan) {
     const lines = [`root: ${plan.root}`, `profile: ${plan.profile}`];
     for (const file of plan.files) {
         lines.push(`${file.path}: ${file.action}`);
-        if (file.action === "create")
+        if (file.action === "create" || file.action === "append") {
             lines.push("---", file.body.trimEnd(), "---");
+        }
     }
     return `${lines.join("\n")}\n`;
 }
@@ -54,6 +84,13 @@ export function applyInitialization(plan) {
     const created = [];
     try {
         for (const file of plan.files) {
+            if (file.action === "append") {
+                const absolute = join(plan.root, file.path);
+                const current = readFileSync(absolute, "utf8");
+                const separator = current.endsWith("\n") ? "\n" : "\n\n";
+                writeFileSync(absolute, `${current}${separator}${file.body}`, "utf8");
+                continue;
+            }
             if (file.action !== "create")
                 continue;
             const absolute = join(plan.root, file.path);

package/dist/core/plan.js

@@ -1,4 +1,6 @@
 import { ACTIVE_RISK_PROFILE_IDS, isActiveRiskProfileId, isFutureRiskProfileId, } from "./profiles.js";
+export const TITO_BOOTSTRAP_START = "<!-- tito:bootstrap start -->";
+export const TITO_BOOTSTRAP_END = "<!-- tito:bootstrap end -->";
 export const ADOPTION_AGENTS_MD = `# Tito bootstrap
 
 This project uses Tito as its root engineering coordinator.
@@ -15,6 +17,9 @@ This project uses Tito as its root engineering coordinator.
 
 Keep this bootstrap compact. Load project documentation only when the task needs it.
 `;
+export function titoBootstrapBlock() {
+    return `${TITO_BOOTSTRAP_START}\n${ADOPTION_AGENTS_MD.trim()}\n${TITO_BOOTSTRAP_END}\n`;
+}
 export class PlanError extends Error {
     code;
     constructor(code, message) {

package/dist/core/upgrade.js

@@ -0,0 +1,72 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { compiledCursorAgents } from "./agents.js";
+import { shippedSkills } from "./init.js";
+import { TITO_BOOTSTRAP_END, TITO_BOOTSTRAP_START, titoBootstrapBlock, } from "./plan.js";
+function readIfFile(root, path) {
+    try {
+        return readFileSync(join(root, path), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function ownedText(current, next) {
+    if (current === null)
+        return "create";
+    return current === next ? "keep" : "replace";
+}
+export function refreshAgentsBootstrap(current) {
+    const block = titoBootstrapBlock().trimEnd();
+    const start = current.indexOf(TITO_BOOTSTRAP_START);
+    const end = current.indexOf(TITO_BOOTSTRAP_END);
+    if (start >= 0 && end > start) {
+        return `${current.slice(0, start)}${block}${current.slice(end + TITO_BOOTSTRAP_END.length)}`;
+    }
+    const heading = current.indexOf("# Tito bootstrap");
+    if (heading >= 0) {
+        const prefix = current.slice(0, heading).trimEnd();
+        return prefix.length === 0 ? `${block}\n` : `${prefix}\n\n${block}\n`;
+    }
+    const trimmed = current.trimEnd();
+    return `${trimmed}\n\n${block}\n`;
+}
+export function planUpgrade(root, ownedFiles) {
+    const files = ownedFiles.map((file) => {
+        const current = readIfFile(root, file.path);
+        const action = ownedText(current, file.body);
+        return action === "keep"
+            ? { path: file.path, action }
+            : { path: file.path, action, body: file.body };
+    });
+    const agents = readIfFile(root, "AGENTS.md");
+    if (agents === null) {
+        files.push({ path: "AGENTS.md", action: "create", body: titoBootstrapBlock() });
+    }
+    else {
+        const next = refreshAgentsBootstrap(agents);
+        files.push(next === agents
+            ? { path: "AGENTS.md", action: "keep" }
+            : { path: "AGENTS.md", action: "replace", body: next });
+    }
+    return files;
+}
+export function titoOwnedFiles() {
+    return [...compiledCursorAgents(), ...shippedSkills()];
+}
+export function formatUpgrade(root, files) {
+    const lines = [`root: ${root}`, "consumer rules: untouched"];
+    for (const file of files) {
+        lines.push(`${file.path}: ${file.action}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function applyUpgrade(root, files) {
+    for (const file of files) {
+        if (file.action === "keep" || file.body === undefined)
+            continue;
+        const absolute = join(root, file.path);
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, file.body, "utf8");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhvupt/tito",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local-first AI development harness for solo builders.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/",
+    "templates/",
     "README.md",
     "LICENSE"
   ],

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

@@ -0,0 +1,38 @@
+---
+name: tito
+description: Runs Tito's chat-first engineering coordination workflow. Invoke explicitly with /tito for repository exploration, planning, approved implementation slices, and review handoffs.
+disable-model-invocation: true
+---
+
+# Tito
+
+Act as the root Tito coordinator in this project.
+Start every response exactly with `Hola, Tito here!`
+
+Ordinary chat follows `AGENTS.md`. `/tito` is the explicit coordinator. Read `tito.yaml` for the risk profile. Read project documentation only when the task needs it. Do not replace existing project guidance.
+
+## Route the task
+
+Recommend one mode before acting:
+
+- **Ask** for read-only exploration, explanation, impact analysis, or diagnosis.
+- **Plan** for ambiguity, architecture, sensitive work, migrations, or work requiring multiple reviewable slices.
+- **Agent** only for one explicitly approved implementation slice.
+
+A new command, a new write behavior, or any technical choice is always Plan
+first. That response contains the plan only. No source edits. "No need to plan"
+applies only to the slice named in that message. Implementation starts only
+after that plan is approved.
+
+For Plan work, the planner decides the technical approach and includes guidance code when it removes ambiguity. Ask the user only for a genuine product or business choice.
+
+## Execute
+
+1. Inspect the repository without mutation and preserve uncommitted work.
+2. State facts, affected files, uncertainties, risks, and the recommended mode.
+3. For Plan work, produce independent slices and stop for approval.
+4. Use one code writer. Specialist advisers and reviewers stay read-only.
+5. Implement and verify only the approved slice, then stop for review.
+6. After a finished module, schedule the tech docs writer and then the user docs writer unless the user waives that handoff.
+
+Never commit, push, publish, deploy, or perform irreversible external actions without explicit approval.

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

@@ -0,0 +1,12 @@
+---
+name: tito-apply
+description: Dry-run Tito's adoption plan. Invoke explicitly with /tito-apply. Uses the same output as tito apply --dry-run.
+disable-model-invocation: true
+---
+
+# Tito apply
+
+Chat adapter for `npx tito apply --dry-run`. Show the command stdout unchanged.
+Start the chat response exactly with `Hola, Tito here!`
+
+The user must name `client-careful`, `solo-balanced`, or `solo-fast`. If they do not, ask which profile to use and stop. Do not omit `--dry-run`. Do not write project files.

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

@@ -0,0 +1,12 @@
+---
+name: tito-init
+description: Preview or confirm Tito initialization. Invoke explicitly with /tito-init. Uses the same plan as tito init.
+disable-model-invocation: true
+---
+
+# Tito init
+
+Chat adapter for `npx tito init`. Show the command stdout unchanged.
+Start the chat response exactly with `Hola, Tito here!`
+
+Preview first without `--confirm`. Run `npx tito init --profile <id> --confirm` only after the user approves that exact plan. In a terminal, omitting `--profile` asks for one. Do not overwrite existing project guidance.

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

@@ -0,0 +1,12 @@
+---
+name: tito-inspect
+description: Run Tito's read-only repository inspection. Invoke explicitly with /tito-inspect. Uses the same report as tito inspect.
+disable-model-invocation: true
+---
+
+# Tito inspect
+
+Chat adapter for `npx tito inspect`. 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. Do not reimplement inspection by reading files yourself. Do not write project files.