@4ge/cli 0.1.0

package/dist/ui/components/action-hints.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+export const ActionHints = ({ hints, interactive, onSelect, onDismiss, }) => {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    useInput((input, key) => {
+        if (!interactive)
+            return;
+        if (key.upArrow) {
+            setSelectedIndex((prev) => (prev > 0 ? prev - 1 : hints.length - 1));
+        }
+        else if (key.downArrow) {
+            setSelectedIndex((prev) => (prev < hints.length - 1 ? prev + 1 : 0));
+        }
+        else if (key.return) {
+            onSelect?.(hints[selectedIndex]?.command ?? '');
+        }
+        else if (key.escape || input === 'q') {
+            onDismiss?.();
+        }
+        else if (key.ctrl && input === 'd') {
+            process.exit(0);
+        }
+    });
+    if (!hints || hints.length === 0) {
+        return null;
+    }
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "dim", children: "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500" }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "yellow", children: "\uD83D\uDCA1 Next steps:" }) }), hints.map((hint, index) => {
+                const isSelected = interactive && index === selectedIndex;
+                const prefix = interactive ? (isSelected ? '▶ ' : '  ') : `  ${index + 1}. `;
+                return (_jsxs(Box, { children: [_jsxs(Text, { color: isSelected ? 'cyan' : undefined, children: [prefix, hint.description] }), _jsxs(Text, { color: "dim", children: [" (", hint.command, ")"] })] }, index));
+            })] }));
+};

