@mx-space/cli 0.14.2 → 0.15.1

package/dist/src/services/Migration.js

@@ -0,0 +1,177 @@
+import { FileSystem } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+import { ConfigMigrationFailed } from '../domain/errors';
+import { Config, stripLegacyConfigFields } from './Config';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const emit = (report, line) => {
+    if (report === null)
+        return;
+    if (report !== undefined) {
+        report(line);
+        return;
+    }
+    process.stderr.write(`${line}\n`);
+};
+const isNotFound = (err) => {
+    if (typeof err === 'object' && err !== null) {
+        const e = err;
+        if (e._tag === 'SystemError' && e.reason === 'NotFound')
+            return true;
+        if (e.code === 'ENOENT')
+            return true;
+    }
+    return false;
+};
+const fileExists = (fs, path) => fs.stat(path).pipe(Effect.map(() => true), Effect.catchAll((err) => isNotFound(err)
+    ? Effect.succeed(false)
+    : Effect.fail(new ConfigMigrationFailed({
+        message: `failed to stat ${path}: ${String(err)}`,
+        cause: err,
+    }))));
+const dirExists = (fs, path) => fs.stat(path).pipe(Effect.map((info) => info.type === 'Directory'), Effect.catchAll((err) => isNotFound(err)
+    ? Effect.succeed(false)
+    : Effect.fail(new ConfigMigrationFailed({
+        message: `failed to stat ${path}: ${String(err)}`,
+        cause: err,
+    }))));
+const tryUnlink = (fs, path, report) => fs.remove(path, { force: true }).pipe(Effect.catchAll((err) => {
+    if (isNotFound(err))
+        return Effect.void;
+    emit(report, `mxs: warning: could not remove stale legacy file ${path}: ${err.message ?? String(err)}`);
+    return Effect.void;
+}));
+// `@clack/prompts` exports a `cancel` symbol; matching by `typeof v === 'symbol'`
+// covers both the real symbol and test fixtures. Inlined here so the migration
+// service does not pull in `@clack/prompts` (the prompt callback is injected
+// at the call site).
+const isCancel = (v) => typeof v === 'symbol';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+const make = Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const config = yield* Config;
+    const runLegacyMigrationIfNeeded = (opts) => Effect.gen(function* () {
+        const report = opts?.report;
+        const legacyConfigPath = yield* config.getLegacyConfigPath;
+        const legacyCredentialsPath = yield* config.getLegacyCredentialsPath;
+        const profilesDir = yield* config.getProfilesDir;
+        const hasConfig = yield* fileExists(fs, legacyConfigPath);
+        const hasCreds = yield* fileExists(fs, legacyCredentialsPath);
+        // Fast path: nothing to migrate.
+        if (!hasConfig && !hasCreds)
+            return null;
+        const profilesExist = yield* dirExists(fs, profilesDir);
+        // Stale-cleanup branch.
+        if (profilesExist) {
+            const toRemove = [];
+            if (hasConfig)
+                toRemove.push(legacyConfigPath);
+            if (hasCreds)
+                toRemove.push(legacyCredentialsPath);
+            for (const p of toRemove) {
+                yield* tryUnlink(fs, p, report);
+            }
+            emit(report, `mxs: removed stale legacy config files at ${toRemove.join(', ')}`);
+            return {
+                profile: null,
+                production: false,
+                cleanedStaleLegacy: true,
+            };
+        }
+        // Full migration branch.
+        let legacyConfig = {};
+        if (hasConfig) {
+            const raw = yield* fs.readFileString(legacyConfigPath).pipe(Effect.catchAll((err) => Effect.fail(new ConfigMigrationFailed({
+                message: `failed to read legacy config at ${legacyConfigPath}: ${String(err)}`,
+                cause: err,
+            }))));
+            try {
+                legacyConfig = JSON.parse(raw);
+            }
+            catch (err) {
+                return yield* Effect.fail(new ConfigMigrationFailed({
+                    message: `failed to read legacy config at ${legacyConfigPath}: ${err.message}`,
+                    cause: err,
+                }));
+            }
+        }
+        let legacyCredentials = null;
+        if (hasCreds) {
+            const raw = yield* fs.readFileString(legacyCredentialsPath).pipe(Effect.catchAll((err) => Effect.fail(new ConfigMigrationFailed({
+                message: `failed to read legacy credentials at ${legacyCredentialsPath}: ${String(err)}`,
+                cause: err,
+            }))));
+            try {
+                legacyCredentials = JSON.parse(raw);
+            }
+            catch (err) {
+                return yield* Effect.fail(new ConfigMigrationFailed({
+                    message: `failed to read legacy credentials at ${legacyCredentialsPath}: ${err.message}`,
+                    cause: err,
+                }));
+            }
+        }
+        let production = false;
+        const tty = opts?.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        const apiUrl = typeof legacyConfig.api_url === 'string'
+            ? legacyConfig.api_url
+            : undefined;
+        if (tty && apiUrl && opts?.promptIsProduction) {
+            const answer = yield* Effect.tryPromise({
+                try: () => opts.promptIsProduction(apiUrl),
+                catch: (err) => new ConfigMigrationFailed({
+                    message: `legacy migration prompt failed: ${String(err)}`,
+                    cause: err,
+                }),
+            });
+            production = isCancel(answer) ? false : Boolean(answer);
+        }
+        // Strip legacy fields and apply production flag.
+        const migratedConfig = {
+            ...stripLegacyConfigFields(legacyConfig),
+        };
+        if (production) {
+            migratedConfig.production = true;
+        }
+        else {
+            delete migratedConfig.production;
+        }
+        yield* config.writeProfileConfig('default', migratedConfig).pipe(Effect.catchAll((err) => Effect.fail(new ConfigMigrationFailed({
+            message: `failed to write profile config during migration: ${String(err)}`,
+            cause: err,
+        }))));
+        if (legacyCredentials !== null) {
+            yield* config
+                .writeProfileCredentials('default', legacyCredentials)
+                .pipe(Effect.catchAll((err) => Effect.fail(new ConfigMigrationFailed({
+                message: `failed to write profile credentials during migration: ${String(err)}`,
+                cause: err,
+            }))));
+        }
+        // Point `current` at the new default profile before unlinking legacy
+        // files, so a crash mid-migration leaves the user with a recoverable
+        // state.
+        yield* config.writeCurrent('default').pipe(Effect.catchAll((err) => Effect.fail(new ConfigMigrationFailed({
+            message: `failed to set current profile to default: ${String(err)}`,
+            cause: err,
+        }))));
+        if (hasConfig)
+            yield* tryUnlink(fs, legacyConfigPath, report);
+        if (hasCreds)
+            yield* tryUnlink(fs, legacyCredentialsPath, report);
+        emit(report, `mxs: migrated single-profile config to profile 'default'.`);
+        return {
+            profile: 'default',
+            production,
+            cleanedStaleLegacy: false,
+        };
+    });
+    const svc = { runLegacyMigrationIfNeeded };
+    return svc;
+});
+export class Migration extends Context.Tag('Migration')() {
+    static Default = Layer.effect(Migration, make);
+}

