@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/cli/output.js

@@ -1,15 +1,90 @@
-import chalk from 'chalk';
-import { grepItem, formatMatchedFields } from '../utils/grep.js';
-import { fieldLabels, sectionHeaders, summaries } from '../strings/labels.js';
+import chalk from "chalk";
+import { stringify as yamlStringify } from "yaml";
+import { fieldLabels, sectionHeaders, summaries } from "../strings/labels.js";
+import { formatMatchedFields, grepItem } from "../utils/grep.js";
 /**
- * Global output format (set by --json flag)
+ * Check if a note has been superseded by another note.
+ * A note is superseded if its ULID appears in any other note's `supersedes` field.
+ */
+export function isNoteSuperseded(note, allNotes) {
+    return allNotes.some((n) => n.supersedes === note._ulid);
+}
+/**
+ * Filter notes to exclude superseded ones.
+ * Returns only notes that have not been superseded.
+ */
+export function filterSupersededNotes(notes) {
+    return notes.filter((note) => !isNoteSuperseded(note, notes));
+}
+/**
+ * Annotate notes with superseded status for JSON output.
+ * Adds a computed `superseded` field to each note.
+ */
+export function annotateNotesWithSuperseded(notes) {
+    return notes.map((note) => ({
+        ...note,
+        superseded: isNoteSuperseded(note, notes),
+    }));
+}
+/**
+ * Valid format values for --format option
+ */
+export const VALID_FORMATS = ["json", "yaml"];
+/**
+ * Global output format (set by --json, --yaml, --raw, or --format flags)
+ * AC: @output-format-option ac-format-json, ac-format-yaml
+ */
+let globalOutputFormat = "text";
+export function setOutputFormat(format) {
+    globalOutputFormat = format;
+}
+export function getOutputFormat() {
+    return globalOutputFormat;
+}
+/**
+ * Set JSON mode (for backward compatibility)
+ * AC: @output-format-option ac-json-shorthand
  */
-let globalJsonMode = false;
 export function setJsonMode(enabled) {
-    globalJsonMode = enabled;
+    if (enabled) {
+        globalOutputFormat = "json";
+    }
+    else if (globalOutputFormat === "json") {
+        globalOutputFormat = "text";
+    }
 }