package/dist/ui/components/cli-header.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import chalk from 'chalk';
+const ART = [
+    '██╗  ██╗ ██████╗ ███████╗     ██████╗██╗     ██╗',
+    '██║  ██║██╔════╝ ██╔════╝    ██╔════╝██║     ██║',
+    '███████║██║  ███╗█████╗      ██║     ██║     ██║',
+    '╚════██║██║   ██║██╔══╝      ██║     ██║     ██║',
+    '     ██║╚██████╔╝███████╗    ╚██████╗███████╗██║',
+    '     ╚═╝ ╚═════╝ ╚══════╝     ╚═════╝╚══════╝╚═╝',
+];
+const MIDDY_ART = [
+    '██  ██  ▄▄▄▄ ▄▄▄▄▄   ▄█████ ██     ██ ',
+    '▀█████ ██ ▄▄ ██▄▄    ██     ██     ██ ',
+    '    ██ ▀███▀ ██▄▄▄   ▀█████ ██████ ██ ',
+];
+const COMPACT_ART = [
+    '┏┓      ┏┓┓ ┳',
+    '┃┃┏┓┏┓  ┃ ┃ ┃',
+    '┗╋┗┫┗   ┗┛┗┛┻',
+    '   ┛          ',
+];
+const START_COLOR = { r: 0, g: 229, b: 255 }; // #00e5ff
+const END_COLOR = { r: 224, g: 64, b: 251 }; // #e040fb
+const lerp = (start, end, t) => Math.round(start + (end - start) * t);
+const applyGradient = (text, width) => {
+    return text
+        .split('')
+        .map((char, i) => {
+        const t = i / (width - 1);
+        const r = lerp(START_COLOR.r, END_COLOR.r, t);
+        const g = lerp(START_COLOR.g, END_COLOR.g, t);
+        const b = lerp(START_COLOR.b, END_COLOR.b, t);
+        return chalk.rgb(r, g, b)(char);
+    })
+        .join('');
+};
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const STATUS_CONFIG = {
+    'checking-connectivity': { label: 'Checking Connectivity', icon: SPINNER_FRAMES, color: 'yellow' },
+    'refreshing-token': { label: 'Refreshing Token', icon: SPINNER_FRAMES, color: 'yellow' },
+    ready: { label: 'Ready', icon: '✓', color: 'green' },
+    'no-connection': { label: 'No Connection', icon: '✗', color: 'red' },
+    'update-required': { label: 'Update Required', icon: '⚠', color: 'magenta' },
+};
+const getArt = (variant) => {
+    const art = variant === 'compact' ? MIDDY_ART : ART;
+    const width = Math.max(...art.map((line) => line.length));
+    return { art, width };
+};
+export function renderHeaderString(version, status = 'ready', headerVariant = 'full') {
+    const { art, width } = getArt(headerVariant);
+    const borderTop = chalk.dim(`╔${'═'.repeat(width + 2)}╗`);
+    const borderBottom = chalk.dim(`╚${'═'.repeat(width + 2)}╝`);
+    const artLines = art
+        .map((line) => {
+        const padding = ' '.repeat(width - line.length);
+        return `${chalk.dim('║ ')}${applyGradient(line + padding, width)}${chalk.dim(' ║')}`;
+    })
+        .join('\n');
+    const currentStatus = STATUS_CONFIG[status];
+    const icon = Array.isArray(currentStatus.icon) ? currentStatus.icon[0] : currentStatus.icon;
+    const statusLabel = chalk[currentStatus.color](`${currentStatus.label} ${icon}`);
+    const statusBar = chalk.dim(`[ 4ge CLI | v${version} | Status: ${statusLabel} ]`);
+    return `\n${borderTop}\n${artLines}\n${borderBottom}\n\n${statusBar}\n`;
+}
+export default function CliHeader({ version, status = 'ready', headerVariant = 'full' }) {
+    const [frame, setFrame] = useState(0);
+    useEffect(() => {
+        setFrame(0);
+    }, [status]);
+    useEffect(() => {
+        const isAnimated = Array.isArray(STATUS_CONFIG[status].icon);
+        if (!isAnimated)
+            return;
+        const timer = setInterval(() => {
+            setFrame((prev) => (prev + 1) % SPINNER_FRAMES.length);
+        }, 80);
+        return () => clearInterval(timer);
+    }, [status]);
+    const { art, width } = getArt(headerVariant);
+    const borderTop = `╔${'═'.repeat(width + 2)}╗`;
+    const borderBottom = `╚${'═'.repeat(width + 2)}╝`;
+    const currentStatus = STATUS_CONFIG[status];
+    const icon = Array.isArray(currentStatus.icon) ? currentStatus.icon[frame] : currentStatus.icon;
+    return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: borderTop }), art.map((line, i) => {
+                        const padding = ' '.repeat(width - line.length);
+                        return (_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "\u2551 " }), _jsx(Text, { children: applyGradient(line + padding, width) }), _jsx(Text, { dimColor: true, children: " \u2551" })] }, i));
+                    }), _jsx(Text, { dimColor: true, children: borderBottom })] }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { dimColor: true, children: ["[ 4ge CLI | v", version, " | Status:", ' ', _jsxs(Text, { color: currentStatus.color, children: [currentStatus.label, " ", icon] }), ' ', "]"] }) })] }));
+}

package/dist/ui/components/confirm-prompt.js

@@ -0,0 +1,28 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { PromptLayout } from './prompt-layout.js';
+export function ConfirmPrompt({ message, onConfirm, defaultYes = false, context, helpText, headerVariant }) {
+    const [activeValue, setActiveValue] = useState(defaultYes);
+    useInput((input, key) => {
+        if (input === 'y' || input === 'Y') {
+            onConfirm(true);
+        }
+        else if (input === 'n' || input === 'N') {
+            onConfirm(false);
+        }
+        else if (key.leftArrow || key.rightArrow) {
+            setActiveValue((prev) => !prev);
+        }
+        else if (key.return) {
+            onConfirm(activeValue);
+        }
+        else if (key.escape) {
+            onConfirm(false);
+        }
+        else if (key.ctrl && input === 'd') {
+            process.exit(0);
+        }
+    });
+    return (_jsx(PromptLayout, { message: message, context: context, helpText: helpText, headerVariant: headerVariant, children: _jsxs(Box, { marginLeft: 1, children: [_jsxs(Text, { color: activeValue ? 'cyan' : undefined, bold: activeValue, children: ["[", activeValue ? 'Y' : 'y', "]es"] }), _jsx(Text, { children: "  " }), _jsxs(Text, { color: !activeValue ? 'cyan' : undefined, bold: !activeValue, children: ["[", !activeValue ? 'N' : 'n', "]o"] })] }) }));
+}

