primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/lib/migration-nag.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Legacy-mode migration nag.
+ *
+ * Prints a one-time, opt-out, rate-limited startup warning that points
+ * users still on the legacy `~/.primitive/credentials.json` config at the
+ * project-scoped `primitive env add` migration path. The warning is purely
+ * informational — it never mutates anything other than the small
+ * `~/.primitive/migration-nag.json` cache used for the 24h rate-limit.
+ *
+ * Detection signal (warn iff ALL of):
+ *   1. `peekLegacyCredentials()` is non-null (legacy creds file present).
+ *   2. `findProjectConfigPath()` is null (no project config in scope).
+ *   3. `./config/.primitive-sync.json` exists in CWD (strong signal the
+ *      user has actually run `primitive config pull` here — the
+ *      population at risk from #548).
+ *
+ * Suppression (skip if ANY of):
+ *   - `PRIMITIVE_NO_MIGRATE_NAG=1`
+ *   - `CI` env var set (non-empty)
+ *   - `!process.stdout.isTTY`
+ *   - argv contains `--help` / `-h` / `--version` / `-V` / `--json`
+ *   - Subcommand is `env *`, `init`, `login`, `logout`, or `token`
+ *   - `now - lastWarnedAt < 24h`
+ *
+ * Modeled on `cli/src/lib/version-check.ts`: the whole body is wrapped
+ * in try/catch that swallows every error so a corrupt cache file or any
+ * other unexpected failure can never break the CLI.
+ *
+ * TODO(#auto-migration): When we ship an interactive auto-migration flow
+ * (separate issue from #552), it should either delete this nag cache or
+ * bump `lastWarnedAt` far into the future so freshly-migrated users
+ * don't see the nag again. The cache lives at `${PRIMITIVE_CONFIG_DIR ||
+ * ~/.primitive}/migration-nag.json`.
+ */
+export interface MaybeWarnLegacyMigrationOptions {
+    argv: string[];
+    /**
+     * Override the working directory used for project-shape detection and
+     * the upward `.primitive/config.json` search. Defaults to
+     * `process.cwd()`. Exists so unit tests (which run in worker threads
+     * that disallow `process.chdir()`) can point at a tmpdir.
+     */
+    cwd?: string;
+}
+/**
+ * Print the legacy-mode migration nag if the detection signal matches
+ * and no suppression condition applies. Never throws.
+ */
+export declare function maybeWarnLegacyMigration(options: MaybeWarnLegacyMigrationOptions): void;

package/dist/src/lib/migration-nag.js

@@ -0,0 +1,163 @@
+/**
+ * Legacy-mode migration nag.
+ *
+ * Prints a one-time, opt-out, rate-limited startup warning that points
+ * users still on the legacy `~/.primitive/credentials.json` config at the
+ * project-scoped `primitive env add` migration path. The warning is purely
+ * informational — it never mutates anything other than the small
+ * `~/.primitive/migration-nag.json` cache used for the 24h rate-limit.
+ *
+ * Detection signal (warn iff ALL of):
+ *   1. `peekLegacyCredentials()` is non-null (legacy creds file present).
+ *   2. `findProjectConfigPath()` is null (no project config in scope).
+ *   3. `./config/.primitive-sync.json` exists in CWD (strong signal the
+ *      user has actually run `primitive config pull` here — the
+ *      population at risk from #548).
+ *
+ * Suppression (skip if ANY of):
+ *   - `PRIMITIVE_NO_MIGRATE_NAG=1`
+ *   - `CI` env var set (non-empty)
+ *   - `!process.stdout.isTTY`
+ *   - argv contains `--help` / `-h` / `--version` / `-V` / `--json`
+ *   - Subcommand is `env *`, `init`, `login`, `logout`, or `token`
+ *   - `now - lastWarnedAt < 24h`
+ *
+ * Modeled on `cli/src/lib/version-check.ts`: the whole body is wrapped
+ * in try/catch that swallows every error so a corrupt cache file or any
+ * other unexpected failure can never break the CLI.
+ *
+ * TODO(#auto-migration): When we ship an interactive auto-migration flow
+ * (separate issue from #552), it should either delete this nag cache or
+ * bump `lastWarnedAt` far into the future so freshly-migrated users
+ * don't see the nag again. The cache lives at `${PRIMITIVE_CONFIG_DIR ||
+ * ~/.primitive}/migration-nag.json`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { warn } from "./output.js";
+import { peekLegacyCredentials } from "./credentials-store.js";
+import { findProjectConfigPath } from "./project-config.js";
+const NAG_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** Resolved per-call so tests can override PRIMITIVE_CONFIG_DIR at runtime. */
+function getConfigDir() {
+    return process.env.PRIMITIVE_CONFIG_DIR || join(homedir(), ".primitive");
+}
+function getNagCacheFile() {
+    return join(getConfigDir(), "migration-nag.json");
+}
+function ensureConfigDir() {
+    const dir = getConfigDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}
+function loadNagCache() {
+    try {
+        const file = getNagCacheFile();
+        if (!existsSync(file))
+            return null;
+        const raw = JSON.parse(readFileSync(file, "utf-8"));
+        if (!raw || typeof raw !== "object")
+            return null;
+        if (typeof raw.lastWarnedAt !== "number")
+            return null;
+        return { lastWarnedAt: raw.lastWarnedAt };
+    }
+    catch {
+        return null;
+    }
+}
+function saveNagCache(cache) {
+    try {
+        ensureConfigDir();
+        writeFileSync(getNagCacheFile(), JSON.stringify(cache, null, 2));
+    }
+    catch {
+        // Swallow — at worst the user gets re-nagged next invocation.
+    }
+}
+/**
+ * Returns true if `argv` indicates the warning should be skipped:
+ *   - any of `--help` / `-h` / `--version` / `-V` / `--json` present, OR
+ *   - the subcommand is on the migration path (`env *`, `init`, `login`,
+ *     `logout`), OR
+ *   - the subcommand is `token`. The `token` command is contractually
+ *     stdout-only (callers pipe its output to `--access-token` or paste it
+ *     into env vars), so any extra warning lines would corrupt that output.
+ *
+ * `argv` is expected to be the same shape as `process.argv` (i.e. the
+ * subcommand sits at index 2, after `node` and the script path). Defensive
+ * about short or unusual argv shapes.
+ */
+function shouldSuppressByArgv(argv) {
+    for (const a of argv) {
+        if (a === "--help" || a === "-h" || a === "--version" || a === "-V" || a === "--json") {
+            return true;
+        }
+    }
+    const subcommand = argv[2];
+    if (subcommand === "env" ||
+        subcommand === "init" ||
+        subcommand === "login" ||
+        subcommand === "logout" ||
+        subcommand === "token") {
+        return true;
+    }
+    return false;
+}
+/**
+ * Returns true when `cwd` looks like a project that has actually been
+ * used with `primitive config` — specifically, when
+ * `<cwd>/config/.primitive-sync.json` exists. Per F4 of the approved
+ * plan, this is the only project-shape signal we use; we deliberately
+ * do not fall back to `package.json` or `.git` to avoid nagging users
+ * who run the CLI for read-only commands from incidental project
+ * directories.
+ */
+function isProjectShaped(cwd) {
+    try {
+        return existsSync(join(cwd, "config", ".primitive-sync.json"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Print the legacy-mode migration nag if the detection signal matches
+ * and no suppression condition applies. Never throws.
+ */
+export function maybeWarnLegacyMigration(options) {
+    try {
+        // --- Fast suppression checks (no disk I/O) ---------------------------
+        if (process.env.PRIMITIVE_NO_MIGRATE_NAG === "1")
+            return;
+        if (process.env.CI)
+            return;
+        if (!process.stdout.isTTY)
+            return;
+        if (shouldSuppressByArgv(options.argv))
+            return;
+        const cwd = options.cwd ?? process.cwd();
+        // --- Detection signal -------------------------------------------------
+        if (!isProjectShaped(cwd))
+            return;
+        if (findProjectConfigPath(cwd) !== null)
+            return;
+        if (peekLegacyCredentials() === null)
+            return;
+        // --- Rate-limit -------------------------------------------------------
+        const cache = loadNagCache();
+        const now = Date.now();
+        if (cache && now - cache.lastWarnedAt < NAG_INTERVAL_MS)
+            return;
+        // --- Print --------------------------------------------------------------
+        warn("Legacy CLI config detected at ~/.primitive/credentials.json.");
+        warn("Run `primitive env add <name> --api-url <url> --app-id <appId>` to upgrade to project-scoped config (see issue #548 for why). Set PRIMITIVE_NO_MIGRATE_NAG=1 to silence.");
+        saveNagCache({ lastWarnedAt: now });
+    }
+    catch {
+        // Never let nag errors affect CLI operation — mirrors version-check.ts.
+    }
+}
+//# sourceMappingURL=migration-nag.js.map

package/dist/src/lib/migration-nag.js.map

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

package/dist/src/lib/object-status-filter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `--status` on a list of one of the five carrying types (issue #2803).
+ *
+ * The filter travels to the server as a query parameter and the server filters
+ * on the CANONICAL value, so `--status paused` matched nothing and exited 0 —
+ * an empty table that reads as "there are none" rather than "that word is gone".
+ * The retired spellings therefore get the same treatment as a retired TOML key:
+ * a refusal naming what replaced them, not silence. An unknown word gets the
+ * vocabulary, because a typo answered with an empty list is the same trap.
+ *
+ * Pure: no network, no config. The list commands call it before their first
+ * request, so the refusal costs nothing and reads the same offline.
+ */
+/** The availability vocabulary. `archived` only for types whose delete writes it. */
+export type ObjectStatusFilter = "active" | "inactive" | "archived";
+/**
+ * Validate a `--status` value for `noun`, or throw with guidance.
+ *
+ * Returns the value to send (lower-cased), or `undefined` when the flag was
+ * not given.
+ */
+export declare function parseStatusFilter(noun: string, value: string | undefined, vocabulary: readonly ObjectStatusFilter[]): string | undefined;

package/dist/src/lib/object-status-filter.js

@@ -0,0 +1,45 @@
+/**
+ * `--status` on a list of one of the five carrying types (issue #2803).
+ *
+ * The filter travels to the server as a query parameter and the server filters
+ * on the CANONICAL value, so `--status paused` matched nothing and exited 0 —
+ * an empty table that reads as "there are none" rather than "that word is gone".
+ * The retired spellings therefore get the same treatment as a retired TOML key:
+ * a refusal naming what replaced them, not silence. An unknown word gets the
+ * vocabulary, because a typo answered with an empty list is the same trap.
+ *
+ * Pure: no network, no config. The list commands call it before their first
+ * request, so the refusal costs nothing and reads the same offline.
+ */
+/** What a retired spelling means now, per the value the operator typed. */
+const RETIRED = {
+    // Webhooks and cron triggers spelled "out of service" as `paused`.
+    paused: "inactive",
+    // Cron triggers escalated to `error_paused`; the reason now lives in
+    // `lastError` beside a plain `inactive`.
+    error_paused: "inactive",
+    // Workflows, integrations and prompts had a `draft` state. Nothing does.
+    draft: "inactive",
+};
+/**
+ * Validate a `--status` value for `noun`, or throw with guidance.
+ *
+ * Returns the value to send (lower-cased), or `undefined` when the flag was
+ * not given.
+ */
+export function parseStatusFilter(noun, value, vocabulary) {
+    if (value === undefined)
+        return undefined;
+    const normalized = String(value).trim().toLowerCase();
+    if (vocabulary.includes(normalized))
+        return normalized;
+    const offered = vocabulary.join(", ");
+    const replacement = RETIRED[normalized];
+    if (replacement) {
+        throw new Error(`--status ${normalized} no longer exists (#2803). Use --status ${replacement} — ` +
+            `it matches rows still storing the old value. Availability is changed with ` +
+            `\`primitive ${noun} enable|disable\`.`);
+    }
+    throw new Error(`--status must be one of: ${offered} (got "${value}").`);
+}
+//# sourceMappingURL=object-status-filter.js.map

