@feltdb/core 0.5.7 → 0.6.0

package/dist/workspace/workspace-connection.js

@@ -0,0 +1,290 @@
+/**
+ * Development Workspace Connection
+ *
+ * Public API for clients (browser, IDE, agent) to discover and connect
+ * to a FeltDB Development Workspace.
+ */
+import fs from 'fs';
+import path from 'path';
+/**
+ * Discover workspace from .feltdb/workspace.json
+ *
+ * Usage:
+ * ```
+ * const workspace = await discoverDevelopmentWorkspace({
+ *   projectDir: process.cwd()
+ * })
+ * ```
+ */
+export async function discoverDevelopmentWorkspace(options) {
+    const workspacePath = path.join(options.projectDir, '.feltdb', 'workspace.json');
+    if (!fs.existsSync(workspacePath)) {
+        throw new Error(`Development Workspace not found at ${workspacePath}. Run "feltdb dev" or create-feltdb to initialize.`);
+    }
+    try {
+        const content = fs.readFileSync(workspacePath, 'utf-8');
+        const workspace = JSON.parse(content);
+        return workspace;
+    }
+    catch (error) {
+        throw new Error(`Failed to read workspace metadata: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Resolve pairing code to workspace ID
+ *
+ * Pairing codes are short-lived tokens (FELT-XXXX) that resolve to
+ * workspace IDs. They expire after 15 minutes.
+ *
+ * Used by clients to auto-discover workspace without manual entry.
+ */
+export async function resolvePairingCode(pairingCode, projectDir) {
+    if (!pairingCode.startsWith('FELT-')) {
+        throw new Error('Invalid pairing code format');
+    }
+    // When projectDir is provided, try local resolution first
+    if (projectDir) {
+        const pairingPath = path.join(projectDir, '.feltdb', 'pairing.json');
+        if (fs.existsSync(pairingPath)) {
+            try {
+                const content = fs.readFileSync(pairingPath, 'utf-8');
+                const pairing = JSON.parse(content);
+                if (pairing.token === pairingCode && Date.now() < pairing.expiresAt) {
+                    return pairing.workspaceId;
+                }
+            }
+            catch {
+                // Fall through to error
+            }
+        }
+    }
+    throw new Error(`Pairing code ${pairingCode} not found or expired. Ensure "feltdb dev" is running and the code is correct.`);
+}
+/**
+ * Connect to a Development Workspace
+ *
+ * Canonical API for clients to establish connection to shared workspace.
+ *
+ * Usage via pairing code (browser/IDE discovery):
+ * ```
+ * const workspace = await connectDevelopmentWorkspace({
+ *   pairingCode: "FELT-7K3P",
+ *   clientId: "vscode-randy",
+ *   clientType: "ide"
+ * })
+ * ```
+ *
+ * Usage via workspace ID (agent/CLI):
+ * ```
+ * const workspace = await connectDevelopmentWorkspace({
+ *   workspaceId: "ws_myapp_1234567890_abc123",
+ *   projectDir: process.cwd(),
+ *   clientId: "claude-code",
+ *   clientType: "agent"
+ * })
+ * ```
+ *
+ * Usage via endpoint (remote connection):
+ * ```
+ * const workspace = await connectDevelopmentWorkspace({
+ *   workspaceId: "ws_...",
+ *   endpoint: "http://localhost:7700",
+ *   auth: { token: "..." }
+ * })
+ * ```
+ */
+export async function connectDevelopmentWorkspace(options) {
+    let workspaceId = options.workspaceId;
+    // Resolve pairing code to workspace ID if provided
+    if (options.pairingCode && !workspaceId) {
+        workspaceId = await resolvePairingCode(options.pairingCode, options.projectDir);
+    }
+    // Discover workspace if no ID provided
+    if (!workspaceId && options.projectDir) {
+        const metadata = await discoverDevelopmentWorkspace({ projectDir: options.projectDir });
+        workspaceId = metadata.workspaceId;
+    }
+    if (!workspaceId) {
+        throw new Error('Cannot connect: provide pairingCode, workspaceId, or projectDir');
+    }
+    const clientId = options.clientId || generateClientId(options.clientType);
+    const clientType = options.clientType || 'other';
+    return new DevelopmentWorkspaceConnection(workspaceId, clientId, clientType, options);
+}
+/**
+ * Generate a unique client ID based on type
+ */
+function generateClientId(clientType) {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 5);
+    const prefix = clientType || 'client';
+    return `${prefix}-${timestamp}-${random}`;
+}
+/**
+ * Development Workspace Connection
+ *
+ * Represents an active connection to a shared development workspace.
+ * Provides methods to publish, subscribe, and query shared state.
+ */
+export class DevelopmentWorkspaceConnection {
+    constructor(workspaceId, clientId, clientType, options) {
+        this.subscriptions = new Map();
+        this.connectedAt = 0;
+        this.connectedClients = new Map();
+        this.workspaceId = workspaceId;
+        this.clientId = clientId;
+        this.clientType = clientType;
+        this.options = options;
+    }
+    /**
+     * Establish connection to workspace
+     */
+    async connect() {
+        this.connectedAt = Date.now();
+        this.registerClient();
+    }
+    /**
+     * Close connection to workspace
+     */
+    async disconnect() {
+        this.subscriptions.clear();
+        this.connectedClients.delete(this.clientId);
+    }
+    /**
+     * Register this client as connected
+     */
+    registerClient() {
+        this.connectedClients.set(this.clientId, {
+            clientId: this.clientId,
+            clientType: this.clientType,
+            connectedAt: this.connectedAt,
+            capabilities: this.getCapabilities(),
+        });
+    }
+    /**
+     * Get capabilities for this client type
+     */
+    getCapabilities() {
+        switch (this.clientType) {
+            case 'browser':
+                return ['visual_selection', 'run_inspection', 'replay'];
+            case 'ide':
+                return ['code_edit', 'file_navigation', 'symbol_lookup'];
+            case 'agent':
+                return ['code_analysis', 'code_generation', 'verification'];
+            case 'cli':
+                return ['workspace_status', 'configuration'];
+            default:
+                return [];
+        }
+    }
+    /**
+     * List connected clients in workspace
+     */
+    clients() {
+        return Array.from(this.connectedClients.values());
+    }
+    /**
+     * Subscribe to workspace entity changes
+     *
+     * Usage:
+     * ```
+     * workspace.subscribe("development_task", (event) => {
+     *   console.log(`Task ${event.entityId}: ${event.type}`)
+     * })
+     * ```
+     */
+    subscribe(collection, handler) {
+        if (!this.subscriptions.has(collection)) {
+            this.subscriptions.set(collection, new Set());
+        }
+        const handlers = this.subscriptions.get(collection);
+        handlers.add(handler);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this.subscriptions.delete(collection);
+            }
+        };
+    }
+    /**
+     * Publish entity to workspace
+     *
+     * Creates new entity in workspace collection.
+     */
+    async publish(collection, entity) {
+        const id = generateEntityId();
+        const event = {
+            id: generateEventId(),
+            workspaceId: this.workspaceId,
+            collection,
+            entityId: id,
+            type: 'created',
+            value: entity,
+            timestamp: Date.now(),
+            originClientId: this.clientId,
+        };
+        this.notifySubscribers(collection, event);
+        return id;
+    }
+    /**
+     * Get entity from workspace
+     */
+    async get(collection, entityId) {
+        // In full implementation, would query FeltDB backend
+        // For now, returns null (placeholder)
+        return null;
+    }
+    /**
+     * Query entities in workspace collection
+     */
+    async query(collection) {
+        // In full implementation, would query FeltDB backend
+        // For now, returns empty array (placeholder)
+        return [];
+    }
+    /**
+     * Update entity in workspace
+     */
+    async update(collection, entityId, updates) {
+        const event = {
+            id: generateEventId(),
+            workspaceId: this.workspaceId,
+            collection,
+            entityId,
+            type: 'updated',
+            value: updates,
+            timestamp: Date.now(),
+            originClientId: this.clientId,
+        };
+        this.notifySubscribers(collection, event);
+    }
+    /**
+     * Notify subscribers of entity changes
+     */
+    notifySubscribers(collection, event) {
+        const handlers = this.subscriptions.get(collection);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(event);
+                }
+                catch (error) {
+                    console.error(`Error in subscription handler: ${error}`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Generate unique entity ID
+ */
+function generateEntityId() {
+    return `entity_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+/**
+ * Generate unique event ID
+ */
+function generateEventId() {
+    return `event_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}

package/dist/workspace/workspace-identity.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Workspace Identity Management
+ *
+ * Manages durable workspace identities and discovery.
+ */
+import type { DevelopmentWorkspace, WorkspaceDiscovery } from './workspace-types.js';
+export declare function createWorkspaceId(projectId: string): string;
+export declare function isValidWorkspaceId(id: string): boolean;
+export declare function createDevelopmentWorkspace(projectId: string, name: string): DevelopmentWorkspace;
+export declare function updateWorkspaceTimestamp(workspace: DevelopmentWorkspace): DevelopmentWorkspace;
+export declare function discoverWorkspace(projectDir: string): Promise<WorkspaceDiscovery | null>;
+export declare function persistWorkspaceDiscovery(projectDir: string, discovery: WorkspaceDiscovery): Promise<void>;
+//# sourceMappingURL=workspace-identity.d.ts.map

package/dist/workspace/workspace-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-identity.d.ts","sourceRoot":"","sources":["../../src/workspace/workspace-identity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAIrF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,oBAAoB,CAStB;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,oBAAoB,GAC9B,oBAAoB,CAKtB;AAED,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA0BpC;AAED,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,kBAAkB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/workspace/workspace-identity.js

@@ -0,0 +1,70 @@
+/**
+ * Workspace Identity Management
+ *
+ * Manages durable workspace identities and discovery.
+ */
+const WORKSPACE_ID_PREFIX = 'ws_';
+export function createWorkspaceId(projectId) {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 8);
+    return `${WORKSPACE_ID_PREFIX}${projectId}_${timestamp}_${random}`;
+}
+export function isValidWorkspaceId(id) {
+    return id.startsWith(WORKSPACE_ID_PREFIX);
+}
+export function createDevelopmentWorkspace(projectId, name) {
+    const now = Date.now();
+    return {
+        id: createWorkspaceId(projectId),
+        name,
+        projectId,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+export function updateWorkspaceTimestamp(workspace) {
+    return {
+        ...workspace,
+        updatedAt: Date.now(),
+    };
+}
+export async function discoverWorkspace(projectDir) {
+    try {
+        if (typeof window !== 'undefined') {
+            return null;
+        }
+        const fs = await import('fs').then((m) => m.promises);
+        const path = await import('path');
+        const configPath = path.join(projectDir, '.feltdb', 'workspace.json');
+        try {
+            const content = await fs.readFile(configPath, 'utf-8');
+            const data = JSON.parse(content);
+            if (isValidWorkspaceId(data.workspaceId) && data.projectId) {
+                return data;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export async function persistWorkspaceDiscovery(projectDir, discovery) {
+    try {
+        if (typeof window !== 'undefined') {
+            return;
+        }
+        const fs = await import('fs').then((m) => m.promises);
+        const path = await import('path');
+        const configDir = path.join(projectDir, '.feltdb');
+        const configPath = path.join(configDir, 'workspace.json');
+        await fs.mkdir(configDir, { recursive: true });
+        await fs.writeFile(configPath, JSON.stringify(discovery, null, 2));
+    }
+    catch (error) {
+        console.error('Failed to persist workspace discovery:', error);
+    }
+}

package/dist/workspace/workspace-types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Development Workspace Types
+ *
+ * Core contracts for durable development state shared across
+ * Browser, IDE, and Agent clients.
+ */
+export interface DevelopmentWorkspace {
+    id: string;
+    name: string;
+    projectId: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export type ClientType = "browser" | "ide" | "agent" | "cli" | "application" | "other";
+export interface WorkspaceEventPayload<T = unknown> {
+    id: string;
+    workspaceId: string;
+    collection: string;
+    entityId: string;
+    type: "created" | "updated" | "deleted";
+    value?: T;
+    timestamp: number;
+    originClientId: string;
+}
+export interface DevelopmentTask {
+    id: string;
+    workspaceId: string;
+    investigationId?: string;
+    title: string;
+    description: string;
+    sourceLocations?: SourceLocation[];
+    status: "open" | "in_progress" | "ready_for_verification" | "verified" | "failed" | "cancelled";
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CodeChange {
+    id: string;
+    workspaceId: string;
+    taskId: string;
+    description: string;
+    sourceLocations: SourceLocation[];
+    changeRef?: string;
+    status: "published" | "ready_for_verification" | "verifying" | "verified" | "failed";
+    createdAt: number;
+    updatedAt: number;
+}
+export interface VerificationResult {
+    id: string;
+    workspaceId: string;
+    taskId: string;
+    codeChangeId: string;
+    status: "fixed" | "regressed" | "unchanged" | "inconclusive";
+    summary: string;
+    originalOutcome?: unknown;
+    newOutcome?: unknown;
+    newErrors: number;
+    createdAt: number;
+}
+export interface SourceLocation {
+    file: string;
+    line?: number;
+    column?: number;
+    endLine?: number;
+    endColumn?: number;
+}
+export interface WorkspaceClient {
+    workspaceId: string;
+    clientId: string;
+    clientType: ClientType;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    get<T>(collection: string, id: string): Promise<T | null>;
+    query<T>(collection: string, query?: unknown): Promise<T[]>;
+    publish<T>(collection: string, value: T): Promise<string>;
+    update<T>(collection: string, id: string, value: Partial<T>): Promise<void>;
+    subscribe<T>(collection: string, callback: (event: WorkspaceEventPayload<T>) => void): () => void;
+}
+export interface WorkspaceDiscovery {
+    workspaceId: string;
+    projectId: string;
+}
+//# sourceMappingURL=workspace-types.d.ts.map

package/dist/workspace/workspace-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-types.d.ts","sourceRoot":"","sources":["../../src/workspace/workspace-types.ts"],"names":[],"mappings":"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"}

package/dist/workspace/workspace-types.js

@@ -0,0 +1,7 @@
+/**
+ * Development Workspace Types
+ *
+ * Core contracts for durable development state shared across
+ * Browser, IDE, and Agent clients.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feltdb/core",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "FeltDB Core - Application-facing database with Browser, Local, and Server runtimes. Durable state, reactive APIs.",
   "license": "MIT",
   "type": "module",
@@ -42,6 +42,10 @@
       "import": "./dist/wasm/feltdb_wasm.js",
       "types": "./dist/wasm/feltdb_wasm.d.ts"
     },
+    "./workspace": {
+      "import": "./dist/workspace/index.js",
+      "types": "./dist/workspace/index.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "files": [