@proletariat/cli 0.3.34 → 0.3.36

package/dist/lib/prompt-json.js

@@ -30,19 +30,140 @@ export const EXIT_ERROR = 1;
  */
 export const EXIT_NEEDS_INPUT = 2;
 /**
- * Check if the current environment is non-TTY (piped output)
+ * All valid JSON envelope type discriminators.
+ * Used for contract tests and schema validation.
+ */
+export const JSON_ENVELOPE_TYPES = [
+    'prompt',
+    'success',
+    'error',
+    'dry-run',
+    'confirmation_needed',
+    'execution_result',
+];
+/**
+ * Required fields per envelope type for contract validation.
+ * Tests use this to verify no fields are accidentally removed.
+ */
+export const JSON_ENVELOPE_REQUIRED_FIELDS = {
+    prompt: ['type', 'prompt', 'metadata'],
+    success: ['type', 'prompt', 'success', 'result', 'metadata'],
+    error: ['type', 'error', 'metadata'],
+    'dry-run': ['type', 'valid', 'metadata'],
+    confirmation_needed: ['type', 'plan', 'confirm_command', 'message', 'metadata'],
+    execution_result: ['type', 'result', 'metadata'],
+};
+/**
+ * Validate that a parsed JSON object conforms to the machine-mode envelope schema.
+ *
+ * Returns an array of validation errors (empty = valid).
+ * Useful for contract tests and runtime validation of JSON output.
+ *
+ * @param obj - Parsed JSON object to validate
+ * @returns Array of validation error strings (empty if valid)
+ */
+export function validateJsonEnvelope(obj) {
+    const errors = [];
+    if (typeof obj !== 'object' || obj === null) {
+        errors.push('Output must be a non-null object');
+        return errors;
+    }
+    const record = obj;
+    // Check type discriminator
+    if (!('type' in record)) {
+        errors.push('Missing required field: type');
+        return errors;
+    }
+    const type = record.type;
+    if (!JSON_ENVELOPE_TYPES.includes(type)) {
+        errors.push(`Invalid envelope type: "${type}". Must be one of: ${JSON_ENVELOPE_TYPES.join(', ')}`);
+        return errors;
+    }
+    // Check required fields for this type
+    const requiredFields = JSON_ENVELOPE_REQUIRED_FIELDS[type];
+    for (const field of requiredFields) {
+        if (!(field in record)) {
+            errors.push(`Missing required field for type "${type}": ${field}`);
+        }
+    }
+    // Validate metadata structure
+    if ('metadata' in record && record.metadata !== undefined) {
+        const metadata = record.metadata;
+        if (typeof metadata !== 'object' || metadata === null) {
+            errors.push('metadata must be a non-null object');
+        }
+        else {
+            if (!('command' in metadata) || typeof metadata.command !== 'string') {
+                errors.push('metadata.command must be a string');
+            }
+            if (!('flags' in metadata) || typeof metadata.flags !== 'object') {
+                errors.push('metadata.flags must be an object');
+            }
+        }
+    }
+    // Type-specific validation
+    if (type === 'prompt' && 'prompt' in record && record.prompt !== null) {
+        const prompt = record.prompt;
+        if (!('type' in prompt)) {
+            errors.push('prompt.type is required when prompt is non-null');
+        }
+    }
+    if (type === 'error' && 'error' in record) {
+        const error = record.error;
+        if (typeof error !== 'object' || error === null) {
+            errors.push('error must be a non-null object');
+        }
+        else {
+            if (!('code' in error) || typeof error.code !== 'string') {
+                errors.push('error.code must be a string');
+            }
+            if (!('message' in error) || typeof error.message !== 'string') {
+                errors.push('error.message must be a string');
+            }
+        }
+    }
+    if (type === 'success') {
+        if (record.success !== true) {
+            errors.push('success field must be true for success type');
+        }
+        if (record.prompt !== null) {
+            errors.push('prompt field must be null for success type');
+        }
+    }
+    if (type === 'confirmation_needed') {
+        if (typeof record.confirm_command !== 'string' || !record.confirm_command) {
+            errors.push('confirm_command must be a non-empty string');
+        }
+    }
+    return errors;
+}
+/**
+ * Check if the current environment is non-TTY (piped input or output)
+ *
+ * Uses the "either" strategy: returns true if EITHER stdin OR stdout is non-TTY.
+ * This covers the primary use case of scripts/agents calling prlt as a subprocess,
+ * where both stdin and stdout are typically non-TTY.
  *
- * @returns true if stdout is not a TTY (e.g., piped to another process)
+ * Returns true if:
+ * - stdin is not a TTY (e.g., piped input)
+ * - stdout is not a TTY (e.g., piped output)
+ * - PRLT_JSON=1 environment variable is set (overrides TTY detection)
+ *
+ * @returns true if either stdin or stdout is not a TTY, or PRLT_JSON=1 is set
  */
 export function isNonTTY() {
-    return !process.stdout.isTTY;
+    if (process.env.PRLT_JSON === '1' || process.env.PRLT_JSON === 'true') {
+        return true;
+    }
+    return !process.stdout.isTTY || !process.stdin.isTTY;
 }
 /**
  * Determine if JSON output mode is active (for AI agents)
  *
  * Returns true if:
  * - The --json flag is set (or -m/--machine aliases)
- * - The environment is non-TTY (piped output)
+ * - The PRLT_JSON=1 environment variable is set
+ * - Either stdin or stdout is non-TTY (piped input/output)
  *
  * @param flags - Command flags object
  * @returns true if JSON mode should be used
@@ -52,7 +173,7 @@ export function shouldOutputJson(flags) {
     if (flags.json === true || flags.machine === true) {
         return true;
     }
-    // Automatic detection for non-TTY environments
+    // Automatic detection for non-TTY environments (includes PRLT_JSON env var)
     return isNonTTY();
 }
 /**
@@ -64,7 +185,8 @@ export const isAgentMode = shouldOutputJson;
  *
  * Returns true if:
  * - The --json flag is set (or -m/--machine aliases)
- * - The environment is non-TTY (piped output)
+ * - The PRLT_JSON=1 environment variable is set
+ * - Either stdin or stdout is non-TTY (piped input/output)
  *
  * @param flags - Command flags object
  * @returns true if machine-readable output mode should be used
@@ -74,7 +196,7 @@ export function isMachineOutput(flags) {
     if (flags.json === true || flags.machine === true) {
         return true;
     }
-    // Automatic detection for non-TTY environments
+    // Automatic detection for non-TTY environments (includes PRLT_JSON env var)
     return isNonTTY();
 }
 /**

package/dist/lib/styles.d.ts

@@ -3,8 +3,41 @@
  *
  * Centralized styling for consistent CLI output across all commands.
  * Avoids chalk.gray which is nearly invisible on dark terminals.
+ *
+ * In non-TTY environments, styled output is automatically suppressed:
+ * - Use `isPlainOutput()` to check if plain text mode is active
+ * - Use `stripAnsi()` to strip ANSI escape codes from strings
+ * - Use `plainText()` to conditionally strip ANSI based on TTY detection
  */
 import chalk from 'chalk';
