@anhvupt/tito 0.1.2 → 0.2.0

package/dist/core/config.js

@@ -1,7 +1,12 @@
-import { isMap, isScalar, parseAllDocuments } from "yaml";
+import { isMap, isScalar, isSeq, parseAllDocuments } from "yaml";
+import { BRANCH_BASES } from "./git-flow.js";
 import { ACTIVE_RISK_PROFILE_IDS, isActiveRiskProfileId, isFutureRiskProfileId, } from "./profiles.js";
 export const CONFIG_SCHEMA_VERSION = 1;
-const FIELDS = new Set(["schemaVersion", "profile"]);
+const FIELDS = new Set(["schemaVersion", "profile", "git", "product"]);
+const SCREEN_LANGUAGES = ["vi", "en"];
+const TENANCY_VALUES = ["single", "multi"];
+const PRODUCT_FIELDS = new Set(["screenLanguage", "tenancy", "surfaces"]);
+const SURFACE_ID = /^[a-z][a-z0-9-]*$/;
 const NON_SCALAR = Symbol("non-scalar");
 export class ConfigValidationError extends Error {
     issues;
@@ -25,6 +30,158 @@ function shown(value) {
     }
     return "a non-scalar value";
 }
+function isBranchBase(value) {
+    return typeof value === "string" && BRANCH_BASES.includes(value);
+}
+function readGitBase(node) {
+    if (!isMap(node))
+        return "invalid";
+    let base = null;
+    for (const item of node.items) {
+        const key = isScalar(item.key) && typeof item.key.value === "string" ? item.key.value : null;
+        if (key !== "defaultBase")
+            return "invalid";
+        const value = isScalar(item.value) ? item.value.value : null;
+        base = isBranchBase(value) ? value : "invalid";
+    }
+    return base;
+}
+function isScreenLanguage(value) {
+    return typeof value === "string" && SCREEN_LANGUAGES.includes(value);
+}
+function isTenancy(value) {
+    return typeof value === "string" && TENANCY_VALUES.includes(value);
+}
+function mappingKey(key) {
+    return isScalar(key) && typeof key.value === "string" ? key.value : null;
+}
+function assembleProduct(parts) {
+    const product = {};
+    if (parts.screenLanguage !== undefined)
+        product.screenLanguage = parts.screenLanguage;
+    if (parts.tenancy !== undefined)
+        product.tenancy = parts.tenancy;
+    if (parts.surfaces !== undefined)
+        product.surfaces = parts.surfaces;
+    return Object.keys(product).length > 0 ? product : undefined;
+}
+function readSurfaces(node) {
+    if (!isSeq(node)) {
+        return {
+            ok: false,
+            issues: [
+                issue("unknown-field", 'Field "product.surfaces" must be a list of ids.', "product.surfaces"),
+            ],
+        };
+    }
+    if (node.items.length === 0) {
+        return {
+            ok: false,
+            issues: [
+                issue("unknown-field", 'Field "product.surfaces" must not be empty. Omit the key instead.', "product.surfaces"),
+            ],
+        };
+    }
+    const issues = [];
+    const surfaces = [];
+    const ids = new Set();
+    for (const entry of node.items) {
+        if (!isMap(entry)) {
+            issues.push(issue("unknown-field", "Each surface must be a mapping with an id.", "product.surfaces"));
+            continue;
+        }
+        let id;
+        let sawId = false;
+        for (const pair of entry.items) {
+            const key = mappingKey(pair.key);
+            if (key !== "id") {
+                issues.push(issue("unknown-field", `Unknown field "product.surfaces.${key ?? ""}".`, "product.surfaces"));
+                continue;
+            }
+            if (sawId) {
+                issues.push(issue("duplicate-key", 'Duplicate key "id".', "product.surfaces"));
+                continue;
+            }
+            sawId = true;
+            id = isScalar(pair.value) ? pair.value.value : NON_SCALAR;
+        }
+        if (!sawId) {
+            issues.push(issue("missing-field", "Missing surface id.", "product.surfaces"));
+            continue;
+        }
+        if (typeof id !== "string") {
+            issues.push(issue("unknown-field", "Surface id must be a string.", "product.surfaces"));
+            continue;
+        }
+        if (!SURFACE_ID.test(id)) {
+            issues.push(issue("unknown-field", `Surface id ${JSON.stringify(id)} must match ^[a-z][a-z0-9-]*$.`, "product.surfaces"));
+            continue;
+        }
+        if (ids.has(id)) {
+            issues.push(issue("duplicate-key", `Duplicate surface id "${id}".`, "product.surfaces"));
+            continue;
+        }
+        ids.add(id);
+        surfaces.push({ id });
+    }
+    return issues.length > 0 ? { ok: false, issues } : { ok: true, surfaces };
+}
+function readProduct(node) {
+    if (!isMap(node)) {
+        return { issues: [issue("unknown-field", 'Unknown field "product".', "product")] };
+    }
+    const issues = [];
+    const seen = new Set();
+    let screenLanguage;
+    let tenancy;
+    let surfaces;
+    for (const item of node.items) {
+        const key = mappingKey(item.key);
+        if (key === null) {
+            issues.push(issue("unknown-field", "Mapping keys must be strings.", "product"));
+            continue;
+        }
+        if (seen.has(key)) {
+            issues.push(issue("duplicate-key", `Duplicate key "${key}".`, `product.${key}`));
+            continue;
+        }
+        seen.add(key);
+        if (!PRODUCT_FIELDS.has(key)) {
+            issues.push(issue("unknown-field", `Unknown field "product.${key}".`, `product.${key}`));
+            continue;
+        }
+        if (key === "screenLanguage") {
+            const value = isScalar(item.value) ? item.value.value : null;
+            if (!isScreenLanguage(value)) {
+                issues.push(issue("unknown-field", 'Unknown field "product.screenLanguage".', "product.screenLanguage"));
+            }
+            else {
+                screenLanguage = value;
+            }
+            continue;
+        }
+        if (key === "tenancy") {
+            const value = isScalar(item.value) ? item.value.value : null;
+            if (!isTenancy(value)) {
+                issues.push(issue("unknown-field", `Unknown tenancy ${shown(value)}.`, "product.tenancy"));
+            }
+            else {
+                tenancy = value;
+            }
+            continue;
+        }
+        const parsed = readSurfaces(item.value);
+        if (!parsed.ok) {
+            issues.push(...parsed.issues);
+            continue;
+        }
+        surfaces = parsed.surfaces;
+    }
+    if (issues.length > 0)
+        return { issues };
+    const product = assembleProduct({ screenLanguage, tenancy, surfaces });
+    return product ? { product, issues } : { issues };
+}
 function profileIssue(value) {
     if (typeof value !== "string") {
         return issue("unknown-profile", "Profile must be a string.", "profile");
@@ -65,6 +222,7 @@ export function parseConfig(text) {
     const issues = [];
     const occurrences = new Map();
     const values = new Map();
+    let product;
     for (const item of document.contents.items) {
         const key = isScalar(item.key) && typeof item.key.value === "string" ? item.key.value : null;
         if (key === null) {
@@ -81,6 +239,23 @@ export function parseConfig(text) {
             issues.push(issue("unknown-field", `Unknown field "${key}".`, key));
             continue;
         }
+        if (key === "git") {
+            const base = readGitBase(item.value);
+            if (base === "invalid") {
+                issues.push(issue("unknown-field", 'Unknown field "git.defaultBase".', "git.defaultBase"));
+            }
+            else if (base) {
+                values.set("git.defaultBase", base);
+            }
+            continue;
+        }
+        if (key === "product") {
+            const parsed = readProduct(item.value);
+            issues.push(...parsed.issues);
+            if (parsed.product)
+                product = parsed.product;
+            continue;
+        }
         values.set(key, isScalar(item.value) ? item.value.value : NON_SCALAR);
     }
     if ((occurrences.get("schemaVersion") ?? 0) === 0) {
@@ -104,5 +279,13 @@ export function parseConfig(text) {
             issue("unknown-profile", "Profile must be a string.", "profile"),
         ]);
     }
+    const defaultBase = values.get("git.defaultBase");
+    const git = isBranchBase(defaultBase) ? { defaultBase } : undefined;
+    if (git && product)
+        return { schemaVersion: CONFIG_SCHEMA_VERSION, profile, git, product };
+    if (git)
+        return { schemaVersion: CONFIG_SCHEMA_VERSION, profile, git };
+    if (product)
+        return { schemaVersion: CONFIG_SCHEMA_VERSION, profile, product };
     return { schemaVersion: CONFIG_SCHEMA_VERSION, profile };
 }

package/dist/core/feedback.js

@@ -0,0 +1,68 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const OUTCOME_LINE = /^outcome:[ \t]*(\S+)[ \t]*$/m;
+export const FEEDBACK_OUTCOMES = ["accepted", "edited", "expanded"];
+export class FeedbackError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "FeedbackError";
+        this.code = code;
+    }
+}
+function errno(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string") {
+        return error.code;
+    }
+    return null;
+}
+function isFeedbackOutcome(value) {
+    return typeof value === "string" && FEEDBACK_OUTCOMES.includes(value);
+}
+export function readFeedbackOutcome(reviewText) {
+    const frontMatter = FRONT_MATTER.exec(reviewText)?.[1];
+    if (frontMatter === undefined) {
+        return "unknown";
+    }
+    const value = OUTCOME_LINE.exec(frontMatter.replace(/\r/g, ""))?.[1];
+    return isFeedbackOutcome(value) ? value : "unknown";
+}
+export function saveFeedback(root, slug, record) {
+    if (!SLUG.test(slug)) {
+        throw new FeedbackError("invalid-slug", "Feedback slug must be a lowercase hyphenated name.");
+    }
+    if (!isFeedbackOutcome(record.outcome)) {
+        throw new FeedbackError("invalid-outcome", `Feedback outcome must be one of: ${FEEDBACK_OUTCOMES.join(", ")}.`);
+    }
+    const dir = join(root, ".tito", "feedback", slug);
+    const planPath = join(dir, "plan.md");
+    const reviewPath = join(dir, "review.md");
+    mkdirSync(dir, { recursive: true });
+    try {
+        writeFileSync(planPath, record.plan, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (errno(error) === "EEXIST") {
+            throw new FeedbackError("already-saved", "The Tito plan is already saved.");
+        }
+        throw error;
+    }
+    try {
+        writeFileSync(reviewPath, `---\noutcome: ${record.outcome}\n---\n${record.review}`, {
+            encoding: "utf8",
+            flag: "wx",
+        });
+    }
+    catch (error) {
+        if (errno(error) === "EEXIST") {
+            throw new FeedbackError("already-saved", "The review is already saved.");
+        }
+        throw error;
+    }
+    return { planPath, reviewPath };
+}

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,8 +2,9 @@ import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSy
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compiledCursorAgents } from "./agents.js";
+import { PULL_REQUEST_TEMPLATE_PATH, pullRequestTemplate } from "./git-flow.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 +32,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 +43,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) {
@@ -63,7 +65,15 @@ export function planInitialization(report, profile) {
     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/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.
@@ -12,9 +14,13 @@ 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.
+- Confirm intent before clarifying. Plans include decisions with conventions, AAA test cases, and docs impact.
 
 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/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,