@telorun/cli 0.70.0 → 0.71.0

package/dist/logger.d.ts

@@ -1,11 +1,33 @@
 import type { AnalysisDiagnostic, LoadedGraph } from "@telorun/analyzer";
 import { type RuntimeDiagnostic } from "@telorun/kernel";
+/** One diagnostic as `-o json` reports it. The shape is the machine contract
+ *  that replaces parsing the prose form: `code` is what a caller branches on,
+ *  and the location is pre-resolved because deriving it needs the loaded graph,
+ *  which the consumer does not have. */
+export interface JsonDiagnostic {
+    file: string;
+    line: number;
+    column: number;
+    severity: "error" | "warning";
+    code?: string;
+    message: string;
+}
+/** The logger's colouring delegates to `Output`'s per-stream palettes.
+ *
+ *  Its methods paint text destined for STDOUT; `log.err` is the same palette
+ *  bound to stderr. Which one a caller wants is decided by where it writes, not
+ *  by the process — `formatDiagnostics` writes to stderr and `check`'s summary
+ *  to stdout, and one shared decision was wrong for whichever stream was
+ *  redirected. Under `-o json` both palettes are plain, so structured output
+ *  cannot carry escapes. */
 export declare function createLogger(verbose: boolean): {
     info: (...args: any[]) => void;
     ok: (text: string) => string;
     warn: (text: string) => string;
     error: (text: string) => string;
     dim: (text: string) => string;
+    /** Palette for text written to stderr. */
+    err: import("./output.js").Palette;
     verbose: boolean;
 };
 export type Logger = ReturnType<typeof createLogger>;
@@ -27,5 +49,6 @@ export declare function formatDiagnostics(diagnostics: RuntimeDiagnostic[], log:
 export declare function formatAnalysisDiagnostics(diagnostics: AnalysisDiagnostic[], graph: LoadedGraph, log: Logger, entryPath: string): {
     errorCount: number;
     warnCount: number;
+    diagnostics: JsonDiagnostic[];
 };
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAyCzB,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO;oBAezB,GAAG,EAAE;eACV,MAAM;iBACJ,MAAM;kBACL,MAAM;gBACR,MAAM;;EAGrB;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,iBAAiB,EAAE,EAChC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,WAAW,GAClB,IAAI,CAmEN;AAED;;yBAEyB;AACzB,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,kBAAkB,EAAE,EACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAqB3C"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAwDzB;;;wCAGwC;AACxC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;4BAO4B;AAC5B,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO;oBAGzB,GAAG,EAAE;eAGV,MAAM;iBACJ,MAAM;kBACL,MAAM;gBACR,MAAM;IAClB,0CAA0C;;;EAI7C;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,iBAAiB,EAAE,EAChC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,WAAW,GAClB,IAAI,CAuEN;AAED;;yBAEyB;AACzB,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,kBAAkB,EAAE,EACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,cAAc,EAAE,CAAA;CAAE,CAmC1E"}

package/dist/logger.js

@@ -1,8 +1,9 @@
 import { DiagnosticSeverity } from "@telorun/analyzer";
 import { findPositions, resolveRange } from "@telorun/ide-support";
-import { decideColor, describeBlockedGroup, groupBlockedResources, } from "@telorun/kernel";
+import { describeBlockedGroup, groupBlockedResources, } from "@telorun/kernel";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { output } from "./output.js";
 /** Render a manifest source for display: a local `file://` URL (how the loader
  *  canonicalizes on-disk manifests) becomes a CWD-relative path, a real remote
  *  URL (`http(s)://`) is kept absolute, and a bare path is made relative. */