package/dist/ui/components/data-table.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+const getStatusColor = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const upper = value.toUpperCase();
+    if (upper.includes('COMPLETE') || upper === 'DONE' || upper === 'SUCCESS')
+        return 'green';
+    if (upper.includes('IN_PROGRESS') || upper === 'PENDING' || upper === 'DOING')
+        return 'yellow';
+    if (upper.includes('FAILED') || upper === 'ERROR' || upper === 'REJECTED')
+        return 'red';
+    return undefined;
+};
+export function DataTable({ data, columns, title, emptyMessage = 'No data available' }) {
+    if (data.length === 0) {
+        return (_jsxs(Box, { flexDirection: "column", paddingY: 1, children: [title && _jsx(Text, { bold: true, underline: true, children: title }), _jsx(Box, { paddingLeft: 2, children: _jsx(Text, { dimColor: true, children: emptyMessage }) })] }));
+    }
+    // Calculate widths
+    const columnWidths = columns.map((col) => {
+        const headerLen = (col.header ?? col.key).length;
+        const maxContentLen = data.reduce((max, item) => {
+            const val = item[col.key];
+            const formatted = col.format ? col.format(val) : String(val ?? '');
+            return Math.max(max, formatted.length);
+        }, 0);
+        return Math.max(col.minWidth ?? 0, headerLen, maxContentLen) + 2;
+    });
+    return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [title && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, underline: true, children: title }) })), _jsx(Box, { children: columns.map((col, i) => (_jsx(Box, { width: columnWidths[i], children: _jsx(Text, { bold: true, children: (col.header ?? col.key).toUpperCase() }) }, col.key))) }), _jsx(Box, { children: columns.map((col, i) => (_jsx(Box, { width: columnWidths[i], children: _jsx(Text, { dimColor: true, children: '-'.repeat(columnWidths[i] - 1) }) }, col.key))) }), data.map((item, rowIndex) => (_jsx(Box, { children: columns.map((col, i) => {
+                    const val = item[col.key];
+                    const formatted = col.format ? col.format(val) : String(val ?? '');
+                    const color = col.color === 'auto' ? getStatusColor(val) : col.color || undefined;
+                    return (_jsx(Box, { width: columnWidths[i], children: _jsx(Text, { color: color, children: formatted }) }, col.key));
+                }) }, rowIndex)))] }));
+}

package/dist/ui/components/detail-view.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export function DetailView({ title, rows }) {
+    return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, underline: true, color: "cyan", children: title }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { dimColor: true, children: '─'.repeat(title.length) }) }), rows.map((row, index) => (_jsxs(Box, { children: [_jsx(Box, { width: 20, children: _jsxs(Text, { dimColor: true, children: [row.label, ":"] }) }), _jsx(Box, { flexGrow: 1, children: row.value ? (_jsx(Text, { color: row.color, children: row.value })) : (_jsx(Text, { dimColor: true, children: "\u2014" })) })] }, index)))] }));
+}

package/dist/ui/components/error-display.js

@@ -0,0 +1,5 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export function ErrorDisplay({ title, message, suggestion }) {
+    return (_jsxs(Box, { flexDirection: "column", marginY: 1, padding: 1, borderStyle: "round", borderColor: "red", children: [_jsx(Box, { marginBottom: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", title] }) }), _jsx(Box, { marginBottom: suggestion ? 1 : 0, children: _jsx(Text, { color: "red", children: message }) }), suggestion && (_jsx(Box, { children: _jsxs(Text, { color: "yellow", children: ["\uD83D\uDCA1 ", suggestion] }) }))] }));
+}

package/dist/ui/components/prompt-layout.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import CliHeader from './cli-header.js';
+export function PromptLayout({ message, context, helpText, children, version, status, headerVariant }) {
+    return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [version && (_jsx(CliHeader, { version: version, status: status ?? 'ready', headerVariant: headerVariant })), context && context.length > 0 && (_jsx(Box, { flexDirection: "column", marginBottom: 1, children: context.map((item, i) => (_jsxs(Text, { dimColor: true, children: [item.label, ": ", item.value] }, i))) })), _jsx(Box, { marginBottom: children ? 1 : 0, children: _jsx(Text, { bold: true, children: message }) }), children, helpText && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: helpText }) }))] }));
+}

