@proletariat/cli 0.3.35 → 0.3.40

package/dist/lib/pmo/storage/types.d.ts

@@ -169,6 +169,7 @@ export interface WorkActionRow {
     prompt: string;
     end_prompt: string | null;
     default_category: string | null;
+    modifies_code: number;
     is_builtin: number;
     position: number;
     created_at: string;

package/dist/lib/pmo/storage/views.d.ts

@@ -1,5 +1,7 @@
 /**
  * Board view operations.
+ *
+ * This module uses Drizzle ORM for type-safe database queries.
  */
 import { Board, BoardView, BoardViewFilter, BoardViewFilters } from '../types.js';
 import { StorageContext } from './types.js';

package/dist/lib/pmo/storage/views.js

@@ -1,11 +1,13 @@
 /**
  * Board view operations.
+ *
+ * This module uses Drizzle ORM for type-safe database queries.
  */
-import { PMO_TABLES } from '../schema.js';
+import { eq, and, like, or, asc, desc, sql } from 'drizzle-orm';
+import { pmoBoardViews, pmoProjects, pmoTickets, pmoWorkflowStatuses, pmoSubtasks, pmoTicketMetadata, } from '../../database/drizzle-schema.js';
 import { PMOError, } from '../types.js';
 import { slugify } from '../utils.js';
 import { getAcceptanceCriteriaSync } from './helpers.js';
-const T = PMO_TABLES;
 export class ViewStorage {
     ctx;
     constructor(ctx) {
@@ -24,33 +26,42 @@ export class ViewStorage {
         if (!identifier)
             return null;
         // 1. Exact ID match
-        const exactMatch = this.ctx.db.prepare(`
-      SELECT id FROM ${T.projects} WHERE id = ?
-    `).get(identifier);
+        const exactMatch = this.ctx.drizzle
+            .select({ id: pmoProjects.id })
+            .from(pmoProjects)
+            .where(eq(pmoProjects.id, identifier))
+            .get();
         if (exactMatch)
             return exactMatch.id;
         // 2. Case-insensitive ID match
-        const caseInsensitiveId = this.ctx.db.prepare(`
-      SELECT id FROM ${T.projects} WHERE LOWER(id) = LOWER(?)
-    `).get(identifier);
+        const caseInsensitiveId = this.ctx.drizzle
+            .select({ id: pmoProjects.id })
+            .from(pmoProjects)
+            .where(sql `LOWER(${pmoProjects.id}) = LOWER(${identifier})`)
+            .get();
         if (caseInsensitiveId)
             return caseInsensitiveId.id;
         // 3. Exact name match
-        const nameMatch = this.ctx.db.prepare(`
-      SELECT id FROM ${T.projects} WHERE name = ?
-    `).get(identifier);
+        const nameMatch = this.ctx.drizzle
+            .select({ id: pmoProjects.id })
+            .from(pmoProjects)
+            .where(eq(pmoProjects.name, identifier))
+            .get();
         if (nameMatch)
             return nameMatch.id;
         // 4. Case-insensitive name match
-        const caseInsensitiveName = this.ctx.db.prepare(`
-      SELECT id FROM ${T.projects} WHERE LOWER(name) = LOWER(?)
-    `).get(identifier);
+        const caseInsensitiveName = this.ctx.drizzle
+            .select({ id: pmoProjects.id })
+            .from(pmoProjects)
+            .where(sql `LOWER(${pmoProjects.name}) = LOWER(${identifier})`)
+            .get();
         if (caseInsensitiveName)
             return caseInsensitiveName.id;
         // 5. Slugified name match
-        const allProjects = this.ctx.db.prepare(`
-      SELECT id, name FROM ${T.projects}
-    `).all();
+        const allProjects = this.ctx.drizzle
+            .select({ id: pmoProjects.id, name: pmoProjects.name })
+            .from(pmoProjects)
+            .all();
         const identifierLower = identifier.toLowerCase();
         for (const project of allProjects) {
             const projectSlug = slugify(project.name);
@@ -64,34 +75,37 @@ export class ViewStorage {
      * List board views.
      */
     async listBoardViews(filter) {
-        let sql = `SELECT * FROM ${T.board_views}`;
+        let query = this.ctx.drizzle
+            .select()
+            .from(pmoBoardViews)
+            .$dynamic();
         const conditions = [];
-        const params = [];
         if (filter?.projectId) {
-            conditions.push('project_id = ?');
-            params.push(filter.projectId);
+            conditions.push(eq(pmoBoardViews.projectId, filter.projectId));
         }
         if (filter?.isDefault !== undefined) {
-            conditions.push('is_default = ?');
-            params.push(filter.isDefault ? 1 : 0);
+            conditions.push(eq(pmoBoardViews.isDefault, filter.isDefault));
         }
         if (filter?.search) {
-            conditions.push('(name LIKE ? OR description LIKE ?)');
-            const searchTerm = `%${filter.search}%`;
-            params.push(searchTerm, searchTerm);
+            conditions.push(or(like(pmoBoardViews.name, `%${filter.search}%`), like(pmoBoardViews.description, `%${filter.search}%`)));
         }
         if (conditions.length > 0) {
-            sql += ' WHERE ' + conditions.join(' AND ');
+            query = query.where(and(...conditions));
         }
-        sql += ' ORDER BY is_default DESC, name ASC';
-        const rows = this.ctx.db.prepare(sql).all(...params);
+        const rows = query
+            .orderBy(desc(pmoBoardViews.isDefault), asc(pmoBoardViews.name))
+            .all();
         return rows.map((row) => this.rowToBoardView(row));
     }
     /**
      * Get a board view by ID.
      */
     async getBoardView(id) {
-        const row = this.ctx.db.prepare(`SELECT * FROM ${T.board_views} WHERE id = ?`).get(id);
+        const row = this.ctx.drizzle
+            .select()
+            .from(pmoBoardViews)
+            .where(eq(pmoBoardViews.id, id))
+            .get();
         if (!row)
             return null;
         return this.rowToBoardView(row);
@@ -111,14 +125,24 @@ export class ViewStorage {
         const filters = JSON.stringify(view.filters || {});
         // If this is set as default, unset other defaults for this project
         if (view.isDefault) {
-            this.ctx.db.prepare(`
-        UPDATE ${T.board_views} SET is_default = 0 WHERE project_id = ?
-      `).run(view.projectId);
+            this.ctx.drizzle
+                .update(pmoBoardViews)
+                .set({ isDefault: false })
+                .where(eq(pmoBoardViews.projectId, view.projectId))
+                .run();
         }
-        this.ctx.db.prepare(`
-      INSERT INTO ${T.board_views} (id, project_id, name, description, is_default, filters, group_by, sort_by, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(id, view.projectId, view.name, view.description || null, view.isDefault ? 1 : 0, filters, view.groupBy || null, view.sortBy || null, now, now);
+        this.ctx.drizzle.insert(pmoBoardViews).values({
+            id,
+            projectId: view.projectId,
+            name: view.name,
+            description: view.description || null,
+            isDefault: view.isDefault || false,
+            filters,
+            groupBy: view.groupBy || null,
+            sortBy: view.sortBy || null,
+            createdAt: String(now),
+            updatedAt: String(now),
+        }).run();
         return (await this.getBoardView(id));
     }
     /**
@@ -129,47 +153,45 @@ export class ViewStorage {
         if (!existing) {
             throw new PMOError('NOT_FOUND', `Board view not found: ${id}`);
         }
-        const updates = ['updated_at = ?'];
-        const params = [Date.now()];
-        if (changes.name !== undefined) {
-            updates.push('name = ?');
-            params.push(changes.name);
-        }
-        if (changes.description !== undefined) {
-            updates.push('description = ?');
-            params.push(changes.description || null);
-        }
+        const updates = {
+            updatedAt: String(Date.now()),
+        };
+        if (changes.name !== undefined)
+            updates.name = changes.name;
+        if (changes.description !== undefined)
+            updates.description = changes.description || null;
         if (changes.isDefault !== undefined) {
             // If setting as default, unset other defaults for this project
             if (changes.isDefault) {
-                this.ctx.db.prepare(`
-          UPDATE ${T.board_views} SET is_default = 0 WHERE project_id = ?
-        `).run(existing.projectId);
+                this.ctx.drizzle
+                    .update(pmoBoardViews)
+                    .set({ isDefault: false })
+                    .where(eq(pmoBoardViews.projectId, existing.projectId))
+                    .run();
             }
-            updates.push('is_default = ?');
-            params.push(changes.isDefault ? 1 : 0);
-        }
-        if (changes.filters !== undefined) {
-            updates.push('filters = ?');
-            params.push(JSON.stringify(changes.filters));
-        }
-        if (changes.groupBy !== undefined) {
-            updates.push('group_by = ?');
-            params.push(changes.groupBy || null);
-        }
-        if (changes.sortBy !== undefined) {
-            updates.push('sort_by = ?');
-            params.push(changes.sortBy || null);
+            updates.isDefault = changes.isDefault;
         }
-        params.push(id);
-        this.ctx.db.prepare(`UPDATE ${T.board_views} SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+        if (changes.filters !== undefined)
+            updates.filters = JSON.stringify(changes.filters);
+        if (changes.groupBy !== undefined)
+            updates.groupBy = changes.groupBy || null;
+        if (changes.sortBy !== undefined)
+            updates.sortBy = changes.sortBy || null;
+        this.ctx.drizzle
+            .update(pmoBoardViews)
+            .set(updates)
+            .where(eq(pmoBoardViews.id, id))
+            .run();
         return (await this.getBoardView(id));
     }
     /**
      * Delete a board view.
      */
     async deleteBoardView(id) {
-        const result = this.ctx.db.prepare(`DELETE FROM ${T.board_views} WHERE id = ?`).run(id);
+        const result = this.ctx.drizzle
+            .delete(pmoBoardViews)
+            .where(eq(pmoBoardViews.id, id))
+            .run();
         if (result.changes === 0) {
             throw new PMOError('NOT_FOUND', `Board view not found: ${id}`);
         }
@@ -178,9 +200,11 @@ export class ViewStorage {
      * Get the default board view for a project.
      */
     async getDefaultBoardView(projectId) {
-        const row = this.ctx.db.prepare(`
-      SELECT * FROM ${T.board_views} WHERE project_id = ? AND is_default = 1
-    `).get(projectId);
+        const row = this.ctx.drizzle
+            .select()
+            .from(pmoBoardViews)
+            .where(and(eq(pmoBoardViews.projectId, projectId), eq(pmoBoardViews.isDefault, true)))
+            .get();
         if (!row)
             return null;
         return this.rowToBoardView(row);
@@ -208,22 +232,32 @@ export class ViewStorage {
         // Override with explicit filters if provided
         const effectiveFilters = { ...viewFilters, ...filters };
         // Get project metadata using resolved ID
-        const projectRow = this.ctx.db.prepare(`SELECT * FROM ${T.projects} WHERE id = ?`).get(resolvedId);
+        const projectRow = this.ctx.drizzle
+            .select({
+            id: pmoProjects.id,
+            name: pmoProjects.name,
+            workflowId: pmoProjects.workflowId,
+            updatedAt: pmoProjects.updatedAt,
+        })
+            .from(pmoProjects)
+            .where(eq(pmoProjects.id, resolvedId))
+            .get();
         if (!projectRow) {
             throw new PMOError('NOT_FOUND', `Project not found: ${projectIdOrName}. Run init() first.`);
         }
-        // Get the project's workflow
-        const projectMeta = this.ctx.db.prepare(`
-      SELECT workflow_id FROM ${T.projects} WHERE id = ?
-    `).get(resolvedId);
-        const workflowId = projectMeta?.workflow_id || 'default';
+        const workflowId = projectRow.workflowId || 'default';
         // Get workflow statuses as columns
-        const columnRows = this.ctx.db.prepare(`
-      SELECT id, workflow_id, name, position
-      FROM ${T.workflow_statuses}
-      WHERE workflow_id = ?
-      ORDER BY position
-    `).all(workflowId);
+        const columnRows = this.ctx.drizzle
+            .select({
+            id: pmoWorkflowStatuses.id,
+            workflowId: pmoWorkflowStatuses.workflowId,
+            name: pmoWorkflowStatuses.name,
+            position: pmoWorkflowStatuses.position,
+        })
+            .from(pmoWorkflowStatuses)
+            .where(eq(pmoWorkflowStatuses.workflowId, workflowId))
+            .orderBy(asc(pmoWorkflowStatuses.position))
+            .all();
         // Filter columns if columnIds filter is set
         const filteredColumnRows = effectiveFilters.columnIds?.length
             ? columnRows.filter((col) => effectiveFilters.columnIds.includes(col.id))
@@ -244,82 +278,101 @@ export class ViewStorage {
             id: projectRow.id,
             name: projectRow.name,
             columns,
-            updatedAt: new Date(projectRow.updated_at),
+            updatedAt: new Date(projectRow.updatedAt),
         };
     }
     /**
      * Get tickets for a column (workflow status) with filters applied.
      */
     async getTicketsForColumnWithFilters(columnId, projectId, filters) {
-        // columnId is now a workflow_status id
-        let sql = `
-      SELECT t.*,
-             ws.position as board_position,
-             ws.name as column_name,
-             ws.name as status_name,
-             ws.category as status_category
-      FROM ${T.tickets} t
-      LEFT JOIN ${T.workflow_statuses} ws ON t.status_id = ws.id
-      WHERE t.status_id = ? AND t.project_id = ?
-    `;
-        const params = [columnId, projectId];
+        // Build conditions array for dynamic WHERE clause
+        const conditions = [
+            eq(pmoTickets.statusId, columnId),
+            eq(pmoTickets.projectId, projectId),
+        ];
         // Apply filters
         if (filters.assignee !== undefined) {
             if (filters.assignee === 'unassigned') {
-                sql += ' AND (t.assignee IS NULL OR t.assignee = "")';
+                conditions.push(or(sql `${pmoTickets.assignee} IS NULL`, eq(pmoTickets.assignee, '')));
             }
             else {
-                sql += ' AND t.assignee = ?';
-                params.push(filters.assignee);
+                conditions.push(eq(pmoTickets.assignee, filters.assignee));
             }
         }
         if (filters.owner !== undefined) {
-            sql += ' AND t.owner = ?';
-            params.push(filters.owner);
+            conditions.push(eq(pmoTickets.owner, filters.owner));
         }
         if (filters.priority !== undefined) {
-            sql += ' AND UPPER(t.priority) = UPPER(?)';
-            params.push(filters.priority);
+            conditions.push(sql `UPPER(${pmoTickets.priority}) = UPPER(${filters.priority})`);
         }
         if (filters.statusCategory !== undefined) {
-            sql += ' AND ws.category = ?';
-            params.push(filters.statusCategory);
+            conditions.push(eq(pmoWorkflowStatuses.category, filters.statusCategory));
         }
         if (filters.statusId !== undefined) {
-            sql += ' AND t.status_id = ?';
-            params.push(filters.statusId);
+            conditions.push(eq(pmoTickets.statusId, filters.statusId));
         }
         if (filters.epicId !== undefined) {
-            sql += ' AND t.epic_id = ?';
-            params.push(filters.epicId);
+            conditions.push(eq(pmoTickets.epicId, filters.epicId));
         }
         if (filters.search !== undefined) {
-            sql += ' AND (t.title LIKE ? OR t.description LIKE ?)';
             const searchTerm = `%${filters.search}%`;
-            params.push(searchTerm, searchTerm);
+            conditions.push(or(like(pmoTickets.title, searchTerm), like(pmoTickets.description, searchTerm)));
         }
-        // Order by ticket position, then created_at as tiebreaker
-        sql += ` ORDER BY t.position ASC, t.created_at ASC`;
-        const rows = this.ctx.db.prepare(sql).all(...params);
+        const rows = this.ctx.drizzle
+            .select({
+            id: pmoTickets.id,
+            project_id: pmoTickets.projectId,
+            title: pmoTickets.title,
+            description: pmoTickets.description,
+            priority: pmoTickets.priority,
+            category: pmoTickets.category,
+            status: pmoTickets.status,
+            status_id: pmoTickets.statusId,
+            owner: pmoTickets.owner,
+            assignee: pmoTickets.assignee,
+            branch: pmoTickets.branch,
+            spec_id: pmoTickets.specId,
+            epic_id: pmoTickets.epicId,
+            labels: pmoTickets.labels,
+            position: pmoTickets.position,
+            created_at: pmoTickets.createdAt,
+            updated_at: pmoTickets.updatedAt,
+            last_synced_from_spec: pmoTickets.lastSyncedFromSpec,
+            last_synced_from_board: pmoTickets.lastSyncedFromBoard,
+            board_position: pmoWorkflowStatuses.position,
+            column_name: pmoWorkflowStatuses.name,
+            status_name: pmoWorkflowStatuses.name,
+            status_category: pmoWorkflowStatuses.category,
+        })
+            .from(pmoTickets)
+            .leftJoin(pmoWorkflowStatuses, eq(pmoTickets.statusId, pmoWorkflowStatuses.id))
+            .where(and(...conditions))
+            .orderBy(asc(pmoTickets.position), asc(pmoTickets.createdAt))
+            .all();
         return Promise.all(rows.map((row) => this.rowToTicketWithColumn(row)));
     }
     async rowToTicketWithColumn(row) {
         // Get subtasks
-        const subtaskRows = this.ctx.db.prepare(`
-      SELECT * FROM ${T.subtasks} WHERE ticket_id = ? ORDER BY position
-    `).all(row.id);
+        const subtaskRows = this.ctx.drizzle
+            .select()
+            .from(pmoSubtasks)
+            .where(eq(pmoSubtasks.ticketId, row.id))
+            .orderBy(asc(pmoSubtasks.position))
+            .all();
         const subtasks = subtaskRows.map((s) => ({
             id: s.id,
             title: s.title,
-            done: s.done === 1,
+            done: s.done ?? false,
         }));
         // Get metadata
-        const metadataRows = this.ctx.db.prepare(`
-      SELECT key, value FROM ${T.ticket_metadata} WHERE ticket_id = ?
-    `).all(row.id);
+        const metadataRows = this.ctx.drizzle
+            .select({ key: pmoTicketMetadata.key, value: pmoTicketMetadata.value })
+            .from(pmoTicketMetadata)
+            .where(eq(pmoTicketMetadata.ticketId, row.id))
+            .all();
         const metadata = {};
         for (const m of metadataRows) {
-            metadata[m.key] = m.value;
+            metadata[m.key] = m.value || '';
         }
         // Parse labels from JSON
         let labels = [];
@@ -347,9 +400,9 @@ export class ViewStorage {
             subtasks,
             labels,
             metadata,
-            acceptanceCriteria: getAcceptanceCriteriaSync(this.ctx.db, row.id),
-            createdAt: new Date(row.created_at),
-            updatedAt: new Date(row.updated_at),
+            acceptanceCriteria: getAcceptanceCriteriaSync(this.ctx.drizzle, row.id),
+            createdAt: new Date(row.created_at || Date.now()),
+            updatedAt: new Date(row.updated_at || Date.now()),
             lastSyncedFromSpec: row.last_synced_from_spec
                 ? new Date(row.last_synced_from_spec)
                 : undefined,
@@ -388,15 +441,15 @@ export class ViewStorage {
     rowToBoardView(row) {
         return {
             id: row.id,
-            projectId: row.project_id,
+            projectId: row.projectId,
             name: row.name,
             description: row.description || undefined,
-            isDefault: row.is_default === 1,
+            isDefault: row.isDefault ?? false,
             filters: row.filters ? JSON.parse(row.filters) : {},
-            groupBy: row.group_by,
-            sortBy: row.sort_by,
-            createdAt: new Date(row.created_at),
-            updatedAt: new Date(row.updated_at),
+            groupBy: row.groupBy,
+            sortBy: row.sortBy,
+            createdAt: new Date(row.createdAt || Date.now()),
+            updatedAt: new Date(row.updatedAt || Date.now()),
         };
     }
 }

package/dist/lib/prompt-command.d.ts

@@ -30,6 +30,26 @@ import { type JsonFlags } from './prompt-json.js';
  * ```
  */
 export declare abstract class PromptCommand extends Command {
+    /**
+     * TTY-aware log method - strips ANSI codes and emoji in non-TTY mode.
+     *
+     * Use this instead of this.log() when outputting styled text (chalk colors, emoji prefixes).
+     * In TTY mode, outputs styled text as-is. In non-TTY mode, strips ANSI and emoji.
+     *
+     * @param message - The styled message (may contain ANSI codes and emoji)
+     * @param args - Additional arguments passed to this.log()
+     */
+    protected logPlain(message?: string, ...args: string[]): void;
+    /**
+     * Check if plain output mode is active (non-TTY, PRLT_PLAIN, NO_COLOR).
+     * Convenience wrapper for use in commands.
+     */
+    protected get isPlain(): boolean;
+    /**
+     * Check if running in non-TTY environment.
+     * Convenience wrapper for use in commands.
+     */
+    protected get isNonTTY(): boolean;
     /**
      * Prompt wrapper - drop-in replacement for inquirer.prompt
      *

package/dist/lib/prompt-command.js

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 import inquirer from 'inquirer';
-import { isAgentMode, outputPromptAsJson, createMetadata, normalizeChoices, } from './prompt-json.js';
+import { isAgentMode, isNonTTY, outputPromptAsJson, createMetadata, normalizeChoices, } from './prompt-json.js';
+import { isPlainOutput, plainText } from './styles.js';
 /**
  * Lightweight base command with prompt() method for JSON mode support.
  *
@@ -31,6 +32,41 @@ import { isAgentMode, outputPromptAsJson, createMetadata, normalizeChoices, } fr
  * ```
  */
 export class PromptCommand extends Command {
+    /**
+     * TTY-aware log method - strips ANSI codes and emoji in non-TTY mode.
+     *
+     * Use this instead of this.log() when outputting styled text (chalk colors, emoji prefixes).
+     * In TTY mode, outputs styled text as-is. In non-TTY mode, strips ANSI and emoji.
+     *
+     * @param message - The styled message (may contain ANSI codes and emoji)
+     * @param args - Additional arguments passed to this.log()
+     */
+    logPlain(message, ...args) {
+        if (message === undefined) {
+            this.log();
+            return;
+        }
+        if (isPlainOutput()) {
+            this.log(plainText(message), ...args);
+        }
+        else {
+            this.log(message, ...args);
+        }
+    }
+    /**
+     * Check if plain output mode is active (non-TTY, PRLT_PLAIN, NO_COLOR).
+     * Convenience wrapper for use in commands.
+     */
+    get isPlain() {
+        return isPlainOutput();
+    }
+    /**
+     * Check if running in non-TTY environment.
+     * Convenience wrapper for use in commands.
+     */
+    get isNonTTY() {
+        return isNonTTY();
+    }
     /**
      * Prompt wrapper - drop-in replacement for inquirer.prompt
      *
@@ -73,7 +109,7 @@ export class PromptCommand extends Command {
      */
     async prompt(questions, jsonModeConfig) {
         // Auto-detect non-TTY: switch to JSON mode when no TTY present
-        if (!jsonModeConfig && !process.stdin.isTTY) {
+        if (!jsonModeConfig && isNonTTY()) {
             jsonModeConfig = { flags: { json: true }, commandName: this.id ?? 'unknown' };
         }
         // Check for JSON/agent mode

package/dist/lib/prompt-json.d.ts

@@ -86,6 +86,8 @@ export interface OutputMetadata {
     flags: Record<string, unknown>;
     /** Timestamp of the output */
     timestamp?: string;
+    /** Resolved PR mode after flag precedence ('create-pr' | 'no-pr') */
+    resolvedPRMode?: string;
 }
 /**
  * JSON output when a prompt would be shown
@@ -193,6 +195,27 @@ export interface ExecutionResultJsonOutput {
  * Union type for all JSON output types
  */
 export type JsonOutput = PromptJsonOutput | SuccessJsonOutput | ErrorJsonOutput | DryRunJsonOutput | ConfirmationNeededJsonOutput | ExecutionResultJsonOutput;
+/**
+ * All valid JSON envelope type discriminators.
+ * Used for contract tests and schema validation.
+ */
+export declare const JSON_ENVELOPE_TYPES: readonly ["prompt", "success", "error", "dry-run", "confirmation_needed", "execution_result"];
+export type JsonEnvelopeType = typeof JSON_ENVELOPE_TYPES[number];
+/**
+ * Required fields per envelope type for contract validation.
+ * Tests use this to verify no fields are accidentally removed.
+ */
+export declare const JSON_ENVELOPE_REQUIRED_FIELDS: Record<JsonEnvelopeType, string[]>;
+/**
+ * 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 declare function validateJsonEnvelope(obj: unknown): string[];
 /**
  * Flags interface for JSON mode detection
  */
@@ -211,9 +234,21 @@ export interface MachineOutputFlags {
     machine?: boolean;
 }
 /**
- * Check if the current environment is non-TTY (piped output)
+ * 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:
+ * - 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 false if:
+ * - PRLT_FORCE_TEXT=1 is set (forces text output in non-TTY environments, useful for testing)
  *
- * @returns true if stdout is not a TTY (e.g., piped to another process)
+ * @returns true if either stdin or stdout is not a TTY, or PRLT_JSON=1 is set
  */
 export declare function isNonTTY(): boolean;
 /**
@@ -221,7 +256,8 @@ export declare function isNonTTY(): boolean;
  *
  * 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
@@ -236,7 +272,8 @@ export declare const isAgentMode: typeof 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