@pinixai/core 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# pinixai-core
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.11. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pinixai/core",
+  "version": "0.1.0",
+  "description": "Clip framework for Pinix — define once, run as CLI / MCP / Pinix bridge",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "clip",
+    "pinix",
+    "mcp",
+    "agent",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/epiral/pinixai-core.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "^1.3.11"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,233 @@
+import { z, type ZodError, type ZodObject, type ZodType } from "zod";
+import { zodToManifestType } from "./manifest";
+
+export class CLIHelpError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CLIHelpError";
+  }
+}
+
+function unwrapSchema(schema: ZodType): ZodType {
+  if (
+    schema instanceof z.ZodOptional ||
+    schema instanceof z.ZodNullable ||
+    schema instanceof z.ZodDefault
+  ) {
+    return unwrapSchema(schema.unwrap());
+  }
+
+  return schema;
+}
+
+function getSchemaDescription(schema: ZodType): string | undefined {
+  if (schema.description) {
+    return schema.description;
+  }
+
+  if (
+    schema instanceof z.ZodOptional ||
+    schema instanceof z.ZodNullable ||
+    schema instanceof z.ZodDefault
+  ) {
+    return getSchemaDescription(schema.unwrap());
+  }
+
+  return undefined;
+}
+
+function getDefaultValue(schema: ZodType): unknown {
+  if (schema instanceof z.ZodDefault) {
+    return (schema as ZodType & { _def: { defaultValue: unknown } })._def.defaultValue;
+  }
+
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+    return getDefaultValue(schema.unwrap());
+  }
+
+  return undefined;
+}
+
+function hasDefaultValue(schema: ZodType): boolean {
+  if (schema instanceof z.ZodDefault) {
+    return true;
+  }
+
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+    return hasDefaultValue(schema.unwrap());
+  }
+
+  return false;
+}
+
+function formatOptionType(schema: ZodType): string {
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodDefault) {
+    return formatOptionType(schema.unwrap());
+  }
+
+  return zodToManifestType(schema);
+}
+
+function formatZodError(error: ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "input";
+      return `${path}: ${issue.message}`;
+    })
+    .join("\n");
+}
+
+function parseBoolean(value: string): boolean {
+  if (value === "true" || value === "1") {
+    return true;
+  }
+
+  if (value === "false" || value === "0") {
+    return false;
+  }
+
+  throw new Error(`Invalid boolean value: ${value}`);
+}
+
+function parseScalarValue(value: string, schema: ZodType): unknown {
+  const normalized = unwrapSchema(schema);
+
+  if (normalized instanceof z.ZodNumber) {
+    const parsed = Number.parseInt(value, 10);
+
+    if (Number.isNaN(parsed)) {
+      throw new Error(`Invalid number value: ${value}`);
+    }
+
+    return parsed;
+  }
+
+  if (normalized instanceof z.ZodBoolean) {
+    return parseBoolean(value);
+  }
+
+  if (normalized instanceof z.ZodLiteral) {
+    const literalValues = Array.from((normalized as ZodType & { values: Set<unknown> }).values);
+    const literalValue = literalValues[0];
+
+    if (typeof literalValue === "number") {
+      const parsed = Number.parseInt(value, 10);
+
+      if (Number.isNaN(parsed)) {
+        throw new Error(`Invalid number value: ${value}`);
+      }
+
+      return parsed;
+    }
+
+    if (typeof literalValue === "boolean") {
+      return parseBoolean(value);
+    }
+  }
+
+  return value;
+}
+
+export function formatCLIHelp(
+  schema: ZodObject,
+  commandName?: string,
+  describe?: string,
+): string {
+  const lines: string[] = [];
+
+  if (commandName) {
+    lines.push(`Command: ${commandName}`);
+  }
+
+  if (describe) {
+    lines.push(describe);
+  }
+
+  const entries = Object.entries(schema.shape);
+  lines.push("Arguments:");
+
+  if (entries.length === 0) {
+    lines.push("  (none)");
+  }
+
+  for (const [key, value] of entries) {
+    const flags: string[] = [value.isOptional() ? "optional" : "required"];
+
+    if (hasDefaultValue(value)) {
+      flags.push(`default: ${JSON.stringify(getDefaultValue(value))}`);
+    }
+
+    const description = getSchemaDescription(value);
+    const suffix = description ? ` - ${description}` : "";
+    lines.push(`  --${key}: ${formatOptionType(value)} (${flags.join(", ")})${suffix}`);
+  }
+
+  lines.push("  --help: boolean (optional) - Show command help");
+
+  return lines.join("\n");
+}
+
+export function parseCLIArgs<T extends ZodObject>(args: string[], schema: T): z.infer<T> {
+  if (args.includes("--help")) {
+    throw new CLIHelpError(formatCLIHelp(schema));
+  }
+
+  const values: Record<string, unknown> = {};
+  const shape = schema.shape as Record<string, ZodType>;
+  let index = 0;
+
+  while (index < args.length) {
+    const arg = args[index];
+
+    if (arg === undefined) {
+      break;
+    }
+
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+
+    const key = arg.slice(2);
+    const field = shape[key];
+
+    if (!field) {
+      throw new Error(`Unknown option: --${key}`);
+    }
+
+    const normalized = unwrapSchema(field);
+    const next = args[index + 1];
+
+    if (normalized instanceof z.ZodBoolean && (next === undefined || next.startsWith("--"))) {
+      values[key] = true;
+      index += 1;
+      continue;
+    }
+
+    if (next === undefined) {
+      throw new Error(`Missing value for --${key}`);
+    }
+
+    if (normalized instanceof z.ZodArray) {
+      const current = values[key];
+      const parsed = parseScalarValue(next, normalized.element);
+
+      if (Array.isArray(current)) {
+        current.push(parsed);
+      } else {
+        values[key] = [parsed];
+      }
+    } else {
+      values[key] = parseScalarValue(next, field);
+    }
+
+    index += 2;
+  }
+
+  const result = schema.safeParse(values);
+
+  if (!result.success) {
+    throw new Error(formatZodError(result.error));
+  }
+
+  return result.data;
+}