package/dist/ui/components/select-prompt.js

@@ -0,0 +1,28 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { PromptLayout } from './prompt-layout.js';
+export function SelectPrompt({ message, options, onSelect, context, helpText, headerVariant }) {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    useInput((input, key) => {
+        if (key.upArrow) {
+            setSelectedIndex((prev) => (prev > 0 ? prev - 1 : options.length - 1));
+        }
+        else if (key.downArrow) {
+            setSelectedIndex((prev) => (prev < options.length - 1 ? prev + 1 : 0));
+        }
+        else if (key.return) {
+            onSelect(options[selectedIndex].value);
+        }
+        else if (key.escape) {
+            onSelect(null);
+        }
+        else if (key.ctrl && input === 'd') {
+            process.exit(0);
+        }
+    });
+    return (_jsx(PromptLayout, { message: message, context: context, helpText: helpText, headerVariant: headerVariant, children: options.map((option, index) => {
+            const isSelected = index === selectedIndex;
+            return (_jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsxs(Text, { color: isSelected ? 'cyan' : undefined, children: [isSelected ? '▶ ' : '  ', option.label] }), option.description && (_jsx(Box, { marginLeft: 4, children: _jsx(Text, { dimColor: true, children: option.description }) }))] }, option.value));
+        }) }));
+}

package/dist/ui/components/spinner.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Text } from 'ink';
+export function Spinner({ message }) {
+    const [frame, setFrame] = useState(0);
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    useEffect(() => {
+        const timer = setInterval(() => {
+            setFrame((prev) => (prev + 1) % frames.length);
+        }, 80);
+        return () => clearInterval(timer);
+    }, [frames.length]);
+    return (_jsxs(Text, { children: [_jsx(Text, { color: "cyan", children: frames[frame] }), " ", message] }));
+}

package/dist/ui/components/success-message.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export function SuccessMessage({ message, path }) {
+    return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: "green", children: "\u2713 " }), _jsx(Text, { children: message })] }), path && (_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2192 ", path] }) }))] }));
+}

package/dist/ui/components/text-input.js

@@ -0,0 +1,29 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+export const TextInput = ({ label, defaultValue = '', placeholder = '', mask = false, onSubmit, onCancel }) => {
+    const [value, setValue] = useState(defaultValue);
+    useInput((input, key) => {
+        if (key.escape) {
+            onCancel(null);
+            return;
+        }
+        if (key.ctrl && input === 'd') {
+            process.exit(0);
+        }
+        if (key.return) {
+            onSubmit(value);
+            return;
+        }
+        if (key.backspace || key.delete) {
+            setValue(prev => prev.slice(0, -1));
+            return;
+        }
+        if (input && !key.ctrl && !key.meta) {
+            setValue(prev => prev + input);
+        }
+    });
+    const displayValue = mask ? '•'.repeat(value.length) : value;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsxs(Text, { color: "cyan", children: [label, ": "] }), _jsx(Text, { children: displayValue || (placeholder ? _jsx(Text, { dimColor: true, children: placeholder }) : '') }), _jsx(Text, { color: "cyan", children: "\u258C" })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "Enter to confirm \u00B7 Esc to cancel" }) })] }));
+};
+export default TextInput;

package/dist/ui/hooks/use-action-hints.js

@@ -0,0 +1,21 @@
+import { useState, useCallback } from 'react';
+import { parseActionHints } from '../../core/api/action-hints.js';
+/**
+ * Hook to manage action hints state.
+ * Parses raw hints from API metadata and tracks user selection.
+ */
+export function useActionHints(rawHints) {
+    const hints = parseActionHints(rawHints);
+    const [selectedCommand, setSelectedCommand] = useState(null);
+    const [dismissed, setDismissed] = useState(false);
+    const reset = useCallback(() => {
+        setSelectedCommand(null);
+        setDismissed(false);
+    }, []);
+    return {
+        hints,
+        selectedCommand,
+        dismissed,
+        reset
+    };
+}

