@trieungoctam/speckit 0.3.5 → 0.3.6

package/README.md

@@ -30,6 +30,8 @@ npx @trieungoctam/speckit@latest session checkpoint --note "red complete"
 npx @trieungoctam/speckit@latest review
 ```
 
+Interactive CLI output is colorized when the terminal supports ANSI colors. Use `NO_COLOR=1` to disable colors, or `SPECKIT_COLOR=1` to force colors for demos and snapshots.
+
 Or install globally:
 
 ```bash

package/dist/cli.js

@@ -19,6 +19,7 @@ import { runCommand } from "./commands/run.js";
 import { readyCommand } from "./commands/ready.js";
 import { reviewCommand } from "./commands/review.js";
 import { closeCommand } from "./commands/close.js";
+import { createColors } from "./core/colors.js";
 export async function main(argv = process.argv.slice(2), root = process.cwd()) {
     const parsed = parseArgs(argv);
     try {
@@ -145,7 +146,8 @@ function isHelp(parsed) {
     return parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h" || has(parsed, "help");
 }
 function printHelp() {
-    console.log(`Speckit - Agile + TDD workflow compiler for agentic IDEs
+    const colors = createColors();
+    console.log(`${colors.bold(colors.cyan("Speckit"))} - Agile + TDD workflow compiler for agentic IDEs
 
 Usage:
   speckit setup

package/dist/commands/doctor.js

@@ -6,8 +6,10 @@ import { detectTestCommands } from "../core/test-detection.js";
 import { coreFiles, enterpriseFiles } from "../core/scaffold.js";
 import { agentFiles } from "../core/agent-scaffold.js";
 import { validateWorkflowContract } from "../core/workflow-validator.js";
+import { createColors } from "../core/colors.js";
 export async function doctorCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const tools = checkTools();
     const tests = await detectTestCommands(options.root);
     const deepChecks = options.deep ? await runDeepChecks(options.root) : [];
@@ -29,24 +31,25 @@ export async function doctorCommand(options) {
         stdout.log(JSON.stringify(report, null, 2));
     }
     else {
-        stdout.log(`Speckit doctor: ${report.status}`);
-        stdout.log(`Node: ${report.node}`);
-        stdout.log(`Tools: ${tools.map((tool) => `${tool.name}=${tool.available ? "ok" : "missing"}`).join(", ")}`);
+        stdout.log(`${colors.bold("Speckit doctor")}: ${colors.status(report.status === "ok", "ok", report.status)}`);
+        stdout.log(`${colors.bold("Node")}: ${report.node}`);
+        stdout.log(`Tools: ${tools.map((tool) => `${tool.name}=${colors.status(tool.available)}`).join(", ")}`);
         for (const tool of tools.filter((tool) => !tool.available)) {
-            stdout.log(`Tool hint ${tool.name}: ${tool.hint}`);
+            stdout.log(`${colors.yellow("Tool hint")} ${tool.name}: ${tool.hint}`);
             if (tool.install?.length) {
-                stdout.log(`Install ${tool.name}: ${tool.install.join(" OR ")}`);
+                stdout.log(`${colors.cyan(`Install ${tool.name}`)}: ${tool.install.join(" OR ")}`);
             }
         }
-        stdout.log(`Tests: ${tests[0]?.command ?? "not detected"}`);
+        stdout.log(`${colors.bold("Tests")}: ${tests[0]?.command ?? colors.yellow("not detected")}`);
         for (const check of deepChecks) {
-            stdout.log(`Deep ${check.name}: ${check.ok ? "ok" : "missing"}`);
+            stdout.log(`Deep ${check.name}: ${colors.status(check.ok)}`);
         }
         for (const check of contractChecks) {
-            stdout.log(`Contract ${check.name}: ${check.ok ? "ok" : check.detail}`);
+            stdout.log(`Contract ${check.name}: ${check.ok ? colors.green("ok") : colors.red(check.detail)}`);
         }
         for (const adapter of adapters) {
-            stdout.log(`Adapter ${adapter.name}: ${adapter.present}/${adapter.total} files present`);
+            const ok = adapter.present === adapter.total;
+            stdout.log(`Adapter ${adapter.name}: ${colors.status(ok, `${adapter.present}/${adapter.total}`, `${adapter.present}/${adapter.total}`)} files present`);
         }
     }
     return report.status === "ok" ? 0 : 1;

package/dist/commands/graph.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { beadsViewerInstallGuide, checkTools, commandExists } from "../adapters/tool-checks.js";
 import { prepareBeadsMirror } from "../core/beads-mirror.js";
+import { createColors } from "../core/colors.js";
 import { readSyncedStories, selectableStories } from "../core/synced-stories.js";
 const robotActions = new Map([
     ["triage", "--robot-triage"],
@@ -37,6 +38,7 @@ export async function graphCommand(options) {
 }
 async function graphSetup(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const tools = checkTools().filter((tool) => ["br", "bd", "bv"].includes(tool.name));
     const mirrorPath = await prepareBeadsMirror(options.root);
     const report = {
@@ -51,9 +53,9 @@ async function graphSetup(options) {
     else {
         stdout.log(beadsViewerInstallGuide());
         stdout.log("");
-        stdout.log(`Mirror: ${mirrorPath}`);
+        stdout.log(`${colors.bold("Mirror")}: ${colors.cyan(mirrorPath)}`);
         for (const tool of tools) {
-            stdout.log(`${tool.name}: ${tool.available ? "ok" : "missing"} - ${tool.hint}`);
+            stdout.log(`${colors.bold(tool.name)}: ${colors.status(tool.available)} - ${colors.dim(tool.hint)}`);
         }
     }
     return 0;

package/dist/commands/init.js

@@ -2,8 +2,10 @@ import { coreFiles, enterpriseFiles } from "../core/scaffold.js";
 import { agentFiles } from "../core/agent-scaffold.js";
 import { writeManagedFiles } from "../core/managed-files.js";
 import { getAdapters } from "../config/adapter-registry.js";
+import { createColors } from "../core/colors.js";
 export async function initCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const selectedIde = options.ide ?? "all";
     const sharedFiles = [...coreFiles(), ...agentFiles()];
     const baseFiles = options.enterprise ? [...sharedFiles, ...enterpriseFiles()] : sharedFiles;
@@ -13,9 +15,9 @@ export async function initCommand(options) {
     const updated = results.filter((result) => result.status === "updated").length;
     const skipped = results.filter((result) => result.status === "skipped");
     const mode = options.enterprise ? "enterprise" : "standard";
-    stdout.log(`Speckit initialized (${mode}): ${created} created, ${updated} updated, ${skipped.length} skipped.`);
+    stdout.log(`${colors.bold("Speckit initialized")} (${colors.cyan(mode)}): ${colors.green(String(created))} created, ${colors.yellow(String(updated))} updated, ${colors.status(skipped.length === 0, String(skipped.length), String(skipped.length))} skipped.`);
     for (const result of skipped) {
-        stdout.log(`skipped ${result.path}: ${result.reason}`);
+        stdout.log(`${colors.yellow("skipped")} ${result.path}: ${result.reason}`);
     }
     return skipped.length > 0 ? 2 : 0;
 }

package/dist/commands/ready.js

@@ -1,20 +1,22 @@
 import { evaluateReadiness } from "../core/readiness.js";
+import { createColors } from "../core/colors.js";
 export async function readyCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const report = await evaluateReadiness(options.root, options.target);
     if (options.json) {
         stdout.log(JSON.stringify(report, null, 2));
         return report.status === "ready" ? 0 : 1;
     }
-    stdout.log(`# Speckit Readiness: ${report.status}`);
+    stdout.log(`# ${colors.bold("Speckit Readiness")}: ${colors.status(report.status === "ready", "ready", report.status)}`);
     if (report.story) {
-        stdout.log(`Story: ${report.story.path}`);
+        stdout.log(`${colors.bold("Story")}: ${colors.cyan(report.story.path)}`);
     }
     for (const check of report.checks) {
-        stdout.log(`- ${check.ok ? "ok" : "blocked"} ${check.name}: ${check.detail}`);
+        stdout.log(`- ${colors.status(check.ok, "ok", "blocked")} ${check.name}: ${check.detail}`);
     }
     if (report.status !== "ready") {
-        stdout.error("Run the suggested setup commands before `speckit run`.");
+        stdout.error(colors.yellow("Run the suggested setup commands before `speckit run`."));
     }
     return report.status === "ready" ? 0 : 1;
 }

package/dist/commands/setup.js

@@ -1,5 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import { adapters } from "../config/adapter-registry.js";
+import { createColors } from "../core/colors.js";
 import { graphCommand } from "./graph.js";
 import { initCommand } from "./init.js";
 const modeChoices = [
@@ -17,6 +18,7 @@ export async function setupCommand(options) {
     const stdin = options.stdin ?? process.stdin;
     const output = options.output ?? process.stdout;
     const stdout = options.stdout ?? console;
+    const colors = createColors(output);
     if (options.answers) {
         return setupFromAnswers(options, stdout, options.answers);
     }
@@ -26,14 +28,14 @@ export async function setupCommand(options) {
     }
     const rl = createInterface({ input: stdin, output });
     try {
-        stdout.log("Speckit setup");
+        stdout.log(colors.bold(colors.cyan("Speckit setup")));
         stdout.log("");
-        const mode = await select(rl, stdout, modeChoices, "Choose setup mode", "1");
-        const ide = await select(rl, stdout, ideChoices, "Choose IDE adapter", "1");
-        const force = await confirm(rl, stdout, "Overwrite unmanaged files if needed?", false);
-        const configureGraph = await confirm(rl, stdout, "Run Beads Viewer setup after init?", true);
+        const mode = await select(rl, stdout, modeChoices, "Choose setup mode", "1", colors);
+        const ide = await select(rl, stdout, ideChoices, "Choose IDE adapter", "1", colors);
+        const force = await confirm(rl, stdout, "Overwrite unmanaged files if needed?", false, colors);
+        const configureGraph = await confirm(rl, stdout, "Run Beads Viewer setup after init?", true, colors);
         stdout.log("");
-        stdout.log(`Selected: ${mode}, ide=${ide}, force=${force ? "yes" : "no"}, graph=${configureGraph ? "yes" : "no"}`);
+        stdout.log(colors.dim(`Selected: ${mode}, ide=${ide}, force=${force ? "yes" : "no"}, graph=${configureGraph ? "yes" : "no"}`));
         stdout.log("");
         const initExit = await initCommand({
             root: options.root,
@@ -53,14 +55,15 @@ export async function setupCommand(options) {
     }
 }
 async function setupFromAnswers(options, stdout, answers) {
-    stdout.log("Speckit setup");
+    const colors = createColors();
+    stdout.log(colors.bold(colors.cyan("Speckit setup")));
     stdout.log("");
-    const mode = selectAnswer(stdout, modeChoices, "Choose setup mode", "1", answers.shift());
-    const ide = selectAnswer(stdout, ideChoices, "Choose IDE adapter", "1", answers.shift());
+    const mode = selectAnswer(stdout, modeChoices, "Choose setup mode", "1", answers.shift(), colors);
+    const ide = selectAnswer(stdout, ideChoices, "Choose IDE adapter", "1", answers.shift(), colors);
     const force = confirmAnswer("Overwrite unmanaged files if needed?", false, answers.shift());
     const configureGraph = confirmAnswer("Run Beads Viewer setup after init?", true, answers.shift());
     stdout.log("");
-    stdout.log(`Selected: ${mode}, ide=${ide}, force=${force ? "yes" : "no"}, graph=${configureGraph ? "yes" : "no"}`);
+    stdout.log(colors.dim(`Selected: ${mode}, ide=${ide}, force=${force ? "yes" : "no"}, graph=${configureGraph ? "yes" : "no"}`));
     stdout.log("");
     const initExit = await initCommand({
         root: options.root,
@@ -75,9 +78,9 @@ async function setupFromAnswers(options, stdout, answers) {
     }
     return initExit;
 }
-function selectAnswer(stdout, choices, prompt, defaultValue, answer) {
-    stdout.log(prompt);
-    choices.forEach((choice, index) => stdout.log(`  ${index + 1}. ${choice.label}`));
+function selectAnswer(stdout, choices, prompt, defaultValue, answer, colors = createColors()) {
+    stdout.log(colors.bold(prompt));
+    choices.forEach((choice, index) => stdout.log(`  ${colors.cyan(String(index + 1))}. ${choice.label}`));
     const selected = (answer?.trim() || defaultValue);
     const index = Number.parseInt(selected, 10) - 1;
     if (!Number.isInteger(index) || !choices[index]) {
@@ -96,33 +99,33 @@ function confirmAnswer(prompt, defaultValue, answer) {
         return false;
     throw new Error(`Invalid yes/no answer for "${prompt}": ${answer}`);
 }
-async function select(rl, stdout, choices, prompt, defaultValue) {
+async function select(rl, stdout, choices, prompt, defaultValue, colors = createColors()) {
     for (;;) {
-        stdout.log(prompt);
+        stdout.log(colors.bold(prompt));
         choices.forEach((choice, index) => {
             const number = String(index + 1);
-            stdout.log(`  ${number}. ${choice.label}`);
+            stdout.log(`  ${colors.cyan(number)}. ${choice.label}`);
         });
-        const answer = (await rl.question(`Select [${defaultValue}]: `)).trim() || defaultValue;
+        const answer = (await rl.question(`${colors.dim("Select")} [${colors.cyan(defaultValue)}]: `)).trim() || defaultValue;
         const index = Number.parseInt(answer, 10) - 1;
         if (Number.isInteger(index) && choices[index]) {
             stdout.log("");
             return choices[index].value;
         }
-        stdout.log(`Invalid selection: ${answer}`);
+        stdout.log(colors.red(`Invalid selection: ${answer}`));
         stdout.log("");
     }
 }
-async function confirm(rl, stdout, prompt, defaultValue) {
+async function confirm(rl, stdout, prompt, defaultValue, colors = createColors()) {
     const suffix = defaultValue ? "Y/n" : "y/N";
     for (;;) {
-        const answer = (await rl.question(`${prompt} [${suffix}]: `)).trim().toLowerCase();
+        const answer = (await rl.question(`${prompt} [${colors.cyan(suffix)}]: `)).trim().toLowerCase();
         if (!answer)
             return defaultValue;
         if (["y", "yes"].includes(answer))
             return true;
         if (["n", "no"].includes(answer))
             return false;
-        stdout.log("Please answer y or n.");
+        stdout.log(colors.yellow("Please answer y or n."));
     }
 }

package/dist/commands/sync.js

@@ -3,8 +3,10 @@ import { join } from "node:path";
 import { markdown, writeManagedFiles } from "../core/managed-files.js";
 import { firstHeading, frontmatterValue } from "../core/story.js";
 import { writeBeadsMirror } from "../core/beads-mirror.js";
+import { createColors } from "../core/colors.js";
 export async function syncCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const storiesDir = join(options.root, ".speckit", "stories");
     let entries;
     try {
@@ -45,7 +47,7 @@ bv --robot-next --format json
         },
     ], true);
     const beadsPath = await writeBeadsMirror(options.root, stories);
-    stdout.log(`Synced ${stories.length} stories to .speckit/sync/beads-sync.jsonl`);
-    stdout.log(`Prepared Beads Viewer mirror at ${beadsPath}`);
+    stdout.log(`Synced ${colors.cyan(String(stories.length))} stories to ${colors.cyan(".speckit/sync/beads-sync.jsonl")}`);
+    stdout.log(`Prepared Beads Viewer mirror at ${colors.cyan(beadsPath)}`);
     return 0;
 }

package/dist/commands/validate.js

@@ -1,6 +1,8 @@
 import { validateWorkflowContract } from "../core/workflow-validator.js";
+import { createColors } from "../core/colors.js";
 export async function validateCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const checks = await validateWorkflowContract(options.root);
     const status = checks.every((check) => check.ok) ? "ok" : "needs-attention";
     const report = { status, checks };
@@ -8,9 +10,9 @@ export async function validateCommand(options) {
         stdout.log(JSON.stringify(report, null, 2));
     }
     else {
-        stdout.log(`Speckit workflow contract: ${status}`);
+        stdout.log(`${colors.bold("Speckit workflow contract")}: ${colors.status(status === "ok", "ok", status)}`);
         for (const check of checks) {
-            stdout.log(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}`);
+            stdout.log(`${colors.status(check.ok, "ok", "fail")} ${check.name}: ${check.detail}`);
         }
     }
     return status === "ok" ? 0 : 1;

package/dist/core/colors.d.ts

@@ -0,0 +1,11 @@
+type ColorOutput = {
+    isTTY?: boolean;
+};
+type ColorName = "blue" | "cyan" | "dim" | "green" | "red" | "yellow" | "bold";
+export type Colors = Record<ColorName, (text: string) => string> & {
+    enabled: boolean;
+    status(ok: boolean, okText?: string, failText?: string): string;
+};
+export declare function createColors(output?: ColorOutput): Colors;
+export declare function colorsEnabled(output?: ColorOutput): boolean;
+export {};

package/dist/core/colors.js

@@ -0,0 +1,40 @@
+const ansi = {
+    blue: [34, 39],
+    cyan: [36, 39],
+    dim: [2, 22],
+    green: [32, 39],
+    red: [31, 39],
+    yellow: [33, 39],
+    bold: [1, 22],
+};
+export function createColors(output) {
+    const enabled = colorsEnabled(output);
+    const style = (name) => (text) => {
+        if (!enabled)
+            return text;
+        const [open, close] = ansi[name];
+        return `\u001B[${open}m${text}\u001B[${close}m`;
+    };
+    return {
+        enabled,
+        blue: style("blue"),
+        cyan: style("cyan"),
+        dim: style("dim"),
+        green: style("green"),
+        red: style("red"),
+        yellow: style("yellow"),
+        bold: style("bold"),
+        status(ok, okText = "ok", failText = "missing") {
+            return ok ? this.green(okText) : this.red(failText);
+        },
+    };
+}
+export function colorsEnabled(output) {
+    if (process.env.NO_COLOR || process.env.SPECKIT_COLOR === "0")
+        return false;
+    if (process.env.FORCE_COLOR === "0")
+        return false;
+    if (process.env.FORCE_COLOR || process.env.SPECKIT_COLOR === "1")
+        return true;
+    return output?.isTTY ?? process.stdout.isTTY ?? false;
+}

package/docs/project-changelog.md

@@ -1,5 +1,17 @@
 # Project Changelog
 
+## 0.3.6 - 2026-05-11
+
+### Added
+
+- Added ANSI color rendering for interactive CLI and TUI output, including setup prompts, init summaries, doctor checks, graph setup, readiness, validation, sync, and help headers.
+- Added `SPECKIT_COLOR=1` / `FORCE_COLOR` support for demos and snapshots, with `NO_COLOR` / `SPECKIT_COLOR=0` opt-out support.
+
+### Quality
+
+- Added color helper regression tests.
+- JSON output remains uncolored for automation.
+
 ## 0.3.5 - 2026-05-11
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trieungoctam/speckit",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Enterprise Agile + TDD workflow compiler for agentic IDEs.",
   "type": "module",
   "files": [