@pinixai/core 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinixai/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Clip framework for Pinix — define once, run as CLI / MCP / Pinix bridge",
   "main": "src/index.ts",
   "module": "src/index.ts",

package/src/clip.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { CLIHelpError, formatCLIHelp, parseCLIArgs } from "./cli";
 import type { HandlerDef } from "./handler";
+import { serveHTTP } from "./http";
 import { serveIPC } from "./ipc";
 import { serveMCP } from "./mcp";
 import { generateManifest } from "./manifest";
@@ -44,6 +45,23 @@ export abstract class Clip {
       return serveIPC(this);
     }
 
+    if (modeOrCommand === "--web") {
+      const portArg = restArgs[0];
+
+      if (portArg === undefined) {
+        return serveHTTP(this);
+      }
+
+      const port = Number.parseInt(portArg, 10);
+
+      if (Number.isNaN(port)) {
+        console.error(`Invalid port: ${portArg}`);
+        return;
+      }
+
+      return serveHTTP(this, port);
+    }
+
     if (modeOrCommand === "--manifest") {
       console.log(this.toManifest());
       return;
@@ -102,6 +120,7 @@ export abstract class Clip {
     lines.push("  bun run <script> --manifest");
     lines.push("  bun run <script> --mcp");
     lines.push("  bun run <script> --ipc");
+    lines.push("  bun run <script> --web [port]");
     lines.push("");
     lines.push("Commands:");
 

package/src/http.ts

@@ -0,0 +1,253 @@
+import { dirname, join, resolve, sep } from "node:path";
+import type { Clip } from "./clip";
+import { zodToManifestType } from "./manifest";
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Headers": "Content-Type",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+};
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function createHeaders(headers?: Headers | Record<string, string>): Headers {
+  const result = new Headers(CORS_HEADERS);
+
+  if (!headers) {
+    return result;
+  }
+
+  const extraHeaders = new Headers(headers);
+
+  for (const [key, value] of extraHeaders.entries()) {
+    result.set(key, value);
+  }
+
+  return result;
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: createHeaders({
+      "Content-Type": "application/json; charset=utf-8",
+    }),
+  });
+}
+
+function textResponse(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: createHeaders({
+      "Content-Type": "text/plain; charset=utf-8",
+    }),
+  });
+}
+
+function errorResponse(message: string, status: number): Response {
+  return jsonResponse({ error: message }, status);
+}
+
+function resolveWithinRoot(root: string, relativePath: string): string | null {
+  const candidate = resolve(root, relativePath);
+
+  if (candidate === root || candidate.startsWith(`${root}${sep}`)) {
+    return candidate;
+  }
+
+  return null;
+}
+
+function getStaticRoots(): string[] {
+  const scriptDir = dirname(Bun.main);
+  return [join(scriptDir, "web", "dist"), join(scriptDir, "web")];
+}
+
+function normalizeStaticPath(pathname: string): string {
+  const decodedPathname = decodeURIComponent(pathname);
+  const trimmedPathname = decodedPathname.replace(/^\/+/, "");
+
+  if (trimmedPathname.length === 0) {
+    return "index.html";
+  }
+
+  if (decodedPathname.endsWith("/")) {
+    return join(trimmedPathname, "index.html");
+  }
+
+  return trimmedPathname;
+}
+
+async function findStaticFile(pathname: string): Promise<ReturnType<typeof Bun.file> | null> {
+  const relativePath = normalizeStaticPath(pathname);
+
+  for (const root of getStaticRoots()) {
+    const candidatePath = resolveWithinRoot(root, relativePath);
+
+    if (!candidatePath) {
+      continue;
+    }
+
+    const file = Bun.file(candidatePath);
+
+    if (await file.exists()) {
+      return file;
+    }
+  }
+
+  return null;
+}
+
+function fileResponse(file: ReturnType<typeof Bun.file>): Response {
+  const headers = file.type
+    ? createHeaders({ "Content-Type": file.type })
+    : createHeaders();
+
+  return new Response(file, { headers });
+}
+
+async function readJSONBody(request: Request): Promise<unknown> {
+  const bodyText = await request.text();
+
+  if (bodyText.trim().length === 0) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(bodyText) as unknown;
+  } catch (error) {
+    throw new Error(`Invalid JSON: ${toErrorMessage(error)}`);
+  }
+}
+
+function listCommands(clip: Clip): Response {
+  const commands = Array.from(clip.getCommands().entries()).map(([name, commandHandler]) => ({
+    name,
+    description: clip.getCommandDescription(name) ?? null,
+    method: "POST",
+    path: `/api/${name}`,
+    input: zodToManifestType(commandHandler.input),
+    output: zodToManifestType(commandHandler.output),
+  }));
+
+  return jsonResponse({ commands });
+}
+
+async function handleCommandRequest(clip: Clip, commandName: string, request: Request): Promise<Response> {
+  const commandHandler = clip.getCommands().get(commandName);
+
+  if (!commandHandler) {
+    return errorResponse(`Unknown command: ${commandName}`, 404);
+  }
+
+  let input: unknown;
+
+  try {
+    input = await readJSONBody(request);
+  } catch (error) {
+    return errorResponse(toErrorMessage(error), 400);
+  }
+
+  let parsedInput: unknown;
+
+  try {
+    parsedInput = await commandHandler.input.parseAsync(input);
+  } catch (error) {
+    return errorResponse(toErrorMessage(error), 400);
+  }
+
+  let output: unknown;
+
+  try {
+    output = await commandHandler.fn(parsedInput as never);
+  } catch (error) {
+    return errorResponse(toErrorMessage(error), 500);
+  }
+
+  try {
+    const parsedOutput = await commandHandler.output.parseAsync(output);
+    return jsonResponse(parsedOutput);
+  } catch (error) {
+    return errorResponse(toErrorMessage(error), 500);
+  }
+}
+
+async function handleStaticRequest(pathname: string): Promise<Response> {
+  const file = await findStaticFile(pathname);
+
+  if (file) {
+    return fileResponse(file);
+  }
+
+  const fallbackFile = await findStaticFile("/index.html");
+
+  if (fallbackFile) {
+    return fileResponse(fallbackFile);
+  }
+
+  return errorResponse(`Static file not found: ${pathname}`, 404);
+}
+
+async function handleRequest(clip: Clip, request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const pathname = url.pathname;
+  const method = request.method.toUpperCase();
+
+  if (method === "OPTIONS") {
+    return new Response(null, {
+      status: 204,
+      headers: createHeaders(),
+    });
+  }
+
+  if (pathname === "/manifest") {
+    if (method !== "GET") {
+      return errorResponse("Method not allowed", 405);
+    }
+
+    return textResponse(clip.toManifest());
+  }
+
+  if (pathname === "/api" || pathname === "/api/") {
+    if (method !== "GET") {
+      return errorResponse("Method not allowed", 405);
+    }
+
+    return listCommands(clip);
+  }
+
+  if (pathname.startsWith("/api/")) {
+    if (method !== "POST") {
+      return errorResponse("Method not allowed", 405);
+    }
+
+    const commandName = pathname.slice("/api/".length);
+
+    if (commandName.length === 0 || commandName.includes("/")) {
+      return errorResponse("Unknown command", 404);
+    }
+
+    return handleCommandRequest(clip, commandName, request);
+  }
+
+  if (method !== "GET" && method !== "HEAD") {
+    return errorResponse("Method not allowed", 405);
+  }
+
+  try {
+    return await handleStaticRequest(pathname);
+  } catch (error) {
+    return errorResponse(toErrorMessage(error), 500);
+  }
+}
+
+export async function serveHTTP(clip: Clip, port = 3000): Promise<void> {
+  const server = Bun.serve({
+    port,
+    fetch: (request) => handleRequest(clip, request),
+  });
+
+  console.error(`Clip "${clip.name}" running at http://localhost:${server.port}`);
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export { Clip } from "./clip";
 export { command } from "./command";
 export { handler, type HandlerDef } from "./handler";
-export { serveIPC } from "./ipc";
+export { serveHTTP } from "./http";
+export { serveIPC, invoke } from "./ipc";
 export { serveMCP } from "./mcp";
 export { z } from "zod";

package/src/ipc.ts

@@ -1,160 +1,161 @@
-import type { z } from "zod";
 import type { Clip } from "./clip";
+import { createIPCManifest } from "./manifest";
 
-type IPCRequest = {
-  id?: unknown;
-  command?: unknown;
-  input?: unknown;
-};
+// === IPC Protocol Types ===
 
-type IPCResponse =
-  | {
-      id: unknown;
-      output: unknown;
-    }
-  | {
-      id: unknown;
-      error: {
-        message: string;
-        code: string;
-      };
-    };
-
-function toErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
+type MessageType = "register" | "registered" | "invoke" | "result" | "error" | "chunk" | "done";
 
-function writeResponse(response: IPCResponse): void {
-  process.stdout.write(`${JSON.stringify(response)}\n`);
+interface BaseMessage {
+  type: MessageType;
+  id?: string;
 }
 
-function isObject(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object";
+interface RegisterMessage extends BaseMessage {
+  type: "register";
+  manifest: { name: string; domain: string; commands: string[]; dependencies: string[] };
 }
 
-function createErrorResponse(id: unknown, message: string, code: string): IPCResponse {
-  return {
-    id,
-    error: {
-      message,
-      code,
-    },
-  };
+interface InvokeMessage extends BaseMessage {
+  type: "invoke";
+  id: string;
+  command?: string;
+  clip?: string;
+  input?: unknown;
 }
 
-async function handleRequestLine(clip: Clip, line: string): Promise<void> {
-  let request: IPCRequest;
+interface ResultMessage extends BaseMessage {
+  type: "result";
+  id: string;
+  output: unknown;
+}
 
-  try {
-    request = JSON.parse(line) as IPCRequest;
-  } catch (error) {
-    writeResponse(createErrorResponse(null, `Invalid JSON: ${toErrorMessage(error)}`, "INVALID_JSON"));
-    return;
-  }
+interface ErrorMessage extends BaseMessage {
+  type: "error";
+  id: string;
+  error: string;
+}
 
-  const { id = null, command, input } = request;
+// === State ===
 
-  if (typeof command !== "string" || command.length === 0) {
-    writeResponse(createErrorResponse(id, "Request command must be a non-empty string", "INVALID_REQUEST"));
-    return;
-  }
+const pendingInvokes = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+let idCounter = 0;
 
-  const commandHandler = clip.getCommands().get(command);
+function nextId(): string {
+  return `c${++idCounter}`;
+}
 
-  if (!commandHandler) {
-    writeResponse(createErrorResponse(id, `Unknown command: ${command}`, "COMMAND_NOT_FOUND"));
-    return;
-  }
+function send(msg: Record<string, unknown>): void {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
 
-  if (!isObject(input)) {
-    writeResponse(createErrorResponse(id, "Request input must be an object", "INVALID_INPUT"));
-    return;
-  }
+// === Public API ===
 
-  try {
-    const parsedInput = await commandHandler.input.parseAsync(input) as z.infer<typeof commandHandler.input>;
-    const output = await commandHandler.fn(parsedInput);
-    const parsedOutput = await commandHandler.output.parseAsync(output);
-
-    writeResponse({
-      id,
-      output: parsedOutput,
-    });
-  } catch (error) {
-    writeResponse(createErrorResponse(id, toErrorMessage(error), "COMMAND_ERROR"));
-  }
+export async function invoke(clip: string, command: string, input: unknown): Promise<unknown> {
+  const id = nextId();
+  return new Promise((resolve, reject) => {
+    pendingInvokes.set(id, { resolve, reject });
+    send({ id, type: "invoke", clip, command, input });
+  });
 }
 
-function redirectConsoleLogToStderr(): void {
-  console.log = (...args: unknown[]) => {
-    const serialized = args
-      .map((arg) => {
-        if (typeof arg === "string") {
-          return arg;
-        }
-
-        try {
-          return JSON.stringify(arg);
-        } catch {
-          return String(arg);
-        }
-      })
-      .join(" ");
+// === IPC Server ===
 
-    process.stderr.write(`${serialized}\n`);
+export async function serveIPC(clip: Clip): Promise<void> {
+  // Redirect console.log to stderr so stdout is reserved for IPC
+  const origLog = console.log;
+  console.log = (...args: unknown[]) => {
+    process.stderr.write(args.map(String).join(" ") + "\n");
   };
-}
 
-export async function serveIPC(clip: Clip): Promise<void> {
-  redirectConsoleLogToStderr();
+  // Register with pinixd
+  const manifest = createIPCManifest(clip);
+  send({ type: "register", manifest });
+
+  // Read messages from stdin
+  const reader = createLineReader(process.stdin);
+  const commands = clip.getCommands();
+
+  for await (const line of reader) {
+    let msg: BaseMessage;
+    try {
+      msg = JSON.parse(line) as BaseMessage;
+    } catch {
+      process.stderr.write(`[ipc] invalid JSON: ${line}\n`);
+      continue;
+    }
 
-  const reader = Bun.stdin.stream().getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
+    if (!msg.type) {
+      process.stderr.write(`[ipc] message missing type: ${line}\n`);
+      continue;
+    }
 
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
+    switch (msg.type) {
+      case "registered":
+        // Registration confirmed
+        break;
 
-      if (done) {
+      case "invoke": {
+        const inv = msg as InvokeMessage;
+        handleInvoke(inv, commands);
         break;
       }
 
-      buffer += decoder.decode(value, { stream: true });
-
-      while (true) {
-        const newlineIndex = buffer.indexOf("\n");
-
-        if (newlineIndex === -1) {
-          break;
-        }
-
-        const line = buffer.slice(0, newlineIndex).trim();
-        buffer = buffer.slice(newlineIndex + 1);
-
-        if (line.length === 0) {
-          continue;
+      case "result": {
+        const res = msg as ResultMessage;
+        const pending = pendingInvokes.get(res.id);
+        if (pending) {
+          pendingInvokes.delete(res.id);
+          pending.resolve(res.output);
         }
+        break;
+      }
 
-        try {
-          await handleRequestLine(clip, line);
-        } catch (error) {
-          writeResponse(createErrorResponse(null, toErrorMessage(error), "INTERNAL_ERROR"));
+      case "error": {
+        const err = msg as ErrorMessage;
+        const pending = pendingInvokes.get(err.id);
+        if (pending) {
+          pendingInvokes.delete(err.id);
+          pending.reject(new Error(err.error));
         }
+        break;
       }
+
+      default:
+        process.stderr.write(`[ipc] unknown message type: ${msg.type}\n`);
     }
+  }
+}
 
-    buffer += decoder.decode();
-    const tail = buffer.trim();
+async function handleInvoke(
+  msg: InvokeMessage,
+  commands: ReturnType<Clip["getCommands"]>,
+): Promise<void> {
+  const cmd = commands.get(msg.command ?? "");
+  if (!cmd) {
+    send({ id: msg.id, type: "error", error: `unknown command: ${msg.command}` });
+    return;
+  }
 
-    if (tail.length > 0) {
-      try {
-        await handleRequestLine(clip, tail);
-      } catch (error) {
-        writeResponse(createErrorResponse(null, toErrorMessage(error), "INTERNAL_ERROR"));
-      }
+  try {
+    const parsed = cmd.input.parse(msg.input ?? {});
+    const output = await cmd.fn(parsed);
+    send({ id: msg.id, type: "result", output });
+  } catch (err) {
+    send({ id: msg.id, type: "error", error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+// === Line Reader ===
+
+async function* createLineReader(stream: NodeJS.ReadableStream): AsyncGenerator<string> {
+  let buffer = "";
+  for await (const chunk of stream) {
+    buffer += chunk.toString();
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (line.trim()) yield line;
     }
-  } finally {
-    reader.releaseLock();
   }
+  if (buffer.trim()) yield buffer;
 }

package/src/manifest.ts

@@ -1,6 +1,13 @@
 import { z, type ZodType } from "zod";
 import type { Clip } from "./clip";
 
+export interface IPCManifest {
+  name: string;
+  domain: string;
+  commands: string[];
+  dependencies: string[];
+}
+
 function formatLiteralValue(value: unknown): string {
   return JSON.stringify(value);
 }
@@ -139,3 +146,16 @@ export function generateManifest(clip: Clip): string {
 
   return lines.join("\n");
 }
+
+export function createIPCManifest(clip: Clip): IPCManifest {
+  const dependencies = (clip as Clip & { dependencies?: unknown }).dependencies;
+
+  return {
+    name: clip.name,
+    domain: clip.domain,
+    commands: Array.from(clip.getCommands().keys()),
+    dependencies: Array.isArray(dependencies)
+      ? dependencies.filter((dependency): dependency is string => typeof dependency === "string")
+      : [],
+  };
+}