package/dist/ui/hooks/use-status.js

@@ -0,0 +1,22 @@
+import { useState, useCallback } from 'react';
+/**
+ * Hook to manage CLI status state.
+ * Tracks the current status and provides helper methods to update it.
+ */
+export function useStatus(initialStatus = 'checking-connectivity') {
+    const [status, setStatus] = useState(initialStatus);
+    const setCheckingConnectivity = useCallback(() => setStatus('checking-connectivity'), []);
+    const setRefreshingToken = useCallback(() => setStatus('refreshing-token'), []);
+    const setReady = useCallback(() => setStatus('ready'), []);
+    const setNoConnection = useCallback(() => setStatus('no-connection'), []);
+    const setUpdateRequired = useCallback(() => setStatus('update-required'), []);
+    return {
+        status,
+        setStatus,
+        setCheckingConnectivity,
+        setRefreshingToken,
+        setReady,
+        setNoConnection,
+        setUpdateRequired,
+    };
+}

package/dist/ui/index.js

@@ -0,0 +1,15 @@
+export { renderTui } from './render.js';
+export { Spinner } from './components/spinner.js';
+export { DataTable } from './components/data-table.js';
+export { DetailView } from './components/detail-view.js';
+export { SelectPrompt } from './components/select-prompt.js';
+export { ConfirmPrompt } from './components/confirm-prompt.js';
+export { TextInput } from './components/text-input.js';
+export { SuccessMessage } from './components/success-message.js';
+export { ErrorDisplay } from './components/error-display.js';
+export { ActionHints as ActionHintsComponent } from './components/action-hints.js';
+export { selectOption, confirmPrompt } from './prompt-helpers.js';
+// Hooks
+export { useActionHints } from './hooks/use-action-hints.js';
+// Core API Hints
+export { parseActionHints, ActionHintSchema, ActionHintsSchema } from '../core/api/action-hints.js';

package/dist/ui/prompt-helpers.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from 'ink';
+import { SelectPrompt } from './components/select-prompt.js';
+import { ConfirmPrompt } from './components/confirm-prompt.js';
+import { TextInput } from './components/text-input.js';
+import { ActionHints } from './components/action-hints.js';
+import chalk from 'chalk';
+/**
+ * Encapsulates the common pattern for interactive prompts:
+ * 1. Create Ink instance
+ * 2. Return Promise that unmounts and resolves with null or the value
+ */
+async function withPromptWrapper(renderFn) {
+    return new Promise((resolve) => {
+        let instance;
+        let settled = false;
+        const cleanup = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (instance) {
+                instance.clear?.();
+                instance.unmount();
+            }
+            resolve(value);
+        };
+        instance = render(renderFn(cleanup));
+        // When Ink handles Ctrl+C (default behavior) or is unmounted, 
+        // we resolve with null to indicate cancellation/exit.
+        instance.waitUntilExit().then(() => {
+            if (settled)
+                return;
+            settled = true;
+            if (instance) {
+                instance.clear?.();
+            }
+            resolve(null);
+        });
+    });
+}
+export async function selectOption(message, options, context, helpText, headerVariant) {
+    return withPromptWrapper((resolve) => (_jsx(SelectPrompt, { message: message, options: options, context: context, helpText: helpText, onSelect: resolve, headerVariant: headerVariant })));
+}
+export async function confirmPrompt(message, defaultYes = false, context, helpText, headerVariant) {
+    return withPromptWrapper((resolve) => (_jsx(ConfirmPrompt, { message: message, context: context, helpText: helpText, onConfirm: resolve, defaultYes: defaultYes, headerVariant: headerVariant })));
+}
+export async function textInput(message, options) {
+    return withPromptWrapper((resolve) => (_jsx(TextInput, { label: message, placeholder: options?.placeholder, mask: options?.mask, defaultValue: options?.defaultValue, onSubmit: resolve, onCancel: () => resolve(null) })));
+}
+export async function renderActionHintsMenu(hints) {
+    return withPromptWrapper((resolve) => (_jsx(ActionHints, { hints: hints, interactive: true, onSelect: (command) => {
+            console.log(`\n  🚀 Run: ${chalk.cyan(command)}\n`);
+            resolve();
+        }, onDismiss: resolve })));
+}

