maestro-agent 0.0.1 → 0.0.3

package/src/skills/skill-md.ts

@@ -0,0 +1,282 @@
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+
+/**
+ * SKILL.md parser and serializer with YAML Frontmatter support.
+ *
+ * Format:
+ * ```markdown
+ * ---
+ * name: my-skill
+ * description: Short description
+ * version: 1.0.0
+ * metadata:
+ *   author: you
+ *   tags: [code, review]
+ * argument-hint: "<file_path> [--fix]"
+ * platforms:
+ *   claude: true
+ *   codex: true
+ *   gemini: false
+ * ---
+ *
+ * # my-skill
+ *
+ * Full markdown body here...
+ * ```
+ */
+
+export interface SkillFrontmatter {
+  name: string;
+  description?: string;
+  version?: string;
+  metadata?: Record<string, any>;
+  "argument-hint"?: string;
+  platforms?: Record<string, boolean>;
+}
+
+export interface ParsedSkillMd {
+  frontmatter: SkillFrontmatter;
+  body: string;
+  raw: string;
+}
+
+/**
+ * Parse a SKILL.md file content into frontmatter + body.
+ * Supports both:
+ * - YAML frontmatter delimited by `---`
+ * - Legacy format: `# Title\n\nDescription...`
+ */
+export function parseSkillMd(content: string): ParsedSkillMd {
+  const raw = content;
+  const trimmed = content.trim();
+
+  // Try YAML frontmatter first
+  if (trimmed.startsWith("---")) {
+    const endIdx = trimmed.indexOf("---", 3);
+    if (endIdx !== -1) {
+      const yamlBlock = trimmed.slice(3, endIdx).trim();
+      const body = trimmed.slice(endIdx + 3).trim();
+      const frontmatter = parseYamlSimple(yamlBlock);
+
+      // If no name in frontmatter, try to extract from body heading
+      if (!frontmatter.name) {
+        const headingMatch = body.match(/^#\s+(.+)/m);
+        if (headingMatch) frontmatter.name = headingMatch[1].trim();
+      }
+
+      return { frontmatter, body, raw };
+    }
+  }
+
+  // Legacy format: # Title\n\nDescription
+  return parseLegacyFormat(trimmed);
+}
+
+/**
+ * Serialize a skill definition back to SKILL.md format with frontmatter.
+ */
+export function serializeSkillMd(frontmatter: SkillFrontmatter, body: string): string {
+  const yaml = serializeYamlSimple(frontmatter);
+  const parts = ["---", yaml, "---", "", body];
+  return parts.join("\n") + "\n";
+}
+
+/**
+ * Merge frontmatter updates into an existing SKILL.md, preserving body.
+ */
+export function updateSkillMdFrontmatter(content: string, updates: Partial<SkillFrontmatter>): string {
+  const parsed = parseSkillMd(content);
+  const merged = { ...parsed.frontmatter, ...updates };
+  return serializeSkillMd(merged, parsed.body);
+}
+
+// ─── Simple YAML Parser (no dependencies) ────────────────────────────────────
+
+function parseYamlSimple(yaml: string): SkillFrontmatter {
+  const result: any = {};
+  const lines = yaml.split("\n");
+  let currentKey = "";
+  let nestedObj: Record<string, any> | null = null;
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    const indent = line.length - line.trimStart().length;
+    const trimmedLine = line.trim();
+
+    // Nested key-value (indented under a parent key)
+    if (indent > 0 && nestedObj !== null && currentKey) {
+      const kvMatch = trimmedLine.match(/^([^:]+):\s*(.*)$/);
+      if (kvMatch) {
+        const [, k, v] = kvMatch;
+        nestedObj[k.trim()] = parseYamlValue(v.trim());
+        continue;
+      }
+    }
+
+    // Top-level key
+    if (indent === 0 && nestedObj !== null) {
+      result[currentKey] = nestedObj;
+      nestedObj = null;
+    }
+
+    const kvMatch = trimmedLine.match(/^([^:]+):\s*(.*)$/);
+    if (kvMatch) {
+      const [, key, value] = kvMatch;
+      const k = key.trim();
+      const v = value.trim();
+
+      if (v === "" || v === "|") {
+        // Start of nested object or multiline
+        currentKey = k;
+        nestedObj = {};
+      } else {
+        currentKey = k;
+        result[k] = parseYamlValue(v);
+        nestedObj = null;
+      }
+    }
+  }
+
+  // Flush any remaining nested object
+  if (nestedObj !== null && currentKey) {
+    result[currentKey] = nestedObj;
+  }
+
+  return result as SkillFrontmatter;
+}
+
+function parseYamlValue(value: string): any {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null" || value === "~") return null;
+  if (/^-?\d+$/.test(value)) return parseInt(value, 10);
+  if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
+
+  // Inline array: [a, b, c]
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1);
+    return inner.split(",").map((s) => parseYamlValue(s.trim()));
+  }
+
+  // Quoted string
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}
+
+function serializeYamlSimple(obj: SkillFrontmatter): string {
+  const lines: string[] = [];
+
+  const simpleKeys: (keyof SkillFrontmatter)[] = ["name", "description", "version", "argument-hint"];
+  for (const key of simpleKeys) {
+    const val = obj[key];
+    if (val !== undefined && val !== null && val !== "") {
+      lines.push(`${key}: ${formatYamlValue(val)}`);
+    }
+  }
+
+  if (obj.metadata && Object.keys(obj.metadata).length > 0) {
+    lines.push("metadata:");
+    for (const [k, v] of Object.entries(obj.metadata)) {
+      lines.push(`  ${k}: ${formatYamlValue(v)}`);
+    }
+  }
+
+  if (obj.platforms && Object.keys(obj.platforms).length > 0) {
+    lines.push("platforms:");
+    for (const [k, v] of Object.entries(obj.platforms)) {
+      lines.push(`  ${k}: ${v}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatYamlValue(val: any): string {
+  if (typeof val === "boolean") return val ? "true" : "false";
+  if (typeof val === "number") return String(val);
+  if (Array.isArray(val)) return `[${val.map((v) => formatYamlValue(v)).join(", ")}]`;
+  if (typeof val === "string") {
+    if (val.includes(":") || val.includes("#") || val.includes('"') || val.includes("'")) {
+      return `"${val.replace(/"/g, '\\"')}"`;
+    }
+    return val;
+  }
+  return JSON.stringify(val);
+}
+
+// ─── Legacy Format Parser ────────────────────────────────────────────────────
+
+function parseLegacyFormat(content: string): ParsedSkillMd {
+  const lines = content.split("\n");
+  let name = "";
+  let nameIdx = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!name && trimmed.startsWith("# ")) {
+      name = trimmed.slice(2).trim();
+      nameIdx = i;
+      break;
+    }
+  }
+
+  // Everything after the title is body
+  const bodyLines = nameIdx >= 0 ? lines.slice(nameIdx + 1) : lines;
+  const bodyText = bodyLines.join("\n").trim();
+
+  // First non-empty paragraph after the title is the description
+  const paragraphs = bodyText.split(/\n\s*\n/);
+  const firstPara = paragraphs[0]?.trim() || "";
+
+  return {
+    frontmatter: { name: name || "Untitled", description: firstPara },
+    body: content,
+    raw: content,
+  };
+}
+
+// ─── Directory Loader ────────────────────────────────────────────────────────
+
+export interface LoadedSkill {
+  frontmatter: SkillFrontmatter;
+  body: string;
+  files: { name: string; path: string }[];
+  dirPath: string;
+}
+
+/**
+ * Load a complete skill definition from a directory.
+ * Reads SKILL.md (with frontmatter), and inventories additional files.
+ * Returns null if the directory doesn't contain a valid SKILL.md.
+ */
+export function loadSkillFromDir(dirPath: string): LoadedSkill | null {
+  const mdPath = join(dirPath, "SKILL.md");
+  if (!existsSync(mdPath)) return null;
+
+  const content = readFileSync(mdPath, "utf-8");
+  const parsed = parseSkillMd(content);
+
+  // Inventory other files in the skill directory
+  const files: { name: string; path: string }[] = [];
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === "SKILL.md") continue;
+      if (entry.isFile()) {
+        files.push({ name: entry.name, path: join(dirPath, entry.name) });
+      }
+    }
+  } catch {}
+
+  return {
+    frontmatter: parsed.frontmatter,
+    body: parsed.body,
+    files,
+    dirPath,
+  };
+}