package/src/clip.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { CLIHelpError, formatCLIHelp, parseCLIArgs } from "./cli";
+import type { HandlerDef } from "./handler";
+import { serveIPC } from "./ipc";
+import { serveMCP } from "./mcp";
+import { generateManifest } from "./manifest";
+
+function isHandlerDef(value: unknown): value is HandlerDef {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const candidate = value as Partial<HandlerDef>;
+  return (
+    candidate.input instanceof z.ZodType &&
+    candidate.output instanceof z.ZodType &&
+    typeof candidate.fn === "function"
+  );
+}
+
+export abstract class Clip {
+  abstract name: string;
+  abstract domain: string;
+  abstract patterns: string[];
+  entities: Record<string, z.ZodObject<any>> = {};
+
+  protected readonly commands = new Map<string, HandlerDef>();
+  protected readonly commandDescriptions = new Map<string, string>();
+
+  async start(): Promise<void> {
+    const args = process.argv.slice(2);
+    const [modeOrCommand, ...restArgs] = args;
+
+    if (!modeOrCommand || modeOrCommand === "--help") {
+      console.log(this.printHelp());
+      return;
+    }
+
+    if (modeOrCommand === "--mcp") {
+      return serveMCP(this);
+    }
+
+    if (modeOrCommand === "--ipc") {
+      return serveIPC(this);
+    }
+
+    if (modeOrCommand === "--manifest") {
+      console.log(this.toManifest());
+      return;
+    }
+
+    const commandName = modeOrCommand;
+    const commandHandler = this.commands.get(commandName);
+
+    if (!commandHandler) {
+      console.error(`Unknown command: ${commandName}`);
+      console.log(this.printHelp());
+      return;
+    }
+
+    if (!(commandHandler.input instanceof z.ZodObject)) {
+      console.error(`CLI mode only supports object input schemas for command: ${commandName}`);
+      return;
+    }
+
+    try {
+      const input = parseCLIArgs(restArgs, commandHandler.input);
+      const output = await commandHandler.fn(input);
+      const parsedOutput = commandHandler.output.parse(output);
+      console.log(JSON.stringify(parsedOutput));
+    } catch (error) {
+      if (error instanceof CLIHelpError) {
+        console.log(this.printCommandHelp(commandName, commandHandler));
+        return;
+      }
+
+      console.error(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  toManifest(): string {
+    return generateManifest(this);
+  }
+
+  printHelp(): string {
+    const lines: string[] = [
+      `${this.name} (${this.domain})`,
+      "",
+    ];
+
+    if (this.patterns.length > 0) {
+      lines.push("Patterns:");
+      for (const pattern of this.patterns) {
+        lines.push(`  ${pattern}`);
+      }
+      lines.push("");
+    }
+
+    lines.push("Usage:");
+    lines.push("  bun run <script> <command> [options]");
+    lines.push("  bun run <script> --help");
+    lines.push("  bun run <script> --manifest");
+    lines.push("  bun run <script> --mcp");
+    lines.push("  bun run <script> --ipc");
+    lines.push("");
+    lines.push("Commands:");
+
+    if (this.commands.size === 0) {
+      lines.push("  (none)");
+      return lines.join("\n");
+    }
+
+    for (const [commandName, commandHandler] of this.commands) {
+      const describe = this.commandDescriptions.get(commandName);
+      lines.push(`  ${commandName}${describe ? ` - ${describe}` : ""}`);
+
+      if (commandHandler.input instanceof z.ZodObject) {
+        const commandHelp = formatCLIHelp(commandHandler.input);
+        lines.push(...commandHelp.split("\n").map((line) => `    ${line}`));
+      } else {
+        lines.push(`    Input: ${commandHandler.input.constructor.name}`);
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  getCommands(): ReadonlyMap<string, HandlerDef> {
+    return this.commands;
+  }
+
+  getCommandDescription(name: string): string | undefined {
+    return this.commandDescriptions.get(name);
+  }
+
+  protected printCommandHelp(commandName: string, commandHandler: HandlerDef): string {
+    const describe = this.commandDescriptions.get(commandName);
+
+    if (!(commandHandler.input instanceof z.ZodObject)) {
+      return [
+        `Command: ${commandName}`,
+        describe,
+        `Input: ${commandHandler.input.constructor.name}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    }
+
+    return formatCLIHelp(commandHandler.input, commandName, describe);
+  }
+
+  static _registerCommand(target: object, propertyKey: string, describe?: string): void {
+    if (!(target instanceof Clip)) {
+      throw new Error("@command can only be used on Clip instances");
+    }
+
+    const clip = target as Clip;
+    const value = (clip as Record<string, unknown>)[propertyKey];
+
+    if (!isHandlerDef(value)) {
+      throw new Error(`@command can only decorate handler() fields: ${propertyKey}`);
+    }
+
+    clip.commands.set(propertyKey, value);
+
+    if (describe) {
+      clip.commandDescriptions.set(propertyKey, describe);
+    }
+  }
+}

package/src/command.ts

@@ -0,0 +1,27 @@
+import type { HandlerDef } from "./handler";
+
+type CommandHost = {
+  constructor: {
+    _registerCommand(target: object, propertyKey: string, describe?: string): void;
+  };
+};
+
+export function command(describe?: string) {
+  return function (
+    _value: undefined,
+    context: ClassFieldDecoratorContext<CommandHost, HandlerDef>,
+  ): void {
+    if (context.static) {
+      throw new Error("@command can only be used on instance fields");
+    }
+
+    if (context.private) {
+      throw new Error("@command cannot be used on private fields");
+    }
+
+    context.addInitializer(function () {
+      const constructor = this.constructor as CommandHost["constructor"];
+      constructor._registerCommand(this, String(context.name), describe);
+    });
+  };
+}

package/src/handler.ts

@@ -0,0 +1,15 @@
+import { z, type ZodType } from "zod";
+
+export interface HandlerDef<I extends ZodType = ZodType, O extends ZodType = ZodType> {
+  input: I;
+  output: O;
+  fn: (input: z.infer<I>) => Promise<z.infer<O>>;
+}
+
+export function handler<I extends ZodType, O extends ZodType>(
+  input: I,
+  output: O,
+  fn: (input: z.infer<I>) => Promise<z.infer<O>>,
+): HandlerDef<I, O> {
+  return { input, output, fn };
+}

package/src/index.ts

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

package/src/ipc.ts

@@ -0,0 +1,160 @@
+import type { z } from "zod";
+import type { Clip } from "./clip";
+
+type IPCRequest = {
+  id?: unknown;
+  command?: unknown;
+  input?: unknown;
+};
+
+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);
+}
+
+function writeResponse(response: IPCResponse): void {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object";
+}
+
+function createErrorResponse(id: unknown, message: string, code: string): IPCResponse {
+  return {
+    id,
+    error: {
+      message,
+      code,
+    },
+  };
+}
+
+async function handleRequestLine(clip: Clip, line: string): Promise<void> {
+  let request: IPCRequest;
+
+  try {
+    request = JSON.parse(line) as IPCRequest;
+  } catch (error) {
+    writeResponse(createErrorResponse(null, `Invalid JSON: ${toErrorMessage(error)}`, "INVALID_JSON"));
+    return;
+  }
+
+  const { id = null, command, input } = request;
+
+  if (typeof command !== "string" || command.length === 0) {
+    writeResponse(createErrorResponse(id, "Request command must be a non-empty string", "INVALID_REQUEST"));
+    return;
+  }
+
+  const commandHandler = clip.getCommands().get(command);
+
+  if (!commandHandler) {
+    writeResponse(createErrorResponse(id, `Unknown command: ${command}`, "COMMAND_NOT_FOUND"));
+    return;
+  }
+
+  if (!isObject(input)) {
+    writeResponse(createErrorResponse(id, "Request input must be an object", "INVALID_INPUT"));
+    return;
+  }
+
+  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"));
+  }
+}
+
+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(" ");
+
+    process.stderr.write(`${serialized}\n`);
+  };
+}
+
+export async function serveIPC(clip: Clip): Promise<void> {
+  redirectConsoleLogToStderr();
+
+  const reader = Bun.stdin.stream().getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) {
+        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;
+        }
+
+        try {
+          await handleRequestLine(clip, line);
+        } catch (error) {
+          writeResponse(createErrorResponse(null, toErrorMessage(error), "INTERNAL_ERROR"));
+        }
+      }
+    }
+
+    buffer += decoder.decode();
+    const tail = buffer.trim();
+
+    if (tail.length > 0) {
+      try {
+        await handleRequestLine(clip, tail);
+      } catch (error) {
+        writeResponse(createErrorResponse(null, toErrorMessage(error), "INTERNAL_ERROR"));
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,141 @@
+import { z, type ZodType } from "zod";
+import type { Clip } from "./clip";
+
+function formatLiteralValue(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function getDefaultValue(schema: ZodType): unknown {
+  if (schema instanceof z.ZodDefault) {
+    return (schema as ZodType & { _def: { defaultValue: unknown } })._def.defaultValue;
+  }
+
+  return undefined;
+}
+
+export function zodToManifestType(schema: ZodType): string {
+  if (schema instanceof z.ZodOptional) {
+    return `${zodToManifestType(schema.unwrap())} (optional)`;
+  }
+
+  if (schema instanceof z.ZodDefault) {
+    return `${zodToManifestType(schema.unwrap())} (default: ${formatLiteralValue(getDefaultValue(schema))})`;
+  }
+
+  if (schema instanceof z.ZodNullable) {
+    return `${zodToManifestType(schema.unwrap())} | null`;
+  }
+
+  if (schema instanceof z.ZodString) {
+    return "string";
+  }
+
+  if (schema instanceof z.ZodNumber) {
+    return "number";
+  }
+
+  if (schema instanceof z.ZodBoolean) {
+    return "boolean";
+  }
+
+  if (schema instanceof z.ZodEnum) {
+    return schema.options.map(formatLiteralValue).join(" | ");
+  }
+
+  if (schema instanceof z.ZodLiteral) {
+    const literalValues = Array.from((schema as ZodType & { values: Set<unknown> }).values);
+    return literalValues.map(formatLiteralValue).join(" | ");
+  }
+
+  if (schema instanceof z.ZodArray) {
+    return `Array<${zodToManifestType(schema.element)}>`;
+  }
+
+  if (schema instanceof z.ZodObject) {
+    const entries = Object.entries(schema.shape);
+
+    if (entries.length === 0) {
+      return "{}";
+    }
+
+    return `{ ${entries
+      .map(([key, value]) => `${key}${value.isOptional() ? "?" : ""}: ${zodToManifestType(value)}`)
+      .join("; ")} }`;
+  }
+
+  if (schema instanceof z.ZodUnion) {
+    return schema.options.map(zodToManifestType).join(" | ");
+  }
+
+  if (schema instanceof z.ZodNull) {
+    return "null";
+  }
+
+  if (schema instanceof z.ZodUndefined) {
+    return "undefined";
+  }
+
+  if (schema instanceof z.ZodAny) {
+    return "any";
+  }
+
+  if (schema instanceof z.ZodUnknown) {
+    return "unknown";
+  }
+
+  return schema.constructor.name.replace(/^Zod/, "").toLowerCase();
+}
+
+export function generateManifest(clip: Clip): string {
+  const lines = [
+    `Clip: ${clip.name}`,
+    `Domain: ${clip.domain}`,
+    "",
+  ];
+
+  if (clip.patterns.length > 0) {
+    lines.push("Patterns:");
+    for (const pattern of clip.patterns) {
+      lines.push(`  ${pattern}`);
+    }
+    lines.push("");
+  }
+
+  const entityEntries = Object.entries(clip.entities);
+  if (entityEntries.length > 0) {
+    lines.push("Entities:");
+    for (const [name, schema] of entityEntries) {
+      const entityDesc = schema.description;
+      lines.push(`  ${name}${entityDesc ? ` — ${entityDesc}` : ""}:`);
+      for (const [field, fieldSchema] of Object.entries(schema.shape)) {
+        const desc = (fieldSchema as z.ZodType).description;
+        const type = zodToManifestType(fieldSchema as z.ZodType);
+        lines.push(`    ${field}: ${type}${desc ? ` — ${desc}` : ""}`);
+      }
+    }
+    lines.push("");
+  }
+
+  lines.push("Commands:");
+
+  const commands = Array.from(clip.getCommands().entries());
+
+  if (commands.length === 0) {
+    lines.push("- none");
+    return lines.join("\n");
+  }
+
+  for (const [name, handler] of commands) {
+    lines.push(`- ${name}`);
+
+    const describe = clip.getCommandDescription(name);
+    if (describe) {
+      lines.push(`  Description: ${describe}`);
+    }
+
+    lines.push(`  Input: ${zodToManifestType(handler.input)}`);
+    lines.push(`  Output: ${zodToManifestType(handler.output)}`);
+  }
+
+  return lines.join("\n");
+}

package/src/mcp.ts

@@ -0,0 +1,38 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Clip } from "./clip";
+
+export async function serveMCP(clip: Clip): Promise<void> {
+  const server = new McpServer({
+    name: clip.name,
+    version: "1.0.0",
+  });
+
+  for (const [name, commandHandler] of clip.getCommands()) {
+    const description = clip.getCommandDescription(name);
+
+    server.registerTool(
+      name,
+      {
+        description,
+        inputSchema: commandHandler.input,
+      },
+      async (input) => {
+        const output = await commandHandler.fn(input);
+        const parsedOutput = commandHandler.output.parse(output);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(parsedOutput),
+            },
+          ],
+        };
+      },
+    );
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}