@anhvupt/tito 0.1.0

package/dist/core/config.js

@@ -0,0 +1,108 @@
+import { isMap, isScalar, parseAllDocuments } from "yaml";
+import { ACTIVE_RISK_PROFILE_IDS, isActiveRiskProfileId, isFutureRiskProfileId, } from "./profiles.js";
+export const CONFIG_SCHEMA_VERSION = 1;
+const FIELDS = new Set(["schemaVersion", "profile"]);
+const NON_SCALAR = Symbol("non-scalar");
+export class ConfigValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues.map((item) => item.message).join("\n"));
+        this.name = "ConfigValidationError";
+        this.issues = issues;
+    }
+}
+function issue(code, message, path) {
+    return path === undefined ? { code, message } : { code, message, path };
+}
+function shown(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint" ||
+        value === null) {
+        return String(value);
+    }
+    return "a non-scalar value";
+}
+function profileIssue(value) {
+    if (typeof value !== "string") {
+        return issue("unknown-profile", "Profile must be a string.", "profile");
+    }
+    if (isFutureRiskProfileId(value)) {
+        return issue("unsupported-profile", `Profile "${value}" is recognized but not available.`, "profile");
+    }
+    if (isActiveRiskProfileId(value))
+        return null;
+    return issue("unknown-profile", `Unknown profile "${value}". Active profiles: ${ACTIVE_RISK_PROFILE_IDS.join(", ")}.`, "profile");
+}
+export function parseConfig(text) {
+    const documents = parseAllDocuments(text, {
+        logLevel: "silent",
+        merge: false,
+        stringKeys: true,
+        uniqueKeys: true,
+        version: "1.2",
+    });
+    const document = documents[0];
+    if (documents.length !== 1 || !document) {
+        const multiple = documents.length > 1;
+        throw new ConfigValidationError([
+            issue(multiple ? "yaml-syntax" : "not-a-mapping", multiple
+                ? "Multiple YAML documents are not allowed."
+                : "Configuration must be a mapping."),
+        ]);
+    }
+    const syntax = document.errors.filter((error) => error.code !== "DUPLICATE_KEY" && error.code !== "NON_STRING_KEY");
+    if (syntax.length > 0) {
+        throw new ConfigValidationError(syntax.map((error) => issue("yaml-syntax", `YAML syntax error (${error.code}).`)));
+    }
+    if (!isMap(document.contents)) {
+        throw new ConfigValidationError([
+            issue("not-a-mapping", "Configuration must be a mapping."),
+        ]);
+    }
+    const issues = [];
+    const occurrences = new Map();
+    const values = new Map();
+    for (const item of document.contents.items) {
+        const key = isScalar(item.key) && typeof item.key.value === "string" ? item.key.value : null;
+        if (key === null) {
+            issues.push(issue("unknown-field", "Mapping keys must be strings."));
+            continue;
+        }
+        const count = (occurrences.get(key) ?? 0) + 1;
+        occurrences.set(key, count);
+        if (count > 1) {
+            issues.push(issue("duplicate-key", `Duplicate key "${key}".`, key));
+            continue;
+        }
+        if (!FIELDS.has(key)) {
+            issues.push(issue("unknown-field", `Unknown field "${key}".`, key));
+            continue;
+        }
+        values.set(key, isScalar(item.value) ? item.value.value : NON_SCALAR);
+    }
+    if ((occurrences.get("schemaVersion") ?? 0) === 0) {
+        issues.push(issue("missing-field", 'Missing required field "schemaVersion".', "schemaVersion"));
+    }
+    else if (occurrences.get("schemaVersion") === 1 && values.get("schemaVersion") !== CONFIG_SCHEMA_VERSION) {
+        issues.push(issue("unsupported-schema-version", `Unsupported schemaVersion ${shown(values.get("schemaVersion"))}. Expected ${CONFIG_SCHEMA_VERSION}.`, "schemaVersion"));
+    }
+    const profileError = (occurrences.get("profile") ?? 0) === 0
+        ? issue("missing-field", 'Missing required field "profile".', "profile")
+        : occurrences.get("profile") === 1
+            ? profileIssue(values.get("profile"))
+            : null;
+    if (profileError)
+        issues.push(profileError);
+    if (issues.length > 0)
+        throw new ConfigValidationError(issues);
+    const profile = values.get("profile");
+    if (typeof profile !== "string" || !isActiveRiskProfileId(profile)) {
+        throw new ConfigValidationError([
+            issue("unknown-profile", "Profile must be a string.", "profile"),
+        ]);
+    }
+    return { schemaVersion: CONFIG_SCHEMA_VERSION, profile };
+}

