npcts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NPC Worldwide
+
+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,139 @@
+# npcts
+
+TypeScript library for building NPC-powered applications with split-pane 
+layouts, file editors, terminals, chat interfaces, and file management.
+
+## Architecture
+
+### Core Interfaces
+- `core/types.ts` - Base types (ModelInfo, Attachment, ToolCall)
+- `core/chat.ts` - Chat client interface
+- `core/files.ts` - File system client interface  
+- `core/browser.ts` - Browser client interface
+- `core/jobs.ts` - Jobs/cron client interface
+- `core/layout.ts` - Layout node types
+
+### Adapters
+Platform-specific implementations of core interfaces:
+- `adapters/base.ts` - AppServices interface definition
+- `adapters/electron/bridge.ts` - Electron/window.api implementation
+
+### UI Components
+
+#### Layout System
+- `LayoutProvider` - Context for split pane state management
+- `LayoutNodeComponent` - Recursive layout tree renderer
+- `SplitView` - Resizable horizontal/vertical splits
+- `PaneHeader` - Pane title bar with close/rename
+- `ContentPaneContainer` - Content type router
+- `AppShell` - Complete application with sidebar + layout
+
+#### File Management
+- `FileSystemProvider` - File operations context
+- `FileTree` - Recursive directory tree
+- `Sidebar` - Workspace sidebar with search
+
+#### Content Viewers
+- `CodeEditor` - CodeMirror-based editor with syntax highlighting
+- `Terminal` - Basic terminal emulator
+- `BrowserViewer` - Embedded browser frame
+- `PdfViewer` - PDF document viewer
+- `CsvViewer` - Spreadsheet table view
+- `ImageViewer` - Image display with zoom/rotate
+
+#### Chat
+- `ChatProvider` - Chat state management with streaming
+- `ChatInterface` - Complete chat UI
+- `ChatView` - Message list with auto-scroll
+- `InputArea` - Message input with file attachments
+- `ConversationList` - Conversation sidebar
+
+#### Primitives
+- `AutosizeTextarea` - Auto-growing textarea
+- `Spinner` - Loading indicator
+
+## Quick Start
+
+### With Electron
+```typescript
+import { createElectronAdapter, AppShell } from "npcts";
+
+const services = createElectronAdapter(window.api);
+
+function App() {
+  return (
+    <AppShell 
+      services={services} 
+      workspacePath="/path/to/workspace"
+    />
+  );
+}
+```
+
+### Custom Adapter
+```typescript
+import type { AppServices, ChatClient, FileSystemClient } from "npcts";
+
+const customServices: AppServices = {
+  chat: customChatClient,
+  files: customFileClient,
+  browser: customBrowserClient,
+  jobs: customJobsClient,
+};
+```
+
+### Layout Only
+```typescript
+import { LayoutProvider, Studio } from "npcts";
+
+function App() {
+  return <Studio services={services} />;
+}
+```
+
+## Project Structure
+```
+src/
+├── adapters/          # Platform implementations
+│   ├── base.ts
+│   └── electron/
+├── core/              # Core interface definitions
+│   ├── types.ts
+│   ├── chat.ts
+│   ├── files.ts
+│   ├── browser.ts
+│   ├── jobs.ts
+│   └── layout.ts
+└── ui/                # React components
+    ├── chat/          # Chat UI components
+    ├── layout/        # Split pane system
+    ├── viewers/       # Content viewers
+    ├── files/         # File management
+    ├── primitives/    # Base components
+    └── markdown/      # Markdown rendering
+```
+
+## Development
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript
+npm run dev          # Watch mode
+npm run check        # Type check only
+```
+
+## Features
+
+- 🎨 Split-pane layout system with drag-to-split
+- 📁 File tree navigation with context menus
+- 💬 Real-time chat with streaming support
+- ✏️ Code editor with syntax highlighting
+- 🖥️ Terminal emulator
+- 🌐 Browser viewer
+- 📄 PDF, CSV, and image viewers
+- 🔌 Pluggable adapter system
+- 📦 TypeScript-first with full type safety
+- ⚛️ React 18+ compatible
+
+## License
+
+MIT

package/dist/adapters/base.d.ts

@@ -0,0 +1,13 @@
+import type { BrowserClient } from "../core/browser";
+import type { ChatClient } from "../core/chat";
+import type { FileSystemClient } from "../core/files";
+import type { JobClient } from "../core/jobs";
+import type { DatabaseClient } from "../core/database";
+export interface AppServices {
+    chat: ChatClient;
+    files: FileSystemClient;
+    jobs?: JobClient;
+    browser?: BrowserClient;
+    database?: DatabaseClient;
+}
+export type AdapterFactory<T = unknown> = (bridge: T) => AppServices;

package/dist/adapters/base.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/electron/bridge.d.ts

@@ -0,0 +1,4 @@
+import type { AdapterFactory } from "../base";
+type ElectronApi = Record<string, any> | undefined;
+export declare const createElectronAdapter: AdapterFactory<ElectronApi>;
+export {};

package/dist/adapters/electron/bridge.js

@@ -0,0 +1,88 @@
+const ensureApi = (api) => {
+    if (!api)
+        throw new Error("Electron preload api is not available on window.api");
+    return api;
+};
+const createChatClient = (rawApi) => {
+    const api = ensureApi(rawApi);
+    return {
+        listConversations: (workspacePath) => {
+            if (api.getConversationsInDirectory && workspacePath) {
+                return api.getConversationsInDirectory(workspacePath);
+            }
+            return api.getConversations?.(workspacePath ?? "") ?? Promise.resolve([]);
+        },
+        createConversation: (workspacePath) => api.createConversation?.({ directory_path: workspacePath }) ??
+            Promise.reject(new Error("createConversation not implemented")),
+        deleteConversation: (conversationId) => api.deleteConversation?.(conversationId) ?? Promise.resolve(),
+        listMessages: (conversationId) => api.getConversationMessages?.(conversationId) ?? Promise.resolve([]),
+        sendMessage: async (request) => {
+            const modelId = typeof request.model === "string" ? request.model : request.model.id;
+            if (request.stream && api.onStreamData) {
+                // The host should expose a stream API that yields chunks; we forward the generator when available.
+                const generator = api.executeCommandStream?.({
+                    commandstr: request.prompt,
+                    conversationId: request.conversationId,
+                    model: modelId,
+                });
+                if (generator)
+                    return generator;
+            }
+            const msg = await api.sendMessage?.({
+                conversationId: request.conversationId,
+                message: request.prompt,
+                model: modelId,
+                attachments: request.attachments,
+            });
+            return msg;
+        },
+        deleteMessage: (conversationId, messageId) => api.deleteMessage?.({ conversationId, messageId }) ?? Promise.resolve(),
+    };
+};
+const createFileSystemClient = (rawApi) => {
+    const api = ensureApi(rawApi);
+    return {
+        readDirectoryStructure: (dirPath) => api.readDirectoryStructure(dirPath),
+        readFileContent: (path) => api.readFileContent(path),
+        writeFileContent: (path, content) => api.writeFileContent(path, content),
+        createDirectory: (path) => api.createDirectory(path),
+        deleteFile: (path) => api.deleteFile(path),
+        deleteDirectory: (path) => api.deleteDirectory(path),
+        rename: (oldPath, newPath) => api.renameFile(oldPath, newPath),
+    };
+};
+const createJobClient = (rawApi) => {
+    const api = ensureApi(rawApi);
+    return {
+        listCronJobs: () => api.getCronDaemons(),
+        addCronJob: (job) => api.addCronJob(job),
+        removeCronJob: (id) => api.removeCronJob(id),
+        listDaemons: () => api.getCronDaemons(),
+        addDaemon: (daemon) => api.addDaemon(daemon),
+        removeDaemon: (id) => api.removeDaemon(id),
+    };
+};
+const createBrowserClient = (rawApi) => {
+    const api = ensureApi(rawApi);
+    return {
+        navigate: (url) => api.browserNavigate({ url }),
+        back: () => api.browserBack({}),
+        forward: () => api.browserForward({}),
+        refresh: () => api.browserRefresh({}),
+        getSelectedText: () => api.browserGetSelectedText({}),
+        listHistory: () => api.browserGetHistory({}),
+        addHistory: (entry) => api.browserAddToHistory(entry),
+        clearHistory: () => api.browserClearHistory({}),
+        listBookmarks: () => api.browserGetBookmarks({}),
+        addBookmark: (bookmark) => api.browserAddBookmark(bookmark),
+        deleteBookmark: (id) => api.browserDeleteBookmark({ id }),
+    };
+};
+export const createElectronAdapter = (bridge) => {
+    return {
+        chat: createChatClient(bridge),
+        files: createFileSystemClient(bridge),
+        jobs: createJobClient(bridge),
+        browser: createBrowserClient(bridge),
+    };
+};

package/dist/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export * from './base';
+export { createElectronAdapter } from './electron/bridge';

package/dist/adapters/index.js

@@ -0,0 +1,3 @@
+// Adapters module exports
+export * from './base';
+export { createElectronAdapter } from './electron/bridge';

package/dist/core/browser.d.ts

@@ -0,0 +1,25 @@
+export interface BrowserHistoryEntry {
+    id: string;
+    title?: string;
+    url: string;
+    visitedAt: string;
+}
+export interface Bookmark {
+    id: string;
+    title: string;
+    url: string;
+    folder?: string;
+}
+export interface BrowserClient {
+    navigate(url: string): Promise<void>;
+    back(): Promise<void>;
+    forward(): Promise<void>;
+    refresh(): Promise<void>;
+    getSelectedText(): Promise<string | null>;
+    listHistory(): Promise<BrowserHistoryEntry[]>;
+    addHistory(entry: Omit<BrowserHistoryEntry, "id" | "visitedAt">): Promise<BrowserHistoryEntry>;
+    clearHistory(): Promise<void>;
+    listBookmarks(): Promise<Bookmark[]>;
+    addBookmark(bookmark: Omit<Bookmark, "id">): Promise<Bookmark>;
+    deleteBookmark(id: string): Promise<void>;
+}

package/dist/core/browser.js

@@ -0,0 +1 @@
+export {};

package/dist/core/chat.d.ts

@@ -0,0 +1,41 @@
+import type { Attachment, ModelInfo, ToolCall } from "./types";
+export interface Conversation {
+    id: string;
+    title?: string;
+    workspacePath?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface ChatMessage {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    createdAt?: string;
+    attachments?: Attachment[];
+    toolCalls?: ToolCall[];
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ChatStreamChunk {
+    id: string;
+    conversationId: string;
+    messageId: string;
+    delta: string;
+    done?: boolean;
+}
+export interface ChatSendRequest {
+    conversationId: string;
+    prompt: string;
+    model: ModelInfo | string;
+    attachments?: Attachment[];
+    context?: Record<string, unknown>;
+    stream?: boolean;
+}
+export interface ChatClient {
+    listConversations(workspacePath?: string): Promise<Conversation[]>;
+    createConversation(workspacePath?: string): Promise<Conversation>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listMessages(conversationId: string): Promise<ChatMessage[]>;
+    sendMessage(request: ChatSendRequest): Promise<ChatMessage | AsyncGenerator<ChatStreamChunk>>;
+    deleteMessage(conversationId: string, messageId: string): Promise<void>;
+}

package/dist/core/chat.js

@@ -0,0 +1 @@
+export {};

package/dist/core/database.d.ts

@@ -0,0 +1,56 @@
+export interface QueryResult<T = Record<string, unknown>> {
+    result?: T[];
+    data?: T[];
+    error?: string;
+    rowsAffected?: number;
+}
+export interface TableInfo {
+    name: string;
+    type: string;
+}
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    primaryKey?: boolean;
+    defaultValue?: unknown;
+}
+export interface DatabaseClient {
+    /**
+     * Execute a SQL query and return results
+     */
+    executeSQL(query: string, params?: unknown[]): Promise<QueryResult>;
+    /**
+     * Get list of tables in the database
+     */
+    getTables(): Promise<string[]>;
+    /**
+     * Get schema information for a specific table
+     */
+    getTableSchema(tableName: string): Promise<ColumnInfo[]>;
+    /**
+     * Execute multiple queries in a transaction
+     */
+    transaction?(queries: string[]): Promise<QueryResult[]>;
+}
+export interface DatabaseConfig {
+    type: 'sqlite' | 'postgres' | 'mysql' | 'custom';
+    connectionString?: string;
+    database?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+}
+export declare function normalizeQueryResult<T = Record<string, unknown>>(response: QueryResult<T> | T[] | {
+    rows?: T[];
+    data?: T[];
+    result?: T[];
+}): T[];
+export declare function createWindowApiDatabaseClient(api: {
+    executeSQL?: (params: {
+        query: string;
+    }) => Promise<QueryResult>;
+    getTables?: () => Promise<string[]>;
+    getTableSchema?: (table: string) => Promise<ColumnInfo[]>;
+}): DatabaseClient;

package/dist/core/database.js

@@ -0,0 +1,50 @@
+// Database abstraction for configurable backends
+// Helper to normalize query results from different backends
+export function normalizeQueryResult(response) {
+    if (Array.isArray(response)) {
+        return response;
+    }
+    if ('rows' in response && Array.isArray(response.rows)) {
+        return response.rows;
+    }
+    if ('data' in response && Array.isArray(response.data)) {
+        return response.data;
+    }
+    if ('result' in response && Array.isArray(response.result)) {
+        return response.result;
+    }
+    return [];
+}
+// Create a database client from window.api (common pattern)
+export function createWindowApiDatabaseClient(api) {
+    return {
+        async executeSQL(query, _params) {
+            if (!api.executeSQL) {
+                return { error: 'executeSQL not available' };
+            }
+            return api.executeSQL({ query });
+        },
+        async getTables() {
+            if (api.getTables) {
+                return api.getTables();
+            }
+            // Fallback: try to query sqlite_master
+            const result = await this.executeSQL("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'");
+            return normalizeQueryResult(result).map((r) => r.name || '');
+        },
+        async getTableSchema(tableName) {
+            if (api.getTableSchema) {
+                return api.getTableSchema(tableName);
+            }
+            // Fallback: PRAGMA for SQLite
+            const result = await this.executeSQL(`PRAGMA table_info(${tableName})`);
+            return normalizeQueryResult(result).map((r) => ({
+                name: r.name || '',
+                type: r.type || 'unknown',
+                nullable: !r.notnull,
+                primaryKey: !!r.pk,
+                defaultValue: r.dflt_value
+            }));
+        }
+    };
+}

package/dist/core/files.d.ts

@@ -0,0 +1,24 @@
+export interface FileNode {
+    path: string;
+    name: string;
+    isDirectory: boolean;
+    sizeBytes?: number;
+    modifiedAt?: string;
+    children?: FileNode[];
+}
+export interface FileSystemClient {
+    readDirectoryStructure(path: string): Promise<FileNode>;
+    readFileContent(path: string): Promise<string>;
+    writeFileContent(path: string, content: string): Promise<void>;
+    createDirectory(path: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    deleteDirectory(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+}
+/**
+ * Normalize a file path by converting backslashes to forward slashes
+ * and removing trailing slashes
+ * @param path - The path to normalize (can be null/undefined)
+ * @returns Normalized path string, or empty string if input is null/undefined
+ */
+export declare const normalizePath: (path: string | null | undefined) => string;

package/dist/core/files.js

@@ -0,0 +1,15 @@
+/**
+ * Normalize a file path by converting backslashes to forward slashes
+ * and removing trailing slashes
+ * @param path - The path to normalize (can be null/undefined)
+ * @returns Normalized path string, or empty string if input is null/undefined
+ */
+export const normalizePath = (path) => {
+    if (!path)
+        return '';
+    let normalizedPath = path.replace(/\\/g, '/');
+    if (normalizedPath.endsWith('/') && normalizedPath.length > 1) {
+        normalizedPath = normalizedPath.slice(0, -1);
+    }
+    return normalizedPath;
+};

package/dist/core/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export * from './layout';
+export * from './files';
+export * from './utils';
+export * from './chat';
+export * from './stream';
+export * from './browser';
+export * from './jobs';
+export * from './database';

package/dist/core/index.js

@@ -0,0 +1,10 @@
+// Core module exports
+export * from './types';
+export * from './layout';
+export * from './files';
+export * from './utils';
+export * from './chat';
+export * from './stream';
+export * from './browser';
+export * from './jobs';
+export * from './database';

package/dist/core/jobs.d.ts

@@ -0,0 +1,20 @@
+export interface CronJob {
+    id: string;
+    schedule: string;
+    command: string;
+    label?: string;
+}
+export interface Daemon {
+    id: string;
+    name: string;
+    command: string;
+    status: "running" | "stopped" | "unknown";
+}
+export interface JobClient {
+    listCronJobs(): Promise<CronJob[]>;
+    addCronJob(job: Omit<CronJob, "id">): Promise<CronJob>;
+    removeCronJob(id: string): Promise<void>;
+    listDaemons(): Promise<Daemon[]>;
+    addDaemon(daemon: Omit<Daemon, "id" | "status">): Promise<Daemon>;
+    removeDaemon(id: string): Promise<void>;
+}

package/dist/core/jobs.js

@@ -0,0 +1 @@
+export {};

package/dist/core/layout.d.ts

@@ -0,0 +1,30 @@
+export type SplitDirection = 'horizontal' | 'vertical';
+export interface SplitNode {
+    type: 'split';
+    id: string;
+    direction: SplitDirection;
+    children: LayoutNode[];
+    sizes: number[];
+}
+export interface ContentNode {
+    type: 'content';
+    id: string;
+    contentType: string;
+    data?: any;
+}
+export type LayoutNode = SplitNode | ContentNode;
+/**
+ * Find a node in the layout tree by following a path of indices
+ * @param node - The root layout node to search from
+ * @param path - Array of child indices to follow
+ * @returns The node at the specified path, or null if not found
+ */
+export declare const findNodeByPath: (node: LayoutNode | null, path: number[]) => LayoutNode | null;
+/**
+ * Find the path to a node with the given ID in the layout tree
+ * @param node - The root layout node to search from
+ * @param id - The ID of the node to find
+ * @param currentPath - The current path (used internally for recursion)
+ * @returns Array of indices representing the path to the node, or null if not found
+ */
+export declare const findNodePath: (node: LayoutNode | null, id: string, currentPath?: number[]) => number[] | null;

package/dist/core/layout.js

@@ -0,0 +1,41 @@
+/**
+ * Find a node in the layout tree by following a path of indices
+ * @param node - The root layout node to search from
+ * @param path - Array of child indices to follow
+ * @returns The node at the specified path, or null if not found
+ */
+export const findNodeByPath = (node, path) => {
+    if (!node || !path)
+        return null;
+    let currentNode = node;
+    for (const index of path) {
+        if (currentNode && currentNode.type === 'split' && currentNode.children && currentNode.children[index]) {
+            currentNode = currentNode.children[index];
+        }
+        else {
+            return null;
+        }
+    }
+    return currentNode;
+};
+/**
+ * Find the path to a node with the given ID in the layout tree
+ * @param node - The root layout node to search from
+ * @param id - The ID of the node to find
+ * @param currentPath - The current path (used internally for recursion)
+ * @returns Array of indices representing the path to the node, or null if not found
+ */
+export const findNodePath = (node, id, currentPath = []) => {
+    if (!node)
+        return null;
+    if (node.id === id)
+        return currentPath;
+    if (node.type === 'split') {
+        for (let i = 0; i < node.children.length; i++) {
+            const result = findNodePath(node.children[i], id, [...currentPath, i]);
+            if (result)
+                return result;
+        }
+    }
+    return null;
+};

package/dist/core/stream.d.ts

@@ -0,0 +1,10 @@
+export type StreamStatus = "idle" | "streaming" | "error";
+export interface StreamController {
+    streamId: string;
+    abort(): Promise<void> | void;
+}
+export interface StreamHandlers<TChunk> {
+    onChunk: (chunk: TChunk) => void;
+    onComplete?: () => void;
+    onError?: (error: unknown) => void;
+}

package/dist/core/stream.js

@@ -0,0 +1 @@
+export {};

package/dist/core/types.d.ts

@@ -0,0 +1,23 @@
+export type Provider = "openai" | "ollama" | "anthropic" | "local" | string;
+export interface Attachment {
+    id: string;
+    name: string;
+    path: string;
+    mime?: string;
+    sizeBytes?: number;
+}
+export interface ModelInfo {
+    id: string;
+    provider: Provider;
+    displayName?: string;
+    contextWindow?: number;
+    supportsImages?: boolean;
+    supportsTools?: boolean;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    status?: "pending" | "running" | "succeeded" | "failed";
+    output?: string;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};