package/dist/src/services/Profile.d.ts

@@ -0,0 +1,29 @@
+import { Context, Effect, Layer } from 'effect';
+import { Generic, ProfileInvalidName, ProfileNotFound, ResourceNotFound } from '../domain/errors';
+import { Config, type ConfigShape, type ResolvedConfig, type StoreOverrides } from './Config';
+export declare const PROFILE_NAME_RE: RegExp;
+export declare const RESERVED_PROFILE_NAMES: Set<string>;
+export interface ProfileSummary {
+    readonly name: string;
+    readonly apiUrl?: string;
+    readonly production: boolean;
+    readonly authenticated: boolean;
+    readonly active: boolean;
+}
+export interface ProfileService {
+    readonly validateName: (name: string) => Effect.Effect<void, ProfileInvalidName>;
+    readonly list: Effect.Effect<readonly string[], Generic>;
+    readonly current: Effect.Effect<string | null, Generic>;
+    readonly use: (name: string) => Effect.Effect<void, ProfileInvalidName | ProfileNotFound | Generic>;
+    readonly mark: (name: string, update: {
+        readonly production?: boolean;
+    }) => Effect.Effect<ConfigShape, ProfileNotFound | Generic>;
+    readonly rm: (name: string) => Effect.Effect<void, ResourceNotFound | Generic>;
+    readonly show: (name: string) => Effect.Effect<ProfileSummary, ProfileNotFound | Generic>;
+    readonly resolve: (overrides?: StoreOverrides) => Effect.Effect<ResolvedConfig, ProfileNotFound | Generic>;
+}
+declare const Profile_base: Context.TagClass<Profile, "Profile", ProfileService>;
+export declare class Profile extends Profile_base {
+    static Default: Layer.Layer<Profile, never, Config>;
+}
+export {};

