@zenalexa/unicli 0.211.2 → 0.213.0-beta.2

package/dist/output/envelope.js

@@ -0,0 +1,96 @@
+/**
+ * Agent-Native v2 envelope — stable contract for machine-readable output.
+ *
+ * All `--json` / `--yaml` / `--md` output wraps payloads in this envelope.
+ * Hard-switch: v0.215 removes any legacy v1 path (DECISION 3 confirmed 2026-04-17).
+ *
+ * NOTE: Names are prefixed "Agent*" to avoid collision with the transport-layer
+ * EnvelopeMeta / EnvelopeError re-exported from src/errors.ts (src/core/envelope.ts).
+ */
+export const SCHEMA_VERSION = "2";
+/** Build a success envelope from context + payload. */
+export function makeEnvelope(ctx, data) {
+    const count = Array.isArray(data) ? data.length : undefined;
+    return {
+        ok: true,
+        schema_version: SCHEMA_VERSION,
+        command: ctx.command,
+        meta: {
+            duration_ms: ctx.duration_ms,
+            ...(count !== undefined ? { count } : {}),
+            ...(ctx.adapter_version !== undefined
+                ? { adapter_version: ctx.adapter_version }
+                : {}),
+            ...(ctx.surface !== undefined ? { surface: ctx.surface } : {}),
+            ...(ctx.operator !== undefined ? { operator: ctx.operator } : {}),
+            ...(ctx.pagination !== undefined &&
+                (ctx.pagination.next_cursor !== undefined ||
+                    ctx.pagination.has_more !== undefined)
+                ? { pagination: ctx.pagination }
+                : {}),
+        },
+        data,
+        error: null,
+    };
+}
+/** Build an error envelope. `data` is forced to null. */
+export function makeError(ctx, err) {
+    return {
+        ok: false,
+        schema_version: SCHEMA_VERSION,
+        command: ctx.command,
+        meta: {
+            duration_ms: ctx.duration_ms,
+            ...(ctx.adapter_version !== undefined
+                ? { adapter_version: ctx.adapter_version }
+                : {}),
+            ...(ctx.surface !== undefined ? { surface: ctx.surface } : {}),
+            ...(ctx.operator !== undefined ? { operator: ctx.operator } : {}),
+        },
+        data: null,
+        error: err,
+    };
+}
+/**
+ * Invariant check — throws `Error` with a descriptive message if the envelope
+ * violates any structural rule. Used by tests and by the formatter before serialization.
+ */
+export function validateEnvelope(env) {
+    if (env.schema_version !== SCHEMA_VERSION) {
+        throw new Error(`envelope schema_version must be "${SCHEMA_VERSION}"`);
+    }
+    if (env.ok && env.error !== null) {
+        throw new Error("envelope.ok=true but error is not null");
+    }
+    if (!env.ok && env.error === null) {
+        throw new Error("envelope.ok=false but error is null");
+    }
+    if (!env.ok && env.data !== null) {
+        throw new Error("envelope.ok=false but data is not null");
+    }
+    if (env.ok && env.data === null) {
+        throw new Error("envelope.ok=true but data is null");
+    }
+    if (typeof env.meta.duration_ms !== "number") {
+        throw new Error("envelope.meta.duration_ms must be a number");
+    }
+    // command must match "<site>.<command>" (covers non-empty as well)
+    if (!/^[a-z0-9_-]+\.[a-z0-9_-]+$/i.test(env.command)) {
+        throw new Error(`envelope.command must match "<site>.<command>" (alnum + _/-), got "${env.command}"`);
+    }
+    // content[].type enum
+    if (env.content !== undefined) {
+        for (const c of env.content) {
+            if (!["text", "image", "resource"].includes(c.type)) {
+                throw new Error(`envelope.content[].type must be text|image|resource, got "${c.type}"`);
+            }
+        }
+    }
+    // meta.count must agree with data.length when both are present
+    if (Array.isArray(env.data) &&
+        env.meta.count !== undefined &&
+        env.meta.count !== env.data.length) {
+        throw new Error(`envelope.meta.count (${env.meta.count}) disagrees with data.length (${env.data.length})`);
+    }
+}
+//# sourceMappingURL=envelope.js.map

package/dist/output/envelope.js.map

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

package/dist/output/formatter.d.ts