package/dist/ui/render.js

@@ -0,0 +1,9 @@
+import { render } from 'ink';
+/**
+ * Render an Ink component and wait for it to exit.
+ * Returns the Ink instance for advanced control.
+ */
+export async function renderTui(element) {
+    const instance = render(element);
+    return instance;
+}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@4ge/cli",
+  "version": "0.1.0",
+  "description": "4ge Service Architecture Bridge & CLI",
+  "main": "dist/index.js",
+  "bin": {
+    "4ge": "bin/run.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Conflate-AI/4ge-cli.git"
+  },
+  "homepage": "https://github.com/Conflate-AI/4ge-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Conflate-AI/4ge-cli/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "oclif": {
+    "commands": "./dist/commands",
+    "bin": "4ge",
+    "dirname": "4ge",
+    "plugins": [
+      "@oclif/plugin-help"
+    ],
+    "flexibleTaxonomy": true
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "node --env-file=.env.local ./bin/dev.js",
+    "test": "node --env-file=.env.test ./node_modules/vitest/vitest.mjs run",
+    "test:watch": "node --env-file=.env.test ./node_modules/vitest/vitest.mjs",
+    "lint": "eslint src/ --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "sync-api": "openapi-ts && prettier --write \"src/generated/api/**/*.ts\"",
+    "prepublishOnly": "tsc"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "package.json",
+    "README.md",
+    "usage.md"
+  ],
+  "keywords": [
+    "4ge",
+    "cli",
+    "oclif",
+    "project-management",
+    "ai-agent"
+  ],
+  "author": "Conflate AI",
+  "packageManager": "pnpm@10.18.0",
+  "dependencies": {
+    "@oclif/core": "^4",
+    "@oclif/plugin-help": "^6.2.49",
+    "@supabase/supabase-js": "^2.106.2",
+    "chalk": "^5.6.2",
+    "ink": "^7.0.3",
+    "open": "^11.0.0",
+    "react": "^19.2.6",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@hey-api/client-fetch": "^0.13.1",
+    "@hey-api/openapi-ts": "0.97.2",
+    "@types/node": "^24.12.4",
+    "@types/react": "^19.2.15",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.4.0",
+    "fast-glob": "^3.3.3",
+    "prettier": "^3.8.3",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "tsx": "^4.22.3",
+    "typescript": "^5.5",
+    "vitest": "^4.1.7"
+  }
+}

package/skills/4ge-cli.md