+/**
+ * Check if JSON mode is active
+ * AC: @output-format-option ac-json-shorthand
+ */
 export function isJsonMode() {
-    return globalJsonMode;
+    return globalOutputFormat === "json";
+}
+/**
+ * Set YAML mode
+ * AC: @output-format-option ac-format-yaml, ac-yaml-shorthand
+ */
+export function setYamlMode(enabled) {
+    if (enabled) {
+        globalOutputFormat = "yaml";
+    }
+    else if (globalOutputFormat === "yaml") {
+        globalOutputFormat = "text";
+    }
+}
+/**
+ * Check if YAML mode is active
+ * AC: @output-format-option ac-format-yaml
+ */
+export function isYamlMode() {
+    return globalOutputFormat === "yaml";
+}
+/**
+ * Check if any structured output mode is active (JSON or YAML)
+ * AC: @output-format-option ac-yaml-no-ansi, ac-yaml-references
+ */
+export function isStructuredMode() {
+    return globalOutputFormat === "json" || globalOutputFormat === "yaml";
 }
 /**
  * Global verbose mode (set by --verbose flag)
@@ -22,12 +97,16 @@ export function getVerboseMode() {
     return globalVerboseMode;
 }
 /**
- * Output data - JSON if --json flag, otherwise formatted
+ * Output data - JSON/YAML if structured mode, otherwise formatted
+ * AC: @output-format-option ac-format-json, ac-format-yaml
  */
 export function output(data, formatter) {
-    if (globalJsonMode) {
+    if (globalOutputFormat === "json") {
         console.log(JSON.stringify(data, null, 2));
     }
+    else if (globalOutputFormat === "yaml") {
+        console.log(yamlStringify(data, { indent: 2 }));
+    }
     else if (formatter) {
         formatter();
     }
@@ -37,31 +116,39 @@ export function output(data, formatter) {
 }
 /**
  * Output success message
+ * AC: @output-format-option ac-format-json, ac-format-yaml
  */
 export function success(message, data) {
-    if (globalJsonMode) {
+    if (globalOutputFormat === "json") {
         console.log(JSON.stringify({ success: true, message, ...data }));
     }
+    else if (globalOutputFormat === "yaml") {
+        console.log(yamlStringify({ success: true, message, ...data }, { indent: 2 }));
+    }
     else {
-        console.log(chalk.green('OK'), message);
+        console.log(chalk.green("OK"), message);
     }
 }
 /**
  * Output error message
+ * AC: @output-format-option ac-format-json, ac-format-yaml
  */
 export function error(message, details) {
-    if (globalJsonMode) {
+    if (globalOutputFormat === "json") {
         console.error(JSON.stringify({ success: false, error: message, details }));
     }
+    else if (globalOutputFormat === "yaml") {
+        console.error(yamlStringify({ success: false, error: message, details }, { indent: 2 }));
+    }
     else {
-        console.error(chalk.red('✗'), message);
+        console.error(chalk.red("✗"), message);
         if (details) {
             console.error(chalk.gray(String(details)));
             // Show suggestion if it's a ShadowError with a suggestion
-            if (details && typeof details === 'object' && 'suggestion' in details) {
+            if (details && typeof details === "object" && "suggestion" in details) {
                 const suggestion = details.suggestion;
                 if (suggestion) {
-                    console.error(chalk.yellow('  Suggestion:'), suggestion);
+                    console.error(chalk.yellow("  Suggestion:"), suggestion);
                 }
             }
         }
@@ -69,24 +156,28 @@ export function error(message, details) {
 }
 /**
  * Output warning message
+ * AC: @output-format-option ac-yaml-no-ansi
  */
 export function warn(message) {
-    if (globalJsonMode) {
-        // Warnings are suppressed in JSON mode
+    if (isStructuredMode()) {
+        // Route warnings to stderr in structured output modes to keep stdout pure
+        console.error(chalk.yellow("⚠"), message);
     }
     else {
-        console.warn(chalk.yellow('⚠'), message);
+        console.warn(chalk.yellow("⚠"), message);
     }
 }
 /**
  * Output info message
+ * AC: @output-format-option ac-yaml-no-ansi
  */
 export function info(message) {
-    if (globalJsonMode) {
-        // Info messages suppressed in JSON mode
+    if (isStructuredMode()) {
+        // Route info to stderr in structured output modes to keep stdout pure
+        console.error(chalk.blue("ℹ"), message);
     }
     else {
-        console.log(chalk.blue('ℹ'), message);
+        console.log(chalk.blue("ℹ"), message);
     }
 }
 /**
@@ -94,15 +185,15 @@ export function info(message) {
  */
 function statusColor(status) {
     switch (status) {
-        case 'pending':
+        case "pending":
             return (t) => chalk.gray(t);
-        case 'in_progress':
+        case "in_progress":
             return (t) => chalk.blue(t);
-        case 'blocked':
+        case "blocked":
             return (t) => chalk.red(t);
-        case 'completed':
+        case "completed":
             return (t) => chalk.green(t);
-        case 'cancelled':
+        case "cancelled":
             return (t) => chalk.strikethrough.gray(t);
         default:
             return (t) => chalk.white(t);
@@ -126,18 +217,20 @@ export function formatTaskRef(task, index) {
 export function formatTask(task, verbose = false, index, full = false) {
     const ref = formatTaskRef(task, index);
     const status = statusColor(task.status)(`[${task.status}]`);
-    const priority = task.priority <= 2 ? chalk.red(`P${task.priority}`) : chalk.gray(`P${task.priority}`);
+    const priority = task.priority <= 2
+        ? chalk.red(`P${task.priority}`)
+        : chalk.gray(`P${task.priority}`);
     let line = `${ref} ${status} ${priority} ${task.title}`;
     if (verbose && !full) {
-        // AC-2: Single verbose (-v) shows current behavior
+        // AC: @task-list-verbose ac-2 - Single verbose (-v) shows current behavior
         if (task.spec_ref) {
             line += chalk.gray(` (spec: ${task.spec_ref})`);
         }
         if (task.depends_on.length > 0) {
-            line += chalk.gray(` deps: [${task.depends_on.join(', ')}]`);
+            line += chalk.gray(` deps: [${task.depends_on.join(", ")}]`);
         }
         if (task.tags.length > 0) {
-            line += chalk.cyan(` #${task.tags.join(' #')}`);
+            line += chalk.cyan(` #${task.tags.join(" #")}`);
         }
     }
     return line;
@@ -148,16 +241,16 @@ export function formatTask(task, verbose = false, index, full = false) {
 function getFirstLine(text, maxLength = 70) {
     if (!text)
         return undefined;
-    const firstLine = text.split('\n')[0].trim();
+    const firstLine = text.split("\n")[0].trim();
     if (firstLine.length <= maxLength)
         return firstLine;
-    return firstLine.slice(0, maxLength - 3) + '...';
+    return `${firstLine.slice(0, maxLength - 3)}...`;
 }
 /**
  * Format full mode context for a task (AC-1, AC-3, AC-5)
  */
 function formatFullModeContext(task, index) {
-    const indent = '    ';
+    const indent = "    ";
     // Show timestamps (AC-1)
     console.log(chalk.gray(`${indent}Created: ${task.created_at}`));
     if (task.started_at) {
@@ -174,7 +267,7 @@ function formatFullModeContext(task, index) {
     }
     // Show pending todos count (AC-1, AC-3)
     if (task.todos && task.todos.length > 0) {
-        const pendingCount = task.todos.filter(t => !t.done).length;
+        const pendingCount = task.todos.filter((t) => !t.done).length;
         if (pendingCount > 0) {
             console.log(chalk.gray(`${indent}Pending todos: ${pendingCount}`));
         }
@@ -184,22 +277,31 @@ function formatFullModeContext(task, index) {
         const result = index.resolve(task.spec_ref);
         if (result.ok) {
             const spec = result.item;
-            const specName = 'title' in spec ? spec.title : ('name' in spec ? spec.name : ('id' in spec ? spec.id : task.spec_ref));
+            const specName = "title" in spec
+                ? spec.title
+                : "name" in spec
+                    ? spec.name
+                    : "id" in spec
+                        ? spec.id
+                        : task.spec_ref;
             console.log(chalk.gray(`${indent}Spec: ${task.spec_ref}`));
             console.log(chalk.cyan(`${indent}  ${specName}`));
             // Show spec description if available
-            if ('description' in spec && spec.description) {
+            if ("description" in spec && spec.description) {
                 const descPreview = getFirstLine(spec.description, 70);
                 console.log(chalk.gray(`${indent}  ${descPreview}`));
             }
             // Show acceptance criteria if available
-            if ('acceptance_criteria' in spec && Array.isArray(spec.acceptance_criteria)) {
+            if ("acceptance_criteria" in spec &&
+                Array.isArray(spec.acceptance_criteria)) {
                 const ac = spec.acceptance_criteria;
                 if (ac.length > 0) {
                     console.log(chalk.gray(`${indent}  Acceptance Criteria: ${ac.length}`));
                     // Show first AC as preview
                     const firstAC = ac[0];
-                    if (typeof firstAC === 'object' && firstAC !== null && 'id' in firstAC) {
+                    if (typeof firstAC === "object" &&
+                        firstAC !== null &&
+                        "id" in firstAC) {
                         console.log(chalk.gray(`${indent}    [${firstAC.id}] ${firstAC.then}`));
                     }
                 }
@@ -208,10 +310,10 @@ function formatFullModeContext(task, index) {
     }
     // Show tags and dependencies if present
     if (task.tags && task.tags.length > 0) {
-        console.log(chalk.gray(`${indent}Tags: ${task.tags.join(', ')}`));
+        console.log(chalk.gray(`${indent}Tags: ${task.tags.join(", ")}`));
     }
     if (task.depends_on && task.depends_on.length > 0) {
-        console.log(chalk.gray(`${indent}Depends on: ${task.depends_on.join(', ')}`));
+        console.log(chalk.gray(`${indent}Depends on: ${task.depends_on.join(", ")}`));
     }
 }
 /**
@@ -220,15 +322,15 @@ function formatFullModeContext(task, index) {
  */
 function formatAutomationStatus(automation) {
     if (!automation) {
-        return chalk.gray('[unassessed]');
+        return chalk.gray("[unassessed]");
     }
     switch (automation) {
-        case 'eligible':
-            return chalk.green('[eligible]');
-        case 'needs_review':
-            return chalk.yellow('[needs_review]');
-        case 'manual_only':
-            return chalk.red('[manual_only]');
+        case "eligible":
+            return chalk.green("[eligible]");
+        case "needs_review":
+            return chalk.yellow("[needs_review]");
+        case "manual_only":
+            return chalk.red("[manual_only]");
         default:
             return chalk.gray(`[${automation}]`);
     }
@@ -245,7 +347,9 @@ export function formatTaskListWithAutomation(tasks, verbose = false, index, grep
     for (const task of tasks) {
         const ref = formatTaskRef(task, index);
         const status = statusColor(task.status)(`[${task.status}]`);
-        const priority = task.priority <= 2 ? chalk.red(`P${task.priority}`) : chalk.gray(`P${task.priority}`);
+        const priority = task.priority <= 2
+            ? chalk.red(`P${task.priority}`)
+            : chalk.gray(`P${task.priority}`);
         const automationLabel = formatAutomationStatus(task.automation);
         let line = `${ref} ${status} ${priority} ${automationLabel} ${task.title}`;
         if (verbose && !full) {
@@ -253,10 +357,10 @@ export function formatTaskListWithAutomation(tasks, verbose = false, index, grep
                 line += chalk.gray(` (spec: ${task.spec_ref})`);
             }
             if (task.depends_on.length > 0) {
-                line += chalk.gray(` deps: [${task.depends_on.join(', ')}]`);
+                line += chalk.gray(` deps: [${task.depends_on.join(", ")}]`);
             }
             if (task.tags.length > 0) {
-                line += chalk.cyan(` #${task.tags.join(' #')}`);
+                line += chalk.cyan(` #${task.tags.join(" #")}`);
             }
         }
         console.log(line);
@@ -298,7 +402,7 @@ export function formatTaskList(tasks, verbose = false, index, grepPattern, full
             }
         }
         else if (full) {
-            // AC-1: Full mode shows richer context
+            // AC: @task-list-verbose ac-1 - Full mode shows richer context
             formatFullModeContext(task, index);
         }
         else {
@@ -314,26 +418,40 @@ export function formatTaskList(tasks, verbose = false, index, grepPattern, full
 /**
  * Format task details
  */
-export function formatTaskDetails(task, index) {
+export function formatTaskDetails(task, index, options = {}) {
     console.log(chalk.bold(task.title));
-    console.log(chalk.gray('─'.repeat(40)));
+    console.log(chalk.gray("─".repeat(40)));
     console.log(`${fieldLabels.ulid}      ${task._ulid}`);
     if (task.slugs.length > 0) {
-        console.log(`${fieldLabels.slugs}     ${task.slugs.join(', ')}`);
+        console.log(`${fieldLabels.slugs}     ${task.slugs.join(", ")}`);
     }
     console.log(`${fieldLabels.type}      ${task.type}`);
     console.log(`${fieldLabels.status}    ${statusColor(task.status)(task.status)}`);
     console.log(`${fieldLabels.priority}  ${task.priority}`);
     // AC: @task-automation-eligibility ac-17 - show automation status
-    const automationDisplay = task.automation || 'unassessed';
-    const automationColor = task.automation === 'eligible' ? chalk.green
-        : task.automation === 'needs_review' ? chalk.yellow
-            : task.automation === 'manual_only' ? chalk.red
+    const automationDisplay = task.automation || "unassessed";
+    const automationColor = task.automation === "eligible"
+        ? chalk.green
+        : task.automation === "needs_review"
+            ? chalk.yellow
+            : task.automation === "manual_only"
+                ? chalk.red
                 : chalk.gray;
     console.log(`${fieldLabels.automation} ${automationColor(automationDisplay)}`);
+    if (task.description?.trim()) {
+        console.log(`\n${sectionHeaders.description}`);
+        const desc = task.description.trim();
+        for (const line of desc.split("\n")) {
+            console.log(`  ${line}`);
+        }
+    }
     if (task.spec_ref) {
         console.log(`${fieldLabels.specRef}  ${task.spec_ref}`);
     }
+    // AC: @plan-derive ac-6 - display plan_ref
+    if (task.plan_ref) {
+        console.log(`Plan ref:  ${task.plan_ref}`);
+    }
     if (task.depends_on.length > 0) {
         if (index) {
             console.log(fieldLabels.depends);
@@ -341,27 +459,33 @@ export function formatTaskDetails(task, index) {
                 const result = index.resolve(ref);
                 if (result.ok) {
                     const item = result.item;
-                    const status = 'status' in item && typeof item.status === 'string'
+                    const status = "status" in item && typeof item.status === "string"
                         ? statusColor(item.status)(`[${item.status}]`)
-                        : chalk.gray('[spec]');
+                        : chalk.gray("[spec]");
                     // Handle both spec items (with title) and meta items (with name or id)
-                    const itemName = 'title' in item ? item.title : ('name' in item ? item.name : ('id' in item ? item.id : ref));
-                    console.log(`  ${ref} ${chalk.gray('→')} ${itemName} ${status}`);
+                    const itemName = "title" in item
+                        ? item.title
+                        : "name" in item
+                            ? item.name
+                            : "id" in item
+                                ? item.id
+                                : ref;
+                    console.log(`  ${ref} ${chalk.gray("→")} ${itemName} ${status}`);
                 }
                 else {
-                    console.log(`  ${ref} ${chalk.red('(unresolved)')}`);
+                    console.log(`  ${ref} ${chalk.red("(unresolved)")}`);
                 }
             }
         }
         else {
-            console.log(`${fieldLabels.depends}   ${task.depends_on.join(', ')}`);
+            console.log(`${fieldLabels.depends}   ${task.depends_on.join(", ")}`);
         }
     }
     if (task.blocked_by.length > 0) {
-        console.log(chalk.red(`${fieldLabels.blocked}   ${task.blocked_by.join(', ')}`));
+        console.log(chalk.red(`${fieldLabels.blocked}   ${task.blocked_by.join(", ")}`));
     }
     if (task.tags.length > 0) {
-        console.log(`${fieldLabels.tags}      ${task.tags.join(', ')}`);
+        console.log(`${fieldLabels.tags}      ${task.tags.join(", ")}`);
     }
     console.log(`${fieldLabels.created}   ${task.created_at}`);
     if (task.started_at) {
@@ -377,34 +501,46 @@ export function formatTaskDetails(task, index) {
             const spec = result.item;
             console.log(`\n${sectionHeaders.specContext}`);
             // Handle both spec items (with title) and meta items (with name)
-            const specName = 'title' in spec ? spec.title : ('name' in spec ? spec.name : ('id' in spec ? spec.id : task.spec_ref));
+            const specName = "title" in spec
+                ? spec.title
+                : "name" in spec
+                    ? spec.name
+                    : "id" in spec
+                        ? spec.id
+                        : task.spec_ref;
             console.log(chalk.cyan(specName));
-            if ('type' in spec && spec.type) {
+            if ("type" in spec && spec.type) {
                 console.log(chalk.gray(`${fieldLabels.type} ${spec.type}`));
             }
             // Show implementation status
-            if ('status' in spec && spec.status && typeof spec.status === 'object') {
+            if ("status" in spec && spec.status && typeof spec.status === "object") {
                 const status = spec.status;
                 if (status.implementation) {
-                    const implColor = status.implementation === 'verified' ? chalk.green
-                        : status.implementation === 'implemented' ? chalk.cyan
-                            : status.implementation === 'in_progress' ? chalk.yellow
+                    const implColor = status.implementation === "verified"
+                        ? chalk.green
+                        : status.implementation === "implemented"
+                            ? chalk.cyan
+                            : status.implementation === "in_progress"
+                                ? chalk.yellow
                                 : chalk.gray;
-                    console.log(chalk.gray(fieldLabels.implementation) + implColor(status.implementation));
+                    console.log(chalk.gray(fieldLabels.implementation) +
+                        implColor(status.implementation));
                 }
             }
-            if ('description' in spec && spec.description) {
+            if ("description" in spec && spec.description) {
                 console.log(chalk.gray(fieldLabels.description));
                 // Indent description lines
                 const desc = String(spec.description).trim();
-                for (const line of desc.split('\n')) {
+                for (const line of desc.split("\n")) {
                     console.log(chalk.gray(`  ${line}`));
                 }
             }
-            if ('acceptance_criteria' in spec && Array.isArray(spec.acceptance_criteria) && spec.acceptance_criteria.length > 0) {
+            if ("acceptance_criteria" in spec &&
+                Array.isArray(spec.acceptance_criteria) &&
+                spec.acceptance_criteria.length > 0) {
                 console.log(chalk.gray(fieldLabels.acceptanceCriteria));
                 for (const ac of spec.acceptance_criteria) {
-                    if (ac && typeof ac === 'object' && 'id' in ac) {
+                    if (ac && typeof ac === "object" && "id" in ac) {
                         const acObj = ac;
                         console.log(chalk.gray(`  [${acObj.id}]`));
                         if (acObj.given)
@@ -417,9 +553,14 @@ export function formatTaskDetails(task, index) {
                 }
             }
             // Show traceability if present
-            if ('traceability' in spec && spec.traceability && typeof spec.traceability === 'object') {
+            if ("traceability" in spec &&
+                spec.traceability &&
+                typeof spec.traceability === "object") {
                 const trace = spec.traceability;
-                const hasTrace = trace.implementation?.length || trace.tests?.length || trace.commits?.length || trace.issues?.length;
+                const hasTrace = trace.implementation?.length ||
+                    trace.tests?.length ||
+                    trace.commits?.length ||
+                    trace.issues?.length;
                 if (hasTrace) {
                     console.log(chalk.gray(fieldLabels.traceability));
                     if (trace.implementation?.length) {
@@ -438,27 +579,38 @@ export function formatTaskDetails(task, index) {
                         }
                     }
                     if (trace.commits?.length) {
-                        console.log(chalk.gray(`  Commits: ${trace.commits.join(', ')}`));
+                        console.log(chalk.gray(`  Commits: ${trace.commits.join(", ")}`));
                     }
                     if (trace.issues?.length) {
-                        console.log(chalk.gray(`  Issues: ${trace.issues.join(', ')}`));
+                        console.log(chalk.gray(`  Issues: ${trace.issues.join(", ")}`));
                     }
                 }
             }
         }
     }
     if (task.notes.length > 0) {
+        // Filter superseded notes unless showAllNotes is true
+        const notesToShow = options.showAllNotes
+            ? task.notes
+            : filterSupersededNotes(task.notes);
+        const hiddenCount = task.notes.length - notesToShow.length;
         console.log(`\n${sectionHeaders.notes}`);
-        for (const note of task.notes) {
-            const author = note.author || 'unknown';
-            console.log(chalk.gray(`[${note.created_at}] ${author}:`));
+        for (const note of notesToShow) {
+            const author = note.author || "unknown";
+            // Mark if this note supersedes another
+            const supersededLabel = note.supersedes ? chalk.gray(" (supersedes earlier note)") : "";
+            console.log(chalk.gray(`[${note.created_at}] ${author}:`) + supersededLabel);
             console.log(note.content);
         }
+        // Show count of hidden notes if any
+        if (hiddenCount > 0) {
+            console.log(chalk.gray(`\n(${hiddenCount} superseded note${hiddenCount > 1 ? "s" : ""} hidden - use --all to show)`));
+        }
     }
     if (task.todos.length > 0) {
         console.log(`\n${sectionHeaders.todos}`);
         for (const todo of task.todos) {
-            const check = todo.done ? chalk.green('✓') : chalk.gray('○');
+            const check = todo.done ? chalk.green("✓") : chalk.gray("○");
             const text = todo.done ? chalk.strikethrough.gray(todo.text) : todo.text;
             console.log(`${check} [${todo.id}] ${text}`);
         }