@anhvupt/tito 0.1.3 → 0.3.0

package/dist/core/git-flow.js

@@ -0,0 +1,174 @@
+export const BRANCH_TYPES = [
+    "feat",
+    "fix",
+    "hot-fix",
+    "chores",
+    "refactor",
+    "debug",
+];
+export const BRANCH_BASES = ["dev", "develop", "main", "master"];
+const TYPE_BY_KIND = {
+    feature: "feat",
+    bug: "fix",
+    "production-emergency": "hot-fix",
+    tooling: "chores",
+    refactor: "refactor",
+    investigation: "debug",
+};
+export function branchSlug(text) {
+    const slug = text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return slug.length > 0 ? slug : "change";
+}
+function isBranchBase(value) {
+    return BRANCH_BASES.includes(value);
+}
+function firstExisting(names, existing, fallback) {
+    return names.find((name) => existing.has(name)) ?? fallback;
+}
+export function suggestBranch(input) {
+    const type = TYPE_BY_KIND[input.taskKind];
+    const existing = new Set(input.existingBases);
+    const current = input.currentBranch;
+    let base;
+    let reason;
+    if (type === "hot-fix") {
+        base =
+            input.defaultBase === "main" || input.defaultBase === "master"
+                ? input.defaultBase
+                : firstExisting(["main", "master"], existing, "main");
+        reason = `A production emergency starts from ${base}.`;
+    }
+    else if (input.continuesFromCurrent && isBranchBase(current)) {
+        base = current;
+        reason = `The work continues from ${current}.`;
+    }
+    else if (input.defaultBase) {
+        base = input.defaultBase;
+        reason = `The project default base is ${input.defaultBase}.`;
+    }
+    else {
+        base = firstExisting(BRANCH_BASES, existing, "main");
+        reason =
+            base === "dev" || base === "develop"
+                ? `Feature work starts from ${base}.`
+                : "This repository has no dev or develop branch.";
+    }
+    const name = `${type}/${branchSlug(input.slug)}`;
+    return {
+        type,
+        base,
+        name,
+        reason,
+        line: `Suggested branch: ${name} from ${base}`,
+    };
+}
+export function checkoutCommands(base, branch) {
+    return [`git checkout ${base}`, `git checkout -b ${branch}`];
+}
+export function prunePlanIndex(entries, planExists) {
+    return entries.filter((entry) => planExists(entry.cursorPlanPath));
+}
+export function linearReference(input) {
+    if (input.issueId && input.issueId.trim().length > 0) {
+        return { issueId: input.issueId.trim(), createIssue: false };
+    }
+    return {
+        issueId: null,
+        createIssue: input.userAskedToCreate,
+    };
+}
+export const PULL_REQUEST_TEMPLATE_PATH = ".github/pull_request_template.md";
+const PULL_REQUEST_HEADINGS = {
+    problem: "## Problem",
+    done: "## What changed",
+    review: "## Review fixes",
+    checks: "## Checks",
+};
+const MAX_PULL_REQUEST_LINES = 50;
+export function pullRequestTemplate() {
+    return [
+        PULL_REQUEST_HEADINGS.problem,
+        "",
+        PULL_REQUEST_HEADINGS.done,
+        "",
+        "-",
+        "",
+        PULL_REQUEST_HEADINGS.review,
+        "",
+        "-",
+        "",
+        PULL_REQUEST_HEADINGS.checks,
+        "",
+        "- Lint:",
+        "- Code quality:",
+        "- Conventions:",
+        "- Tests:",
+        "- Build:",
+        "- Docs:",
+        "",
+    ].join("\n");
+}
+function bullet(item) {
+    const text = item.trim();
+    if (text.length === 0 || text.includes("\n"))
+        return null;
+    return `- ${text}`;
+}
+function bullets(items) {
+    const lines = [];
+    for (const item of items) {
+        const line = bullet(item);
+        if (line === null)
+            return null;
+        lines.push(line);
+    }
+    return lines;
+}
+export function pullRequestDescription(input) {
+    const problem = input.problem.trim();
+    if (problem.length === 0 || problem.includes("\n"))
+        return null;
+    const done = bullets(input.done);
+    const checks = bullets(input.checks);
+    if (done === null || checks === null || done.length === 0 || checks.length === 0)
+        return null;
+    const review = bullets(input.reviewFixes.length > 0 ? input.reviewFixes : ["No review fixes."]);
+    if (review === null)
+        return null;
+    const lines = [
+        PULL_REQUEST_HEADINGS.problem,
+        problem,
+        "",
+        PULL_REQUEST_HEADINGS.done,
+        ...done,
+        "",
+        PULL_REQUEST_HEADINGS.review,
+        ...review,
+        "",
+        PULL_REQUEST_HEADINGS.checks,
+        ...checks,
+    ];
+    if (lines.length < 2 || lines.length > MAX_PULL_REQUEST_LINES)
+        return null;
+    return lines.join("\n");
+}
+export function mergeDecision(input) {
+    if (!input.userAskedToMerge) {
+        return { allowed: false, reason: "Wait for the user to call for the merge." };
+    }
+    if (!input.hasApproval) {
+        return { allowed: false, reason: "The pull request has no approval." };
+    }
+    return {
+        allowed: true,
+        reason: "The user called for the merge and the pull request has an approval.",
+    };
+}
+export function canApprovePullRequest() {
+    return false;
+}