@@ -1,11 +1,39 @@
 /**
- * Output formatter — renders command results in multiple formats.
+ * Output formatter — renders command results in agent-friendly formats.
  *
- * Formats: table (human), json (agent), yaml, csv, md
- * Auto-detects piped output and switches to json for agent consumption.
+ * Supported formats (6): json, yaml, csv, md, compact, table (deprecated)
+ *
+ *   - json    — v2 AgentEnvelope as JSON
+ *   - yaml    — v2 AgentEnvelope as YAML (zero deps, minimal serializer)
+ *   - md      — v2 AgentEnvelope as agent-native Markdown (frontmatter + sections)
+ *   - csv     — legacy comma-separated with quoted escapes (array-only)
+ *   - compact — one row per line, `|` separator, no headers (array-only)
+ *   - table   — deprecated alias for md; emits stderr warning
+ *
+ * `format()` requires a ctx (AgentContext) parameter — callers must supply
+ * at least command name and duration_ms. This is intentional: the compiler
+ * enforces that every call site plumbs through command metadata.
+ *
+ * Non-TTY stdout and agent user-agents both default to "md" (v2 envelope MD).
  */
 import type { OutputFormat } from "../types.js";
-export declare function format(data: unknown[], columns: string[] | undefined, fmt: OutputFormat): string;
-/** Auto-detect if output should be agent-optimized (piped stdout) */
+import type { AgentContext } from "./envelope.js";
+/**
+ * Format command output. For agent-facing formats (json/yaml/md) the payload
+ * is wrapped in a v2 AgentEnvelope. For csv/compact legacy formats the payload
+ * is rendered as a flat table (unchanged).
+ *
+ * `ctx` is REQUIRED — callers must supply at least command name and duration_ms.
+ */
+export declare function format(data: unknown[] | Record<string, unknown> | null | undefined, columns: string[] | undefined, fmt: OutputFormat, ctx: AgentContext): string;
+/**
+ * Auto-pick output format.
+ *  - explicit param → that format
+ *  - env UNICLI_OUTPUT or OUTPUT ∈ {md|json|yaml|csv|compact|table} → that format
+ *  - non-TTY stdout OR isAgentUA() → "md"
+ *  - TTY human → "md"
+ */
 export declare function detectFormat(explicit?: OutputFormat): OutputFormat;
+/** Detect whether an AI agent / coding tool invoked us. Public for tests. */
+export declare function isAgentUA(): boolean;
 //# sourceMappingURL=formatter.d.ts.map

package/dist/output/formatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/output/formatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAgB,MAAM,CACpB,IAAI,EAAE,OAAO,EAAE,EACf,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAC7B,GAAG,EAAE,YAAY,GAChB,MAAM,CAkBR;AAsED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,CAIlE"}
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/output/formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,eAAe,CAAC;AAMjE;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5D,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAC7B,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,YAAY,GAChB,MAAM,CAoBR;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,CAclE;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,IAAI,OAAO,CASnC"}

package/dist/output/formatter.js

@@ -1,74 +1,116 @@
 /**
- * Output formatter — renders command results in multiple formats.
+ * Output formatter — renders command results in agent-friendly formats.
  *
- * Formats: table (human), json (agent), yaml, csv, md
- * Auto-detects piped output and switches to json for agent consumption.
+ * Supported formats (6): json, yaml, csv, md, compact, table (deprecated)
+ *
+ *   - json    — v2 AgentEnvelope as JSON
+ *   - yaml    — v2 AgentEnvelope as YAML (zero deps, minimal serializer)
+ *   - md      — v2 AgentEnvelope as agent-native Markdown (frontmatter + sections)
+ *   - csv     — legacy comma-separated with quoted escapes (array-only)
+ *   - compact — one row per line, `|` separator, no headers (array-only)
+ *   - table   — deprecated alias for md; emits stderr warning
+ *
+ * `format()` requires a ctx (AgentContext) parameter — callers must supply
+ * at least command name and duration_ms. This is intentional: the compiler
+ * enforces that every call site plumbs through command metadata.
+ *
+ * Non-TTY stdout and agent user-agents both default to "md" (v2 envelope MD).
  */