package/src/transport/http-api.ts

@@ -0,0 +1,75 @@
+import type { Transport, TransportProcess, TransportSpawnOptions } from "./types";
+
+export interface HttpApiTransportOptions {
+  target: string;
+  fetchImpl?: typeof fetch;
+}
+
+export class HttpApiTransport implements Transport {
+  readonly type = "http-api";
+
+  private readonly target: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: HttpApiTransportOptions) {
+    this.target = opts.target.replace(/\/$/, "");
+    this.fetchImpl = opts.fetchImpl || fetch;
+  }
+
+  async spawn(cmd: string, args: string[], opts: TransportSpawnOptions = {}): Promise<TransportProcess> {
+    const res = await this.fetchImpl(`${this.target}/spawn`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        cmd,
+        args,
+        cwd: opts.cwd,
+        env: opts.env || {},
+      }),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`HTTP API transport spawn failed (${res.status}): ${text || res.statusText}`);
+    }
+
+    const payload = await res.json() as {
+      pid?: number;
+      stdout?: string;
+      stderr?: string;
+      exit_code?: number;
+      session_id?: string;
+    };
+
+    return {
+      pid: payload.pid ?? 0,
+      stdin: { write: () => {} },
+      stdout: textStream(payload.stdout || ""),
+      stderr: textStream(payload.stderr || ""),
+      exited: Promise.resolve(payload.exit_code ?? 0),
+      kill: () => {},
+    };
+  }
+
+  async healthcheck(): Promise<{ ok: boolean; detail?: string }> {
+    try {
+      const res = await this.fetchImpl(`${this.target}/health`, { method: "GET" });
+      return { ok: res.ok, detail: res.ok ? "ok" : `status ${res.status}` };
+    } catch (err: any) {
+      return { ok: false, detail: err.message };
+    }
+  }
+
+  close() {
+    // No persistent connection for HTTP
+  }
+}
+
+function textStream(text: string): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      if (text) controller.enqueue(new TextEncoder().encode(text));
+      controller.close();
+    },
+  });
+}