@@ -26,7 +27,7 @@ function displaySourcePath(raw) {
  *  Undefined when nothing located it — a diagnostic whose resource is synthetic
  *  and whose file matches no graph source. A pointer to line 1 would be worse
  *  than none: it sends the reader somewhere the error is not. */
-function resolveLocation(graph, d, fallbackSource) {
+function resolveLocationParts(graph, d, fallbackSource) {
     const located = findPositions(graph, d.data);
     if (!located && !d.range)
         return undefined;
@@ -34,28 +35,38 @@ function resolveLocation(graph, d, fallbackSource) {
         positionIndex: located?.positionIndex,
         sourceLine: located?.sourceLine,
     });
-    return `${displaySourcePath(located?.file ?? fallbackSource)}:${range.start.line + 1}:${range.start.character + 1}`;
+    // 1-based for display; the analyzer's own range is 0-based.
+    return {
+        file: displaySourcePath(located?.file ?? fallbackSource),
+        line: range.start.line + 1,
+        column: range.start.character + 1,
+    };
 }
+function resolveLocation(graph, d, fallbackSource) {
+    const parts = resolveLocationParts(graph, d, fallbackSource);
+    return parts && `${parts.file}:${parts.line}:${parts.column}`;
+}
+/** The logger's colouring delegates to `Output`'s per-stream palettes.
+ *
+ *  Its methods paint text destined for STDOUT; `log.err` is the same palette
+ *  bound to stderr. Which one a caller wants is decided by where it writes, not
+ *  by the process — `formatDiagnostics` writes to stderr and `check`'s summary
+ *  to stdout, and one shared decision was wrong for whichever stream was
+ *  redirected. Under `-o json` both palettes are plain, so structured output
+ *  cannot carry escapes. */
 export function createLogger(verbose) {
-    // The color decision follows `kernel/specs/logging.md` §11.2's precedence
-    // order exactly, shared with the `pretty` log encoding rather than
-    // reimplemented here. Notably this adds `NO_COLOR` support, which the CLI
-    // previously ignored, and stops treating a bare `FORCE_COLOR=0` as "on" —
-    // both behavior changes, both required by the spec.
-    //
-    // The decision is made against stdout, which is where this logger writes.
-    const useColor = decideColor({
-        setting: "auto",
-        env: process.env,
-        isTTY: Boolean(process.stdout.isTTY),
-    });
-    const wrap = (code, text) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+    const out = output();
     return {
-        info: (...args) => console.log(...args),
-        ok: (text) => wrap("32", text),
-        warn: (text) => wrap("33", text),
-        error: (text) => wrap("31", text),
-        dim: (text) => wrap("2", text),
+        info: (...args) => {
+            if (!out.isJson)
+                out.line(args.map((a) => String(a)).join(" "));
+        },
+        ok: (text) => out.stdout.ok(text),
+        warn: (text) => out.stdout.warn(text),
+        error: (text) => out.stdout.error(text),
+        dim: (text) => out.stdout.dim(text),
+        /** Palette for text written to stderr. */
+        err: out.stderr,
         verbose,
     };
 }
@@ -74,12 +85,16 @@ export function formatDiagnostics(diagnostics, log, displayPath, graph) {
     // Column the `error`/`warning` label occupies, so a collapsed group line sits
     // under the resource names it summarizes rather than under the label.
     const NAME_COLUMN = " ".repeat("  error  ".length);
+    const out = output();
+    // This renderer writes to stderr throughout, so it paints with the stderr
+    // palette — the stdout one may be coloured when stderr is redirected.
+    const paint = log.err;
     const render = (entries, indent) => {
         for (const d of entries) {
             const skip = d.derived && !log.verbose;
             if (!skip) {
-                const severityLabel = d.severity === "warning" ? log.warn("warning") : log.error("error");
-                const code = d.code ? `  ${log.dim(d.code)}` : "";
+                const severityLabel = d.severity === "warning" ? paint.warn("warning") : paint.error("error");
+                const code = d.code ? `  ${paint.dim(d.code)}` : "";
                 // A static failure that nothing could locate falls through to the
                 // resource / bare-path branches below, which at least name what failed.
                 const location = d.origin && graph
@@ -91,28 +106,28 @@ export function formatDiagnostics(diagnostics, log, displayPath, graph) {
                     if (!d.details)
                         return;
                     for (const line of d.details.split("\n")) {
-                        console.error(`${detailIndent}${log.dim(line)}`);
+                        out.errLine(`${detailIndent}${paint.dim(line)}`);
                     }
                 };
                 if (location) {
                     // Static-analysis failure — the position names the exact spot, so it
                     // renders exactly as `telo check` does. Repeating the resource here
                     // would duplicate it: an analyzer message already names its own.
-                    console.error(`${indent}${location}  ${severityLabel}  ${d.message}${code}`);
+                    out.errLine(`${indent}${location}  ${severityLabel}  ${d.message}${code}`);
                     printDetails(`${indent}  `);
                 }
                 else if (d.resource) {
                     // Runtime diagnostic — the failure is pinned to a resource, so the
                     // entry manifest path adds no information. Show kind + name + message
                     // and any structured details indented below.
-                    const who = `${d.kind ? `${log.dim(d.kind)} ` : ""}${d.resource}`;
-                    console.error(`${indent}  ${severityLabel}  ${who}: ${d.message}${code}`);
+                    const who = `${d.kind ? `${paint.dim(d.kind)} ` : ""}${d.resource}`;
+                    out.errLine(`${indent}  ${severityLabel}  ${who}: ${d.message}${code}`);
                     printDetails(`${indent}${NAME_COLUMN}  `);
                 }
                 else {
                     // Non-resource diagnostic (e.g. loader/parse failure) — keep the file
                     // path since it is the only location cue we have.
-                    console.error(`${indent}${displayPath}  ${severityLabel}  ${d.message}${code}`);
+                    out.errLine(`${indent}${displayPath}  ${severityLabel}  ${d.message}${code}`);
                     printDetails(`${indent}  `);
                 }
             }
@@ -124,7 +139,7 @@ export function formatDiagnostics(diagnostics, log, displayPath, graph) {
         }
         if (!log.verbose) {
             for (const [blockedBy, names] of groupBlockedResources(entries)) {
-                console.error(`${indent}${NAME_COLUMN}${log.dim(describeBlockedGroup(blockedBy, names))}`);
+                out.errLine(`${indent}${NAME_COLUMN}${paint.dim(describeBlockedGroup(blockedBy, names))}`);
             }
         }
     };
@@ -136,20 +151,34 @@ export function formatDiagnostics(diagnostics, log, displayPath, graph) {
 export function formatAnalysisDiagnostics(diagnostics, graph, log, entryPath) {
     let errorCount = 0;
     let warnCount = 0;
+    const out = output();
+    const collected = [];
     for (const d of diagnostics) {
         // `check` prints one line per diagnostic and has no resource-named form to
         // fall back to, so an unlocatable one still leads with the entry manifest.
-        const loc = resolveLocation(graph, d, entryPath) ?? `${displaySourcePath(entryPath)}:1:1`;
-        const severityLabel = (d.severity ?? DiagnosticSeverity.Warning) <= DiagnosticSeverity.Error
-            ? log.error("error")
-            : log.warn("warning");
+        const parts = resolveLocationParts(graph, d, entryPath) ?? {
+            file: displaySourcePath(entryPath),
+            line: 1,
+            column: 1,
+        };
+        const isError = (d.severity ?? DiagnosticSeverity.Warning) <= DiagnosticSeverity.Error;
+        const severityLabel = isError ? log.error("error") : log.warn("warning");
         const code = d.code ? `  ${log.dim(String(d.code))}` : "";
-        console.log(`${loc}  ${severityLabel}  ${d.message}${code}`);
-        if ((d.severity ?? DiagnosticSeverity.Warning) <= DiagnosticSeverity.Error)
+        // Silent under `-o json`: the structured payload carries the same
+        // diagnostics with their location resolved, so printing here too would
+        // interleave prose into a document a consumer parses.
+        out.line(`${parts.file}:${parts.line}:${parts.column}  ${severityLabel}  ${d.message}${code}`);
+        collected.push({
+            ...parts,
+            severity: isError ? "error" : "warning",
+            ...(d.code === undefined ? {} : { code: String(d.code) }),
+            message: d.message,
+        });
+        if (isError)
             errorCount++;
         else
             warnCount++;
     }
-    return { errorCount, warnCount };
+    return { errorCount, warnCount, diagnostics: collected };
 }
 //# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,GAEtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;6EAE6E;AAC7E,SAAS,iBAAiB,CAAC,GAAW;IACpC,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;iEAWiE;AACjE,SAAS,oBAAoB,CAC3B,KAAkB,EAClB,CAAqB,EACrB,cAAsB;IAEtB,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC3C,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,EAAE;QAC5B,aAAa,EAAE,OAAO,EAAE,aAAa;QACrC,UAAU,EAAE,OAAO,EAAE,UAAU;KAChC,CAAC,CAAC;IACH,4DAA4D;IAC5D,OAAO;QACL,IAAI,EAAE,iBAAiB,CAAC,OAAO,EAAE,IAAI,IAAI,cAAc,CAAC;QACxD,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;QAC1B,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC;KAClC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,KAAkB,EAClB,CAAqB,EACrB,cAAsB;IAEtB,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,EAAE,CAAC,EAAE,cAAc,CAAC,CAAC;IAC7D,OAAO,KAAK,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;AAChE,CAAC;AAeD;;;;;;;4BAO4B;AAC5B,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,OAAO;QACL,IAAI,EAAE,CAAC,GAAG,IAAW,EAAE,EAAE;YACvB,IAAI,CAAC,GAAG,CAAC,MAAM;gBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,EAAE,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC;QACzC,IAAI,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QAC7C,KAAK,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAC/C,GAAG,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QAC3C,0CAA0C;QAC1C,GAAG,EAAE,GAAG,CAAC,MAAM;QACf,OAAO;KACR,CAAC;AACJ,CAAC;AAID;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAAgC,EAChC,GAAW,EACX,WAAmB,EACnB,KAAmB;IAEnB,8EAA8E;IAC9E,sEAAsE;IACtE,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,0EAA0E;IAC1E,sEAAsE;IACtE,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC;IAEtB,MAAM,MAAM,GAAG,CAAC,OAA4B,EAAE,MAAc,EAAQ,EAAE;QACpE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YACvC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,aAAa,GAAG,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC9F,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAEpD,kEAAkE;gBAClE,wEAAwE;gBACxE,MAAM,QAAQ,GACZ,CAAC,CAAC,MAAM,IAAI,KAAK;oBACf,CAAC,CAAC,eAAe,CACb,KAAK,EACL,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAC7D,WAAW,CACZ;oBACH,CAAC,CAAC,SAAS,CAAC;gBAEhB,uEAAuE;gBACvE,4EAA4E;gBAC5E,MAAM,YAAY,GAAG,CAAC,YAAoB,EAAQ,EAAE;oBAClD,IAAI,CAAC,CAAC,CAAC,OAAO;wBAAE,OAAO;oBACvB,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;wBACzC,GAAG,CAAC,OAAO,CAAC,GAAG,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACnD,CAAC;gBACH,CAAC,CAAC;gBAEF,IAAI,QAAQ,EAAE,CAAC;oBACb,qEAAqE;oBACrE,oEAAoE;oBACpE,iEAAiE;oBACjE,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,QAAQ,KAAK,aAAa,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC;oBAC3E,YAAY,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;gBAC9B,CAAC;qBAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;oBACtB,mEAAmE;oBACnE,sEAAsE;oBACtE,6CAA6C;oBAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;oBACpE,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,KAAK,aAAa,KAAK,GAAG,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC;oBACxE,YAAY,CAAC,GAAG,MAAM,GAAG,WAAW,IAAI,CAAC,CAAC;gBAC5C,CAAC;qBAAM,CAAC;oBACN,sEAAsE;oBACtE,kDAAkD;oBAClD,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,WAAW,KAAK,aAAa,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC;oBAC9E,YAAY,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YAED,0EAA0E;YAC1E,0EAA0E;YAC1E,oDAAoD;YACpD,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM;gBAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,CAAC;QAC9D,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACjB,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,qBAAqB,CAAC,OAAO,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;YAC7F,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED;;yBAEyB;AACzB,MAAM,UAAU,yBAAyB,CACvC,WAAiC,EACjC,KAAkB,EAClB,GAAW,EACX,SAAiB;IAEjB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,MAAM,SAAS,GAAqB,EAAE,CAAC;IAEvC,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,2EAA2E;QAC3E,2EAA2E;QAC3E,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,EAAE,CAAC,EAAE,SAAS,CAAC,IAAI;YACzD,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC;YAClC,IAAI,EAAE,CAAC;YACP,MAAM,EAAE,CAAC;SACV,CAAC;QACF,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,kBAAkB,CAAC,OAAO,CAAC,IAAI,kBAAkB,CAAC,KAAK,CAAC;QACvF,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzE,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAE1D,kEAAkE;QAClE,uEAAuE;QACvE,sDAAsD;QACtD,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,aAAa,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC;QAE/F,SAAS,CAAC,IAAI,CAAC;YACb,GAAG,KAAK;YACR,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YACvC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,OAAO,EAAE,CAAC,CAAC,OAAO;SACnB,CAAC,CAAC;QAEH,IAAI,OAAO;YAAE,UAAU,EAAE,CAAC;;YACrB,SAAS,EAAE,CAAC;IACnB,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAC3D,CAAC"}

package/dist/output.d.ts

@@ -0,0 +1,111 @@
+/** Output encodings the CLI can produce. `yaml` is deliberately absent: the flag
+ *  is an enum precisely so it can gain a value later without a second flag. */
+export type OutputFormat = "text" | "json";
+export declare const OUTPUT_FORMATS: OutputFormat[];
+/** A colour palette bound to ONE stream.
+ *
+ *  Colour is a property of the descriptor being written to, not of the process:
+ *  `telo check 2>/dev/null` leaves stdout a TTY and stderr not, and a single
+ *  process-wide decision is wrong for one of them either way. The CLI used to
+ *  decide once from `process.stdout.isTTY` while `formatDiagnostics` wrote to
+ *  stderr, so redirecting one stream and not the other produced escapes where
+ *  they could not be rendered — the leak this splits apart. */
+export interface Palette {
+    ok(text: string): string;
+    warn(text: string): string;
+    error(text: string): string;
+    dim(text: string): string;
+}
+/** The minimum of a writable stream this needs. Narrow on purpose: a test hands
+ *  in a recording pair, so `Output` never reads process globals. */
+export interface OutputStream {
+    isTTY?: boolean;
+    write(chunk: string): unknown;
+}
+export interface OutputOptions {
+    format: OutputFormat;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    env?: NodeJS.ProcessEnv;
+}
+/** The single seam every CLI-owned write goes through.
+ *
+ *  The stream split is the whole contract:
+ *
+ *  - **stdout is the machine surface.** Under `-o json` it carries the payload
+ *    and nothing else, so a consumer parses it whole.
+ *  - **stderr is the human surface, in BOTH formats.** Prose keeps flowing under
+ *    `-o json` — the convention npm, cargo and kubectl follow — because the
+ *    alternative is silence: a command that reports a failure reason through
+ *    prose would otherwise have it swallowed, leaving `{"ok":false}` with no
+ *    cause. Suppressing stderr was error swallowing, which Telo forbids.
+ *
+ *  `telo run` is exempt from `-o json` entirely; see `emit`. */
+export declare class Output {
+    readonly format: OutputFormat;
+    readonly stdout: Palette;
+    readonly stderr: Palette;
+    private readonly outStream;
+    private readonly errStream;
+    constructor(options: OutputOptions);
+    get isJson(): boolean;
+    /** Human-readable line on stdout. Suppressed under `-o json`, where stdout is
+     *  reserved for the payload. */
+    line(text?: string): void;
+    /** Human-readable line on stderr. Written in BOTH formats — stderr is not the
+     *  machine contract, and silencing it loses the reason a command failed. */
+    errLine(text?: string): void;
+    /** Emit a command's structured RESULT ENVELOPE. A no-op in text mode.
+     *
+     *  Every command that owns its stdout calls this exactly once, including when
+     *  it has nothing interesting to report — a consumer cannot distinguish
+     *  "nothing to say" from "this command ignores the flag", so a bare envelope
+     *  is the difference between a contract and a guess.
+     *
+     *  `telo run` is the ONE exemption, and it is a property of the command rather
+     *  than an oversight: the kernel runs in-process and the app's own output goes
+     *  to these same descriptors (`teeStdio` copies, it does not redirect), so
+     *  NEITHER stream is the CLI's to claim. An envelope written after arbitrary
+     *  app output is unparseable, which is the exact failure `-o json` exists to
+     *  remove. The machine surface for a run already exists and is `--debug`,
+     *  whose wire protocol is framed per event precisely because it shares a
+     *  stream. */
+    emit(payload: unknown): void;
+    /** Write a bare DOCUMENT to stdout, in either format.
+     *
+     *  For the commands whose structured form is the document itself rather than a
+     *  result report — `cel`, `search`, `module versions|manifest|digest|resources|kinds`.
+     *  Unconditional because their per-command `--json` flag predates `-o` and
+     *  must keep working under the default `text` format. One serializer with
+     *  `emit`, so the CLI has a single JSON encoding rather than three. */
+    document(payload: unknown): void;
+    /** Write verbatim content to stdout, unconditionally and with no framing.
+     *
+     *  For the one case that is neither prose nor a JSON payload: `telo module
+     *  manifest` printing a module's `telo.yaml` bytes, which ARE the output. It
+     *  bypasses format handling because the bytes are the answer in every format
+     *  — the `--json` path wraps them in a document instead and never reaches
+     *  here. */
+    raw(content: string): void;
+}
+export declare function configureOutput(format: OutputFormat): void;
+/** Swap the ambient instance, returning a restore function.
+ *
+ *  For tests of code that reaches the seam through the accessor rather than
+ *  through a parameter — they hand in an `Output` over recording streams instead
+ *  of spying on `process.stderr.write`. */
+export declare function installOutput(replacement: Output): () => void;
+export declare function output(): Output;
+/** yargs has already rejected anything outside `choices` by the time a handler
+ *  runs, so an unrecognized value here means the enum grew and this function was
+ *  not updated. Throwing is the point: silently degrading `-o yaml` to text is
+ *  the worst failure a format flag can have. */
+export declare function parseOutputFormat(value: unknown): OutputFormat;
+/** Free-function forms of the seam, for the many call sites that only need to
+ *  write a line and would otherwise each bind a local. They read the singleton
+ *  per call, so they observe the configured format no matter when they run. */
+export declare const outLine: (text?: string) => void;
+export declare const outErrLine: (text?: string) => void;
+export declare const outEmit: (payload: unknown) => void;
+export declare const outDocument: (payload: unknown) => void;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAEA;+EAC+E;AAC/E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C,eAAO,MAAM,cAAc,EAAE,YAAY,EAAqB,CAAC;AAE/D;;;;;;;+DAO+D;AAC/D,MAAM,WAAW,OAAO;IACtB,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAiBD;oEACoE;AACpE,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;gEAYgE;AAChE,qBAAa,MAAM;IACjB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,aAAa;IAkBlC,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;oCACgC;IAChC,IAAI,CAAC,IAAI,SAAK,GAAG,IAAI;IAIrB;gFAC4E;IAC5E,OAAO,CAAC,IAAI,SAAK,GAAG,IAAI;IAIxB;;;;;;;;;;;;;;kBAcc;IACd,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5B;;;;;;2EAMuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIhC;;;;;;gBAMY;IACZ,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAG3B;AAWD,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED;;;;2CAI2C;AAC3C,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,IAAI,CAM7D;AAED,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED;;;gDAGgD;AAChD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAK9D;AAED;;+EAE+E;AAC/E,eAAO,MAAM,OAAO,GAAI,aAAS,KAAG,IAA0B,CAAC;AAC/D,eAAO,MAAM,UAAU,GAAI,aAAS,KAAG,IAA6B,CAAC;AACrE,eAAO,MAAM,OAAO,GAAI,SAAS,OAAO,KAAG,IAA6B,CAAC;AACzE,eAAO,MAAM,WAAW,GAAI,SAAS,OAAO,KAAG,IAAiC,CAAC"}

package/dist/output.js

@@ -0,0 +1,143 @@
+import { decideColor } from "@telorun/kernel";
+export const OUTPUT_FORMATS = ["text", "json"];
+const PLAIN = {
+    ok: (t) => t,
+    warn: (t) => t,
+    error: (t) => t,
+    dim: (t) => t,
+};
+function paletteFor(isTTY, env) {
+    // Follows `kernel/specs/logging.md` §11.2 precedence, shared with the `pretty`
+    // log encoding rather than reimplemented.
+    if (!decideColor({ setting: "auto", env, isTTY }))
+        return PLAIN;
+    const wrap = (code) => (text) => `\x1b[${code}m${text}\x1b[0m`;
+    return { ok: wrap("32"), warn: wrap("33"), error: wrap("31"), dim: wrap("2") };
+}
+/** The single seam every CLI-owned write goes through.
+ *
+ *  The stream split is the whole contract:
+ *
+ *  - **stdout is the machine surface.** Under `-o json` it carries the payload
+ *    and nothing else, so a consumer parses it whole.
+ *  - **stderr is the human surface, in BOTH formats.** Prose keeps flowing under
+ *    `-o json` — the convention npm, cargo and kubectl follow — because the
+ *    alternative is silence: a command that reports a failure reason through
+ *    prose would otherwise have it swallowed, leaving `{"ok":false}` with no
+ *    cause. Suppressing stderr was error swallowing, which Telo forbids.
+ *
+ *  `telo run` is exempt from `-o json` entirely; see `emit`. */
+export class Output {
+    format;
+    stdout;
+    stderr;
+    outStream;
+    errStream;
+    constructor(options) {
+        const { format, stdout = process.stdout, stderr = process.stderr, env = process.env, } = options;
+        this.format = format;
+        this.outStream = stdout;
+        this.errStream = stderr;
+        // Structured output must never carry escapes: a consumer parses it, and no
+        // terminal renders it. Deciding this here rather than at each call site is
+        // what makes "JSON is always clean" true by construction. stderr keeps its
+        // colour under `-o json` because it stays the human surface.
+        this.stdout = format === "text" ? paletteFor(Boolean(stdout.isTTY), env) : PLAIN;
+        this.stderr = paletteFor(Boolean(stderr.isTTY), env);
+    }
+    get isJson() {
+        return this.format === "json";
+    }
+    /** Human-readable line on stdout. Suppressed under `-o json`, where stdout is
+     *  reserved for the payload. */
+    line(text = "") {
+        if (this.format === "text")
+            this.outStream.write(`${text}\n`);
+    }
+    /** Human-readable line on stderr. Written in BOTH formats — stderr is not the
+     *  machine contract, and silencing it loses the reason a command failed. */
+    errLine(text = "") {
+        this.errStream.write(`${text}\n`);
+    }
+    /** Emit a command's structured RESULT ENVELOPE. A no-op in text mode.
+     *
+     *  Every command that owns its stdout calls this exactly once, including when
+     *  it has nothing interesting to report — a consumer cannot distinguish
+     *  "nothing to say" from "this command ignores the flag", so a bare envelope
+     *  is the difference between a contract and a guess.
+     *
+     *  `telo run` is the ONE exemption, and it is a property of the command rather
+     *  than an oversight: the kernel runs in-process and the app's own output goes
+     *  to these same descriptors (`teeStdio` copies, it does not redirect), so
+     *  NEITHER stream is the CLI's to claim. An envelope written after arbitrary
+     *  app output is unparseable, which is the exact failure `-o json` exists to
+     *  remove. The machine surface for a run already exists and is `--debug`,
+     *  whose wire protocol is framed per event precisely because it shares a
+     *  stream. */
+    emit(payload) {
+        if (this.format === "json")
+            this.outStream.write(serialize(payload));
+    }
+    /** Write a bare DOCUMENT to stdout, in either format.
+     *
+     *  For the commands whose structured form is the document itself rather than a
+     *  result report — `cel`, `search`, `module versions|manifest|digest|resources|kinds`.
+     *  Unconditional because their per-command `--json` flag predates `-o` and
+     *  must keep working under the default `text` format. One serializer with
+     *  `emit`, so the CLI has a single JSON encoding rather than three. */
+    document(payload) {
+        this.outStream.write(serialize(payload));
+    }
+    /** Write verbatim content to stdout, unconditionally and with no framing.
+     *
+     *  For the one case that is neither prose nor a JSON payload: `telo module
+     *  manifest` printing a module's `telo.yaml` bytes, which ARE the output. It
+     *  bypasses format handling because the bytes are the answer in every format
+     *  — the `--json` path wraps them in a document instead and never reaches
+     *  here. */
+    raw(content) {
+        this.outStream.write(content);
+    }
+}
+function serialize(payload) {
+    return `${JSON.stringify(payload, null, 2)}\n`;
+}
+/** Configured once from argv by a yargs middleware, before any handler runs, so
+ *  call sites far from the handler reach the same decision without threading it
+ *  through every signature. Tests construct an `Output` directly instead. */
+let current = new Output({ format: "text" });
+export function configureOutput(format) {
+    current = new Output({ format });
+}
+/** Swap the ambient instance, returning a restore function.
+ *
+ *  For tests of code that reaches the seam through the accessor rather than
+ *  through a parameter — they hand in an `Output` over recording streams instead
+ *  of spying on `process.stderr.write`. */
+export function installOutput(replacement) {
+    const previous = current;
+    current = replacement;
+    return () => {
+        current = previous;
+    };
+}
+export function output() {
+    return current;
+}
+/** yargs has already rejected anything outside `choices` by the time a handler
+ *  runs, so an unrecognized value here means the enum grew and this function was
+ *  not updated. Throwing is the point: silently degrading `-o yaml` to text is
+ *  the worst failure a format flag can have. */
+export function parseOutputFormat(value) {
+    if (OUTPUT_FORMATS.includes(value))
+        return value;
+    throw new Error(`Unsupported --output format '${String(value)}'. Expected one of: ${OUTPUT_FORMATS.join(", ")}.`);
+}
+/** Free-function forms of the seam, for the many call sites that only need to
+ *  write a line and would otherwise each bind a local. They read the singleton
+ *  per call, so they observe the configured format no matter when they run. */
+export const outLine = (text = "") => current.line(text);
+export const outErrLine = (text = "") => current.errLine(text);
+export const outEmit = (payload) => current.emit(payload);
+export const outDocument = (payload) => current.document(payload);
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/cli",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "Telo CLI - Command-line interface for the Telo runtime.",
   "keywords": [
     "telo",