package/dist/src/lib/object-status-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-status-filter.js","sourceRoot":"","sources":["../../../src/lib/object-status-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,2EAA2E;AAC3E,MAAM,OAAO,GAA2B;IACtC,mEAAmE;IACnE,MAAM,EAAE,UAAU;IAClB,qEAAqE;IACrE,yCAAyC;IACzC,YAAY,EAAE,UAAU;IACxB,yEAAyE;IACzE,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,KAAyB,EACzB,UAAyC;IAEzC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACtD,IAAK,UAAgC,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAE9E,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,YAAY,UAAU,2CAA2C,WAAW,KAAK;YAC/E,4EAA4E;YAC5E,eAAe,IAAI,oBAAoB,CAC1C,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,4BAA4B,OAAO,UAAU,KAAK,KAAK,CAAC,CAAC;AAC3E,CAAC"}

package/dist/src/lib/output.d.ts

@@ -0,0 +1,109 @@
+export interface TableColumn {
+    header: string;
+    key: string;
+    width?: number;
+    /**
+     * Opt-in flexible sizing (#1065). When `true`, the column is sized from the
+     * remaining terminal width (`options.maxWidth ?? process.stdout.columns`)
+     * minus the sibling columns' widths and the inter-column padding, so the
+     * table shows as much of this column as fits **without wrapping**. Clamped to
+     * `[max(flexFloor, header length), flexMax]`. On a non-TTY (`maxWidth`
+     * undefined — piped/redirected) there is no width to wrap against, so the
+     * column is sized to `flexMax` (or its content width when `flexMax` is
+     * unset). Reading the terminal width is gated to flex columns: tables with no
+     * flex column never consult `process.stdout.columns` and stay byte-for-byte
+     * (and TTY-) unchanged.
+     */
+    flex?: boolean;
+    /** Minimum width for a `flex` column. Default 0 (header length is always honored). */
+    flexFloor?: number;
+    /** Maximum width for a `flex` column. Default unbounded. */
+    flexMax?: number;
+    align?: "left" | "right" | "center";
+    format?: (value: any) => string;
+    /**
+     * Opt-in truncation. When `true` (and the column has a resolved width — a
+     * fixed `width` or a computed `flex` width), cell values longer than that
+     * width are ellipsized to fit the column so downstream columns stay aligned.
+     * Defaults to `false` so existing tables keep their current non-truncating
+     * behavior — only columns that explicitly opt in are clipped.
+     */
+    truncate?: boolean;
+}
+export declare function formatTable(data: Record<string, any>[], columns: TableColumn[], options?: {
+    maxWidth?: number;
+}): string;
+export declare function success(message: string): void;
+export declare function error(message: string): void;
+/**
+ * Render an API error (or any Error) with its message plus the server's
+ * structured `details` payload, if present. Shared by `config push`,
+ * `workflows create`/`update`, and any command that surfaces server-side
+ * validation failures (#1173).
+ *
+ * The server's error envelope can emit `details` as either:
+ *   - an **array** of validation-issue strings/objects (e.g. the workflow
+ *     identity validator's per-step reasons), or
+ *   - an **object** (#666 schema gate — `{ code, ... }`).
+ *
+ * Both shapes are rendered without throwing; an absent/empty `details` prints
+ * just the message. Duck-typed (reads `.message`/`.details`) so it works on
+ * any `ApiError` instance without importing the class — keeping `output.ts`
+ * dependency-free.
+ */
+export declare function printApiError(err: unknown): void;
+export declare function warn(message: string): void;
+export declare function info(message: string): void;
+export declare function dim(message: string): void;
+export declare function heading(message: string): void;
+export declare function json(data: any): void;
+/**
+ * Print one compact JSON object on its own line (NDJSON) to stdout.
+ *
+ * A documented exception to the "single parseable JSON document" stdout rule
+ * above (issue #695): a `--follow` tail is an unbounded stream, so it cannot be
+ * one array — it emits one object per row per line, which a consumer reads with
+ * `jq -c` line by line. `--json --watch` still emits one array per redraw via
+ * `json()`; only the append-only follow stream uses `jsonLine`.
+ */
+export declare function jsonLine(obj: unknown): void;
+export declare function formatDate(date: string | Date | null | undefined): string;
+/**
+ * Colour a status value for terminal output. Covers both the resource
+ * lifecycle statuses (draft/active/archived/deprecated) and the canonical
+ * workflow-run vocabulary from `lib/run-status.ts` (#2348), which every run
+ * status surface now reports:
+ *
+ *   queued, running, apply_pending, apply_claimed,
+ *   completed, failed, terminated, missing, skipped
+ *
+ * `terminated`, `queued`, the two apply-flow states and `missing` used to fall
+ * through to the uncoloured default, so an aborted run and a parked run read
+ * exactly like an unknown value.
+ */
+export declare function formatStatus(status: string | undefined | null): string;
+export declare function formatId(id: string): string;
+export declare function formatBoolean(value: boolean | undefined | null): string;
+export declare function formatNumber(value: number | undefined | null): string;
+export declare function formatDuration(ms: number | undefined | null): string;
+export declare function formatPercent(value: number | undefined | null): string;
+export declare function keyValue(label: string, value: string | number | boolean | null | undefined): void;
+/**
+ * Print a `label: value` line on **stdout** as part of a command's primary
+ * data output (e.g., `primitive integrations get <id>`,
+ * `primitive workflows get <id>`). Same visual rendering as `keyValue()`,
+ * but on the data stream so the value survives `> out.txt` redirection.
+ *
+ * Use `keyValue()` (stderr) for post-action diagnostic summaries; use
+ * `result()` (stdout) for fields the caller specifically requested.
+ */
+export declare function result(label: string, value: string | number | boolean | null | undefined): void;
+export declare function divider(): void;
+/**
+ * In-place progress indicator for long-running commands (e.g. polling a
+ * batch run). Writes to stderr so it can't corrupt JSON on stdout under
+ * `--json`. Callers should follow the final progress line with `progressEnd()`
+ * to print a trailing newline.
+ */
+export declare function progress(message: string): void;
+export declare function progressEnd(): void;