package/dist/core/init.js

@@ -2,6 +2,8 @@ import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSy
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compiledCursorAgents } from "./agents.js";
+import { SCREEN_LANGUAGES, TENANCY_VALUES, isSurfaceId, } from "./config.js";
+import { BRANCH_BASES, PULL_REQUEST_TEMPLATE_PATH, pullRequestTemplate, } from "./git-flow.js";
 import { ACTIVE_RISK_PROFILE_IDS } from "./profiles.js";
 import { PlanError, TITO_BOOTSTRAP_START, planAdoption, titoBootstrapBlock, } from "./plan.js";
 export class InitError extends Error {
@@ -23,6 +25,106 @@ export async function promptForProfile(ask) {
     }
     return answer;
 }
+export const GIT_BASE_PROMPT = "Git base (dev, develop, main, master): ";
+export const SCREEN_LANGUAGE_PROMPT = "Screen language (vi, en): ";
+export const TENANCY_PROMPT = "Tenancy (single, multi): ";
+export const SURFACES_PROMPT = "Surfaces (comma-separated ids): ";
+export const AUTO_PULL_REQUEST_PROMPT = "Auto-create a pull request after implementation? [Y/n] ";
+export const INIT_SETTING_KEYS = [
+    "defaultBase",
+    "screenLanguage",
+    "tenancy",
+    "surfaces",
+    "autoPullRequest",
+];
+async function askOneOf(ask, prompt, allowed) {
+    for (;;) {
+        const answer = (await ask(prompt)).trim();
+        if (allowed.includes(answer))
+            return answer;
+    }
+}
+async function askSurfaces(ask) {
+    for (;;) {
+        const answer = (await ask(SURFACES_PROMPT)).trim();
+        if (answer === "")
+            return undefined;
+        const ids = answer
+            .split(",")
+            .map((part) => part.trim())
+            .filter((part) => part.length > 0);
+        if (ids.length === 0)
+            return undefined;
+        const seen = new Set();
+        const valid = ids.every((id) => {
+            if (!isSurfaceId(id) || seen.has(id))
+                return false;
+            seen.add(id);
+            return true;
+        });
+        if (valid)
+            return ids.map((id) => ({ id }));
+    }
+}
+async function askAutoPullRequest(ask) {
+    for (;;) {
+        const answer = (await ask(AUTO_PULL_REQUEST_PROMPT)).trim().toLowerCase();
+        if (answer === "" || answer === "y" || answer === "yes")
+            return true;
+        if (answer === "n" || answer === "no")
+            return false;
+    }
+}
+export async function promptForSettings(ask, keys) {
+    const answers = {};
+    for (const key of keys) {
+        if (key === "defaultBase") {
+            answers.defaultBase = await askOneOf(ask, GIT_BASE_PROMPT, BRANCH_BASES);
+            continue;
+        }
+        if (key === "screenLanguage") {
+            answers.screenLanguage = await askOneOf(ask, SCREEN_LANGUAGE_PROMPT, SCREEN_LANGUAGES);
+            continue;
+        }
+        if (key === "tenancy") {
+            answers.tenancy = await askOneOf(ask, TENANCY_PROMPT, TENANCY_VALUES);
+            continue;
+        }
+        if (key === "surfaces") {
+            const surfaces = await askSurfaces(ask);
+            if (surfaces !== undefined)
+                answers.surfaces = surfaces;
+            continue;
+        }
+        answers.autoPullRequest = await askAutoPullRequest(ask);
+    }
+    return answers;
+}
+export function titoYamlBody(profile, settings) {
+    const lines = ["schemaVersion: 1", `profile: ${profile}`];
+    const gitLines = [];
+    if (settings.defaultBase !== undefined)
+        gitLines.push(`  defaultBase: ${settings.defaultBase}`);
+    if (settings.autoPullRequest !== undefined) {
+        gitLines.push(`  autoPullRequest: ${settings.autoPullRequest}`);
+    }
+    if (gitLines.length > 0)
+        lines.push("git:", ...gitLines);
+    const productLines = [];
+    if (settings.screenLanguage !== undefined) {
+        productLines.push(`  screenLanguage: ${settings.screenLanguage}`);
+    }
+    if (settings.tenancy !== undefined)
+        productLines.push(`  tenancy: ${settings.tenancy}`);
+    if (settings.surfaces !== undefined && settings.surfaces.length > 0) {
+        productLines.push("  surfaces:");
+        for (const surface of settings.surfaces)
+            productLines.push(`    - id: ${surface.id}`);
+    }
+    if (productLines.length > 0)
+        lines.push("product:", ...productLines);
+    return `${lines.join("\n")}\n`;
+}
 function exists(root, path) {
     try {
         return statSync(join(root, path)).isFile();
@@ -55,16 +157,35 @@ function agentsBootstrap(report) {
         body: `\n${titoBootstrapBlock()}`,
     };
 }
-export function planInitialization(report, profile) {
+export function planInitialization(report, profile, settings) {
     const adoption = planAdoption(report, profile);
-    const files = adoption.files.map((file) => file.path === "AGENTS.md" ? agentsBootstrap(report) : file);
+    const files = adoption.files.map((file) => {
+        if (file.path === "AGENTS.md")
+            return agentsBootstrap(report);
+        if (file.path === "tito.yaml" && file.action === "create" && settings !== undefined) {
+            return {
+                path: "tito.yaml",
+                action: "create",
+                body: titoYamlBody(adoption.profile, settings),
+            };
+        }
+        return file;
+    });
     const agents = compiledCursorAgents().map((agent) => exists(report.root, agent.path)
         ? { path: agent.path, action: "conflict" }
         : { path: agent.path, action: "create", body: agent.body });
     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] };
+    const template = pullRequestTemplate();
+    const pullRequest = exists(report.root, PULL_REQUEST_TEMPLATE_PATH)
+        ? { path: PULL_REQUEST_TEMPLATE_PATH, action: "keep" }
+        : { path: PULL_REQUEST_TEMPLATE_PATH, action: "create", body: template };
+    return {
+        root: adoption.root,
+        profile: adoption.profile,
+        files: [...files, ...agents, ...skills, pullRequest],
+    };
 }
 export function formatInitialization(plan) {
     const lines = [`root: ${plan.root}`, `profile: ${plan.profile}`];

package/dist/core/models.js

@@ -0,0 +1,116 @@
+const CLASS_TIER = {
+    explore: "Scout",
+    docs: "Scout",
+    ordinary: "Standard",
+    core: "Standard",
+    reasoning: "Reasoning",
+};
+const CLASS_ESCALATION = {
+    explore: "Step up when the slice is foundation, a core feature, or a core calculation.",
+    docs: "Step up when the slice is foundation, a core feature, or a core calculation.",
+    ordinary: "Step up when the slice is foundation, a core feature, or a core calculation.",
+    core: "Ask the user before selecting a more expensive model.",
+    reasoning: "Ask the user before selecting a more expensive model.",
+};
+function rulesFor(host, taskClass) {
+    if (host === "cursor") {
+        if (taskClass === "explore" || taskClass === "docs" || taskClass === "ordinary") {
+            return {
+                family: "Grok",
+                matchGroups: [(slug) => slug.startsWith("grok-"), (slug) => slug.startsWith("cursor-grok-")],
+                pick: "highest",
+            };
+        }
+        if (taskClass === "core") {
+            return {
+                family: "Codex",
+                matchGroups: [(slug) => slug.includes("codex"), (slug) => slug.startsWith("composer-")],
+                pick: "highest",
+            };
+        }
+        return {
+            family: "Opus",
+            matchGroups: [(slug) => slug.startsWith("claude-opus-")],
+            pick: "highest",
+        };
+    }
+    if (taskClass === "explore" || taskClass === "docs") {
+        return {
+            family: "Sonnet",
+            matchGroups: [(slug) => slug.startsWith("claude-sonnet-")],
+            pick: "lowest",
+        };
+    }
+    if (taskClass === "ordinary") {
+        return {
+            family: "Sonnet",
+            matchGroups: [(slug) => slug.startsWith("claude-sonnet-")],
+            pick: "highest",
+        };
+    }
+    return {
+        family: "Opus",
+        matchGroups: [(slug) => slug.startsWith("claude-opus-")],
+        pick: "highest",
+    };
+}
+function versionTuple(slug) {
+    const groups = slug.match(/\d+/g) ?? [];
+    return groups.map((value) => Number.parseInt(value, 10));
+}
+function compareVersions(left, right) {
+    const limit = Math.max(left.length, right.length);
+    for (let index = 0; index < limit; index += 1) {
+        const a = left[index];
+        const b = right[index];
+        if (a === undefined && b === undefined) {
+            return 0;
+        }
+        if (a === undefined) {
+            return -1;
+        }
+        if (b === undefined) {
+            return 1;
+        }
+        if (a !== b) {
+            return a - b;
+        }
+    }
+    return 0;
+}
+function pickVersion(slugs, pick) {
+    const direction = pick === "highest" ? 1 : -1;
+    return [...slugs].sort((a, b) => compareVersions(versionTuple(a), versionTuple(b)) * direction).at(-1) ?? slugs[0];
+}
+export function recommendModel({ host, taskClass, catalog, userModel, }) {
+    const tier = CLASS_TIER[taskClass];
+    const escalation = CLASS_ESCALATION[taskClass];
+    if (typeof userModel === "string" && userModel.length > 0) {
+        return {
+            status: "selected",
+            model: userModel,
+            tier,
+            reason: "Used the explicit model requested by the user.",
+            escalation,
+        };
+    }
+    const rule = rulesFor(host, taskClass);
+    for (const matcher of rule.matchGroups) {
+        const matches = catalog.filter((slug) => matcher(slug));
+        if (matches.length > 0) {
+            const model = pickVersion(matches, rule.pick);
+            return {
+                status: "selected",
+                model,
+                tier,
+                reason: `Selected the ${rule.pick} version in the ${rule.family} family.`,
+                escalation,
+            };
+        }
+    }
+    return {
+        status: "ask",
+        family: rule.family,
+        reason: `No matching ${rule.family} model was found in the current catalog.`,
+    };
+}

package/dist/core/plan.js

@@ -14,6 +14,10 @@ This project uses Tito as its root engineering coordinator.
 - Never commit, push, publish, deploy, or perform irreversible external actions without explicit approval.
 - Use \`/tito\` when Tito coordination is wanted.
 - Plans own technical decisions and include guidance code when useful.
+- 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.
+- Confirm intent before clarifying. Plans open with Domain (business impact first), then Decisions, Test cases, Docs impact, and Slices and branch.
+- 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.
+- 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.
 
 Keep this bootstrap compact. Load project documentation only when the task needs it.
 `;

package/dist/core/profiles.js

@@ -27,8 +27,8 @@ export const RISK_PROFILES = deepFreeze({
     "client-careful": {
         id: "client-careful",
         status: "active",
-        maxWriters: 1,
-        writerConstraint: "one-at-a-time",
+        maxWriters: 3,
+        writerConstraint: "bounded-parallel",
         independentReview: "required",
         preferredAuthoredLines: { min: 100, max: 200 },
         maxAuthoredLinesWithoutApproval: 300,
@@ -49,8 +49,8 @@ export const RISK_PROFILES = deepFreeze({
     "solo-balanced": {
         id: "solo-balanced",
         status: "active",
-        maxWriters: 1,
-        writerConstraint: "one-at-a-time",
+        maxWriters: 6,
+        writerConstraint: "bounded-parallel",
         humanReview: "feature-boundaries",
         independentReviewFor: ["security", "data", "migrations", "architecture"],
         diffLimits: "moderate",
@@ -60,8 +60,8 @@ export const RISK_PROFILES = deepFreeze({
     "solo-fast": {
         id: "solo-fast",
         status: "active",
-        maxWriters: 1,
-        writerConstraint: "one-at-a-time",
+        maxWriters: 12,
+        writerConstraint: "bounded-parallel",
         agentSelfReview: "allowed",
         humanReview: "milestones",
         safetyFloor: MANDATORY_ESCALATION_TOPICS,