+/**
+ * Check if plain text output should be used (no colors, no emoji).
+ *
+ * Returns true when:
+ * - stdout is not a TTY (piped output)
+ * - PRLT_JSON=1 environment variable is set
+ * - PRLT_PLAIN=1 environment variable is set (plain text without JSON)
+ * - NO_COLOR environment variable is set (standard convention)
+ *
+ * @returns true if output should be plain text
+ */
+export declare function isPlainOutput(): boolean;
+/**
+ * Strip ANSI escape codes from a string
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * Strip emoji characters from a string
+ */
+export declare function stripEmoji(text: string): string;
+/**
+ * Convert styled text to plain text if in non-TTY mode.
+ * Strips ANSI codes and emoji prefixes.
+ *
+ * @param text - The styled text
+ * @returns Plain text in non-TTY mode, original text in TTY mode
+ */
+export declare function plainText(text: string): string;
 /**
  * Text styles for different semantic purposes
  */
@@ -96,3 +129,7 @@ export declare const prefix: {
     export: string;
     watch: string;
 };
+/**
+ * Get a TTY-aware prefix - returns plain text alternatives in non-TTY mode
+ */
+export declare function getPrefix(type: keyof typeof prefix): string;

package/dist/lib/styles.js

@@ -3,8 +3,63 @@
  *
  * Centralized styling for consistent CLI output across all commands.
  * Avoids chalk.gray which is nearly invisible on dark terminals.
+ *
+ * In non-TTY environments, styled output is automatically suppressed:
+ * - Use `isPlainOutput()` to check if plain text mode is active
+ * - Use `stripAnsi()` to strip ANSI escape codes from strings
+ * - Use `plainText()` to conditionally strip ANSI based on TTY detection
  */
 import chalk from 'chalk';
+import { isNonTTY } from './prompt-json.js';
+/**
+ * Check if plain text output should be used (no colors, no emoji).
+ *
+ * Returns true when:
+ * - stdout is not a TTY (piped output)
+ * - PRLT_JSON=1 environment variable is set
+ * - PRLT_PLAIN=1 environment variable is set (plain text without JSON)
+ * - NO_COLOR environment variable is set (standard convention)
+ *
+ * @returns true if output should be plain text
+ */
+export function isPlainOutput() {
+    if (process.env.PRLT_PLAIN === '1' || process.env.PRLT_PLAIN === 'true') {
+        return true;
+    }
+    if (process.env.NO_COLOR !== undefined) {
+        return true;
+    }
+    return isNonTTY();
+}
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\x1B\[[0-9;]*[a-zA-Z]/g;
+/**
+ * Strip ANSI escape codes from a string
+ */
+export function stripAnsi(text) {
+    return text.replace(ANSI_REGEX, '');
+}
+// eslint-disable-next-line no-misleading-character-class
+const EMOJI_REGEX = /[\u{1F300}-\u{1F9FF}\u{2600}-\u{27BF}\u{FE00}-\u{FE0F}\u{200D}\u{20E3}\u{E0020}-\u{E007F}]+/gu;
+/**
+ * Strip emoji characters from a string
+ */
+export function stripEmoji(text) {
+    return text.replace(EMOJI_REGEX, '').replace(/^\s+/, '');
+}
+/**
+ * Convert styled text to plain text if in non-TTY mode.
+ * Strips ANSI codes and emoji prefixes.
+ *
+ * @param text - The styled text
+ * @returns Plain text in non-TTY mode, original text in TTY mode
+ */
+export function plainText(text) {
+    if (isPlainOutput()) {
+        return stripEmoji(stripAnsi(text));
+    }
+    return text;
+}
 /**
  * Text styles for different semantic purposes
  */
@@ -193,3 +248,21 @@ export const prefix = {
     export: '📤',
     watch: '👀',
 };
+/**
+ * Get a TTY-aware prefix - returns plain text alternatives in non-TTY mode
+ */
+export function getPrefix(type) {
+    if (isPlainOutput()) {
+        const plainPrefixes = {
+            success: '[OK]',
+            error: '[ERROR]',
+            warning: '[WARN]',
+            info: '[INFO]',
+            sync: '[SYNC]',
+            export: '[EXPORT]',
+            watch: '[WATCH]',
+        };
+        return plainPrefixes[type] || '';
+    }
+    return prefix[type];
+}