@4ge/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conflate AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# 4ge-CLI: A Universal Interface for 4ge Resources
+
+The official Command Line Interface and API Bridge for the 4ge Service Architecture. 
+
+This CLI is designed with a **Dual-Output Architecture**: it provides a rich, interactive Terminal User Interface (TUI) for human developers and a strict, deterministic JSON output stream for AI Agents.
+
+## Project Overview
+
+**Problem Statement:**
+Developing and automating workflows within the 4ge ecosystem presents a dual challenge:
+1.  **For Human Developers:** Interacting with complex APIs often involves fragmented tools, manual data parsing, and a steep learning curve to translate service mesh logic into actionable insights. This leads to inefficient debugging, inconsistent context, and slower development cycles when trying to understand project states or access artifacts locally.
+2.  **For AI Agents:** Automating tasks against APIs demands highly reliable, deterministic, and self-validating interfaces. Traditional command-line tools, primarily designed for human readability, frequently produce inconsistent outputs, lack robust error handling, and can easily break fragile automation scripts. This hinders the development of dependable, AI-driven workflows.
+
+Both human developers and AI agents currently lack a unified, secure, and context-aware local interface that caters specifically to their distinct interaction needs, forcing compromises between usability and automation reliability.
+
+**Solution: The 4ge-CLI**
+The 4ge-CLI is designed as the definitive local interface for the 4ge ecosystem, bridging the gap between powerful 4ge APIs and diverse user environments. It provides a robust, intuitive, and secure command-line experience specifically engineered for both high-fidelity human interaction and seamless, error-proof AI Agent orchestration.
+
+**Core Vision:**
+To be the primary external gateway to 4ge resources, the 4ge-CLI translates the intricate 4ge service mesh into an intuitive, nested command structure. Its innovative "Dual-Output" strategy ensures optimal experiences: human developers benefit from a rich, interactive Terminal User Interface (TUI), while AI agents receive a consistently structured, schema-validated JSON stream, guaranteeing reliability for automated processes.
+
+**Key Personas:**
+
+*   **The Developer (Human):**
+    *   **Description:** An engineer, product manager, or data scientist who interacts directly with 4ge resources.
+    *   **Goals:** Quickly understand the state of their 4ge workspace, projects, and artifacts; efficiently troubleshoot issues; explore 4ge resources with minimal friction; and securely manage local configuration and credentials.
+    *   **Motivations:** Desires a visually appealing and interactive TUI that offers immediate feedback, guided exploration, and clear status updates, reducing cognitive load and accelerating workflow. They want to avoid manual API calls or cumbersome web interfaces for routine information retrieval.
+    *   **CLI Value:** Provides a rich, color-coded TUI with interactive prompts, progress indicators, and easily navigable tables, making complex data digestible and interaction intuitive.
+
+*   **The AI Agent (Machine):**
+    *   **Description:** An automated script, bot, or intelligent agent designed to interact with 4ge APIs programmatically. This includes CI/CD pipelines, custom automation scripts, or advanced AI-driven workflow engines.
+    *   **Goals:** Execute commands deterministically, receive predictable and machine-readable outputs, ensure zero-error execution loops, and securely authenticate without human intervention.
+    *   **Motivations:** Requires absolute reliability and consistency to build resilient automation. Any deviation in output format or unexpected errors can halt critical operations. They need strict validation and clear error reporting to maintain continuous operation.
+    *   **CLI Value:** Offers a `--json` output flag that returns strictly schema-validated JSON, leveraging Zod for contract enforcement. Supports headless authentication via API keys, robust error tracing, and "Action Hints" to guide subsequent automated commands, enabling highly reliable and autonomous operations.
+
+**Core Capabilities & Functional Highlights:**
+
+The 4ge-CLI is built upon a foundation designed for reliability, security, and developer efficiency:
+
+1.  **Unified Gateway Communication:** Acts as a thin client, delegating business logic to the 4ge Core API. It intelligently signals `X-Client-Type: 4ge-agent` for machine interactions and processes "Action Hints" for guided automation.
+2.  **Secure Local State Management:** Manages non-sensitive configuration in `.4ge/config.yaml` (e.g., `project_id`, `environment`) and securely stores sensitive credentials (JWTs, Refresh Tokens, API Keys) in the user's home directory (`~/.4ge/credentials.json`) to prevent accidental exposure.
+3.  **Flexible Authentication & Identity:** Supports PKCE-based OAuth for interactive human login and `4GE_API_KEY` (Personal Access Tokens) for seamless headless authentication in automated environments. Commands inherently respect user permissions via Supabase RLS policies.
+4.  **Context-Aware Operations:** The `4ge init` command establishes a local `.4ge/config.yaml`, anchoring the CLI to a specific project. Subsequent commands automatically leverage this local context, eliminating redundant flag usage and providing folder-specific information.
+5.  **Schema-Driven Reliability:** Employs a "Contract-First" approach, where internal Zod schemas mirror Core API definitions. This ensures robust input validation and response parsing, providing detailed error traces for agents and user-friendly "Update Required" messages for humans in case of schema mismatches.
+6.  **Three-Tier Output Design (UX):**
+    *   **Pretty Mode (Default):** Ink-rendered styled output — color-coded tables, detail views, spinners, and success/error feedback. No follow-up prompts. Command runs, shows result, exits.
+    *   **Interactive Mode (`--interactive` / `-i`):** Everything in Pretty, plus action-hint navigation menus, follow-up command suggestions, and prompts for missing values. Configurable as default via `cli.default_mode: interactive` in `.4ge/config.yaml`.
+    *   **Machine Mode (`--json`):** Strict `{ "data": T, "error": null, "metadata": {...} }` JSON envelope. No Ink, no prompts, no colors. Fully deterministic for AI agents.
+    
+    **Mode Resolution:** `--interactive`/`--no-interactive` flag → `cli.default_mode` config → `pretty` (hard default)
+
+> **Note for Contributors**: When implementing new commands, always extract the inner `.data` from SDK responses before passing to `outputJson()`. See the [Technical Specification](docs/technical-specification.md#-outputjson-double-nesting-anti-pattern) for details.
+7.  **Foundational Integration Features (MVP):** Enables read-only inspection of active 4ge resources, fetching specific project details, and loading artifact statuses and the artifacts themselves. Future enhancements include resource management (scaffolding) and syncing capabilities.
+8.  **Enhanced Safety & Validation:** Supports `--dry-run` for previewing changes, crucial for automated workflows. Comprehensive Zod schema validation for all command inputs and API responses prevents "state-drift" and ensures data integrity.
+
+-----
+
+## 🏗 Architecture & Stack
+
+- **Runtime:** Node.js 24.x (LTS)
+- **Package Manager:** pnpm
+- **Framework:** [oclif v4](https://oclif.io/) (Nested Command Structure)
+- **UI (Human):** [Ink](https://github.com/vadimdemedes/ink) (React-based terminal rendering)
+- **UI (Machine):** Standardized `--json` flag output
+- **API Sync:** `@hey-api/openapi-ts` (Contract-driven Zod schema and TypeScript generation)
+- **State Management:** Local `.4ge/config.yaml` 
+
+
+## 🛠 TUI Mode Configuration
+
+The 4ge-CLI provides three output modes, configurable per-command or as a project default:
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| **Pretty** | Default (no flags) | Styled Ink output (tables, spinners, colors). No follow-up prompts. |
+| **Interactive** | `--interactive` / `-i` | Pretty output + action-hint menus, follow-up suggestions, selection prompts. |
+| **Machine** | `--json` / `-j` | Strict JSON envelope. No TUI, no prompts, no colors. Fully deterministic for AI agents. |
+
+### Setting the Default Mode
+
+To make interactive mode the default for a project:
+
+```bash
+4ge config:set cli.default_mode interactive
+```
+
+This writes to `.4ge/config.yaml`:
+```yaml
+cli:
+  default_mode: interactive
+```
+
+### Resolution Order
+
+When running a command, the mode is resolved as:
+1. `--interactive` flag → forced interactive
+2. `--no-interactive` flag → forced pretty (overrides config)
+3. `cli.default_mode` in `.4ge/config.yaml` → uses config value
+4. *(fallback)* → pretty mode
+
+**Note:** `4ge init` is always interactive regardless of mode settings — it's an inherently interactive setup flow.
+
+### Examples
+
+```bash
+# Pretty mode — styled table, no prompts
+4ge project:list
+
+# Interactive mode — table + select an item + action hints
+4ge project:list --interactive
+
+# Override config back to pretty
+4ge project:list --no-interactive
+
+# Machine mode — strict JSON
+4ge project:list --json
+```
+
+## 🚀 Prerequisites
+
+**End users:** Node.js v24+ (git + GitHub SSH key for private install).
+
+**Contributors:** Node.js v24+, pnpm v9+.
+
+
+## 🛠 Getting Started
+
+### End users (install from npm)
+
+```bash
+npm install -g @4ge/cli
+4ge --help
+```
+
+Requires Node.js 24+ (no git, no SSH key needed). The package ships prebuilt
+— no build step on your machine. Update later with `npm update -g @4ge/cli`.
+
+### Contributors (from source)
+
+1. **Clone and Install:**
+
+```bash
+   git clone git@github.com:Conflate-AI/4ge-cli.git
+   cd 4ge-cli
+   pnpm install
+```
+
+2. **Sync the Core API Contract:**
+The 4ge-CLI uses a "Contract-First" approach. It does not define its own data models. Before running or building the CLI, you must sync the Zod schemas and API clients from the Core API's OpenAPI specification.
+*Ensure the 4ge Core API is running locally or accessible via the URL in `openapi-ts.config.ts`, then run:*
+
+```bash
+pnpm sync-api
+```
+
+*This will populate the `src/generated/api` directory.*
+
+
+3. **Run Locally:**
+
+```bash
+pnpm dev --help
+```
+
+4. **Authenticate:**
+```bash
+4ge auth:login --token <api_key>      # installed
+# or, in dev:
+pnpm dev auth:login --token <api_key>
+```
+
+5. **Initialize a Project:**
+```bash
+4ge init          # offers to install the agent skill (default: No)
+```
+
+## 📂 Repository Structure
+
+```
+.
+├── bin/                 # Executable entry points (run.js, dev.js)
+├── src/
+│   ├── base.ts          # BaseCommand with --json flag support
+│   ├── commands/        # oclif command implementations
+│   │   ├── index.ts     # Root command (help)
+│   │   ├── init.ts      # 4ge init
+│   │   ├── login.ts     # 4ge login (alias)
+│   │   ├── whoami.ts    # 4ge whoami (alias)
+│   │   └── auth/        # 4ge auth:login | auth:logout | auth:status | auth:profile:use
+│   ├── core/            # Business logic (framework-agnostic)
+│   │   ├── auth/        # Credential storage, resolution, API client
+│   │   ├── config/      # .4ge/config.yaml parser, Zod schema
+│   │   ├── skill/       # Agent skill path resolution + installer
+│   │   └── api/         # Response extraction, validation, retry
+│   ├── generated/       # ⚠️ DO NOT EDIT: Auto-generated from Core API
+│   └── ui/              # Ink React components (TUI)
+│       ├── components/  # Spinner, DataTable, DetailView, SelectPrompt, ConfirmPrompt, etc.
+│       ├── hooks/       # useActionHints hook
+│       ├── prompt-helpers.tsx  # Ink-based interactive prompt renderers
+│       └── render.ts    # renderTui() helper
+├── skills/              # Canonical agent skill (4ge-cli.md) — ships in npm pkg
+├── openapi-ts.config.ts # Configuration for the API contract sync
+└── package.json         # Scripts and dependencies
+```
+
+## ✅ Current Implementation Status
+
+| Phase | Status | Commands Available |
+|-------|--------|--------------------|
+| Phase 1: Foundation (Auth + Config) | ✅ Complete | `auth:login | auth:status | auth:logout | auth:profile:list | auth:profile:use | auth:profile:delete`, `init`, `login`, `whoami` |
+| Phase 2: Read Operations | ✅ Complete | `project:list | project:info | project:pull | project:create | project:update`, `plan:pull | plan:versions`, `epic/story/feature:list | :show | :pull` |
+| Phase 3: Write Operations | ✅ Complete | `epic/story/feature:update`, `idea:create | idea:graduate | idea:list | idea:show | idea:update`, `template:list | template:info | template:create | template:update | template:delete`, `template:feature:create | :list | :update | :delete`, `config:set | config:get | config:show | config:manage` |
+| Phase 4: Enhanced UX (TUI) | ✅ Complete | Ink TUI with spinner, tables, detail views, selection prompts, action hints, `--interactive` flag, `cli.default_mode` config |
+| Phase 5: Advanced UX | ✅ Partial | `config:manage` ✅, `--dry-run` ✅, `--retry` ✅, hierarchy config defaults ✅, agent skill install (`skill:install`) ✅, OAuth realtime flow ✅ |
+| Phase 6: Flows | 🗓 Planned | `flow:list | flow:show | flow:pull | flow:update` (issue #012) |
+
+
+## 🤖 AI Agent Integration
+
+This CLI is a primary tool for 4ge AI Agents. When integrating, Agents must adhere to the following rules:
+
+1. **JSON Mode:** Always append the `--json` flag. This disables all interactive prompts and returns a deterministic, Zod-validated payload.
+2. **Authentication:** Agents should bypass OAuth by providing a Personal Access Token via the `4GE_API_KEY` environment variable.
+3. **Telemetry:** Agents interacting with the CLI should expect the `X-Client-Type: 4ge-agent` header to be automatically applied to upstream Core API requests.
+4. **Skill install:** To teach an agent how to use the CLI, install the bundled skill into the project: `4ge skill:install` (default target `.agents/skills/4ge-cli/SKILL.md`, picked up by Cursor/Cline/Codex/Gemini CLI/GitHub Copilot/OpenCode). Use `--agent pi`/`--agent claude-code`/etc. for a specific harness, `--global` for user scope, `--force` to overwrite. `4ge init` also offers this on completion.
+
+See `skills/4ge-cli.md` for the canonical skill content (command reference, response envelope, workflow patterns).
+

package/bin/dev.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env -S node --import tsx
+import { execute } from '@oclif/core'
+await execute({ dir: import.meta.url, development: true })

package/bin/run.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execute } from '@oclif/core'
+await execute({ dir: import.meta.url })

package/dist/base.js

@@ -0,0 +1,398 @@
+import { Command, Flags } from '@oclif/core';
+import { createApiClient, checkConnectivity, ConnectivityError, ensureFreshToken, getApiBaseUrl, isAuthError, getAuthErrorHint } from './core/auth/index.js';
+import { withRetry as runWithRetry } from './core/api/retry.js';
+export class BaseCommand extends Command {
+    // --json flag: when true, suppress interactive prompts, output deterministic JSON,
+    // and send X-Client-Type: 4ge-agent header
+    static baseFlags = {
+        json: Flags.boolean({
+            char: 'j',
+            description: 'Output deterministic JSON for machine consumption (suppresses interactive prompts)',
+            default: false,
+        }),
+        interactive: Flags.boolean({
+            description: 'Enable interactive mode with follow-up prompts and suggestions',
+            aliases: ['i'],
+            allowNo: true, // enables --no-interactive
+        }),
+        'dry-run': Flags.boolean({
+            description: 'Preview changes without executing them',
+            default: false,
+        }),
+        retry: Flags.integer({
+            description: 'Retry transient API failures (network errors, 429, 5xx) with exponential backoff',
+            default: 0,
+        }),
+    };
+    flags;
+    localConfig = null;
+    static connectivityChecked = false;
+    static assetsMigrated = false;
+    get isJsonMode() {
+        return this.flags?.json ?? false;
+    }
+    get isInteractiveMode() {
+        if (this.isJsonMode)
+            return false;
+        const interactive = this.flags?.interactive;
+        if (interactive === true)
+            return true;
+        if (interactive === false)
+            return false;
+        return this.localConfig?.cli?.default_mode === 'interactive';
+    }
+    get isDryRun() {
+        return this.flags?.['dry-run'] === true;
+    }
+    get retryCount() {
+        const n = this.flags?.retry;
+        return Number.isFinite(n) && n > 0 ? n : 0;
+    }
+    /** Retry attempts recorded by the most recent {@link withRetry} call. */
+    lastRetryAttempts = [];
+    async init() {
+        await super.init();
+        const { flags } = await this.parse(this.constructor);
+        this.flags = flags;
+        // Load local config for isInteractiveMode resolution
+        try {
+            const { readConfig } = await import('./core/config/index.js');
+            this.localConfig = await readConfig();
+        }
+        catch {
+            this.localConfig = null;
+        }
+    }
+    async renderInk(element) {
+        if (this.isJsonMode)
+            return; // safety gate — should never be called in json mode
+        const { render } = await import('ink');
+        const instance = render(element);
+        await instance.waitUntilExit();
+    }
+    /**
+     * Renders the CLI header and exits.
+     * Useful for non-interactive commands that want to show branding/status.
+     */
+    async renderHeader(status = 'ready', headerVariant = 'full') {
+        if (this.isJsonMode)
+            return;
+        const { renderHeaderString } = await import('./ui/components/cli-header.js');
+        this.log(renderHeaderString(this.config.version, status, headerVariant));
+    }
+    async getProjectIdOrExit() {
+        if (!this.localConfig?.project_id) {
+            const message = 'Project not initialized. Run `4ge init` first to set project context.';
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({ message, code: 'NOT_INITIALIZED' });
+            }
+            else {
+                this.error(message);
+            }
+        }
+        return this.localConfig.project_id;
+    }
+    /**
+     * One-time migration of legacy root-level assets into .4ge/assets/.
+     *
+     * Pull commands call this before writing so old layouts are upgraded transparently.
+     * Fail-safe: never throws — commands must still work with stale layouts.
+     */
+    async migrateAssetsIfNeeded() {
+        if (BaseCommand.assetsMigrated)
+            return;
+        try {
+            const { migrateLegacyAssets } = await import('./core/config/index.js');
+            await migrateLegacyAssets();
+            // Only mark complete after a successful (or no-op) migration.
+            // A failed attempt leaves the guard unset so the next command retries —
+            // migration is idempotent, so retries are safe.
+            BaseCommand.assetsMigrated = true;
+        }
+        catch {
+            // best-effort: never block command execution on migration errors.
+        }
+    }
+    async getClient(options) {
+        options?.onStatusChange?.('refreshing-token');
+        const credential = await ensureFreshToken();
+        if (!credential) {
+            const message = 'Not authenticated. Run `4ge auth login --token <api_key>` first.';
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({ message, code: 'NO_CREDENTIALS' });
+            }
+            this.error(message);
+        }
+        const baseUrl = getApiBaseUrl();
+        const client = createApiClient({ credential, isJsonMode: this.isJsonMode, baseUrl });
+        if (!BaseCommand.connectivityChecked) {
+            const check = async () => {
+                try {
+                    options?.onStatusChange?.('checking-connectivity');
+                    await checkConnectivity(baseUrl);
+                    BaseCommand.connectivityChecked = true;
+                    options?.onStatusChange?.('ready');
+                }
+                catch (error) {
+                    if (error.code === 'CONNECTION_ERROR' || error instanceof ConnectivityError) {
+                        options?.onStatusChange?.('no-connection');
+                        const message = error.message || 'Failed to connect to API';
+                        const code = error.code || 'CONNECTION_ERROR';
+                        if (this.isJsonMode) {
+                            this.outputErrorAndExit({ message, code });
+                        }
+                        else {
+                            this.error(message);
+                        }
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            };
+            if (this.isJsonMode) {
+                await check();
+            }
+            else if (options?.onStatusChange) {
+                await check();
+            }
+            else {
+                await this.withSpinner('Connecting...', check);
+            }
+        }
+        return client;
+    }
+    outputJson(data, metadata) {
+        this.log(JSON.stringify({
+            data,
+            error: null,
+            metadata: {
+                // Spread caller metadata first (e.g. source, request_id, action_hints
+                // from the API), then enforce CLI-owned keys so a caller-provided
+                // `timestamp` never overrides the locally-generated one.
+                ...metadata,
+                // Surface retry attempts from the most recent withRetry call, if any.
+                ...(this.lastRetryAttempts.length > 0 ? { retries: this.lastRetryAttempts } : {}),
+                timestamp: new Date().toISOString(),
+            },
+        }, null, 2));
+    }
+    outputError(error, metadata) {
+        const errorObj = typeof error === 'string'
+            ? { message: error }
+            : error;
+        this.log(JSON.stringify({
+            data: null,
+            error: errorObj,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                ...metadata,
+            },
+        }, null, 2));
+    }
+    outputErrorAndExit(error, metadata) {
+        this.outputError(error, metadata);
+        this.exit(1);
+    }
+    /**
+     * Extract the error code from an auth-related error object.
+     * Returns the auth code (TOKEN_EXPIRED, INVALID_API_KEY, UNAUTHORIZED) if present,
+     * or 'AUTH_ERROR' as a fallback for 401-status errors without a specific code.
+     */
+    getAuthErrorCode(error) {
+        if (error?.code === 'TOKEN_EXPIRED' || error?.code === 'INVALID_API_KEY' || error?.code === 'UNAUTHORIZED') {
+            return error.code;
+        }
+        if (error?.error?.code === 'TOKEN_EXPIRED' || error?.error?.code === 'INVALID_API_KEY' || error?.error?.code === 'UNAUTHORIZED') {
+            return error.error.code;
+        }
+        if (error?.status === 401 || error?.error?.status === 401) {
+            return 'AUTH_ERROR';
+        }
+        return 'AUTH_ERROR';
+    }
+    /**
+     * Extract the human-readable detail message from an auth-related error.
+     */
+    getAuthDetail(error) {
+        if (error?.message)
+            return error.message;
+        if (error?.error?.message)
+            return error.error.message;
+        if (error instanceof Error)
+            return error.message;
+        if (typeof error === 'string')
+            return error;
+        if (error?.status === 401)
+            return 'Authentication required';
+        return 'Unknown authentication error';
+    }
+    /**
+     * Determine the hint for an auth-related error, using getAuthErrorHint()
+     * for recognized auth codes, or a generic fallback for other 401s.
+     */
+    getAuthHint(error) {
+        const specificHint = getAuthErrorHint(error) || getAuthErrorHint(error?.error);
+        if (specificHint)
+            return specificHint;
+        if (error?.code === 'UNAUTHORIZED' || error?.error?.code === 'UNAUTHORIZED') {
+            return 'Please check your authentication credentials';
+        }
+        if (error?.status === 401 || error?.error?.status === 401) {
+            return 'Please check your authentication credentials';
+        }
+        return 'Please check your authentication credentials';
+    }
+    handleError(message, error) {
+        const errObj = error;
+        // Detect auth-related errors (TOKEN_EXPIRED, INVALID_API_KEY, UNAUTHORIZED, 401)
+        if (isAuthError(errObj) || isAuthError(errObj?.error) ||
+            errObj?.code === 'UNAUTHORIZED' || errObj?.error?.code === 'UNAUTHORIZED' ||
+            errObj?.status === 401 || errObj?.error?.status === 401) {
+            const authCode = this.getAuthErrorCode(errObj);
+            const authDetail = this.getAuthDetail(errObj);
+            const authHint = this.getAuthHint(errObj);
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({
+                    message: `${message}: ${authDetail}`,
+                    code: authCode,
+                    hint: authHint,
+                });
+            }
+            else {
+                this.error(`${message}: ${authDetail}
+💡 ${authHint}`);
+            }
+            return;
+        }
+        // Non-auth errors: existing logic
+        let detail = 'Unknown error';
+        if (error instanceof Error) {
+            detail = error.message;
+        }
+        else if (typeof error === 'string') {
+            detail = error;
+        }
+        else if (error && typeof error === 'object') {
+            // Handle SDK error response structure: { error: { message: ... } } or { message: ... }
+            const nestedError = errObj.error;
+            if (nestedError && typeof nestedError === 'object') {
+                detail = nestedError.message || JSON.stringify(nestedError);
+            }
+            else if (typeof nestedError === 'string') {
+                detail = nestedError;
+            }
+            else if (errObj.message) {
+                detail = errObj.message;
+            }
+            else {
+                detail = JSON.stringify(errObj);
+            }
+        }
+        if (this.isJsonMode) {
+            this.outputErrorAndExit({ message, code: 'API_ERROR', details: detail });
+        }
+        else {
+            this.error(`${message}: ${detail}`);
+        }
+    }
+    async selectOption(message, options, config) {
+        if (this.isJsonMode) {
+            this.outputError({ message: 'Interactive selection not available in JSON mode', code: 'INTERACTIVE_REQUIRED' });
+            this.exit(1);
+        }
+        const { selectOption } = await import('./ui/prompt-helpers.js');
+        const result = await selectOption(message, options, config?.context, config?.helpText, config?.headerVariant);
+        return result;
+    }
+    async textInput(message, options) {
+        if (this.isJsonMode) {
+            this.outputError({ message: 'Interactive text input not available in JSON mode', code: 'INTERACTIVE_REQUIRED' });
+            this.exit(1);
+        }
+        const { textInput } = await import('./ui/prompt-helpers.js');
+        const result = await textInput(message, options);
+        return result;
+    }
+    async confirmPrompt(message, defaultYes = false, config) {
+        if (this.isJsonMode)
+            return false;
+        const { confirmPrompt } = await import('./ui/prompt-helpers.js');
+        const result = await confirmPrompt(message, defaultYes, config?.context, config?.helpText, config?.headerVariant);
+        return result ?? false;
+    }
+    async confirmAction(message, force, config) {
+        if (this.isDryRun || force)
+            return true;
+        if (this.isJsonMode) {
+            this.outputError({ message: 'Confirmation required. Use --force to skip confirmation.', code: 'CONFIRMATION_REQUIRED' });
+            this.exit(1);
+        }
+        const confirmed = await this.confirmPrompt(message, false, config);
+        if (!confirmed) {
+            this.log('Aborted.');
+            return false;
+        }
+        return true;
+    }
+    async withRetry(fn) {
+        if (this.retryCount === 0) {
+            return fn();
+        }
+        const { result, attempts } = await runWithRetry(fn, { maxAttempts: this.retryCount });
+        // Accumulate across multiple calls within a single run so commands that
+        // make several API calls (e.g. template:pull fetches project + template)
+        // report every retry in metadata.retries.
+        this.lastRetryAttempts.push(...attempts);
+        return result;
+    }
+    async withSpinner(message, fn) {
+        const run = this.retryCount > 0 ? () => this.withRetry(fn) : fn;
+        if (this.isJsonMode)
+            return run();
+        const { render } = await import('ink');
+        const { Spinner } = await import('./ui/components/spinner.js');
+        const React = await import('react');
+        const instance = render(React.createElement(Spinner, { message }));
+        try {
+            const result = await run();
+            instance.clear?.();
+            instance.unmount();
+            return result;
+        }
+        catch (error) {
+            instance.clear?.();
+            instance.unmount();
+            throw error;
+        }
+    }
+    async handleActionHints(rawHints) {
+        if (!this.isInteractiveMode)
+            return;
+        const { parseActionHints } = await import('./core/api/action-hints.js');
+        const hints = parseActionHints(rawHints);
+        if (hints.length === 0)
+            return;
+        const { renderActionHintsMenu } = await import('./ui/prompt-helpers.js');
+        await renderActionHintsMenu(hints);
+    }
+    async handleDryRun(payload) {
+        if (this.isJsonMode) {
+            this.outputJson(null, { dry_run: true, would_execute: payload });
+        }
+        else {
+            const { SuccessMessage } = await import('./ui/index.js');
+            const React = await import('react');
+            await this.renderInk(React.createElement(SuccessMessage, { message: '[DRY-RUN] Would execute operation' }));
+            this.log(`  Payload: ${JSON.stringify(payload, null, 2)}`);
+        }
+    }
+    // Handle errors — in JSON mode output JSON error, otherwise use oclif default
+    async catch(error) {
+        if (this.isJsonMode) {
+            this.outputError({ message: error.message, code: error.code || error.constructor.name });
+            this.exit(1);
+        }
+        throw error;
+    }
+}