package/dist/core/init.js

@@ -0,0 +1,65 @@
+import { mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { compiledCursorAgents } from "./agents.js";
+import { PlanError, planAdoption, } from "./plan.js";
+export class InitError extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.name = "InitError";
+        this.code = "conflict";
+    }
+}
+function exists(root, path) {
+    try {
+        return statSync(join(root, path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function planInitialization(report, profile) {
+    const adoption = planAdoption(report, profile);
+    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] };
+}
+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")
+            lines.push("---", file.body.trimEnd(), "---");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function applyInitialization(plan) {
+    const conflicts = plan.files.filter((file) => file.action === "conflict");
+    if (conflicts.length > 0) {
+        throw new InitError(`Refusing to write because ${conflicts.map((file) => file.path).join(", ")} already exists.`);
+    }
+    const created = [];
+    try {
+        for (const file of plan.files) {
+            if (file.action !== "create")
+                continue;
+            const absolute = join(plan.root, file.path);
+            mkdirSync(dirname(absolute), { recursive: true });
+            writeFileSync(absolute, file.body, { encoding: "utf8", flag: "wx" });
+            created.push(absolute);
+        }
+    }
+    catch (error) {
+        for (const absolute of created) {
+            try {
+                unlinkSync(absolute);
+            }
+            catch {
+                // Keep the original write error.
+            }
+        }
+        throw error;
+    }
+}
+export { PlanError };

package/dist/core/inspect.js

@@ -0,0 +1,89 @@
+import { readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ConfigValidationError, parseConfig, } from "./config.js";
+export class InspectionError extends Error {
+    code;
+    path;
+    constructor(code, path, message) {
+        super(message);
+        this.name = "InspectionError";
+        this.code = code;
+        this.path = path;
+    }
+}
+function errno(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string") {
+        return error.code;
+    }
+    return null;
+}
+function fail(code, path, message) {
+    throw new InspectionError(code, path, message);
+}
+function fileKind(path) {
+    try {
+        if (statSync(path).isFile())
+            return "file";
+        fail("filesystem", path, `${path} must be a file.`);
+    }
+    catch (error) {
+        if (error instanceof InspectionError)
+            throw error;
+        const code = errno(error);
+        if (code === "ENOENT")
+            return "absent";
+        if (code === "EACCES" || code === "EPERM") {
+            fail("inaccessible", path, `Cannot read ${path}.`);
+        }
+        fail("filesystem", path, `Cannot inspect ${path}.`);
+    }
+}
+function readConfig(path) {
+    if (fileKind(path) === "absent")
+        return { status: "absent" };
+    try {
+        return { status: "valid", config: parseConfig(readFileSync(path, "utf8")) };
+    }
+    catch (error) {
+        if (error instanceof ConfigValidationError) {
+            return { status: "invalid", issues: error.issues };
+        }
+        fail("filesystem", path, `Cannot read ${path}.`);
+    }
+}
+export function inspectRepository(root) {
+    const resolved = resolve(root);
+    try {
+        if (!statSync(resolved).isDirectory()) {
+            fail("not-a-directory", resolved, `${resolved} is not a directory.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof InspectionError)
+            throw error;
+        const code = errno(error);
+        if (code === "EACCES" || code === "EPERM") {
+            fail("inaccessible", resolved, `Cannot read ${resolved}.`);
+        }
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            fail("not-a-directory", resolved, `${resolved} is not a directory.`);
+        }
+        fail("filesystem", resolved, `Cannot inspect ${resolved}.`);
+    }
+    return {
+        root: resolved,
+        titoYaml: readConfig(join(resolved, "tito.yaml")),
+        agentsMd: fileKind(join(resolved, "AGENTS.md")) === "file" ? "present" : "absent",
+    };
+}
+export function formatInspection(report) {
+    const config = report.titoYaml.status === "absent"
+        ? "absent"
+        : report.titoYaml.status === "valid"
+            ? `valid profile=${report.titoYaml.config.profile}`
+            : `invalid ${report.titoYaml.issues.map((item) => item.code).join(",")}`;
+    return `root: ${report.root}\ntito.yaml: ${config}\nAGENTS.md: ${report.agentsMd}\n`;
+}

package/dist/core/lifecycle.js

@@ -0,0 +1,54 @@
+export const LIFECYCLE_STATES = Object.freeze([
+    "DISCOVERY",
+    "PLANNED",
+    "APPROVED",
+    "IMPLEMENTING",
+    "READY_FOR_REVIEW",
+    "APPROVED_FOR_COMMIT",
+    "DONE",
+]);
+const LINEAR_NEXT = {
+    DISCOVERY: "PLANNED",
+    PLANNED: "APPROVED",
+    APPROVED: "IMPLEMENTING",
+    IMPLEMENTING: "READY_FOR_REVIEW",
+    READY_FOR_REVIEW: "APPROVED_FOR_COMMIT",
+    APPROVED_FOR_COMMIT: "DONE",
+    DONE: null,
+};
+export class LifecycleTransitionError extends Error {
+    code;
+    from;
+    to;
+    constructor(code, from, to, message) {
+        super(message);
+        this.name = "LifecycleTransitionError";
+        this.code = code;
+        this.from = from;
+        this.to = to;
+    }
+}
+function isLifecycleState(value) {
+    return LIFECYCLE_STATES.includes(value);
+}
+function reject(code, from, to, message) {
+    throw new LifecycleTransitionError(code, from, to, message);
+}
+export function transitionLifecycle(from, to, authorization) {
+    if (!isLifecycleState(from) || !isLifecycleState(to)) {
+        reject("invalid-state", from, to, "Lifecycle transition requires known states.");
+    }
+    if (LINEAR_NEXT[from] === to)
+        return to;
+    if (from === "DISCOVERY" && to === "APPROVED") {
+        if (authorization.approvedSmallSlice)
+            return to;
+        reject("missing-authorization", from, to, "DISCOVERY can move to APPROVED only for an explicitly approved small slice.");
+    }
+    if (from === "READY_FOR_REVIEW" && to === "IMPLEMENTING") {
+        if (authorization.inScopeReviewRevision)
+            return to;
+        reject("missing-authorization", from, to, "READY_FOR_REVIEW can return to IMPLEMENTING only for an in-scope review revision.");
+    }
+    reject("illegal-transition", from, to, `Cannot transition from ${from} to ${to}.`);
+}

package/dist/core/plan.js

@@ -0,0 +1,59 @@
+import { ACTIVE_RISK_PROFILE_IDS, isActiveRiskProfileId, isFutureRiskProfileId, } from "./profiles.js";
+export const ADOPTION_AGENTS_MD = `# Tito bootstrap
+
+This project uses Tito as its root engineering coordinator.
+
+- Start every Tito-coordinated chat response exactly with \`Hola, Tito here!\`
+- Keep that marker out of CLI and machine-readable output.
+- Treat ordinary requests as Tito-coordinated work.
+- Recommend Ask, Plan, or Agent before acting.
+- Preserve uncommitted work and use one code writer at a time.
+- Stop for human approval between reviewable slices.
+- 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.
+
+Keep this bootstrap compact. Load project documentation only when the task needs it.
+`;
+export class PlanError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PlanError";
+        this.code = code;
+    }
+}
+function configBody(profile) {
+    return `schemaVersion: 1\nprofile: ${profile}\n`;
+}
+function requireProfile(profile) {
+    if (profile.trim() === "") {
+        throw new PlanError("missing-profile", "Missing required profile.");
+    }
+    if (isFutureRiskProfileId(profile)) {
+        throw new PlanError("unsupported-profile", `Profile "${profile}" is recognized but not available.`);
+    }
+    if (!isActiveRiskProfileId(profile)) {
+        throw new PlanError("unknown-profile", `Unknown profile "${profile}". Active profiles: ${ACTIVE_RISK_PROFILE_IDS.join(", ")}.`);
+    }
+    return profile;
+}
+export function planAdoption(report, profile) {
+    const selected = requireProfile(profile);
+    const titoYaml = report.titoYaml.status === "absent"
+        ? { path: "tito.yaml", action: "create", body: configBody(selected) }
+        : { path: "tito.yaml", action: "conflict" };
+    const agentsMd = report.agentsMd === "absent"
+        ? { path: "AGENTS.md", action: "create", body: ADOPTION_AGENTS_MD }
+        : { path: "AGENTS.md", action: "keep" };
+    return { root: report.root, profile: selected, files: [titoYaml, agentsMd] };
+}
+export function formatAdoptionPlan(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")
+            lines.push("---", file.body.trimEnd(), "---");
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/core/profiles.js

@@ -0,0 +1,81 @@
+export const MANDATORY_ESCALATION_TOPICS = Object.freeze([
+    "authentication-and-authorization",
+    "payments",
+    "secrets",
+    "production-data",
+    "destructive-database-changes",
+    "privacy-sensitive-information",
+    "public-infrastructure",
+    "irreversible-external-actions",
+    "accounting-and-financial-invariants",
+]);
+export const ACTIVE_RISK_PROFILE_IDS = [
+    "client-careful",
+    "solo-balanced",
+    "solo-fast",
+];
+export const FUTURE_RISK_PROFILE_IDS = ["small-team"];
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}
+export const RISK_PROFILES = deepFreeze({
+    "client-careful": {
+        id: "client-careful",
+        status: "active",
+        maxWriters: 1,
+        writerConstraint: "one-at-a-time",
+        independentReview: "required",
+        preferredAuthoredLines: { min: 100, max: 200 },
+        maxAuthoredLinesWithoutApproval: 300,
+        maxAuthoredFiles: 6,
+        stackedUnreviewedChanges: false,
+        humanApproval: "every-slice",
+        migrationsRequireRollbackPlans: true,
+        unapprovedActions: [
+            "commit",
+            "merge",
+            "push",
+            "deployment",
+            "publication",
+            "external-write",
+        ],
+        safetyFloor: MANDATORY_ESCALATION_TOPICS,
+    },
+    "solo-balanced": {
+        id: "solo-balanced",
+        status: "active",
+        maxWriters: 1,
+        writerConstraint: "one-at-a-time",
+        humanReview: "feature-boundaries",
+        independentReviewFor: ["security", "data", "migrations", "architecture"],
+        diffLimits: "moderate",
+        automation: "deterministic-and-reversible",
+        safetyFloor: MANDATORY_ESCALATION_TOPICS,
+    },
+    "solo-fast": {
+        id: "solo-fast",
+        status: "active",
+        maxWriters: 1,
+        writerConstraint: "one-at-a-time",
+        agentSelfReview: "allowed",
+        humanReview: "milestones",
+        safetyFloor: MANDATORY_ESCALATION_TOPICS,
+    },
+});
+export const FUTURE_RISK_PROFILES = deepFreeze({
+    "small-team": {
+        id: "small-team",
+        status: "unavailable",
+    },
+});
+export function isActiveRiskProfileId(value) {
+    return ACTIVE_RISK_PROFILE_IDS.includes(value);
+}
+export function isFutureRiskProfileId(value) {
+    return FUTURE_RISK_PROFILE_IDS.includes(value);
+}

package/dist/core/routing.js

@@ -0,0 +1,35 @@
+export const CURSOR_MODES = Object.freeze(["Ask", "Plan", "Agent"]);
+export function recommendMode(facts) {
+    const escalation = facts.escalationTopics.length > 0;
+    const criticalWork = facts.migration || facts.securitySensitive || facts.accountingInvariant;
+    const planning = facts.ambiguous ||
+        facts.multiModule ||
+        facts.architectureChange ||
+        facts.requiresSlicing;
+    const carefulHandling = escalation || criticalWork;
+    const independentReview = carefulHandling || facts.architectureChange;
+    const reasonCodes = [];
+    if (facts.approvedImplementationSlice) {
+        reasonCodes.push("approved-implementation-slice");
+    }
+    if (escalation)
+        reasonCodes.push("mandatory-escalation");
+    if (criticalWork)
+        reasonCodes.push("critical-work");
+    if (planning)
+        reasonCodes.push("planning-required");
+    if (facts.approvedImplementationSlice) {
+        return { mode: "Agent", reasonCodes, carefulHandling, independentReview };
+    }
+    if (reasonCodes.length > 0) {
+        return { mode: "Plan", reasonCodes, carefulHandling, independentReview };
+    }
+    return {
+        mode: "Ask",
+        reasonCodes: [
+            facts.intent === "read-only" ? "read-only-discovery" : "change-needs-approval",
+        ],
+        carefulHandling: false,
+        independentReview: false,
+    };
+}