package/src/transport/index.ts

@@ -0,0 +1,4 @@
+export { LocalPtyTransport } from "./local-pty";
+export { SshTransport } from "./ssh";
+export { HttpApiTransport } from "./http-api";
+export type { Transport, TransportProcess, TransportSpawnOptions } from "./types";

package/src/transport/local-pty.ts

@@ -0,0 +1,119 @@
+import { EventEmitter } from "events";
+import { appendFileSync } from "fs";
+import type { Transport, TransportSpawnOptions } from "./types";
+
+export interface PtySessionOptions {
+  cwd: string;
+  env?: Record<string, string>;
+  transcriptPath?: string;
+}
+
+export interface PtySession extends EventEmitter {
+  id: string;
+  pid: number;
+  stdin: WritableStream<Uint8Array> | { write(data: string): void };
+  write(data: string): void;
+  kill(): void;
+}
+
+export class LocalPtyTransport implements Transport {
+  readonly type = "local-pty" as const;
+
+  async spawn(id: string, cmd: string, args: string[], opts: PtySessionOptions): Promise<PtySession>;
+  async spawn(cmd: string, args: string[], opts?: TransportSpawnOptions): Promise<any>;
+  async spawn(...allArgs: any[]): Promise<any> {
+    // Overload: (id, cmd, args, opts) or (cmd, args, opts)
+    if (typeof allArgs[1] === "string") {
+      return this.spawnPty(allArgs[0], allArgs[1], allArgs[2], allArgs[3]);
+    }
+    // Transport interface: spawn(cmd, args, opts)
+    const [cmd, args, opts] = allArgs;
+    const proc = Bun.spawn([cmd, ...(args || [])], {
+      cwd: opts?.cwd,
+      env: { ...process.env, ...(opts?.env || {}) },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    return {
+      pid: proc.pid,
+      stdin: proc.stdin,
+      stdout: proc.stdout,
+      stderr: proc.stderr,
+      exited: proc.exited,
+      kill: () => proc.kill(),
+    };
+  }
+
+  private spawnPty(id: string, cmd: string, args: string[], opts: PtySessionOptions): PtySession {
+    const proc = Bun.spawn([cmd, ...args], {
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const emitter = new EventEmitter() as PtySession;
+    emitter.id = id;
+    emitter.pid = proc.pid;
+    emitter.stdin = proc.stdin;
+    emitter.write = (data: string) => {
+      proc.stdin.write(data);
+    };
+    emitter.kill = () => {
+      proc.kill();
+    };
+
+    // stdout 流
+    (async () => {
+      const reader = proc.stdout.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const text = new TextDecoder().decode(value);
+        if (opts.transcriptPath) {
+          appendFileSync(opts.transcriptPath, text);
+        }
+        emitter.emit("data", text);
+      }
+    })();
+
+    // stderr 流
+    (async () => {
+      const reader = proc.stderr.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const text = new TextDecoder().decode(value);
+        if (opts.transcriptPath) {
+          appendFileSync(opts.transcriptPath, text);
+        }
+        emitter.emit("data", text);
+      }
+    })();
+
+    // 退出
+    proc.exited.then((code) => {
+      emitter.emit("exit", code);
+    });
+
+    return emitter;
+  }
+
+  async healthcheck(): Promise<{ ok: boolean; detail?: string }> {
+    try {
+      const proc = Bun.spawn(["echo", "ok"], { stdout: "pipe" });
+      const code = await proc.exited;
+      return { ok: code === 0, detail: code === 0 ? "ok" : `exit ${code}` };
+    } catch (err: any) {
+      return { ok: false, detail: err.message };
+    }
+  }
+
+  close() {
+    // No-op for local transport
+  }
+}
+
+export const localPty = new LocalPtyTransport();

package/src/transport/ssh.ts

@@ -0,0 +1,176 @@
+import { Client } from "ssh2";
+import type { ClientChannel, ConnectConfig } from "ssh2";
+import type { Transport, TransportProcess, TransportSpawnOptions } from "./types";
+
+export interface SshTransportOptions extends ConnectConfig {
+  target?: string;
+  clientFactory?: () => Client;
+}
+
+export class SshTransport implements Transport {
+  readonly type = "ssh";
+
+  private readonly config: ConnectConfig;
+  private readonly clientFactory: () => Client;
+  private client: Client | null = null;
+  private connected = false;
+  private connecting: Promise<void> | null = null;
+
+  constructor(opts: SshTransportOptions) {
+    const { target, clientFactory, ...config } = opts;
+    this.config = {
+      ...config,
+      host: config.host || target,
+      keepaliveInterval: config.keepaliveInterval ?? 15000,
+      keepaliveCountMax: config.keepaliveCountMax ?? 3,
+    };
+    this.clientFactory = clientFactory || (() => new Client());
+  }
+
+  private async ensureConnected(): Promise<Client> {
+    if (this.connected && this.client) return this.client;
+    if (this.connecting) {
+      await this.connecting;
+      return this.client!;
+    }
+    this.connecting = this.doConnect();
+    await this.connecting;
+    this.connecting = null;
+    return this.client!;
+  }
+
+  private doConnect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const client = this.clientFactory();
+      client.once("error", (err) => {
+        this.connected = false;
+        this.client = null;
+        reject(err);
+      });
+      client.once("ready", () => {
+        this.client = client;
+        this.connected = true;
+        // Handle unexpected disconnects
+        client.once("close", () => {
+          this.connected = false;
+          this.client = null;
+        });
+        client.once("end", () => {
+          this.connected = false;
+          this.client = null;
+        });
+        resolve();
+      });
+      client.connect(this.config);
+    });
+  }
+
+  async spawn(cmd: string, args: string[], opts: TransportSpawnOptions = {}): Promise<TransportProcess> {
+    const client = await this.ensureConnected();
+    const command = buildRemoteCommand(cmd, args, opts.cwd, opts.env);
+
+    return new Promise((resolve, reject) => {
+      client.exec(command, (err, channel) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve(channelProcess(channel));
+      });
+    });
+  }
+
+  async healthcheck(): Promise<{ ok: boolean; detail?: string }> {
+    try {
+      const client = await this.ensureConnected();
+      return new Promise((resolve) => {
+        client.exec("echo ok", (err, channel) => {
+          if (err) {
+            resolve({ ok: false, detail: err.message });
+            return;
+          }
+          let output = "";
+          channel.on("data", (chunk: Buffer) => { output += chunk.toString(); });
+          channel.on("close", () => {
+            resolve({ ok: output.trim() === "ok", detail: output.trim() || "no output" });
+          });
+        });
+      });
+    } catch (err: any) {
+      return { ok: false, detail: err.message };
+    }
+  }
+
+  close() {
+    if (this.client) {
+      this.client.end();
+      this.client = null;
+      this.connected = false;
+    }
+  }
+}
+
+function channelProcess(channel: ClientChannel): TransportProcess {
+  let stdoutController: ReadableStreamDefaultController<Uint8Array>;
+  let stderrController: ReadableStreamDefaultController<Uint8Array>;
+  let resolveExit: (code: number) => void;
+
+  const exited = new Promise<number>((resolve) => {
+    resolveExit = resolve;
+  });
+
+  const stdout = new ReadableStream<Uint8Array>({
+    start(controller) {
+      stdoutController = controller;
+    },
+  });
+  const stderr = new ReadableStream<Uint8Array>({
+    start(controller) {
+      stderrController = controller;
+    },
+  });
+
+  channel.on("data", (chunk: Buffer | string) => {
+    stdoutController.enqueue(toBytes(chunk));
+  });
+  channel.stderr.on("data", (chunk: Buffer | string) => {
+    stderrController.enqueue(toBytes(chunk));
+  });
+  channel.on("close", (code: number | null | undefined) => {
+    stdoutController.close();
+    stderrController.close();
+    resolveExit(code ?? 0);
+  });
+
+  return {
+    pid: 0,
+    stdin: {
+      write(data: string) {
+        channel.write(data);
+      },
+    },
+    stdout,
+    stderr,
+    exited,
+    kill() {
+      channel.close();
+    },
+  };
+}
+
+function buildRemoteCommand(cmd: string, args: string[], cwd?: string, env?: Record<string, string>): string {
+  const envPrefix = env
+    ? Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`).join(" ") + " "
+    : "";
+  const command = envPrefix + [cmd, ...args].map(shellQuote).join(" ");
+  return cwd ? `cd ${shellQuote(cwd)} && ${command}` : command;
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function toBytes(chunk: Buffer | string): Uint8Array {
+  return typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+}

package/src/transport/types.ts

@@ -0,0 +1,20 @@
+export interface Transport {
+  readonly type: "local-pty" | "ssh" | "http-api";
+  spawn(cmd: string, args: string[], opts?: TransportSpawnOptions): Promise<TransportProcess>;
+  healthcheck?(): Promise<{ ok: boolean; detail?: string }>;
+  close?(): void;
+}
+
+export interface TransportSpawnOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface TransportProcess {
+  pid: number;
+  stdin: { write(data: string): void };
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  kill(): void;
+}