@@ -0,0 +1,113 @@
+# 4ge CLI Skill
+
+This document provides instructions for AI agents to interact with the 4ge
+Product Management Platform using the `4ge` CLI.
+
+## 🚨 Preconditions (User Action Required)
+Before using this CLI, the user **MUST** have completed:
+- **Authentication**: Set the `4GE_API_KEY` environment variable or run `4ge auth:login`.
+- **Initialization**: Run `4ge init` in the project root.
+- **Configuration**: `.4ge/config.yaml` exists with a valid `project_id`.
+
+**Do NOT attempt to run `auth:login`, `init`, or manual configuration commands.**
+The CLI is already installed and configured in this project.
+
+## ⌨️ Command Syntax
+All interactions follow this structure:
+
+```bash
+4ge <namespace>:<command> [options] --json
+```
+
+- **Namespace:Command**: Colon-separated (e.g. `epic:list`, `story:show`, `auth:status`).
+- **Required flag**: `--json` is **mandatory** in agent mode for machine-readable output.
+- **Positional arguments**: A few commands take a direct arg without a flag (e.g. `idea:show <ID>`).
+
+## 🛠 Usage Guidelines
+
+### 1. Always use JSON mode
+Append `--json` to **every** command.
+
+```bash
+4ge epic:list --json
+```
+
+#### Response envelope
+```json
+{
+  "data": { ... },
+  "error": null | { "message": string, "code"?: string, "details"?: any, "hint"?: string },
+  "metadata": { "timestamp": "ISO8601", "action_hints": [{ "description": string, "command": string }] }
+}
+```
+`--json` mode sets the `X-Client-Type: 4ge-agent` header on API calls.
+
+### 2. Action hints
+`metadata.action_hints` provides **optional** next-step suggestions. Use judgment
+to decide relevance. `action_hints` is only present when the API provides it —
+do not assume it always exists.
+
+### 3. Error handling
+If `error` is non-null:
+- Inspect `error.message` and `error.code`.
+- Follow `error.hint` for recovery.
+- Run with `--help` if a flag issue is suspected.
+
+### 4. Discovery
+When unsure of flags or subcommands, run `<command> --help` (e.g.
+`4ge story:list --help`).
+
+### 5. Preview changes before applying (dry-run)
+All mutation commands accept `--dry-run`. It prints the payload that **would** be
+sent without executing it. Always use it before running a mutation for the first
+time against a resource.
+
+```bash
+4ge story:update --story-id <id> --status COMPLETE --dry-run --json
+```
+
+### 6. Retry transient failures
+All commands accept `--retry <n>` (attempts with exponential backoff + jitter).
+Use it for network-flaky operations.
+
+```bash
+4ge epic:pull --id <id> --retry 3 --json
+```
+
+## 📋 Command Reference
+
+| Namespace | Commands | Key Flags |
+|-----------|----------|-----------|
+| **project** | `create`, `info`, `list`, `pull`, `update` | `--workspace` (create), `--name`, `--description`, `--template`, `--force`, `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
+| **epic** | `list`, `show`, `pull`, `update` | `--epic-id` / `--id` (pull), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
+| **story** | `list`, `show`, `pull`, `update` | `--story-id` / `--id` (pull), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
+| **feature** | `list`, `show`, `pull`, `update` | `--feature-id` / `--id` (pull), `--status`, `--roadmap`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
+| **idea** | `create`, `graduate`, `list`, `show`, `update` | `<ID>` (positional for show), `--title`, `--workspace`, `--dry-run`, `--retry` |
+| **template** | `create`, `delete`, `info`, `list`, `pull`, `update` | `--id`, `--name`, `--workspace`, `--description`, `--force`, `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
+| **template:feature** | `create`, `delete`, `list`, `update` | `--id`, `--template-id`, `--name`, `--description`, `--status`, `--dry-run`, `--retry` |
+| **plan** | `pull`, `versions` | `--roadmap` (now\|next\|later), `--status`, `--save`, `--stdout`, `--retry` |
+| **auth** | `status`, `logout`, `profile:list`, `profile:use`, `profile:delete` | *(login/logout are user-only)* |
+| **config** | `set`, `get`, `show`, `manage` | `manage` opens interactive config editor; `set`/`get` take `key` / `key=value` |
+| **skill** | `install` | `--agent`, `--global`, `--force` (installs this skill file for an agent harness) |
+| *(root)* | `init`, `whoami` | `init` sets up `.4ge/config.yaml`; `whoami` aliases `auth:status` |
+
+### Project context
+Epic, story, and feature commands read the project from `.4ge/config.yaml`.
+No `--project-id` flag is needed for those namespaces.
+
+### Hierarchy config defaults
+`.4ge/config.yaml` may define:
+- `hierarchy.default_roadmap_filter` (now\|next\|later\|all) — fall-back for `--roadmap` on pull commands.
+- `hierarchy.recursive_pull` (bool) — fall-back for `--recursive` on pull commands.
+
+Flags always override config; bare `4ge <ns>:pull --id <id>` honours the config defaults.
+
+## 🔄 Common Workflow Patterns
+
+1. **Explore projects**: `4ge project:list --json`
+2. **List epics** (honours config `default_roadmap_filter`): `4ge epic:list --json`
+3. **Drill down**: `4ge story:show --story-id <id> --json`
+4. **Pull full hierarchy tree**: `4ge epic:pull --id <id> --recursive --json`
+5. **Sync local plan assets**: `4ge plan:pull --json`
+6. **Preview a mutation**: `4ge story:update --story-id <id> --status COMPLETE --dry-run --json`
+7. **Apply the mutation**: drop `--dry-run` and re-run.