@pinixai/core 0.4.0 → 0.5.1

package/package.json

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

package/src/bindings.ts

@@ -0,0 +1,8 @@
+export interface Binding {
+  alias: string;
+  hub?: string;
+  hub_token?: string;
+  clip_token?: string;
+}
+
+export type Bindings = Record<string, Binding>;

package/src/cli.ts

@@ -93,9 +93,9 @@ function parseScalarValue(value: string, schema: ZodType): unknown {
   const normalized = unwrapSchema(schema);
 
   if (normalized instanceof z.ZodNumber) {
-    const parsed = Number.parseInt(value, 10);
+    const parsed = Number(value);
 
-    if (Number.isNaN(parsed)) {
+    if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
       throw new Error(`Invalid number value: ${value}`);
     }
 
@@ -111,9 +111,9 @@ function parseScalarValue(value: string, schema: ZodType): unknown {
     const literalValue = literalValues[0];
 
     if (typeof literalValue === "number") {
-      const parsed = Number.parseInt(value, 10);
+      const parsed = Number(value);
 
-      if (Number.isNaN(parsed)) {
+      if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
         throw new Error(`Invalid number value: ${value}`);
       }
 

package/src/clip.ts

@@ -20,9 +20,9 @@ function isHandlerDef(value: unknown): value is HandlerDef {
 }
 
 export abstract class Clip {
-  abstract name: string;
   abstract domain: string;
   abstract patterns: string[];
+  dependencies: Record<string, { package: string; version: string }> = {};
   entities: Record<string, z.ZodObject<any>> = {};
 
   protected readonly commands = new Map<string, HandlerDef>();
@@ -52,9 +52,9 @@ export abstract class Clip {
         return serveHTTP(this);
       }
 
-      const port = Number.parseInt(portArg, 10);
+      const port = Number(portArg);
 
-      if (Number.isNaN(port)) {
+      if (Number.isNaN(port) || !Number.isFinite(port) || port !== Math.floor(port) || port < 0) {
         console.error(`Invalid port: ${portArg}`);
         return;
       }
@@ -101,8 +101,9 @@ export abstract class Clip {
   }
 
   printHelp(): string {
+    const name = getClipName(this);
     const lines: string[] = [
-      `${this.name} (${this.domain})`,
+      name ? `${name} (${this.domain})` : this.domain,
       "",
     ];
 
@@ -187,3 +188,8 @@ export abstract class Clip {
     }
   }
 }
+
+export function getClipName(clip: Clip): string | undefined {
+  const value = (clip as { name?: unknown }).name;
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/http.ts

@@ -1,5 +1,5 @@
 import { dirname, join, resolve, sep } from "node:path";
-import type { Clip } from "./clip";
+import { getClipName, type Clip } from "./clip";
 import { zodToManifestType } from "./manifest";
 
 const CORS_HEADERS = {
@@ -249,5 +249,5 @@ export async function serveHTTP(clip: Clip, port = 3000): Promise<void> {
     fetch: (request) => handleRequest(clip, request),
   });
 
-  console.error(`Clip "${clip.name}" running at http://localhost:${server.port}`);
+  console.error(`Clip "${getClipName(clip) ?? clip.constructor.name}" running at http://localhost:${server.port}`);
 }

package/src/index.ts

@@ -1,7 +1,9 @@
 export { Clip } from "./clip";
+export type { Binding, Bindings } from "./bindings";
 export { command } from "./command";
 export { handler, type HandlerDef, type Stream } from "./handler";
 export { serveHTTP } from "./http";
-export { serveIPC, invoke } from "./ipc";
+export { serveIPC, invoke, redirectConsoleToStderr } from "./ipc";
+export type { IPCCommandInfo, IPCManifest } from "./manifest";
 export { serveMCP } from "./mcp";
 export { z } from "zod";

package/src/ipc.ts

@@ -1,6 +1,10 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import type { Binding, Bindings } from "./bindings";
 import type { Clip } from "./clip";
 import type { Stream } from "./handler";
-import { createIPCManifest } from "./manifest";
+import { createIPCManifest, type IPCManifest } from "./manifest";
 
 // === IPC Protocol Types ===
 
@@ -13,7 +17,12 @@ interface BaseMessage {
 
 interface RegisterMessage extends BaseMessage {
   type: "register";
-  manifest: { name: string; domain: string; commands: string[]; dependencies: string[] };
+  manifest: IPCManifest;
+}
+
+interface RegisteredMessage extends BaseMessage {
+  type: "registered";
+  alias?: string;
 }
 
 interface InvokeMessage extends BaseMessage {
@@ -22,6 +31,9 @@ interface InvokeMessage extends BaseMessage {
   command?: string;
   clip?: string;
   input?: unknown;
+  hub?: string;
+  hub_token?: string;
+  clip_token?: string;
 }
 
 interface ResultMessage extends BaseMessage {
@@ -36,10 +48,83 @@ interface ErrorMessage extends BaseMessage {
   error: string;
 }
 
+interface ChunkMessage extends BaseMessage {
+  type: "chunk";
+  id: string;
+  output: unknown;
+}
+
+interface DoneMessage extends BaseMessage {
+  type: "done";
+  id: string;
+}
+
 // === State ===
 
 const pendingInvokes = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
 let idCounter = 0;
+let registeredAlias: string | undefined;
+const bindings = loadBindings();
+
+function loadBindings(): Bindings {
+  const bindingsPath = join(dirname(Bun.main), "bindings.json");
+
+  try {
+    const parsed = JSON.parse(readFileSync(bindingsPath, "utf8")) as unknown;
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+
+    const loadedBindings: Bindings = {};
+    for (const [slot, value] of Object.entries(parsed)) {
+      const binding = normalizeBinding(value);
+      if (binding) {
+        loadedBindings[slot] = binding;
+      }
+    }
+
+    return loadedBindings;
+  } catch {
+    return {};
+  }
+}
+
+function normalizeBinding(value: unknown): Binding | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  const alias = asNonEmptyString(candidate.alias);
+
+  if (!alias) {
+    return null;
+  }
+
+  const binding: Binding = { alias };
+  const hub = asNonEmptyString(candidate.hub);
+  const hubToken = asNonEmptyString(candidate.hub_token);
+  const clipToken = asNonEmptyString(candidate.clip_token);
+
+  if (hub) {
+    binding.hub = hub;
+  }
+
+  if (hubToken) {
+    binding.hub_token = hubToken;
+  }
+
+  if (clipToken) {
+    binding.clip_token = clipToken;
+  }
+
+  return binding;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
 
 function nextId(): string {
   return `c${++idCounter}`;
@@ -51,22 +136,41 @@ function send(msg: Record<string, unknown>): void {
 
 // === Public API ===
 
-export async function invoke(clip: string, command: string, input: unknown): Promise<unknown> {
+export async function invoke(slot: string, command: string, input: unknown): Promise<unknown> {
+  const binding = bindings[slot];
   const id = nextId();
+
   return new Promise((resolve, reject) => {
     pendingInvokes.set(id, { resolve, reject });
-    send({ id, type: "invoke", clip, command, input });
+    send({
+      id,
+      type: "invoke",
+      clip: binding?.alias ?? slot,
+      command,
+      input,
+      hub: binding?.hub,
+      hub_token: binding?.hub_token,
+      clip_token: binding?.clip_token,
+    });
   });
 }
 
+// === Stdout Protection ===
+
+export function redirectConsoleToStderr(): void {
+  const write = (...args: unknown[]) => {
+    process.stderr.write(args.map(String).join(" ") + "\n");
+  };
+  console.log = write;
+  console.info = write;
+  console.debug = write;
+}
+
 // === IPC Server ===
 
 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");
-  };
+  redirectConsoleToStderr();
 
   // Register with pinixd
   const manifest = createIPCManifest(clip);
@@ -92,7 +196,7 @@ export async function serveIPC(clip: Clip): Promise<void> {
 
     switch (msg.type) {
       case "registered":
-        // Registration confirmed
+        registeredAlias = asNonEmptyString((msg as RegisteredMessage).alias);
         break;
 
       case "invoke": {
@@ -121,10 +225,32 @@ export async function serveIPC(clip: Clip): Promise<void> {
         break;
       }
 
+      case "chunk": {
+        // Streaming chunks — currently ignored on client side
+        // Future: could accumulate or forward to a stream callback
+        break;
+      }
+
+      case "done": {
+        const done = msg as DoneMessage;
+        const pending = pendingInvokes.get(done.id);
+        if (pending) {
+          pendingInvokes.delete(done.id);
+          pending.resolve(undefined);
+        }
+        break;
+      }
+
       default:
         process.stderr.write(`[ipc] unknown message type: ${msg.type}\n`);
     }
   }
+
+  // Clean up pending invokes on EOF
+  for (const [id, pending] of pendingInvokes) {
+    pending.reject(new Error("IPC connection closed"));
+  }
+  pendingInvokes.clear();
 }
 
 async function handleInvoke(
@@ -138,7 +264,7 @@ async function handleInvoke(
   }
 
   try {
-    const parsed = cmd.input.parse(msg.input ?? {});
+    const parsed = await cmd.input.parseAsync(msg.input ?? {});
     let streamed = false;
     const stream: Stream = {
       chunk(data: unknown): void {
@@ -154,7 +280,8 @@ async function handleInvoke(
       return;
     }
 
-    send({ id: msg.id, type: "result", output });
+    const validatedOutput = await cmd.output.parseAsync(output);
+    send({ id: msg.id, type: "result", output: validatedOutput });
   } catch (err) {
     send({ id: msg.id, type: "error", error: err instanceof Error ? err.message : String(err) });
   }
@@ -163,14 +290,17 @@ async function handleInvoke(
 // === Line Reader ===
 
 async function* createLineReader(stream: NodeJS.ReadableStream): AsyncGenerator<string> {
+  const decoder = new StringDecoder("utf8");
   let buffer = "";
   for await (const chunk of stream) {
-    buffer += chunk.toString();
+    buffer += decoder.write(chunk as Buffer);
     const lines = buffer.split("\n");
     buffer = lines.pop() ?? "";
     for (const line of lines) {
       if (line.trim()) yield line;
     }
   }
+  const remaining = decoder.end();
+  if (remaining) buffer += remaining;
   if (buffer.trim()) yield buffer;
 }

package/src/manifest.ts

@@ -1,11 +1,22 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { z, type ZodType } from "zod";
-import type { Clip } from "./clip";
+import { getClipName, type Clip } from "./clip";
 
-export interface IPCManifest {
+export interface IPCCommandInfo {
   name: string;
+  description?: string;
+  input?: string;
+  output?: string;
+}
+
+export interface IPCManifest {
   domain: string;
-  commands: string[];
-  dependencies: string[];
+  description?: string;
+  commands: IPCCommandInfo[];
+  dependencies: Record<string, { package: string; version: string }>;
+  package?: string;
+  version?: string;
 }
 
 function formatLiteralValue(value: unknown): string {
@@ -94,11 +105,8 @@ export function zodToManifestType(schema: ZodType): string {
 }
 
 export function generateManifest(clip: Clip): string {
-  const lines = [
-    `Clip: ${clip.name}`,
-    `Domain: ${clip.domain}`,
-    "",
-  ];
+  const name = getClipName(clip);
+  const lines = name ? [`Clip: ${name}`, `Domain: ${clip.domain}`, ""] : [`Domain: ${clip.domain}`, ""];
 
   if (clip.patterns.length > 0) {
     lines.push("Patterns:");
@@ -147,15 +155,62 @@ export function generateManifest(clip: Clip): string {
   return lines.join("\n");
 }
 
+function findJsonFile(filename: string): Record<string, unknown> | null {
+  let dir = dirname(Bun.main);
+  for (;;) {
+    const filePath = join(dir, filename);
+    if (existsSync(filePath)) {
+      try {
+        return JSON.parse(readFileSync(filePath, "utf8")) as Record<string, unknown>;
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function resolvePackageInfo(): { package?: string; version?: string } {
+  const pinixJson = findJsonFile("pinix.json");
+  const packageJson = findJsonFile("package.json");
+
+  return {
+    package: asString(pinixJson?.name) ?? asString(packageJson?.name),
+    version: asString(pinixJson?.version) ?? asString(packageJson?.version),
+  };
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
 export function createIPCManifest(clip: Clip): IPCManifest {
-  const dependencies = (clip as Clip & { dependencies?: unknown }).dependencies;
+  const pkgInfo = resolvePackageInfo();
+
+  const commands: IPCCommandInfo[] = [];
+
+  for (const [name, handler] of clip.getCommands()) {
+    const description = clip.getCommandDescription(name);
+    const cmd: IPCCommandInfo = { name };
+    if (description) cmd.description = description;
+
+    try {
+      cmd.input = JSON.stringify(z.toJSONSchema(handler.input));
+    } catch {}
+    try {
+      cmd.output = JSON.stringify(z.toJSONSchema(handler.output));
+    } catch {}
+
+    commands.push(cmd);
+  }
 
   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")
-      : [],
+    commands,
+    dependencies: clip.dependencies,
+    ...pkgInfo,
   };
 }

package/src/mcp.ts

@@ -1,10 +1,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import type { Clip } from "./clip";
+import { getClipName, type Clip } from "./clip";
+import { redirectConsoleToStderr } from "./ipc";
 
 export async function serveMCP(clip: Clip): Promise<void> {
+  // Redirect console.log to stderr so stdout is reserved for MCP JSON-RPC
+  redirectConsoleToStderr();
   const server = new McpServer({
-    name: clip.name,
+    name: getClipName(clip) ?? clip.constructor.name,
     version: "1.0.0",
   });