package/dist/src/services/Profile.js

@@ -0,0 +1,115 @@
+import { Context, Effect, Layer } from 'effect';
+import { Generic, ProfileInvalidName, ProfileNotFound, ResourceNotFound, } from '../domain/errors';
+import { Config, } from './Config';
+// ---------------------------------------------------------------------------
+// Name validation
+// ---------------------------------------------------------------------------
+export const PROFILE_NAME_RE = /^[\d_a-z-]{1,32}$/;
+export const RESERVED_PROFILE_NAMES = new Set(['current']);
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+const make = Effect.gen(function* () {
+    const config = yield* Config;
+    const validateName = (name) => Effect.gen(function* () {
+        if (!name || name.length === 0) {
+            return yield* Effect.fail(new ProfileInvalidName({
+                name,
+                message: 'profile name must not be empty',
+            }));
+        }
+        if (RESERVED_PROFILE_NAMES.has(name)) {
+            return yield* Effect.fail(new ProfileInvalidName({
+                name,
+                message: `profile name '${name}' is reserved`,
+            }));
+        }
+        if (!PROFILE_NAME_RE.test(name)) {
+            return yield* Effect.fail(new ProfileInvalidName({
+                name,
+                message: `profile name '${name}' is invalid; must match ^[a-z0-9_-]{1,32}$`,
+            }));
+        }
+    });
+    const list = config.listProfileDirs;
+    const current = config.readCurrent;
+    const use = (name) => Effect.gen(function* () {
+        yield* validateName(name);
+        const exists = yield* config.profileExists(name);
+        if (!exists) {
+            return yield* Effect.fail(new ProfileNotFound({
+                name,
+                message: `profile '${name}' does not exist`,
+            }));
+        }
+        yield* config.writeCurrent(name);
+    });
+    const mark = (name, update) => Effect.gen(function* () {
+        const exists = yield* config.profileExists(name);
+        if (!exists) {
+            return yield* Effect.fail(new ProfileNotFound({
+                name,
+                message: `profile '${name}' does not exist`,
+            }));
+        }
+        return yield* config.updateProfileConfig(name, (prev) => {
+            const next = { ...prev };
+            if (update.production === undefined)
+                return next;
+            if (update.production) {
+                return { ...next, production: true };
+            }
+            const stripped = { ...next };
+            delete stripped.production;
+            return stripped;
+        });
+    });
+    const rm = (name) => Effect.gen(function* () {
+        const exists = yield* config.profileExists(name);
+        if (!exists) {
+            return yield* Effect.fail(new ResourceNotFound({
+                kind: 'profile',
+                ref: name,
+                message: `profile '${name}' does not exist`,
+            }));
+        }
+        yield* config.removeProfileDir(name);
+    });
+    const show = (name) => Effect.gen(function* () {
+        const exists = yield* config.profileExists(name);
+        if (!exists) {
+            return yield* Effect.fail(new ProfileNotFound({
+                name,
+                message: `profile '${name}' does not exist`,
+            }));
+        }
+        const cfg = yield* config.readProfileConfig(name);
+        const creds = yield* config.readProfileCredentials(name);
+        const active = (yield* config.readCurrent) === name;
+        return {
+            name,
+            apiUrl: cfg.api_url,
+            production: Boolean(cfg.production),
+            authenticated: creds !== null,
+            active,
+        };
+    });
+    const resolve = (overrides) => config.resolve(overrides).pipe(Effect.catchTags({
+        ConfigMissingApiUrl: (e) => Effect.fail(new Generic({ message: e.message, cause: e })),
+        ConfigMigrationFailed: (e) => Effect.fail(new Generic({ message: e.message, cause: e })),
+    }));
+    const svc = {
+        validateName,
+        list,
+        current,
+        use,
+        mark,
+        rm,
+        show,
+        resolve,
+    };
+    return svc;
+});
+export class Profile extends Context.Tag('Profile')() {
+    static Default = Layer.effect(Profile, make);
+}

