@pokit/tabs-core 0.0.1

package/dist/ring-buffer.js

@@ -0,0 +1,270 @@
+/**
+ * Ring Buffer Implementation
+ *
+ * A fixed-capacity circular buffer with O(1) push operations.
+ * When full, oldest elements are automatically overwritten.
+ *
+ * Key features:
+ * - O(1) push operations (no array shifting)
+ * - Configurable capacity with buffer pressure warnings
+ * - Track number of dropped items
+ * - Dropped line indicator support
+ */
+// =============================================================================
+// RingBuffer Class
+// =============================================================================
+/**
+ * A circular buffer that overwrites oldest items when full.
+ * All operations are O(1) except toArray() which is O(n).
+ */
+export class RingBuffer {
+    buffer;
+    head = 0; // Points to next write position
+    _length = 0;
+    capacity;
+    maxLineLength;
+    warnAtPercentage;
+    onPressure;
+    _droppedCount = 0;
+    warningEmitted = false;
+    constructor(options) {
+        this.capacity = options.capacity;
+        this.maxLineLength = options.maxLineLength;
+        this.warnAtPercentage = options.warnAtPercentage ?? 80;
+        this.onPressure = options.onPressure;
+        this.buffer = new Array(this.capacity);
+    }
+    /**
+     * Number of items currently in the buffer
+     */
+    get length() {
+        return this._length;
+    }
+    /**
+     * Number of items that have been dropped due to capacity limits
+     */
+    get droppedCount() {
+        return this._droppedCount;
+    }
+    /**
+     * Current buffer usage as a percentage (0-100)
+     */
+    get usagePercentage() {
+        return (this._length / this.capacity) * 100;
+    }
+    /**
+     * Whether the buffer is at capacity
+     */
+    get isFull() {
+        return this._length === this.capacity;
+    }
+    /**
+     * Push an item into the buffer.
+     * If full, the oldest item is overwritten and droppedCount is incremented.
+     *
+     * @param item - The item to add
+     * @returns true if an item was dropped, false otherwise
+     */
+    push(item) {
+        let dropped = false;
+        // Truncate string items if maxLineLength is set
+        let processedItem = item;
+        if (this.maxLineLength && typeof item === 'string') {
+            processedItem =
+                item.length > this.maxLineLength
+                    ? (item.slice(0, this.maxLineLength) + '…')
+                    : item;
+        }
+        // Check if we're about to overwrite
+        if (this._length === this.capacity) {
+            this._droppedCount++;
+            dropped = true;
+        }
+        else {
+            this._length++;
+        }
+        // Write to current head position
+        this.buffer[this.head] = processedItem;
+        this.head = (this.head + 1) % this.capacity;
+        // Check for buffer pressure warning
+        this.checkPressure();
+        return dropped;
+    }
+    /**
+     * Push multiple items into the buffer.
+     *
+     * @param items - Array of items to add
+     * @returns Number of items that were dropped
+     */
+    pushMany(items) {
+        let droppedThisCall = 0;
+        for (const item of items) {
+            if (this.push(item)) {
+                droppedThisCall++;
+            }
+        }
+        return droppedThisCall;
+    }
+    /**
+     * Clear all items from the buffer and reset dropped count.
+     */
+    clear() {
+        this.buffer = new Array(this.capacity);
+        this.head = 0;
+        this._length = 0;
+        this._droppedCount = 0;
+        this.warningEmitted = false;
+    }
+    /**
+     * Convert buffer contents to an array in correct order (oldest to newest).
+     * This is O(n) where n is the number of items in the buffer.
+     */
+    toArray() {
+        if (this._length === 0)
+            return [];
+        const result = new Array(this._length);
+        if (this._length < this.capacity) {
+            // Buffer not full yet, items are from 0 to head-1
+            for (let i = 0; i < this._length; i++) {
+                result[i] = this.buffer[i];
+            }
+        }
+        else {
+            // Buffer is full, read from head (oldest) to head-1 (newest)
+            for (let i = 0; i < this._length; i++) {
+                const index = (this.head + i) % this.capacity;
+                result[i] = this.buffer[index];
+            }
+        }
+        return result;
+    }
+    /**
+     * Get the item at the specified index (0 = oldest).
+     */
+    get(index) {
+        if (index < 0 || index >= this._length)
+            return undefined;
+        if (this._length < this.capacity) {
+            return this.buffer[index];
+        }
+        else {
+            const actualIndex = (this.head + index) % this.capacity;
+            return this.buffer[actualIndex];
+        }
+    }
+    /**
+     * Get a slice of items from the buffer.
+     *
+     * @param start - Start index (inclusive)
+     * @param end - End index (exclusive), defaults to length
+     */
+    slice(start, end) {
+        const actualEnd = end ?? this._length;
+        const normalizedStart = Math.max(0, start);
+        const normalizedEnd = Math.min(this._length, actualEnd);
+        if (normalizedStart >= normalizedEnd)
+            return [];
+        const result = [];
+        for (let i = normalizedStart; i < normalizedEnd; i++) {
+            const item = this.get(i);
+            if (item !== undefined) {
+                result.push(item);
+            }
+        }
+        return result;
+    }
+    /**
+     * Reset the warning flag so it can be emitted again.
+     * Useful after displaying a warning to the user.
+     */
+    resetWarning() {
+        this.warningEmitted = false;
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    checkPressure() {
+        if (this.warningEmitted || !this.onPressure)
+            return;
+        const usage = this.usagePercentage;
+        if (usage >= this.warnAtPercentage) {
+            this.warningEmitted = true;
+            this.onPressure(usage);
+        }
+    }
+}
+const DEFAULT_MAX_LINES = 10_000;
+const DEFAULT_MAX_LINE_LENGTH = 5_000;
+const DEFAULT_WARN_PERCENTAGE = 80;
+/**
+ * Specialized output buffer for tab process output.
+ * Wraps RingBuffer with dropped line indicator support.
+ */
+export class OutputBuffer {
+    buffer;
+    tabId;
+    lastReportedDropped = 0;
+    constructor(options = {}) {
+        this.tabId = options.tabId ?? 'unknown';
+        this.buffer = new RingBuffer({
+            capacity: options.maxLines ?? DEFAULT_MAX_LINES,
+            maxLineLength: options.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH,
+            warnAtPercentage: options.warnAtPercentage ?? DEFAULT_WARN_PERCENTAGE,
+            onPressure: options.onPressure
+                ? (usage) => options.onPressure(this.tabId, usage)
+                : undefined,
+        });
+    }
+    get length() {
+        return this.buffer.length;
+    }
+    get droppedCount() {
+        return this.buffer.droppedCount;
+    }
+    get usagePercentage() {
+        return this.buffer.usagePercentage;
+    }
+    get isFull() {
+        return this.buffer.isFull;
+    }
+    /**
+     * Push lines into the buffer.
+     */
+    push(...lines) {
+        this.buffer.pushMany(lines);
+    }
+    /**
+     * Clear the buffer.
+     */
+    clear() {
+        this.buffer.clear();
+        this.lastReportedDropped = 0;
+    }
+    /**
+     * Get all lines as an array with dropped line indicator if applicable.
+     * The dropped indicator is inserted at the beginning if lines were dropped.
+     */
+    toArray() {
+        const lines = this.buffer.toArray();
+        const dropped = this.buffer.droppedCount;
+        if (dropped > 0 && dropped !== this.lastReportedDropped) {
+            this.lastReportedDropped = dropped;
+        }
+        if (dropped > 0) {
+            return [`... (${dropped.toLocaleString()} lines dropped) ...`, ...lines];
+        }
+        return lines;
+    }
+    /**
+     * Get lines without the dropped indicator.
+     */
+    toArrayRaw() {
+        return this.buffer.toArray();
+    }
+    /**
+     * Reset the warning flag.
+     */
+    resetWarning() {
+        this.buffer.resetWarning();
+    }
+}

package/dist/state-reducer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * State Reducer for Event-Driven CLI
+ *
+ * Builds a state tree from CLI events using a reducer pattern.
+ * Framework-agnostic - used by both Ink and OpenTUI adapters.
+ */
+import type { CLIEvent, GroupId } from '@pokit/core';
+import type { EventDrivenState, ActivityNode, GroupNode } from './types.js';
+/**
+ * Create initial state
+ */
+export declare function createInitialState(): EventDrivenState;
+/**
+ * Reducer function for CLI events
+ */
+export declare function reducer(state: EventDrivenState, event: CLIEvent): EventDrivenState;
+/**
+ * Get activities that belong to a tabs group
+ */
+export declare function getTabsGroupActivities(state: EventDrivenState, groupId: GroupId): ActivityNode[];
+/**
+ * Find the first tabs group in the state
+ */
+export declare function findTabsGroup(state: EventDrivenState): GroupNode | undefined;
+//# sourceMappingURL=state-reducer.d.ts.map

package/dist/state-reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-reducer.d.ts","sourceRoot":"","sources":["../src/state-reducer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAc,OAAO,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5E;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,gBAAgB,CASrD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,QAAQ,GAAG,gBAAgB,CA0JlF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,EAAE,CAOhG;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAO5E"}

package/dist/state-reducer.js

@@ -0,0 +1,175 @@
+/**
+ * State Reducer for Event-Driven CLI
+ *
+ * Builds a state tree from CLI events using a reducer pattern.
+ * Framework-agnostic - used by both Ink and OpenTUI adapters.
+ */
+/**
+ * Create initial state
+ */
+export function createInitialState() {
+    return {
+        appName: undefined,
+        version: undefined,
+        exitCode: undefined,
+        activities: new Map(),
+        groups: new Map(),
+        rootChildren: [],
+    };
+}
+/**
+ * Reducer function for CLI events
+ */
+export function reducer(state, event) {
+    switch (event.type) {
+        case 'root:start':
+            return {
+                ...state,
+                appName: event.appName,
+                version: event.version,
+            };
+        case 'root:end':
+            return {
+                ...state,
+                exitCode: event.exitCode,
+            };
+        case 'group:start': {
+            const newGroup = {
+                type: 'group',
+                id: event.id,
+                parentId: event.parentId,
+                label: event.label,
+                layout: event.layout,
+                children: [],
+            };
+            const newGroups = new Map(state.groups);
+            newGroups.set(event.id, newGroup);
+            if (event.parentId) {
+                const parentGroup = state.groups.get(event.parentId);
+                if (parentGroup) {
+                    const updatedParent = {
+                        ...parentGroup,
+                        children: [...parentGroup.children, event.id],
+                    };
+                    newGroups.set(event.parentId, updatedParent);
+                }
+                return { ...state, groups: newGroups };
+            }
+            return {
+                ...state,
+                groups: newGroups,
+                rootChildren: [...state.rootChildren, event.id],
+            };
+        }
+        case 'group:end':
+            return state;
+        case 'activity:start': {
+            const newActivity = {
+                type: 'activity',
+                id: event.id,
+                parentId: event.parentId,
+                label: event.label,
+                status: 'running',
+                meta: event.meta,
+                logs: [],
+            };
+            const newActivities = new Map(state.activities);
+            newActivities.set(event.id, newActivity);
+            if (event.parentId) {
+                const parentGroup = state.groups.get(event.parentId);
+                if (parentGroup) {
+                    const newGroups = new Map(state.groups);
+                    const updatedParent = {
+                        ...parentGroup,
+                        children: [...parentGroup.children, event.id],
+                    };
+                    newGroups.set(event.parentId, updatedParent);
+                    return { ...state, activities: newActivities, groups: newGroups };
+                }
+                return { ...state, activities: newActivities };
+            }
+            return {
+                ...state,
+                activities: newActivities,
+                rootChildren: [...state.rootChildren, event.id],
+            };
+        }
+        case 'activity:update': {
+            const activity = state.activities.get(event.id);
+            if (!activity)
+                return state;
+            const updatedActivity = {
+                ...activity,
+                progress: event.payload.progress ?? activity.progress,
+                message: event.payload.message ?? activity.message,
+            };
+            const newActivities = new Map(state.activities);
+            newActivities.set(event.id, updatedActivity);
+            return { ...state, activities: newActivities };
+        }
+        case 'activity:success': {
+            const activity = state.activities.get(event.id);
+            if (!activity)
+                return state;
+            const updatedActivity = {
+                ...activity,
+                status: 'success',
+            };
+            const newActivities = new Map(state.activities);
+            newActivities.set(event.id, updatedActivity);
+            return { ...state, activities: newActivities };
+        }
+        case 'activity:failure': {
+            const activity = state.activities.get(event.id);
+            if (!activity)
+                return state;
+            const errorMessage = event.error instanceof Error ? event.error.message : String(event.error);
+            const updatedActivity = {
+                ...activity,
+                status: 'failure',
+                message: errorMessage,
+            };
+            const newActivities = new Map(state.activities);
+            newActivities.set(event.id, updatedActivity);
+            return { ...state, activities: newActivities };
+        }
+        case 'log': {
+            if (!event.activityId)
+                return state;
+            const activity = state.activities.get(event.activityId);
+            if (!activity)
+                return state;
+            const updatedActivity = {
+                ...activity,
+                logs: [...activity.logs, { level: event.level, message: event.message }],
+            };
+            const newActivities = new Map(state.activities);
+            newActivities.set(event.activityId, updatedActivity);
+            return { ...state, activities: newActivities };
+        }
+        default:
+            return state;
+    }
+}
+/**
+ * Get activities that belong to a tabs group
+ */
+export function getTabsGroupActivities(state, groupId) {
+    const group = state.groups.get(groupId);
+    if (!group || group.layout !== 'tabs')
+        return [];
+    return group.children
+        .map((childId) => state.activities.get(childId))
+        .filter((activity) => activity !== undefined);
+}
+/**
+ * Find the first tabs group in the state
+ */
+export function findTabsGroup(state) {
+    for (const group of state.groups.values()) {
+        if (group.layout === 'tabs') {
+            return group;
+        }
+    }
+    return undefined;
+}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared Types for CLI Tabs
+ *
+ * Framework-agnostic types used by both Ink and OpenTUI adapters.
+ */
+import type { ActivityId, GroupId, GroupLayout } from '@pokit/core';
+export type TabStatus = 'running' | 'done' | 'error' | 'stopped';
+export type TabProcess = {
+    id: string;
+    label: string;
+    exec: string;
+    output: string[];
+    status: TabStatus;
+    exitCode?: number;
+};
+export declare const MAX_OUTPUT_LINES = 10000;
+export declare const MAX_LINE_LENGTH = 5000;
+export declare const BUFFER_WARNING_THRESHOLD = 80;
+/**
+ * Status indicator configuration for tabs.
+ *
+ * Color scheme:
+ * - running: green (active process)
+ * - done: cyan (completed/inactive)
+ * - error: red (failed)
+ * - stopped: yellow (manually stopped)
+ */
+export type StatusIndicator = {
+    color: string;
+    colorBright: string;
+    icon: string;
+};
+export declare const STATUS_INDICATORS: Record<TabStatus, StatusIndicator>;
+export declare function getStatusIndicator(status: TabStatus, bright?: boolean): {
+    color: string;
+    icon: string;
+};
+/**
+ * Activity node in the state tree
+ */
+export type ActivityNode = {
+    type: 'activity';
+    id: ActivityId;
+    parentId?: GroupId | ActivityId;
+    label: string;
+    status: 'running' | 'success' | 'failure';
+    progress?: number;
+    message?: string;
+    meta?: Record<string, unknown>;
+    logs: Array<{
+        level: string;
+        message: string;
+    }>;
+};
+/**
+ * Group node in the state tree
+ */
+export type GroupNode = {
+    type: 'group';
+    id: GroupId;
+    parentId?: GroupId;
+    label: string;
+    layout: GroupLayout;
+    children: Array<ActivityId | GroupId>;
+};
+/**
+ * Root state for the event-driven CLI
+ */
+export type EventDrivenState = {
+    appName?: string;
+    version?: string;
+    exitCode?: number;
+    activities: Map<ActivityId, ActivityNode>;
+    groups: Map<GroupId, GroupNode>;
+    rootChildren: Array<ActivityId | GroupId>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMpE,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEjE,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,eAAO,MAAM,eAAe,OAAQ,CAAC;AACrC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAM3C;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,SAAS,EAAE,eAAe,CAKhE,CAAC;AAEF,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,GAAE,OAAe,GACtB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMjC;AAMD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,UAAU,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAC1C,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAChC,YAAY,EAAE,KAAK,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC;CAC3C,CAAC"}

package/dist/types.js

@@ -0,0 +1,21 @@
+/**
+ * Shared Types for CLI Tabs
+ *
+ * Framework-agnostic types used by both Ink and OpenTUI adapters.
+ */
+export const MAX_OUTPUT_LINES = 10_000;
+export const MAX_LINE_LENGTH = 5_000;
+export const BUFFER_WARNING_THRESHOLD = 80; // Percentage
+export const STATUS_INDICATORS = {
+    running: { color: '#00AA00', colorBright: '#00FF00', icon: '●' },
+    done: { color: '#00AAAA', colorBright: '#00FFFF', icon: '○' },
+    error: { color: '#AA0000', colorBright: '#FF0000', icon: '✗' },
+    stopped: { color: '#AAAA00', colorBright: '#FFFF00', icon: '■' },
+};
+export function getStatusIndicator(status, bright = false) {
+    const indicator = STATUS_INDICATORS[status];
+    return {
+        color: bright ? indicator.colorBright : indicator.color,
+        icon: indicator.icon,
+    };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@pokit/tabs-core",
+  "version": "0.0.1",
+  "description": "Core tab management utilities for pok CLI applications",
+  "keywords": [
+    "cli",
+    "command-line",
+    "typescript",
+    "bun",
+    "terminal",
+    "pok",
+    "pokjs",
+    "tabs",
+    "tab-management",
+    "process-manager"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/notation-dev/openpok.git",
+    "directory": "packages/tabs-core"
+  },
+  "homepage": "https://github.com/notation-dev/openpok#readme",
+  "bugs": {
+    "url": "https://github.com/notation-dev/openpok/issues"
+  },
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "@pokit/core": "0.0.1"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.0",
+    "react": "^19.2.0",
+    "@pokit/core": "0.0.1"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}