@telorun/cli 0.69.0 → 0.71.0

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.69.0",
+  "version": "0.71.0",
   "description": "Telo CLI - Command-line interface for the Telo runtime.",
   "keywords": [
     "telo",
@@ -34,11 +34,11 @@
     "dist"
   ],
   "dependencies": {
-    "@telorun/analyzer": "0.56.0",
+    "@telorun/analyzer": "0.56.1",
     "@telorun/glob": "0.2.0",
-    "@telorun/ide-support": "0.11.2",
-    "@telorun/kernel": "0.69.0",
-    "@telorun/sdk": "0.68.0",
+    "@telorun/ide-support": "0.11.3",
+    "@telorun/kernel": "0.70.0",
+    "@telorun/sdk": "0.70.0",
     "@telorun/templating": "0.12.0",
     "dotenv": "^17.4.0",
     "packageurl-js": "^2.0.1",