package/dist/src/services/Renderer/content.d.ts

@@ -0,0 +1,16 @@
+export declare const asRecord: (value: unknown) => Record<string, unknown>;
+export declare const first: (record: Record<string, unknown>, ...keys: string[]) => unknown;
+export declare const firstString: (record: Record<string, unknown>, ...keys: string[]) => string;
+export declare const contentFormat: (doc: Record<string, unknown>) => string;
+export declare const publishState: (doc: Record<string, unknown>) => string | undefined;
+export declare const relationLabel: (value: unknown) => string | undefined;
+export declare const relationSlugOrLabel: (value: unknown) => string | undefined;
+export declare const formatScalar: (value: unknown) => string;
+export declare const escapeXml: (value: string) => string;
+export declare const unwrapDocument: (data: unknown) => unknown;
+export declare const pickArticleTranslationMeta: (payload: unknown, docId: unknown) => Record<string, unknown> | undefined;
+export declare const tryLexicalToLitexml: (jsonStr: string) => string | null;
+export declare const renderContent: (doc: Record<string, unknown>, llm?: boolean) => {
+    body: string;
+    format: "litexml" | "markdown" | "text";
+};

package/dist/src/services/Renderer/content.js

@@ -0,0 +1,110 @@
+import { serializeMxLexicalToLitexml, stripMxLitexmlDocWrapper, } from '@mx-space/editor';
+export const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+export const first = (record, ...keys) => {
+    for (const key of keys) {
+        if (record[key] !== undefined && record[key] !== null)
+            return record[key];
+    }
+    return undefined;
+};
+export const firstString = (record, ...keys) => {
+    const value = first(record, ...keys);
+    return typeof value === 'string' ? value : '';
+};
+export const contentFormat = (doc) => {
+    const value = first(doc, 'content_format', 'contentFormat');
+    return typeof value === 'string' ? value : 'markdown';
+};
+export const publishState = (doc) => {
+    const value = first(doc, 'is_published', 'isPublished');
+    if (typeof value === 'boolean')
+        return value ? 'published' : 'draft';
+    return undefined;
+};
+export const relationLabel = (value) => {
+    if (!value)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    const obj = asRecord(value);
+    return (firstString(obj, 'name') ||
+        firstString(obj, 'slug') ||
+        firstString(obj, 'id'));
+};
+export const relationSlugOrLabel = (value) => {
+    if (!value)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    const obj = asRecord(value);
+    return (firstString(obj, 'slug') ||
+        firstString(obj, 'name') ||
+        firstString(obj, 'id'));
+};
+export const formatScalar = (value) => {
+    if (Array.isArray(value))
+        return value.map(formatScalar).join(', ');
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'object' && value !== null)
+        return JSON.stringify(value);
+    return String(value);
+};
+export const escapeXml = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+export const unwrapDocument = (data) => {
+    const obj = asRecord(data);
+    const nested = obj.data;
+    if (nested && typeof nested === 'object' && !Array.isArray(nested))
+        return nested;
+    return data;
+};
+export const pickArticleTranslationMeta = (payload, docId) => {
+    const translation = asRecord(asRecord(asRecord(payload).meta).translation);
+    if (Object.keys(translation).length === 0)
+        return undefined;
+    const direct = asRecord(translation.article);
+    if (Object.keys(direct).length > 0)
+        return direct;
+    if (docId === undefined || docId === null)
+        return undefined;
+    const entry = asRecord(translation[String(docId)]);
+    const article = asRecord(entry.article);
+    return Object.keys(article).length > 0 ? article : undefined;
+};
+export const tryLexicalToLitexml = (jsonStr) => {
+    try {
+        const parsed = JSON.parse(jsonStr);
+        const xml = serializeMxLexicalToLitexml(parsed, { compact: false });
+        return stripMxLitexmlDocWrapper(xml).trim();
+    }
+    catch {
+        return null;
+    }
+};
+export const renderContent = (doc, llm = false) => {
+    const format = contentFormat(doc);
+    const content = firstString(doc, 'content');
+    const text = firstString(doc, 'text');
+    if (format === 'lexical' && content) {
+        // For LLM consumers, prefer the plain `text` field over litexml — easier
+        // to parse and free of markup boilerplate.
+        if (llm) {
+            if (text)
+                return { body: text, format: 'text' };
+            const xml = tryLexicalToLitexml(content);
+            return xml !== null
+                ? { body: xml, format: 'litexml' }
+                : { body: content, format: 'text' };
+        }
+        const xml = tryLexicalToLitexml(content);
+        if (xml !== null)
+            return { body: xml, format: 'litexml' };
+        return { body: text || content, format: text ? 'text' : 'markdown' };
+    }
+    return {
+        body: content || text || '',
+        format: format === 'markdown' ? 'markdown' : 'text',
+    };
+};

