@anhvupt/tito 0.1.3 → 0.3.0

package/dist/core/admin.js

@@ -0,0 +1,241 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+export class AdminError extends Error {
+    code;
+    path;
+    constructor(code, path, message) {
+        super(message);
+        this.name = "AdminError";
+        this.code = code;
+        this.path = path;
+    }
+}
+const SECRET_BASENAMES = new Set([".env", "credentials.json", "id_rsa"]);
+export function isSecretFilename(filePath) {
+    const name = basename(filePath);
+    if (SECRET_BASENAMES.has(name))
+        return true;
+    return name.startsWith(".env.");
+}
+export function resolveAdminRoot(explicit) {
+    if (explicit !== undefined)
+        return resolve(explicit);
+    return join(homedir(), ".config", "tito", "admin");
+}
+export function reposFilePath(adminRoot) {
+    return join(resolve(adminRoot), "repos.json");
+}
+export function contextFilePath(adminRoot) {
+    return join(resolve(adminRoot), "context.json");
+}
+function errno(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string") {
+        return error.code;
+    }
+    return null;
+}
+function assertDirectory(path) {
+    const resolved = resolve(path);
+    try {
+        if (!statSync(resolved).isDirectory()) {
+            throw new AdminError("not-a-directory", resolved, `${resolved} is not a directory.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof AdminError)
+            throw error;
+        const code = errno(error);
+        if (code === "ENOENT") {
+            throw new AdminError("not-a-directory", resolved, `${resolved} is not a directory.`);
+        }
+        throw new AdminError("filesystem", resolved, `Cannot inspect ${resolved}.`);
+    }
+    return resolved;
+}
+function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        throw new AdminError("filesystem", path, error instanceof Error ? error.message : `Cannot write ${path}.`);
+    }
+}
+function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        const code = errno(error);
+        if (code === "ENOENT")
+            return null;
+        throw new AdminError("filesystem", path, error instanceof Error ? error.message : `Cannot read ${path}.`);
+    }
+}
+function isAdminRepo(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return typeof record.path === "string" && typeof record.addedAt === "string";
+}
+export function loadRepos(adminRoot) {
+    const path = reposFilePath(adminRoot);
+    if (!existsSync(path))
+        return [];
+    const raw = readJsonFile(path);
+    if (!Array.isArray(raw)) {
+        throw new AdminError("filesystem", path, `${path} must contain a JSON array.`);
+    }
+    const repos = [];
+    for (const item of raw) {
+        if (!isAdminRepo(item)) {
+            throw new AdminError("filesystem", path, `${path} has an invalid repo entry.`);
+        }
+        repos.push({ path: item.path, addedAt: item.addedAt });
+    }
+    return repos;
+}
+export function saveRepos(adminRoot, repos) {
+    writeJsonAtomic(reposFilePath(adminRoot), repos);
+}
+export function loadContexts(adminRoot) {
+    const path = contextFilePath(adminRoot);
+    if (!existsSync(path))
+        return [];
+    const raw = readJsonFile(path);
+    if (!Array.isArray(raw)) {
+        throw new AdminError("filesystem", path, `${path} must contain a JSON array.`);
+    }
+    return raw;
+}
+export function saveContexts(adminRoot, contexts) {
+    writeJsonAtomic(contextFilePath(adminRoot), contexts);
+}
+const defaultClock = () => new Date().toISOString();
+export function defaultGitRunner(cwd, args) {
+    const result = spawnSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (result.error) {
+        throw new AdminError("git", cwd, result.error.message);
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "git command failed").trim();
+        throw new AdminError("git", cwd, detail);
+    }
+    return result.stdout ?? "";
+}
+export function addRepo(adminRoot, repoPath, options = {}) {
+    const path = assertDirectory(repoPath);
+    const repos = loadRepos(adminRoot);
+    const existing = repos.find((repo) => repo.path === path);
+    if (existing !== undefined) {
+        return { repo: existing, created: false };
+    }
+    const clock = options.clock ?? defaultClock;
+    const repo = { path, addedAt: clock() };
+    repos.push(repo);
+    saveRepos(adminRoot, repos);
+    return { repo, created: true };
+}
+export function listRepos(adminRoot) {
+    return loadRepos(adminRoot);
+}
+export function removeRepo(adminRoot, repoPath) {
+    const path = resolve(repoPath);
+    const repos = loadRepos(adminRoot);
+    const index = repos.findIndex((repo) => repo.path === path);
+    if (index < 0) {
+        throw new AdminError("not-registered", path, `${path} is not registered.`);
+    }
+    const [removed] = repos.splice(index, 1);
+    if (removed === undefined) {
+        throw new AdminError("not-registered", path, `${path} is not registered.`);
+    }
+    saveRepos(adminRoot, repos);
+    return removed;
+}
+function parseCommitLog(stdout) {
+    const commits = [];
+    const blocks = stdout.split(/\n(?=◆)/);
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (trimmed.length === 0)
+            continue;
+        const lines = trimmed.split("\n");
+        const header = lines[0];
+        if (header === undefined || !header.startsWith("◆"))
+            continue;
+        const parts = header.slice(1).split("\0");
+        const subject = parts[0] ?? "";
+        const date = parts[1] ?? "";
+        const files = [];
+        for (const line of lines.slice(1)) {
+            const file = line.trim();
+            if (file.length === 0)
+                continue;
+            if (isSecretFilename(file))
+                continue;
+            files.push(file);
+        }
+        commits.push({ subject, date, files });
+    }
+    return commits;
+}
+export function readRepoContext(repoPath, options = {}) {
+    const path = assertDirectory(repoPath);
+    const git = options.git ?? defaultGitRunner;
+    const branch = git(path, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    const log = git(path, [
+        "log",
+        "-n",
+        "50",
+        "--pretty=format:◆%s%x00%cI",
+        "--name-only",
+    ]);
+    return {
+        path,
+        branch,
+        recentCommits: parseCommitLog(log),
+    };
+}
+export function refreshRepos(adminRoot, options = {}) {
+    const repos = loadRepos(adminRoot);
+    const contexts = [];
+    for (const repo of repos) {
+        contexts.push(readRepoContext(repo.path, options));
+    }
+    saveContexts(adminRoot, contexts);
+    return contexts;
+}
+export function formatRepos(repos) {
+    if (repos.length === 0)
+        return "No registered repositories.\n";
+    return `${repos.map((repo) => `${repo.path}\t${repo.addedAt}`).join("\n")}\n`;
+}
+export function formatContexts(contexts) {
+    if (contexts.length === 0)
+        return "No repository context.\n";
+    const lines = [];
+    for (const context of contexts) {
+        lines.push(`path: ${context.path}`);
+        lines.push(`branch: ${context.branch}`);
+        lines.push(`commits: ${context.recentCommits.length}`);
+        for (const commit of context.recentCommits) {
+            lines.push(`- ${commit.date}\t${commit.subject}`);
+            for (const file of commit.files) {
+                lines.push(`  ${file}`);
+            }
+        }
+        lines.push("");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}

package/dist/core/agents.js

@@ -24,6 +24,9 @@ export function compileCursorAgent(id) {
     const knowledge = manifest.knowledge
         .map((item) => `- \`${item.id}\` (${item.load})`)
         .join("\n");
+    const stackGuidance = manifest.knowledge.some((item) => item.load === "stack")
+        ? "For a stack entry, use the stack owner's official resource for the project's version. Judge it before use. Do not copy it into the repo.\n\n"
+        : "";
     return `---
 name: ${AGENT_FILE_NAMES[id].replace(/\.md$/, "")}
 description: >
@@ -47,7 +50,7 @@ Use only the mode named in Tito's task packet. A read-only mode must not edit fi
 
 ${knowledge}
 
-Do not restate project documentation. Load it only when the task needs it.
+${stackGuidance}Do not restate project documentation. Load it only when the task needs it.
 
 ## Handoffs
 

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"]);
+export const SCREEN_LANGUAGES = ["vi", "en"];
+export 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,202 @@ function shown(value) {
     }
     return "a non-scalar value";
 }
+function isBranchBase(value) {
+    return typeof value === "string" && BRANCH_BASES.includes(value);
+}
+export function isSurfaceId(value) {
+    return SURFACE_ID.test(value);
+}
+function assembleGit(parts) {
+    const git = {};
+    if (parts.defaultBase !== undefined)
+        git.defaultBase = parts.defaultBase;
+    if (parts.autoPullRequest !== undefined)
+        git.autoPullRequest = parts.autoPullRequest;
+    return Object.keys(git).length > 0 ? git : undefined;
+}
+function readGit(node) {
+    if (!isMap(node)) {
+        return { issues: [issue("unknown-field", 'Field "git" must be a mapping.', "git")] };
+    }
+    const issues = [];
+    const seen = new Set();
+    let defaultBase;
+    let autoPullRequest = undefined;
+    for (const item of node.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.", "git"));
+            continue;
+        }
+        if (seen.has(key)) {
+            issues.push(issue("duplicate-key", `Duplicate key "${key}".`, `git.${key}`));
+            continue;
+        }
+        seen.add(key);
+        if (key === "defaultBase") {
+            const value = isScalar(item.value) ? item.value.value : null;
+            if (!isBranchBase(value)) {
+                issues.push(issue("unknown-field", 'Unknown field "git.defaultBase".', "git.defaultBase"));
+            }
+            else {
+                defaultBase = value;
+            }
+            continue;
+        }
+        if (key === "autoPullRequest") {
+            const value = isScalar(item.value) ? item.value.value : NON_SCALAR;
+            if (typeof value !== "boolean") {
+                issues.push(issue("unknown-field", 'Field "git.autoPullRequest" must be a boolean.', "git.autoPullRequest"));
+            }
+            else {
+                autoPullRequest = value;
+            }
+            continue;
+        }
+        issues.push(issue("unknown-field", `Unknown field "git.${key}".`, `git.${key}`));
+    }
+    if (issues.length > 0)
+        return { issues };
+    const git = assembleGit({ defaultBase, autoPullRequest });
+    return git ? { git, issues } : { issues };
+}
+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 +266,8 @@ export function parseConfig(text) {
     const issues = [];
     const occurrences = new Map();
     const values = new Map();
+    let git;
+    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 +284,20 @@ export function parseConfig(text) {
             issues.push(issue("unknown-field", `Unknown field "${key}".`, key));
             continue;
         }
+        if (key === "git") {
+            const parsed = readGit(item.value);
+            issues.push(...parsed.issues);
+            if (parsed.git)
+                git = parsed.git;
+            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 +321,10 @@ export function parseConfig(text) {
             issue("unknown-profile", "Profile must be a string.", "profile"),
         ]);
     }
-    return { schemaVersion: CONFIG_SCHEMA_VERSION, profile };
+    const result = { schemaVersion: CONFIG_SCHEMA_VERSION, profile };
+    if (git)
+        result.git = git;
+    if (product)
+        result.product = product;
+    return result;
 }

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 };
+}