package/dist/src/lib/output.js

@@ -1,5 +1,24 @@
 import chalk from "chalk";
-export function formatTable(data, columns) {
+/**
+ * Ellipsize `str` (its visible, ANSI-stripped length) to at most `width`
+ * characters. Strings already within `width` are returned unchanged. Very
+ * narrow widths still keep a sensible result: width 1-3 returns leading dots.
+ *
+ * NOTE: assumes the value carries no ANSI styling (the only opt-in caller —
+ * the guides DESCRIPTION column — passes plain strings). Truncating mid-escape
+ * would corrupt styling, so truncation is opt-in per column rather than global.
+ */
+function truncateToWidth(str, width) {
+    const stripped = stripAnsi(str);
+    if (stripped.length <= width)
+        return str;
+    if (width <= 0)
+        return "";
+    if (width <= 3)
+        return ".".repeat(width);
+    return stripped.slice(0, width - 1) + "…";
+}
+export function formatTable(data, columns, options) {
     if (data.length === 0) {
         return chalk.dim("No results found.");
     }
@@ -12,6 +31,33 @@ export function formatTable(data, columns) {
         }));
         return col.width ?? Math.max(headerWidth, maxDataWidth);
     });
+    // Flex pass (#1065): size the first column marked `flex` from the remaining
+    // terminal width so the table shows as much as fits without ever wrapping.
+    // The sibling widths above are already content-derived, so subtracting their
+    // ACTUAL widths plus the exact `2 * (N - 1)` inter-column padding makes the
+    // no-wrap guarantee structural rather than maintained by hand. Gated to flex
+    // columns so non-flex tables never read `process.stdout.columns`.
+    const flexIndex = columns.findIndex((col) => col.flex);
+    if (flexIndex !== -1) {
+        const col = columns[flexIndex];
+        const floor = Math.max(col.flexFloor ?? 0, col.header.length);
+        const cap = col.flexMax ?? Infinity;
+        const maxWidth = options?.maxWidth ?? process.stdout.columns;
+        if (typeof maxWidth === "number") {
+            const siblingWidth = widths.reduce((sum, w, i) => (i === flexIndex ? sum : sum + w), 0);
+            const padding = 2 * (columns.length - 1);
+            const avail = maxWidth - siblingWidth - padding;
+            // Clamp to [floor, cap]; never below the floor (so the header/min content
+            // stays readable) and never negative.
+            widths[flexIndex] = Math.min(cap, Math.max(floor, avail));
+        }
+        else {
+            // Non-TTY (piped/redirected): no terminal width to wrap against. Show as
+            // much as the cap allows — full content up to the contract max — falling
+            // back to the content-derived width when no cap is set.
+            widths[flexIndex] = cap === Infinity ? widths[flexIndex] : cap;
+        }
+    }
     // Format header
     const header = columns
         .map((col, i) => {
@@ -24,7 +70,13 @@ export function formatTable(data, columns) {
     // Format rows
     const rows = data.map((row) => columns
         .map((col, i) => {
-        const value = col.format ? col.format(row[col.key]) : String(row[col.key] ?? "");
+        let value = col.format ? col.format(row[col.key]) : String(row[col.key] ?? "");
+        // Opt-in: clip over-long cells to the column's resolved width (a fixed
+        // `width` or a computed `flex` width) so the columns that follow stay
+        // aligned (e.g. guides DESCRIPTION before LANGUAGES).
+        if (col.truncate && (col.width !== undefined || col.flex)) {
+            value = truncateToWidth(value, widths[i]);
+        }
         return padString(value, widths[i], col.align ?? "left");
     })
         .join("  "));
@@ -47,33 +99,119 @@ function stripAnsi(str) {
     // Simple ANSI escape code stripper
     return str.replace(/\x1b\[[0-9;]*m/g, "");
 }
+// Stream-routing convention (see issue #695):
+//   - data → stdout (`json`, `result`, plus the formatter helpers below
+//     that just return strings for callers to print themselves).
+//   - diagnostics → stderr (`success`, `warn`, `info`, `dim`, `heading`,
+//     `keyValue`, `divider`, `error`).
+//
+// This mirrors `git`/`kubectl`/`aws`/`gh` so that any command with a `--json`
+// flag emits a single parseable JSON document on stdout, regardless of
+// status, warning, or progress text the same command may print. Callers
+// running interactively still see diagnostics by default because terminals
+// display stderr; users redirecting `2>/dev/null` get a quiet pipe; users
+// running `2>&1` get everything mixed.
+//
+// `result()` vs. `keyValue()` (data vs. diagnostic split):
+//   `keyValue()` is a *diagnostic* helper — use it for the `key: value`
+//   summary lines printed *after* a side-effecting command like `apps create`,
+//   `workflows update`, or `secrets set` (those summaries are nice context but
+//   are not what the caller asked the command to produce). `result()` is the
+//   *data* counterpart — use it for the primary fields a `get` / `show` /
+//   `describe` command emits, where the caller ran the command specifically
+//   to read those fields. Keeping the two on different streams means
+//   `primitive integrations get foo > out.txt` produces a non-empty `out.txt`
+//   even though the same command's status diagnostics still go to stderr.
 export function success(message) {
-    console.log(chalk.green("✓") + " " + message);
+    console.error(chalk.green("✓") + " " + message);
 }
 export function error(message) {
     console.error(chalk.red("✗") + " " + message);
 }
+/**
+ * Render an API error (or any Error) with its message plus the server's
+ * structured `details` payload, if present. Shared by `config push`,
+ * `workflows create`/`update`, and any command that surfaces server-side
+ * validation failures (#1173).
+ *
+ * The server's error envelope can emit `details` as either:
+ *   - an **array** of validation-issue strings/objects (e.g. the workflow
+ *     identity validator's per-step reasons), or
+ *   - an **object** (#666 schema gate — `{ code, ... }`).
+ *
+ * Both shapes are rendered without throwing; an absent/empty `details` prints
+ * just the message. Duck-typed (reads `.message`/`.details`) so it works on
+ * any `ApiError` instance without importing the class — keeping `output.ts`
+ * dependency-free.
+ */
+export function printApiError(err) {
+    const e = err;
+    const message = typeof e?.message === "string" && e.message.length > 0
+        ? e.message
+        : String(err);
+    error(message);
+    const details = e?.details;
+    if (Array.isArray(details)) {
+        for (const detail of details) {
+            console.error(`    - ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
+        }
+    }
+    else if (details && typeof details === "object") {
+        // Object form (#666 schema gate): render each key so the reason isn't
+        // hidden. Skip the redundant `code` (already implied by the message).
+        for (const [key, value] of Object.entries(details)) {
+            if (key === "code")
+                continue;
+            console.error(`    ${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+        }
+    }
+}
 export function warn(message) {
-    console.log(chalk.yellow("!") + " " + message);
+    console.error(chalk.yellow("!") + " " + message);
 }
 export function info(message) {
-    console.log(chalk.blue("i") + " " + message);
+    console.error(chalk.blue("i") + " " + message);
 }
 export function dim(message) {
-    console.log(chalk.dim(message));
+    console.error(chalk.dim(message));
 }
 export function heading(message) {
-    console.log(chalk.bold.underline(message));
+    console.error(chalk.bold.underline(message));
 }
 export function json(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+/**
+ * Print one compact JSON object on its own line (NDJSON) to stdout.
+ *
+ * A documented exception to the "single parseable JSON document" stdout rule
+ * above (issue #695): a `--follow` tail is an unbounded stream, so it cannot be
+ * one array — it emits one object per row per line, which a consumer reads with
+ * `jq -c` line by line. `--json --watch` still emits one array per redraw via
+ * `json()`; only the append-only follow stream uses `jsonLine`.
+ */
+export function jsonLine(obj) {
+    console.log(JSON.stringify(obj));
+}
 export function formatDate(date) {
     if (!date)
         return chalk.dim("-");
     const d = new Date(date);
     return d.toISOString().replace("T", " ").slice(0, 19);
 }
+/**
+ * Colour a status value for terminal output. Covers both the resource
+ * lifecycle statuses (draft/active/archived/deprecated) and the canonical
+ * workflow-run vocabulary from `lib/run-status.ts` (#2348), which every run
+ * status surface now reports:
+ *
+ *   queued, running, apply_pending, apply_claimed,
+ *   completed, failed, terminated, missing, skipped
+ *
+ * `terminated`, `queued`, the two apply-flow states and `missing` used to fall
+ * through to the uncoloured default, so an aborted run and a parked run read
+ * exactly like an unknown value.
+ */
 export function formatStatus(status) {
     if (!status)
         return "-";
@@ -90,8 +228,24 @@ export function formatStatus(status) {
         case "running":
         case "pending":
             return chalk.blue(status);
+        case "queued":
+            return chalk.cyan(status);
+        // Finished executing, parked waiting for a client to claim/apply.
+        case "apply_pending":
+        case "apply_claimed":
+            return chalk.magenta(status);
         case "failed":
             return chalk.red(status);
+        // Aborted before completion — an end state, but not a failure.
+        case "terminated":
+            return chalk.gray(status);
+        // No live instance to report on.
+        case "missing":
+            return chalk.yellow(status);
+        // #2636 — the run never ran: its declarative lock was held and the
+        // definition declared `onContention: "ignore"`. An outcome, not a failure.
+        case "skipped":
+            return chalk.dim.cyan(status);
         default:
             return status;
     }
@@ -130,6 +284,23 @@ export function formatPercent(value) {
     return `${(value * 100).toFixed(1)}%`;
 }
 export function keyValue(label, value) {
+    const formattedValue = value === null || value === undefined
+        ? chalk.dim("-")
+        : typeof value === "boolean"
+            ? formatBoolean(value)
+            : String(value);
+    console.error(`${chalk.dim(label + ":")} ${formattedValue}`);
+}
+/**
+ * Print a `label: value` line on **stdout** as part of a command's primary
+ * data output (e.g., `primitive integrations get <id>`,
+ * `primitive workflows get <id>`). Same visual rendering as `keyValue()`,
+ * but on the data stream so the value survives `> out.txt` redirection.
+ *
+ * Use `keyValue()` (stderr) for post-action diagnostic summaries; use
+ * `result()` (stdout) for fields the caller specifically requested.
+ */
+export function result(label, value) {
     const formattedValue = value === null || value === undefined
         ? chalk.dim("-")
         : typeof value === "boolean"
@@ -138,6 +309,18 @@ export function keyValue(label, value) {
     console.log(`${chalk.dim(label + ":")} ${formattedValue}`);
 }
 export function divider() {
-    console.log(chalk.dim("-".repeat(60)));
+    console.error(chalk.dim("-".repeat(60)));
+}
+/**
+ * In-place progress indicator for long-running commands (e.g. polling a
+ * batch run). Writes to stderr so it can't corrupt JSON on stdout under
+ * `--json`. Callers should follow the final progress line with `progressEnd()`
+ * to print a trailing newline.
+ */
+export function progress(message) {
+    process.stderr.write(`\r${message}`);
+}
+export function progressEnd() {
+    process.stderr.write("\n");
 }
 //# sourceMappingURL=output.js.map