@anhvupt/tito 0.1.2 → 0.1.3

package/README.md

@@ -92,6 +92,17 @@ 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
 overridden by that project's `tito.yaml`. The safety floor still cannot 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

@@ -3,7 +3,7 @@ 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 { ADOPTION_AGENTS_MD, PlanError, planAdoption, } from "./plan.js";
+import { PlanError, TITO_BOOTSTRAP_START, planAdoption, titoBootstrapBlock, } from "./plan.js";
 export class InitError extends Error {
     code;
     constructor(message) {
@@ -31,7 +31,7 @@ function exists(root, path) {
         return false;
     }
 }
-function shippedSkills() {
+export function shippedSkills() {
     const root = join(dirname(fileURLToPath(import.meta.url)), "../../templates/cursor/skills");
     return readdirSync(root, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
@@ -42,16 +42,17 @@ function shippedSkills() {
 }
 function agentsBootstrap(report) {
     if (report.agentsMd === "absent") {
-        return { path: "AGENTS.md", action: "create", body: ADOPTION_AGENTS_MD };
+        return { path: "AGENTS.md", action: "create", body: titoBootstrapBlock() };
     }
     const current = readFileSync(join(report.root, "AGENTS.md"), "utf8");
-    if (current.includes("Hola, Tito here!")) {
+    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${ADOPTION_AGENTS_MD}`,
+        body: `\n${titoBootstrapBlock()}`,
     };
 }
 export function planInitialization(report, profile) {

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.2",
+  "version": "0.1.3",
   "description": "Local-first AI development harness for solo builders.",
   "license": "Apache-2.0",
   "type": "module",

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

@@ -19,6 +19,11 @@ Recommend one mode before acting:
 - **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