@elliots/typical-compiler 0.2.0-beta.1

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import type { ProjectHandle, TransformResult } from './types.js';
+export interface TypicalCompilerOptions {
+    /** Path to the typical binary. If not provided, uses the bundled binary. */
+    binaryPath?: string;
+    /** Current working directory for the compiler. */
+    cwd?: string;
+}
+export declare class TypicalCompiler {
+    private process;
+    private pendingRequests;
+    private buffer;
+    private binaryPath;
+    private cwd;
+    private nextRequestId;
+    constructor(options?: TypicalCompilerOptions);
+    start(): Promise<void>;
+    close(): Promise<void>;
+    loadProject(configFileName: string): Promise<ProjectHandle>;
+    transformFile(project: ProjectHandle | string, fileName: string): Promise<TransformResult>;
+    release(handle: ProjectHandle | string): Promise<void>;
+    /**
+     * Transform a standalone TypeScript source string.
+     * Creates a temporary project to enable type checking.
+     *
+     * @param fileName - Virtual filename for error messages (e.g., "test.ts")
+     * @param source - TypeScript source code
+     * @returns Transformed code with validation
+     */
+    transformSource(fileName: string, source: string): Promise<TransformResult>;
+    private request;
+    private handleData;
+}

package/dist/client.js

@@ -0,0 +1,161 @@
+import { spawn } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { encodeRequest, decodeResponse } from './protocol.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const debug = process.env.DEBUG === '1';
+function debugLog(...args) {
+    if (debug) {
+        console.error(...args);
+    }
+}
+function getBinaryPath() {
+    // Try platform-specific package first
+    const platform = process.platform; // darwin, linux, win32
+    const arch = process.arch; // arm64, x64
+    const pkgName = `@elliots/typical-compiler-${platform}-${arch}`;
+    try {
+        const pkg = require(pkgName);
+        debugLog(`[CLIENT] Using platform binary from ${pkgName}`);
+        return pkg.binaryPath;
+    }
+    catch {
+        // Fallback to local bin (for development)
+        debugLog(`[CLIENT] Platform package ${pkgName} not found, falling back to local bin`);
+        return join(__dirname, '..', 'bin', 'typical');
+    }
+}
+export class TypicalCompiler {
+    process = null;
+    pendingRequests = new Map();
+    buffer = Buffer.alloc(0);
+    binaryPath;
+    cwd;
+    nextRequestId = 0;
+    constructor(options = {}) {
+        this.binaryPath = options.binaryPath ?? getBinaryPath();
+        this.cwd = options.cwd ?? process.cwd();
+    }
+    async start() {
+        if (this.process) {
+            throw new Error('Compiler already started');
+        }
+        this.process = spawn(this.binaryPath, ['--cwd', this.cwd], {
+            stdio: ['pipe', 'pipe', 'inherit'],
+        });
+        // Don't let the child process keep the Node process alive
+        this.process.unref();
+        this.process.stdout.on('data', (data) => {
+            this.handleData(data);
+        });
+        this.process.on('error', err => {
+            console.error('Compiler process error:', err);
+        });
+        this.process.on('exit', code => {
+            this.process = null;
+            // Reject any pending requests
+            for (const [, { reject }] of this.pendingRequests) {
+                reject(new Error(`Compiler process exited with code ${code}`));
+            }
+            this.pendingRequests.clear();
+        });
+        // Test the connection with echo
+        const result = await this.request('echo', 'ping');
+        if (result !== 'ping') {
+            throw new Error(`Echo test failed: expected "ping", got "${result}"`);
+        }
+    }
+    async close() {
+        if (this.process) {
+            const proc = this.process;
+            this.process = null;
+            // Clear pending requests to avoid errors after close
+            this.pendingRequests.clear();
+            proc.stdin?.end();
+            proc.kill();
+        }
+    }
+    async loadProject(configFileName) {
+        return this.request('loadProject', { configFileName });
+    }
+    async transformFile(project, fileName) {
+        const projectId = typeof project === 'string' ? project : project.id;
+        return this.request('transformFile', {
+            project: projectId,
+            fileName,
+        });
+    }
+    async release(handle) {
+        const id = typeof handle === 'string' ? handle : handle.id;
+        await this.request('release', id);
+    }
+    /**
+     * Transform a standalone TypeScript source string.
+     * Creates a temporary project to enable type checking.
+     *
+     * @param fileName - Virtual filename for error messages (e.g., "test.ts")
+     * @param source - TypeScript source code
+     * @returns Transformed code with validation
+     */
+    async transformSource(fileName, source) {
+        return this.request('transformSource', {
+            fileName,
+            source,
+        });
+    }
+    async request(method, payload) {
+        if (!this.process) {
+            throw new Error('Compiler not started');
+        }
+        // Use unique request ID to correlate request/response
+        const requestId = `${method}:${this.nextRequestId++}`;
+        const requestData = encodeRequest(requestId, payload);
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(requestId, {
+                resolve: resolve,
+                reject,
+            });
+            this.process.stdin.write(requestData);
+        });
+    }
+    handleData(data) {
+        // Append new data to buffer
+        this.buffer = Buffer.concat([this.buffer, data]);
+        debugLog(`[CLIENT DEBUG] handleData: received ${data.length} bytes, buffer now ${this.buffer.length} bytes`);
+        // Try to decode messages
+        while (this.buffer.length > 0) {
+            try {
+                debugLog(`[CLIENT DEBUG] Attempting to decode ${this.buffer.length} bytes...`);
+                const { messageType, method, payload, bytesConsumed } = decodeResponse(this.buffer);
+                debugLog(`[CLIENT DEBUG] Decoded: type=${messageType} method=${method} payload=${payload.length} bytes, consumed=${bytesConsumed}`);
+                // Find the pending request
+                const pending = this.pendingRequests.get(method);
+                if (!pending) {
+                    const pendingKeys = [...this.pendingRequests.keys()].join(', ') || '(none)';
+                    throw new Error(`No pending request for method: ${method}. Pending requests: ${pendingKeys}. ` + `This indicates a protocol bug - received response for a request that wasn't made or was already resolved.`);
+                }
+                this.pendingRequests.delete(method);
+                if (messageType === 4 /* MessageType.Response */) {
+                    // Parse JSON payload
+                    const result = payload.length > 0 ? JSON.parse(payload.toString('utf8')) : null;
+                    pending.resolve(result);
+                }
+                else if (messageType === 5 /* MessageType.Error */) {
+                    pending.reject(new Error(payload.toString('utf8')));
+                }
+                else {
+                    pending.reject(new Error(`Unexpected message type: ${messageType}`));
+                }
+                // Remove only the processed bytes from buffer
+                this.buffer = this.buffer.subarray(bytesConsumed);
+            }
+            catch (e) {
+                // Not enough data yet, wait for more
+                debugLog(`[CLIENT DEBUG] Decode failed (waiting for more data): ${e}`);
+                break;
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { TypicalCompiler, type TypicalCompilerOptions } from './client.js';
+export type { ProjectHandle, TransformResult, RawSourceMap } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { TypicalCompiler } from './client.js';

package/dist/protocol.d.ts

@@ -0,0 +1,21 @@
+/**
+ * MessagePack-like binary protocol for communicating with the typical compiler.
+ * This matches the protocol used by tsgo's --api mode.
+ */
+export declare const enum MessageType {
+    Unknown = 0,
+    Request = 1,
+    CallResponse = 2,
+    CallError = 3,
+    Response = 4,
+    Error = 5,
+    Call = 6
+}
+export declare function encodeRequest(method: string, payload: unknown): Buffer;
+export interface DecodedMessage {
+    messageType: MessageType;
+    method: string;
+    payload: Buffer;
+    bytesConsumed: number;
+}
+export declare function decodeResponse(data: Buffer): DecodedMessage;

package/dist/protocol.js

@@ -0,0 +1,113 @@
+/**
+ * MessagePack-like binary protocol for communicating with the typical compiler.
+ * This matches the protocol used by tsgo's --api mode.
+ */
+const MessagePackTypeFixedArray3 = 0x93;
+const MessagePackTypeBin8 = 0xc4;
+const MessagePackTypeBin16 = 0xc5;
+const MessagePackTypeBin32 = 0xc6;
+const MessagePackTypeU8 = 0xcc;
+export function encodeRequest(method, payload) {
+    const methodBuf = Buffer.from(method, 'utf8');
+    const payloadStr = JSON.stringify(payload);
+    const payloadBuf = Buffer.from(payloadStr, 'utf8');
+    // Calculate total size
+    // 1 byte for array marker (0x93)
+    // 2 bytes for message type (0xCC + type)
+    // variable for method bin
+    // variable for payload bin
+    const methodBinSize = getBinEncodingSize(methodBuf.length);
+    const payloadBinSize = getBinEncodingSize(payloadBuf.length);
+    const totalSize = 1 + 2 + methodBinSize + methodBuf.length + payloadBinSize + payloadBuf.length;
+    const buf = Buffer.alloc(totalSize);
+    let offset = 0;
+    // Fixed array of 3 elements
+    buf[offset++] = MessagePackTypeFixedArray3;
+    // Message type (u8)
+    buf[offset++] = MessagePackTypeU8;
+    buf[offset++] = 1 /* MessageType.Request */;
+    // Method (bin)
+    offset = writeBin(buf, offset, methodBuf);
+    // Payload (bin)
+    offset = writeBin(buf, offset, payloadBuf);
+    return buf;
+}
+export function decodeResponse(data) {
+    let offset = 0;
+    // Check array marker
+    if (data[offset++] !== MessagePackTypeFixedArray3) {
+        throw new Error(`Expected 0x93, got 0x${data[0].toString(16)}`);
+    }
+    // Read message type
+    if (data[offset++] !== MessagePackTypeU8) {
+        throw new Error(`Expected 0xCC for message type`);
+    }
+    const messageType = data[offset++];
+    // Read method
+    const { value: methodBuf, newOffset: offset2 } = readBin(data, offset);
+    offset = offset2;
+    const method = methodBuf.toString('utf8');
+    // Read payload
+    const { value: payload, newOffset: offset3 } = readBin(data, offset);
+    return { messageType, method, payload, bytesConsumed: offset3 };
+}
+function getBinEncodingSize(length) {
+    if (length < 256)
+        return 2; // 1 byte type + 1 byte length
+    if (length < 65536)
+        return 3; // 1 byte type + 2 bytes length
+    return 5; // 1 byte type + 4 bytes length
+}
+function writeBin(buf, offset, data) {
+    const length = data.length;
+    if (length < 256) {
+        buf[offset++] = MessagePackTypeBin8;
+        buf[offset++] = length;
+    }
+    else if (length < 65536) {
+        buf[offset++] = MessagePackTypeBin16;
+        buf.writeUInt16BE(length, offset);
+        offset += 2;
+    }
+    else {
+        buf[offset++] = MessagePackTypeBin32;
+        buf.writeUInt32BE(length, offset);
+        offset += 4;
+    }
+    data.copy(buf, offset);
+    return offset + length;
+}
+function readBin(buf, offset) {
+    if (offset >= buf.length) {
+        throw new Error('Not enough data: need type byte');
+    }
+    const type = buf[offset++];
+    let length;
+    switch (type) {
+        case MessagePackTypeBin8:
+            if (offset >= buf.length)
+                throw new Error('Not enough data: need length byte');
+            length = buf[offset++];
+            break;
+        case MessagePackTypeBin16:
+            if (offset + 2 > buf.length)
+                throw new Error('Not enough data: need 2 length bytes');
+            length = buf.readUInt16BE(offset);
+            offset += 2;
+            break;
+        case MessagePackTypeBin32:
+            if (offset + 4 > buf.length)
+                throw new Error('Not enough data: need 4 length bytes');
+            length = buf.readUInt32BE(offset);
+            offset += 4;
+            break;
+        default:
+            throw new Error(`Expected bin type (0xC4-0xC6), got 0x${type.toString(16)}`);
+    }
+    // Check if we have enough data for the full payload
+    if (offset + length > buf.length) {
+        throw new Error(`Not enough data: need ${length} bytes, have ${buf.length - offset}`);
+    }
+    const value = buf.subarray(offset, offset + length);
+    return { value, newOffset: offset + length };
+}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export interface ProjectHandle {
+    id: string;
+    configFile: string;
+    rootFiles: string[];
+}
+export interface RawSourceMap {
+    version: number;
+    file: string;
+    sourceRoot?: string;
+    sources: string[];
+    names: string[];
+    mappings: string;
+    sourcesContent?: (string | null)[];
+}
+export interface TransformResult {
+    code: string;
+    sourceMap?: RawSourceMap;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@elliots/typical-compiler",
+  "version": "0.2.0-beta.1",
+  "description": "TypeScript compiler powered by tsgo for typical validation",
+  "keywords": [
+    "compiler",
+    "runtime",
+    "typescript",
+    "validation"
+  ],
+  "license": "MIT",
+  "author": "elliots",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "optionalDependencies": {
+    "@elliots/typical-compiler-darwin-arm64": "0.2.0-beta.1",
+    "@elliots/typical-compiler-darwin-x64": "0.2.0-beta.1",
+    "@elliots/typical-compiler-linux-arm64": "0.2.0-beta.1",
+    "@elliots/typical-compiler-linux-x64": "0.2.0-beta.1",
+    "@elliots/typical-compiler-win32-arm64": "0.2.0-beta.1",
+    "@elliots/typical-compiler-win32-x64": "0.2.0-beta.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:go": "./go/scripts/sync-shims.sh && cd go && go build -o ../bin/typical ./cmd/typical",
+    "test": "npx tsx test/e2e.ts"
+  }
+}