@pedrocivita/tocket 2.1.0 → 2.2.0

package/dist/commands/init.cmd.js

@@ -119,8 +119,12 @@ export function registerInitCommand(program) {
         .command("init")
         .description("Scaffold an agentic workspace with Memory Bank and triangulation config")
         .option("-f, --force", "Overwrite existing files without prompting")
+        .option("--minimal", "Scaffold only essential files (.context/ + TOCKET.md)")
+        .option("--name <name>", "Project name (skip prompt)")
+        .option("--description <desc>", "Project description (skip prompt)")
         .action(async (options) => {
         const force = options.force ?? false;
+        const minimal = options.minimal ?? false;
         const cwd = process.cwd();
         const globalConfig = await getConfig();
         if (!globalConfig.theme?.disableBanner) {
@@ -142,11 +146,11 @@ export function registerInitCommand(program) {
                 console.log(info(`Extras:    ${stack.extras.join(", ")}`));
             console.log();
         }
-        const projectName = await input({
+        const projectName = options.name ?? await input({
             message: "Project Name:",
             default: detectedName || undefined,
         });
-        const description = await input({
+        const description = options.description ?? await input({
             message: "Short Description:",
             default: detectedDescription || undefined,
         });
@@ -169,7 +173,15 @@ export function registerInitCommand(program) {
             ],
             [join(".context", "progress.md"), progressMd(projectName)],
         ];
-        for (const [filePath, content] of files) {
+        const minimalPaths = new Set([
+            "TOCKET.md",
+            join(".context", "activeContext.md"),
+            join(".context", "systemPatterns.md"),
+        ]);
+        const filesToWrite = minimal
+            ? files.filter(([path]) => minimalPaths.has(path))
+            : files;
+        for (const [filePath, content] of filesToWrite) {
             const fullPath = join(cwd, filePath);
             const exists = await fileExists(fullPath);
             if (exists && !force) {

package/dist/commands/lint.cmd.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from "commander";
+export interface LintResult {
+    severity: "pass" | "warn" | "info" | "fail";
+    message: string;
+    file?: string;
+    suggestion?: string;
+}
+export declare function lintActiveContext(content: string): LintResult[];
+export declare function lintSystemPatterns(content: string): LintResult[];
+export declare function lintProtocolSpec(content: string): LintResult[];
+export declare function lintAgentConfig(name: string, content: string): LintResult[];
+export declare function registerLintCommand(program: Command): void;

package/dist/commands/lint.cmd.js

@@ -0,0 +1,269 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { success as themePass, warn as themeWarn, error as themeFail, heading, dim, info as themeInfo } from "../utils/theme.js";
+import { isGitRepo } from "../utils/git.js";
+export function lintActiveContext(content) {
+    const results = [];
+    // Check required sections exist
+    const requiredSections = ["## Current Focus", "## Recent Changes", "## Open Decisions"];
+    for (const section of requiredSections) {
+        if (content.includes(section)) {
+            results.push({ severity: "pass", message: `Has ${section} section` });
+        }
+        else {
+            results.push({
+                severity: "fail",
+                message: `Missing ${section} section`,
+                suggestion: `Add a "${section}" heading to activeContext.md`,
+            });
+        }
+    }
+    // Check Current Focus is populated
+    const focusMatch = content.match(/## Current Focus\s*\n+([\s\S]*?)(?=\n##|\n*$)/);
+    const focusBody = focusMatch?.[1]?.trim() ?? "";
+    if (!focusBody || focusBody.startsWith("_") || focusBody.includes("No active tasks")) {
+        results.push({
+            severity: "warn",
+            message: "Current Focus is empty or placeholder",
+            suggestion: "Run tocket focus \"your current task\" to set it",
+        });
+    }
+    else {
+        results.push({ severity: "pass", message: "Current Focus is populated" });
+    }
+    // Check Open Decisions section
+    const decisionsMatch = content.match(/## Open Decisions\s*\n+([\s\S]*?)(?=\n##|\n*$)/);
+    const decisionsBody = decisionsMatch?.[1]?.trim() ?? "";
+    if (!decisionsBody || decisionsBody.startsWith("_")) {
+        results.push({
+            severity: "info",
+            message: "Open Decisions section is empty",
+            suggestion: "List any unresolved decisions or write \"None\" if all resolved",
+        });
+    }
+    return results;
+}
+export function lintSystemPatterns(content) {
+    const results = [];
+    const hasConvention = content.includes("- ") || content.includes("| ");
+    if (hasConvention) {
+        results.push({ severity: "pass", message: "Has documented conventions" });
+    }
+    else {
+        results.push({
+            severity: "warn",
+            message: "No conventions documented",
+            suggestion: "Add bullet points or a table with your project's coding conventions",
+        });
+    }
+    // Check for key decisions table
+    if (content.includes("Key Decisions") || content.includes("key decisions")) {
+        const hasDecisionRows = content.match(/\|[^|]+\|[^|]+\|[^|]+\|/g);
+        const hasDataRows = hasDecisionRows && hasDecisionRows.length > 2; // header + separator + at least 1 row
+        if (hasDataRows) {
+            results.push({ severity: "pass", message: "Has key decisions recorded" });
+        }
+        else {
+            results.push({
+                severity: "info",
+                message: "Key Decisions table is empty",
+                suggestion: "Record architectural decisions with rationale and date",
+            });
+        }
+    }
+    return results;
+}
+export function lintProtocolSpec(content) {
+    const results = [];
+    if (content.includes("payload") || content.includes("Payload")) {
+        results.push({ severity: "pass", message: "References payload format" });
+    }
+    else {
+        results.push({
+            severity: "warn",
+            message: "Does not reference payload format",
+            suggestion: "TOCKET.md should describe the payload XML handoff format",
+        });
+    }
+    if (content.includes("Memory Bank") || content.includes(".context/")) {
+        results.push({ severity: "pass", message: "References Memory Bank" });
+    }
+    else {
+        results.push({
+            severity: "warn",
+            message: "Does not reference Memory Bank",
+            suggestion: "TOCKET.md should describe the .context/ directory",
+        });
+    }
+    return results;
+}
+export function lintAgentConfig(name, content) {
+    const results = [];
+    if (content.includes(".context/") || content.includes(".context\\")) {
+        results.push({ severity: "pass", message: `References .context/` });
+    }
+    else {
+        results.push({
+            severity: "warn",
+            message: `Does not reference .context/`,
+            suggestion: `Add instructions to read .context/ before acting`,
+        });
+    }
+    return results;
+}
+function severityIcon(severity) {
+    switch (severity) {
+        case "pass": return themePass("");
+        case "warn": return themeWarn("");
+        case "info": return themeInfo("");
+        case "fail": return themeFail("");
+    }
+}
+export function registerLintCommand(program) {
+    program
+        .command("lint")
+        .description("Audit .context/ content quality and suggest improvements")
+        .action(() => {
+        const cwd = process.cwd();
+        let passCount = 0;
+        let warnCount = 0;
+        let infoCount = 0;
+        let failCount = 0;
+        console.log(heading("\nTocket Lint\n"));
+        // Check TOCKET.md exists
+        const tocketPath = join(cwd, "TOCKET.md");
+        if (!existsSync(tocketPath)) {
+            console.log(themeFail("  TOCKET.md not found. Run tocket init first."));
+            process.exitCode = 1;
+            return;
+        }
+        // Lint activeContext.md
+        const acPath = join(cwd, ".context", "activeContext.md");
+        if (existsSync(acPath)) {
+            console.log(dim("  .context/activeContext.md"));
+            const content = readFileSync(acPath, "utf-8");
+            const results = lintActiveContext(content);
+            for (const r of results) {
+                printResult(r);
+                countResult(r.severity);
+            }
+            // Staleness check
+            const stats = statSync(acPath);
+            const daysSince = Math.floor((Date.now() - stats.mtimeMs) / (1000 * 60 * 60 * 24));
+            if (daysSince > 7) {
+                const r = {
+                    severity: "warn",
+                    message: `Last modified ${daysSince} days ago`,
+                    suggestion: "Update activeContext.md with current state",
+                };
+                printResult(r);
+                countResult(r.severity);
+            }
+            console.log();
+        }
+        else {
+            console.log(dim("  .context/activeContext.md"));
+            console.log(`    ${severityIcon("fail")} File missing (required)`);
+            failCount++;
+            console.log();
+        }
+        // Lint systemPatterns.md
+        const spPath = join(cwd, ".context", "systemPatterns.md");
+        if (existsSync(spPath)) {
+            console.log(dim("  .context/systemPatterns.md"));
+            const content = readFileSync(spPath, "utf-8");
+            const results = lintSystemPatterns(content);
+            for (const r of results) {
+                printResult(r);
+                countResult(r.severity);
+            }
+            console.log();
+        }
+        // Lint TOCKET.md
+        console.log(dim("  TOCKET.md"));
+        const tocketContent = readFileSync(tocketPath, "utf-8");
+        const tocketResults = lintProtocolSpec(tocketContent);
+        for (const r of tocketResults) {
+            printResult(r);
+            countResult(r.severity);
+        }
+        console.log();
+        // Lint agent configs
+        const agentFiles = ["CLAUDE.md", "GEMINI.md"];
+        for (const af of agentFiles) {
+            const afPath = join(cwd, af);
+            if (existsSync(afPath)) {
+                console.log(dim(`  ${af}`));
+                const content = readFileSync(afPath, "utf-8");
+                const results = lintAgentConfig(af, content);
+                for (const r of results) {
+                    printResult(r);
+                    countResult(r.severity);
+                }
+                console.log();
+            }
+        }
+        // Uncommitted context check
+        if (isGitRepo(cwd)) {
+            try {
+                const output = execSync("git status --porcelain .context/", {
+                    cwd,
+                    encoding: "utf-8",
+                }).trim();
+                if (output) {
+                    const count = output.split("\n").length;
+                    console.log(dim("  git"));
+                    const r = {
+                        severity: "info",
+                        message: `${count} uncommitted change(s) in .context/`,
+                        suggestion: "Commit .context/ changes to preserve shared memory",
+                    };
+                    printResult(r);
+                    countResult(r.severity);
+                    console.log();
+                }
+            }
+            catch {
+                // git error — skip
+            }
+        }
+        // Summary
+        const total = passCount + warnCount + infoCount + failCount;
+        console.log(dim(`  ${passCount} passed, ${warnCount} warnings, ${infoCount} info, ${failCount} failures (${total} checks)`));
+        console.log();
+        if (failCount > 0) {
+            console.log(themeFail("Context has issues that need attention."));
+            process.exitCode = 1;
+        }
+        else if (warnCount > 0) {
+            console.log(themeWarn("Context is functional but could be improved."));
+        }
+        else {
+            console.log(themePass("Context is in great shape."));
+        }
+        function printResult(r) {
+            const icon = severityIcon(r.severity);
+            console.log(`    ${icon} ${r.message}`);
+            if (r.suggestion) {
+                console.log(`      ${dim(r.suggestion)}`);
+            }
+        }
+        function countResult(severity) {
+            switch (severity) {
+                case "pass":
+                    passCount++;
+                    break;
+                case "warn":
+                    warnCount++;
+                    break;
+                case "info":
+                    infoCount++;
+                    break;
+                case "fail":
+                    failCount++;
+                    break;
+            }
+        }
+    });
+}

package/dist/commands/sync.cmd.js

@@ -9,7 +9,8 @@ export function registerSyncCommand(program) {
     program
         .command("sync")
         .description("Update Memory Bank from git history and session artifacts")
-        .action(async () => {
+        .option("--summary <text>", "Session summary (skip prompt)")
+        .action(async (options) => {
         const progressPath = join(process.cwd(), ".context", "progress.md");
         const contextDir = join(process.cwd(), ".context");
         if (!existsSync(contextDir)) {
@@ -18,7 +19,7 @@ export function registerSyncCommand(program) {
             return;
         }
         const config = await getConfig();
-        const summary = await input({
+        const summary = options.summary ?? await input({
             message: "What did you accomplish in this session?",
         });
         const commits = getRecentCommitsRaw();

package/dist/commands/validate.cmd.d.ts

@@ -1,2 +1,9 @@
 import type { Command } from "commander";
+export interface CheckResult {
+    icon: string;
+    message: string;
+}
+export declare function checkFile(basePath: string, relativePath: string, required: boolean): CheckResult;
+export declare function checkStale(basePath: string, relativePath: string): CheckResult | null;
+export declare function checkAgentFile(basePath: string): CheckResult;
 export declare function registerValidateCommand(program: Command): void;

package/dist/commands/validate.cmd.js

@@ -4,7 +4,7 @@ import { success as themePass, warn as themeWarn, error as themeFail, heading }
 const PASS = themePass("");
 const WARN = themeWarn("");
 const FAIL = themeFail("");
-function checkFile(basePath, relativePath, required) {
+export function checkFile(basePath, relativePath, required) {
     const fullPath = join(basePath, relativePath);
     if (existsSync(fullPath)) {
         return { icon: PASS, message: `${relativePath} found` };
@@ -14,7 +14,7 @@ function checkFile(basePath, relativePath, required) {
     }
     return { icon: WARN, message: `${relativePath} missing (optional)` };
 }
-function checkStale(basePath, relativePath) {
+export function checkStale(basePath, relativePath) {
     const fullPath = join(basePath, relativePath);
     if (!existsSync(fullPath))
         return null;
@@ -28,7 +28,7 @@ function checkStale(basePath, relativePath) {
     }
     return null;
 }
-function checkAgentFile(basePath) {
+export function checkAgentFile(basePath) {
     const agentFiles = [
         "CLAUDE.md",
         "GEMINI.md",

package/dist/index.js

@@ -10,6 +10,8 @@ import { registerConfigCommand } from "./commands/config.cmd.js";
 import { registerEjectCommand } from "./commands/eject.cmd.js";
 import { registerFocusCommand } from "./commands/focus.cmd.js";
 import { registerStatusCommand } from "./commands/status.cmd.js";
+import { registerDoctorCommand } from "./commands/doctor.cmd.js";
+import { registerLintCommand } from "./commands/lint.cmd.js";
 const pkg = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf-8"));
 const program = new Command();
 program
@@ -24,6 +26,8 @@ registerConfigCommand(program);
 registerEjectCommand(program);
 registerFocusCommand(program);
 registerStatusCommand(program);
+registerDoctorCommand(program);
+registerLintCommand(program);
 // No-args: show interactive dashboard (TTY) or help (non-TTY)
 const args = process.argv.slice(2);
 if (args.length === 0 && process.stdin.isTTY) {

package/dist/tests/doctor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/doctor.test.js

@@ -0,0 +1,102 @@
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { checkContentHealth, checkGitTracking, checkStaleness } from "../commands/doctor.cmd.js";
+describe("checkContentHealth", () => {
+    const tempDir = mkdtempSync(join(tmpdir(), "tocket-doctor-content-"));
+    after(() => {
+        rmSync(tempDir, { recursive: true, force: true });
+    });
+    it("detects active focus in activeContext.md", () => {
+        mkdirSync(join(tempDir, ".context"), { recursive: true });
+        writeFileSync(join(tempDir, ".context", "activeContext.md"), "# Active Context\n\n## Current Focus\n\nWorking on feature X.\n\n## Recent Changes\n", "utf-8");
+        const results = checkContentHealth(tempDir);
+        const focusResult = results.find((r) => r.message.includes("active focus"));
+        assert.ok(focusResult);
+        assert.ok(focusResult.message.includes("active focus"));
+    });
+    it("warns when Current Focus is placeholder", () => {
+        const dir = join(tempDir, "placeholder");
+        mkdirSync(join(dir, ".context"), { recursive: true });
+        writeFileSync(join(dir, ".context", "activeContext.md"), "# Active Context\n\n## Current Focus\n\n_Describe what you're working on._\n", "utf-8");
+        const results = checkContentHealth(dir);
+        const focusResult = results.find((r) => r.message.includes("no meaningful"));
+        assert.ok(focusResult);
+    });
+    it("detects conventions in systemPatterns.md", () => {
+        writeFileSync(join(tempDir, ".context", "systemPatterns.md"), "# Patterns\n\n## Conventions\n\n- Code in English\n- ESM only\n", "utf-8");
+        const results = checkContentHealth(tempDir);
+        const patternResult = results.find((r) => r.message.includes("documented conventions"));
+        assert.ok(patternResult);
+    });
+    it("warns when systemPatterns.md has no conventions", () => {
+        const dir = join(tempDir, "empty-patterns");
+        mkdirSync(join(dir, ".context"), { recursive: true });
+        writeFileSync(join(dir, ".context", "systemPatterns.md"), "# Patterns\n\nNothing here yet.\n", "utf-8");
+        const results = checkContentHealth(dir);
+        const patternResult = results.find((r) => r.message.includes("no conventions"));
+        assert.ok(patternResult);
+    });
+    it("validates TOCKET.md contains protocol keywords", () => {
+        writeFileSync(join(tempDir, "TOCKET.md"), "# Tocket Protocol\n\nThe payload version is 2.0.\n", "utf-8");
+        const results = checkContentHealth(tempDir);
+        const tocketResult = results.find((r) => r.message.includes("protocol keywords"));
+        assert.ok(tocketResult);
+    });
+    it("checks agent config references .context/", () => {
+        writeFileSync(join(tempDir, "CLAUDE.md"), "# Claude\n\nRead `.context/` before acting.\n", "utf-8");
+        const results = checkContentHealth(tempDir);
+        const agentResult = results.find((r) => r.message.includes("CLAUDE.md references"));
+        assert.ok(agentResult);
+    });
+    it("warns when agent config does not reference .context/", () => {
+        const dir = join(tempDir, "no-ref");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "CLAUDE.md"), "# Claude\n\nJust some instructions.\n", "utf-8");
+        const results = checkContentHealth(dir);
+        const agentResult = results.find((r) => r.message.includes("does not reference"));
+        assert.ok(agentResult);
+    });
+});
+describe("checkGitTracking", () => {
+    // Use the Tocket repo itself for git tests
+    const tocketRoot = join(import.meta.dirname, "..", "..");
+    it("returns results in a git repository", () => {
+        const results = checkGitTracking(tocketRoot);
+        assert.ok(results.length > 0);
+    });
+    it("detects .context/ is not gitignored", () => {
+        const results = checkGitTracking(tocketRoot);
+        const ignoreResult = results.find((r) => r.message.includes("gitignore"));
+        assert.ok(ignoreResult);
+        assert.ok(ignoreResult.message.includes("not gitignored"));
+    });
+    it("returns warn for non-git directory", () => {
+        const tempDir = mkdtempSync(join(tmpdir(), "tocket-doctor-git-"));
+        try {
+            const results = checkGitTracking(tempDir);
+            assert.ok(results.some((r) => r.message.includes("Not a git repository")));
+        }
+        finally {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+});
+describe("checkStaleness", () => {
+    const tempDir = mkdtempSync(join(tmpdir(), "tocket-doctor-stale-"));
+    after(() => {
+        rmSync(tempDir, { recursive: true, force: true });
+    });
+    it("returns null when .context/activeContext.md does not exist", () => {
+        const result = checkStaleness(tempDir);
+        assert.equal(result, null);
+    });
+    it("returns null when file is fresh", () => {
+        mkdirSync(join(tempDir, ".context"), { recursive: true });
+        writeFileSync(join(tempDir, ".context", "activeContext.md"), "fresh", "utf-8");
+        const result = checkStaleness(tempDir);
+        assert.equal(result, null);
+    });
+});

package/dist/tests/generate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/generate.test.js

@@ -0,0 +1,67 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { buildPayloadXml } from "../commands/generate.cmd.js";
+describe("buildPayloadXml", () => {
+    const baseTask = {
+        intent: "Add input validation",
+        scope: "src/commands/sync.cmd.ts",
+        priority: "medium",
+        skills: "",
+    };
+    it("produces valid XML with version 2.0", () => {
+        const xml = buildPayloadXml([baseTask]);
+        assert.ok(xml.includes('<payload version="2.0">'));
+        assert.ok(xml.includes("</payload>"));
+    });
+    it("includes intent, scope, and priority in meta", () => {
+        const xml = buildPayloadXml([baseTask]);
+        assert.ok(xml.includes("<intent>Add input validation</intent>"));
+        assert.ok(xml.includes("<scope>src/commands/sync.cmd.ts</scope>"));
+        assert.ok(xml.includes("<priority>medium</priority>"));
+    });
+    it("omits skills tag when skills is empty", () => {
+        const xml = buildPayloadXml([baseTask]);
+        assert.ok(!xml.includes("<skills>"));
+    });
+    it("includes skills tag when skills is provided", () => {
+        const task = { ...baseTask, skills: "core,lsp" };
+        const xml = buildPayloadXml([task]);
+        assert.ok(xml.includes("<skills>core,lsp</skills>"));
+    });
+    it("generates correct task ids for multiple tasks", () => {
+        const tasks = [
+            { ...baseTask, intent: "Task one" },
+            { ...baseTask, intent: "Task two" },
+            { ...baseTask, intent: "Task three" },
+        ];
+        const xml = buildPayloadXml(tasks);
+        assert.ok(xml.includes('task id="1"'));
+        assert.ok(xml.includes('task id="2"'));
+        assert.ok(xml.includes('task id="3"'));
+    });
+    it("includes action text from each task intent", () => {
+        const tasks = [
+            { ...baseTask, intent: "First action" },
+            { ...baseTask, intent: "Second action" },
+        ];
+        const xml = buildPayloadXml(tasks);
+        assert.ok(xml.includes("<action>First action</action>"));
+        assert.ok(xml.includes("<action>Second action</action>"));
+    });
+    it("includes validate section", () => {
+        const xml = buildPayloadXml([baseTask]);
+        assert.ok(xml.includes("<validate>"));
+        assert.ok(xml.includes("<check>"));
+    });
+    it("uses first task meta for the payload-level meta", () => {
+        const tasks = [
+            { intent: "Main goal", scope: "src/", priority: "high", skills: "api" },
+            { intent: "Secondary", scope: "test/", priority: "low", skills: "" },
+        ];
+        const xml = buildPayloadXml(tasks);
+        // Meta should come from first task
+        assert.ok(xml.includes("<intent>Main goal</intent>"));
+        assert.ok(xml.includes("<scope>src/</scope>"));
+        assert.ok(xml.includes("<priority>high</priority>"));
+    });
+});

package/dist/tests/git.test.js

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { isGitRepo, getStagedFiles, getModifiedFiles, getRecentCommits, getRecentCommitsRaw, getCurrentBranch, } from "../utils/git.js";
+import { isGitRepo, getStagedFiles, getModifiedFiles, getRecentCommits, getRecentCommitsRaw, getCurrentBranch, getLastCommitMessage, } from "../utils/git.js";
 // Use the Tocket repo itself for "in git" tests
 const tocketRoot = join(import.meta.dirname, "..", "..");
 describe("git - in a git repository", () => {
@@ -33,6 +33,11 @@ describe("git - in a git repository", () => {
         const files = getModifiedFiles(tocketRoot);
         assert.ok(Array.isArray(files));
     });
+    it("getLastCommitMessage returns a non-empty string", () => {
+        const msg = getLastCommitMessage(tocketRoot);
+        assert.ok(typeof msg === "string");
+        assert.ok(msg.length > 0);
+    });
 });
 describe("git - in a non-git directory", () => {
     const tempDir = mkdtempSync(join(tmpdir(), "tocket-git-test-"));
@@ -58,4 +63,7 @@ describe("git - in a non-git directory", () => {
     it("getCurrentBranch returns empty string", () => {
         assert.equal(getCurrentBranch(tempDir), "");
     });
+    it("getLastCommitMessage returns empty string", () => {
+        assert.equal(getLastCommitMessage(tempDir), "");
+    });
 });

package/dist/tests/init.test.d.ts

@@ -0,0 +1 @@
+export {};