package/dist/src/services/Renderer/datetime.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Coerce an arbitrary value (ISO string, epoch ms or s, Date) into a Date.
+ * Returns null when the value cannot be interpreted as a calendar time.
+ */
+export declare const toDate: (value: unknown) => Date | null;
+/** Local-time `YYYY-MM-DD HH:mm`. Seconds are dropped for readability. */
+export declare const formatAbsoluteDateTime: (date: Date) => string;
+/**
+ * Relative phrase versus `now` (default = the moment of the call).
+ * Bucketing uses the same thresholds as date-fns `formatDistance` so the
+ * output reads naturally without 1-minute precision noise.
+ */
+export declare const formatRelativeTime: (date: Date, now?: Date) => string;
+export type DateTimeStyle = 'abs' | 'rel' | 'both';
+export interface FormatDateTimeOptions {
+    /** `abs` (default) → `YYYY-MM-DD HH:mm`; `rel` → relative phrase; `both` → abs (rel). */
+    readonly style?: DateTimeStyle;
+    /** Shortcut for `style: 'both'`. */
+    readonly relative?: boolean;
+    /** Override "now" — primarily for tests. */
+    readonly now?: Date;
+}
+/**
+ * Format an arbitrary timestamp-shaped value for a readable view.
+ *
+ * Falls back to `String(value)` when the value cannot be parsed as a date,
+ * and to `''` when the value is nullish — letting the caller filter the
+ * field out instead of rendering `null` / `undefined`.
+ */
+export declare const formatDateTime: (value: unknown, opts?: FormatDateTimeOptions) => string;
+/** True when `value` is a `Date` or an ISO-8601-ish string. */
+export declare const looksLikeTimestamp: (value: unknown) => boolean;
+/**
+ * Format `value` as a human-friendly timestamp when it looks like one;
+ * return `null` otherwise so the caller can fall back to its scalar
+ * formatter without committing to the timestamp shape.
+ */
+export declare const tryFormatTimestamp: (value: unknown, opts?: FormatDateTimeOptions) => string | null;

package/dist/src/services/Renderer/datetime.js