-import chalk from "chalk";
-import Table from "cli-table3";
-export function format(data, columns, fmt) {
-    if (!data || data.length === 0) {
-        return fmt === "json" ? "[]" : chalk.dim("No results");
-    }
-    switch (fmt) {
-        case "json":
-            return JSON.stringify(data, null, 2);
-        case "yaml":
-            return toYaml(data);
-        case "csv":
-            return toCsv(data, columns);
-        case "md":
-            return toMarkdown(data, columns);
-        case "table":
-        default:
-            return toTable(data, columns);
+import { makeEnvelope, makeError } from "./envelope.js";
+import { renderMd } from "./md.js";
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Format command output. For agent-facing formats (json/yaml/md) the payload
+ * is wrapped in a v2 AgentEnvelope. For csv/compact legacy formats the payload
+ * is rendered as a flat table (unchanged).
+ *
+ * `ctx` is REQUIRED — callers must supply at least command name and duration_ms.
+ */
+export function format(data, columns, fmt, ctx) {
+    if (fmt === "csv")
+        return toCsv(toArray(data), columns);
+    if (fmt === "compact")
+        return toCompact(toArray(data), columns);
+    if (fmt === "table") {
+        process.stderr.write("[deprecated] `-f table` → `md`. Migrate before v0.215.\n");
+        fmt = "md";
     }
+    const envelope = ctx.error
+        ? makeError(ctx, ctx.error)
+        : makeEnvelope(ctx, data ?? []);
+    if (fmt === "md")
+        return renderMd(envelope);
+    if (fmt === "json")
+        return JSON.stringify(envelope, null, 2);
+    if (fmt === "yaml")
+        return renderYamlEnvelope(envelope);
+    // Unknown format — JSON envelope as safe default
+    return JSON.stringify(envelope, null, 2);
 }
-function toTable(data, columns) {
-    const rows = data;
-    const cols = columns ?? Object.keys(rows[0] ?? {});
-    const table = new Table({
-        head: cols.map((c) => chalk.bold.cyan(c)),
-        style: { head: [], border: [] },
-        wordWrap: true,
-    });
-    for (const row of rows) {
-        table.push(cols.map((c) => truncate(String(row[c] ?? ""), 60)));
+/**
+ * Auto-pick output format.
+ *  - explicit param → that format
+ *  - env UNICLI_OUTPUT or OUTPUT ∈ {md|json|yaml|csv|compact|table} → that format
+ *  - non-TTY stdout OR isAgentUA() → "md"
+ *  - TTY human → "md"
+ */
+export function detectFormat(explicit) {
+    if (explicit)
+        return explicit;
+    const envOverride = (process.env.UNICLI_OUTPUT ?? process.env.OUTPUT)?.toLowerCase();
+    if (envOverride &&
+        ["md", "json", "yaml", "csv", "compact", "table"].includes(envOverride)) {
+        return envOverride;
     }
-    return table.toString();
+    if (!process.stdout.isTTY)
+        return "md";
+    if (isAgentUA())
+        return "md";
+    return "md";
+}
+/** Detect whether an AI agent / coding tool invoked us. Public for tests. */
+export function isAgentUA() {
+    return Boolean(process.env.CLAUDE_CODE ||
+        process.env.CODEX_CLI ||
+        process.env.OPENCODE ||
+        process.env.HERMES_AGENT ||
+        process.env.UNICLI_AGENT ||
+        /Claude-Code|Codex|Agent|LLM/i.test(process.env.USER_AGENT ?? ""));
+}
+// ── Internal helpers ──────────────────────────────────────────────────────────
+/** Normalize data to array for legacy csv/compact formats. */
+function toArray(d) {
+    if (d === null || d === undefined)
+        return [];
+    if (Array.isArray(d))
+        return d;
+    // Object → single-row array (best-effort for tabular legacy formats)
+    return [d];
 }
 function toCsv(data, columns) {
+    if (data.length === 0)
+        return "";
     const rows = data;
     const cols = columns ?? Object.keys(rows[0] ?? {});
     const header = cols.join(",");
     const body = rows.map((r) => cols.map((c) => csvEscape(String(r[c] ?? ""))).join(","));
     return [header, ...body].join("\n");
 }
-function toMarkdown(data, columns) {
+function toCompact(data, columns) {
+    if (data.length === 0)
+        return "";
     const rows = data;
     const cols = columns ?? Object.keys(rows[0] ?? {});
-    const header = `| ${cols.join(" | ")} |`;
-    const separator = `| ${cols.map(() => "---").join(" | ")} |`;
-    const body = rows.map((r) => `| ${cols.map((c) => String(r[c] ?? "")).join(" | ")} |`);
-    return [header, separator, ...body].join("\n");
-}
-function toYaml(data) {
-    return data
-        .map((item, i) => {
-        const obj = item;
-        const entries = Object.entries(obj)
-            .map(([k, v]) => `  ${k}: ${yamlValue(v)}`)
-            .join("\n");
-        return `- # ${i + 1}\n${entries}`;
-    })
+    return rows
+        .map((r) => cols.map((c) => compactCell(r[c])).join("|"))
         .join("\n");
 }
-function yamlValue(v) {
+function compactCell(v) {
     if (v === null || v === undefined)
-        return "null";
-    if (typeof v === "string")
-        return v.includes(":") || v.includes("#") ? `"${v}"` : v;
-    return String(v);
+        return "";
+    return String(v)
+        .replace(/[\r\n]+/g, " ")
+        .replace(/\|/g, "/");
 }
 function csvEscape(s) {
     if (s.includes(",") || s.includes('"') || s.includes("\n")) {
@@ -76,15 +118,65 @@ function csvEscape(s) {
     }
     return s;
 }
-function truncate(s, max) {
-    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+// ── YAML envelope serializer (zero deps) ─────────────────────────────────────
+/**
+ * Minimal YAML serializer for AgentEnvelope objects.
+ * Handles: string, number, boolean, null, arrays of primitives/objects, nested objects.
+ * Does NOT handle: cycles, Date, Buffer, BigInt (envelope doesn't contain these).
+ */
+function renderYamlEnvelope(envelope) {
+    return yamlValue(envelope, 0) + "\n";
 }
-/** Auto-detect if output should be agent-optimized (piped stdout) */
-export function detectFormat(explicit) {
-    if (explicit)
-        return explicit;
-    if (!process.stdout.isTTY)
-        return "json";
-    return "table";
+function yamlValue(value, indent) {
+    const pad = " ".repeat(indent);
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "boolean")
+        return String(value);
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "string")
+        return yamlString(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        return value
+            .map((item) => {
+            const rendered = yamlValue(item, indent + 2);
+            // Inline scalars go on same line; objects/arrays start on next line
+            if (rendered.includes("\n")) {
+                return `${pad}-\n${pad}  ${rendered.trimStart()}`;
+            }
+            return `${pad}- ${rendered}`;
+        })
+            .join("\n");
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return "{}";
+        return keys
+            .map((k) => {
+            const v = obj[k];
+            const rendered = yamlValue(v, indent + 2);
+            if (rendered.includes("\n")) {
+                return `${pad}${k}:\n${rendered}`;
+            }
+            return `${pad}${k}: ${rendered}`;
+        })
+            .join("\n");
+    }
+    return String(value);
+}
+function yamlString(s) {
+    // Scalars that need quoting: empty, contains special chars, looks like number/bool/null
+    if (s === "" ||
+        /[\n\r:#{}[\],&*?|<>=!%@`]/.test(s) ||
+        /^(true|false|null|yes|no|on|off)$/i.test(s) ||
+        /^-?\d/.test(s)) {
+        return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r")}"`;
+    }
+    return s;
 }
 //# sourceMappingURL=formatter.js.map

package/dist/output/formatter.js.map

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

package/dist/output/md.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent-Native Markdown renderer — turns an AgentEnvelope into a
+ * frontmatter + sectioned markdown document for LLM consumption.
+ *
+ * Output contract:
+ *  - YAML frontmatter block (always)
+ *  - ## Data (success only)
+ *  - ## Context (success, conditional)
+ *  - ## Next Actions (success, pagination-conditional)
+ *  - ## Error / ## Suggestion / ## Alternatives (error only)
+ *  - Trailing newline
+ */
+import type { AgentEnvelope } from "./envelope.js";
+/**
+ * Render an AgentEnvelope as agent-native markdown.
+ *
+ * Pure function — no side effects. Output always ends with a single `\n`.
+ */
+export declare function renderMd(envelope: AgentEnvelope): string;
+//# sourceMappingURL=md.d.ts.map

package/dist/output/md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"md.d.ts","sourceRoot":"","sources":["../../src/output/md.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,aAAa,EAKd,MAAM,eAAe,CAAC;AA0RvB;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAMxD"}