@@ -0,0 +1,147 @@
+// ---------------------------------------------------------------------------
+// Human-friendly date/time formatting for readable CLI output.
+//
+// Why this file exists: the legacy renderers stringified API timestamps
+// directly, which left raw ISO 8601 like `2026-05-19T14:32:00.000Z` in
+// every `readable` field. That format is precise but hard to scan. The
+// helpers here keep ISO as a normalization step and emit a friendlier
+// surface form for human consumption.
+//
+// Two surface forms are exposed:
+//
+//   - `abs`  → `YYYY-MM-DD HH:mm` in the local timezone (default).
+//   - `rel`  → "3 days ago" / "in 2 hours".
+//   - `both` → `YYYY-MM-DD HH:mm (3 days ago)`.
+//
+// `--json` / `--pretty-json` are unaffected: those paths stringify the raw
+// data shape and never invoke the view layer.
+// ---------------------------------------------------------------------------
+const pad2 = (n) => String(n).padStart(2, '0');
+/**
+ * Coerce an arbitrary value (ISO string, epoch ms or s, Date) into a Date.
+ * Returns null when the value cannot be interpreted as a calendar time.
+ */
+export const toDate = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value <= 0)
+            return null;
+        // Heuristic: values below 1e12 are seconds since epoch (covers 2001+).
+        const ms = value < 1e12 ? value * 1000 : value;
+        const date = new Date(ms);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return null;
+        const date = new Date(trimmed);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    return null;
+};
+/** Local-time `YYYY-MM-DD HH:mm`. Seconds are dropped for readability. */
+export const formatAbsoluteDateTime = (date) => {
+    const y = date.getFullYear();
+    const m = pad2(date.getMonth() + 1);
+    const d = pad2(date.getDate());
+    const hh = pad2(date.getHours());
+    const mm = pad2(date.getMinutes());
+    return `${y}-${m}-${d} ${hh}:${mm}`;
+};
+const phrase = (count, unit, past) => {
+    const plural = count === 1 ? unit : `${unit}s`;
+    return past ? `${count} ${plural} ago` : `in ${count} ${plural}`;
+};
+/**
+ * Relative phrase versus `now` (default = the moment of the call).
+ * Bucketing uses the same thresholds as date-fns `formatDistance` so the
+ * output reads naturally without 1-minute precision noise.
+ */
+export const formatRelativeTime = (date, now = new Date()) => {
+    const diffMs = date.getTime() - now.getTime();
+    const past = diffMs < 0;
+    const seconds = Math.abs(diffMs) / 1000;
+    if (seconds < 45)
+        return past ? 'just now' : 'in a moment';
+    if (seconds < 90)
+        return phrase(1, 'minute', past);
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 45)
+        return phrase(minutes, 'minute', past);
+    if (minutes < 90)
+        return phrase(1, 'hour', past);
+    const hours = Math.round(minutes / 60);
+    if (hours < 22)
+        return phrase(hours, 'hour', past);
+    if (hours < 36)
+        return phrase(1, 'day', past);
+    const days = Math.round(hours / 24);
+    if (days < 7)
+        return phrase(days, 'day', past);
+    if (days < 11)
+        return phrase(1, 'week', past);
+    const weeks = Math.round(days / 7);
+    if (weeks < 5)
+        return phrase(weeks, 'week', past);
+    if (days < 60)
+        return phrase(1, 'month', past);
+    const months = Math.round(days / 30);
+    if (months < 12)
+        return phrase(months, 'month', past);
+    const years = Math.round(days / 365.25);
+    return phrase(years, 'year', past);
+};
+/**
+ * Format an arbitrary timestamp-shaped value for a readable view.
+ *
+ * Falls back to `String(value)` when the value cannot be parsed as a date,
+ * and to `''` when the value is nullish — letting the caller filter the
+ * field out instead of rendering `null` / `undefined`.
+ */
+export const formatDateTime = (value, opts = {}) => {
+    const date = toDate(value);
+    if (!date) {
+        if (value === null || value === undefined)
+            return '';
+        return String(value);
+    }
+    const style = opts.style ?? (opts.relative ? 'both' : 'abs');
+    if (style === 'rel')
+        return formatRelativeTime(date, opts.now);
+    const abs = formatAbsoluteDateTime(date);
+    if (style === 'both') {
+        const rel = formatRelativeTime(date, opts.now);
+        return rel ? `${abs} (${rel})` : abs;
+    }
+    return abs;
+};
+// ---------------------------------------------------------------------------
+// Auto-detection helpers (used by generic readable renderers).
+// ---------------------------------------------------------------------------
+// ISO-8601-ish detector: matches both `2026-05-19T14:32:00Z` and the space
+// variant `2026-05-19 14:32:00`. Date-only strings (`2026-05-19`) are
+// intentionally NOT matched — they often appear as opaque ids/slugs.
+const ISO_LIKE_RE = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}/;
+/** True when `value` is a `Date` or an ISO-8601-ish string. */
+export const looksLikeTimestamp = (value) => {
+    if (value instanceof Date)
+        return !Number.isNaN(value.getTime());
+    if (typeof value === 'string')
+        return ISO_LIKE_RE.test(value);
+    return false;
+};
+/**
+ * Format `value` as a human-friendly timestamp when it looks like one;
+ * return `null` otherwise so the caller can fall back to its scalar
+ * formatter without committing to the timestamp shape.
+ */
+export const tryFormatTimestamp = (value, opts = {}) => {
+    if (!looksLikeTimestamp(value))
+        return null;
+    return formatDateTime(value, opts);
+};

package/dist/src/services/Renderer/errors.d.ts

@@ -0,0 +1,3 @@
+import { type CliError } from '../../domain/errors';
+import type { OutputOptions } from './options';
+export declare const emitErrorSync: (err: CliError, opts: OutputOptions) => void;