@poncho-ai/cli 0.37.0 → 0.38.1

package/src/logger.ts

@@ -0,0 +1,9 @@
+export {
+  createLogger,
+  setLogLevel,
+  formatError,
+  url,
+  muted,
+  num,
+  type Logger,
+} from "@poncho-ai/sdk";

package/src/mcp-commands.ts

@@ -0,0 +1,283 @@
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import {
+  LocalMcpBridge,
+  loadPonchoConfig,
+} from "@poncho-ai/harness";
+import dotenv from "dotenv";
+import {
+  writeConfigFile,
+  ensureEnvPlaceholder,
+  removeEnvPlaceholder,
+} from "./scaffolding.js";
+
+const normalizeMcpName = (entry: { url?: string; name?: string }): string =>
+  entry.name ?? entry.url ?? `mcp_${Date.now()}`;
+
+export { normalizeMcpName };
+
+export const mcpAdd = async (
+  workingDir: string,
+  options: {
+    url?: string;
+    name?: string;
+    envVars?: string[];
+    authBearerEnv?: string;
+    headers?: string[];
+  },
+): Promise<void> => {
+  const config = (await loadPonchoConfig(workingDir)) ?? { mcp: [] };
+  const mcp = [...(config.mcp ?? [])];
+  if (!options.url) {
+    throw new Error("Remote MCP only: provide --url for a remote MCP server.");
+  }
+  if (options.url.startsWith("ws://") || options.url.startsWith("wss://")) {
+    throw new Error("WebSocket MCP URLs are no longer supported. Use an HTTP MCP endpoint.");
+  }
+  if (!options.url.startsWith("http://") && !options.url.startsWith("https://")) {
+    throw new Error("Invalid MCP URL. Expected http:// or https://.");
+  }
+  const parsedHeaders: Record<string, string> | undefined =
+    options.headers && options.headers.length > 0
+      ? Object.fromEntries(
+          options.headers.map((h) => {
+            const idx = h.indexOf(":");
+            if (idx < 1) {
+              throw new Error(`Invalid header format "${h}". Expected "Name: value".`);
+            }
+            return [h.slice(0, idx).trim(), h.slice(idx + 1).trim()];
+          }),
+        )
+      : undefined;
+  const serverName = options.name ?? normalizeMcpName({ url: options.url });
+  mcp.push({
+    name: serverName,
+    url: options.url,
+    env: options.envVars ?? [],
+    auth: options.authBearerEnv
+      ? {
+          type: "bearer",
+          tokenEnv: options.authBearerEnv,
+        }
+      : undefined,
+    headers: parsedHeaders,
+  });
+
+  await writeConfigFile(workingDir, { ...config, mcp });
+  let envSeedMessage: string | undefined;
+  if (options.authBearerEnv) {
+    const envPath = resolve(workingDir, ".env");
+    const envExamplePath = resolve(workingDir, ".env.example");
+    const addedEnv = await ensureEnvPlaceholder(envPath, options.authBearerEnv);
+    const addedEnvExample = await ensureEnvPlaceholder(envExamplePath, options.authBearerEnv);
+    if (addedEnv || addedEnvExample) {
+      envSeedMessage = `Added ${options.authBearerEnv}= to ${addedEnv ? ".env" : ""}${addedEnv && addedEnvExample ? " and " : ""}${addedEnvExample ? ".env.example" : ""}.`;
+    }
+  }
+  const nextSteps: string[] = [];
+  let step = 1;
+  if (options.authBearerEnv) {
+    nextSteps.push(`  ${step}) Set token in .env: ${options.authBearerEnv}=...`);
+    step += 1;
+  }
+  nextSteps.push(`  ${step}) Discover tools: poncho mcp tools list ${serverName}`);
+  step += 1;
+  nextSteps.push(`  ${step}) Select tools:   poncho mcp tools select ${serverName}`);
+  step += 1;
+  nextSteps.push(`  ${step}) Verify config:  poncho mcp list`);
+  process.stdout.write(
+    [
+      `MCP server added: ${serverName}`,
+      ...(envSeedMessage ? [envSeedMessage] : []),
+      "Next steps:",
+      ...nextSteps,
+      "",
+    ].join("\n"),
+  );
+};
+
+export const mcpList = async (workingDir: string): Promise<void> => {
+  const config = await loadPonchoConfig(workingDir);
+  const mcp = config?.mcp ?? [];
+  if (mcp.length === 0) {
+    process.stdout.write("No MCP servers configured.\n");
+    return;
+  }
+  process.stdout.write("Configured MCP servers:\n");
+  for (const entry of mcp) {
+    const auth =
+      entry.auth?.type === "bearer" ? `auth=bearer:${entry.auth.tokenEnv}` : "auth=none";
+    const headerKeys = entry.headers ? Object.keys(entry.headers) : [];
+    const headerInfo = headerKeys.length > 0 ? `, headers=${headerKeys.join(",")}` : "";
+    process.stdout.write(
+      `- ${entry.name ?? entry.url} (remote: ${entry.url}, ${auth}${headerInfo})\n`,
+    );
+  }
+};
+
+export const mcpRemove = async (workingDir: string, name: string): Promise<void> => {
+  const config = (await loadPonchoConfig(workingDir)) ?? { mcp: [] };
+  const before = config.mcp ?? [];
+  const removed = before.filter((entry) => normalizeMcpName(entry) === name);
+  const filtered = before.filter((entry) => normalizeMcpName(entry) !== name);
+  await writeConfigFile(workingDir, { ...config, mcp: filtered });
+  const removedTokenEnvNames = new Set(
+    removed
+      .map((entry) =>
+        entry.auth?.type === "bearer" ? entry.auth.tokenEnv?.trim() ?? "" : "",
+      )
+      .filter((value) => value.length > 0),
+  );
+  const stillUsedTokenEnvNames = new Set(
+    filtered
+      .map((entry) =>
+        entry.auth?.type === "bearer" ? entry.auth.tokenEnv?.trim() ?? "" : "",
+      )
+      .filter((value) => value.length > 0),
+  );
+  const removedFromExample: string[] = [];
+  for (const tokenEnv of removedTokenEnvNames) {
+    if (stillUsedTokenEnvNames.has(tokenEnv)) {
+      continue;
+    }
+    const changed = await removeEnvPlaceholder(resolve(workingDir, ".env.example"), tokenEnv);
+    if (changed) {
+      removedFromExample.push(tokenEnv);
+    }
+  }
+  process.stdout.write(`Removed MCP server: ${name}\n`);
+  if (removedFromExample.length > 0) {
+    process.stdout.write(
+      `Removed unused token placeholder(s) from .env.example: ${removedFromExample.join(", ")}\n`,
+    );
+  }
+};
+
+const resolveMcpEntry = async (
+  workingDir: string,
+  serverName: string,
+): Promise<{ config: import("@poncho-ai/harness").PonchoConfig; index: number }> => {
+  const config = (await loadPonchoConfig(workingDir)) ?? { mcp: [] };
+  const entries = config.mcp ?? [];
+  const index = entries.findIndex((entry) => normalizeMcpName(entry) === serverName);
+  if (index < 0) {
+    throw new Error(`MCP server "${serverName}" is not configured.`);
+  }
+  return { config, index };
+};
+
+export { resolveMcpEntry };
+
+const discoverMcpTools = async (
+  workingDir: string,
+  serverName: string,
+): Promise<string[]> => {
+  dotenv.config({ path: resolve(workingDir, ".env") });
+  const { config, index } = await resolveMcpEntry(workingDir, serverName);
+  const entry = (config.mcp ?? [])[index];
+  const bridge = new LocalMcpBridge({ mcp: [entry] });
+  try {
+    await bridge.startLocalServers();
+    await bridge.discoverTools();
+    return bridge.listDiscoveredTools(normalizeMcpName(entry));
+  } finally {
+    await bridge.stopLocalServers();
+  }
+};
+
+export { discoverMcpTools };
+
+export const mcpToolsList = async (
+  workingDir: string,
+  serverName: string,
+): Promise<void> => {
+  const discovered = await discoverMcpTools(workingDir, serverName);
+  if (discovered.length === 0) {
+    process.stdout.write(`No tools discovered for MCP server "${serverName}".\n`);
+    return;
+  }
+  process.stdout.write(`Discovered tools for "${serverName}":\n`);
+  for (const tool of discovered) {
+    process.stdout.write(`- ${tool}\n`);
+  }
+};
+
+export const mcpToolsSelect = async (
+  workingDir: string,
+  serverName: string,
+  options: {
+    all?: boolean;
+    toolsCsv?: string;
+  },
+): Promise<void> => {
+  const discovered = await discoverMcpTools(workingDir, serverName);
+  if (discovered.length === 0) {
+    process.stdout.write(`No tools discovered for MCP server "${serverName}".\n`);
+    return;
+  }
+  let selected: string[] = [];
+  if (options.all) {
+    selected = [...discovered];
+  } else if (options.toolsCsv && options.toolsCsv.trim().length > 0) {
+    const requested = options.toolsCsv
+      .split(",")
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0);
+    selected = discovered.filter((tool) => requested.includes(tool));
+  } else {
+    process.stdout.write(`Discovered tools for "${serverName}":\n`);
+    discovered.forEach((tool, idx) => {
+      process.stdout.write(`${idx + 1}. ${tool}\n`);
+    });
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question(
+      "Enter comma-separated tool numbers/names to allow (or * for all): ",
+    );
+    rl.close();
+    const raw = answer.trim();
+    if (raw === "*") {
+      selected = [...discovered];
+    } else {
+      const tokens = raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+      const fromIndex = tokens
+        .map((token) => Number.parseInt(token, 10))
+        .filter((value) => !Number.isNaN(value))
+        .map((index) => discovered[index - 1])
+        .filter((value): value is string => typeof value === "string");
+      const byName = discovered.filter((tool) => tokens.includes(tool));
+      selected = [...new Set([...fromIndex, ...byName])];
+    }
+  }
+  if (selected.length === 0) {
+    throw new Error("No valid tools selected.");
+  }
+  const includePatterns =
+    selected.length === discovered.length
+      ? [`${serverName}/*`]
+      : selected.sort();
+  process.stdout.write(`Selected MCP tools: ${includePatterns.join(", ")}\n`);
+  process.stdout.write(
+    "\nRequired next step: add MCP intent in AGENT.md or SKILL.md allowed-tools. Without this, these MCP tools will not be registered for the model.\n",
+  );
+  process.stdout.write(
+    "\nOption A: AGENT.md (global fallback intent)\n" +
+      "Paste this into AGENT.md frontmatter:\n" +
+      "---\n" +
+      "allowed-tools:\n" +
+      includePatterns.map((tool) => `  - mcp:${tool}`).join("\n") +
+      "\n---\n",
+  );
+  process.stdout.write(
+    "\nOption B: SKILL.md (only when that skill is activated)\n" +
+      "Paste this into SKILL.md frontmatter:\n" +
+      "---\n" +
+      "allowed-tools:\n" +
+      includePatterns.map((tool) => `  - mcp:${tool}`).join("\n") +
+      "\napproval-required:\n" +
+      includePatterns.map((tool) => `  - mcp:${tool}`).join("\n") +
+      "\n---\n",
+  );
+};

package/src/project-init.ts

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { generateAgentId } from "@poncho-ai/harness";
+import {
+  AGENT_TEMPLATE,
+  ENV_TEMPLATE,
+  GITIGNORE_TEMPLATE,
+  PACKAGE_TEMPLATE,
+  README_TEMPLATE,
+  SKILL_TEMPLATE,
+  SKILL_TOOL_TEMPLATE,
+  TEST_TEMPLATE,
+} from "./templates.js";
+import {
+  ensureFile,
+  renderConfigFile,
+  scaffoldDeployTarget,
+} from "./scaffolding.js";
+import { runPnpmInstall } from "./skills.js";
+import {
+  runInitOnboarding,
+  type InitOnboardingOptions,
+} from "./init-onboarding.js";
+import {
+  initializeOnboardingMarker,
+} from "./init-feature-context.js";
+
+const gitInit = (cwd: string): Promise<boolean> =>
+  new Promise((resolve) => {
+    const child = spawn("git", ["init"], { cwd, stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("close", (code) => resolve(code === 0));
+  });
+
+export const initProject = async (
+  projectName: string,
+  options?: {
+    workingDir?: string;
+    onboarding?: InitOnboardingOptions;
+    envExampleOverride?: string;
+  },
+): Promise<void> => {
+  const baseDir = options?.workingDir ?? process.cwd();
+  const projectDir = resolve(baseDir, projectName);
+  await mkdir(projectDir, { recursive: true });
+
+  const onboardingOptions: InitOnboardingOptions = options?.onboarding ?? {
+    yes: true,
+    interactive: false,
+  };
+  const onboarding = await runInitOnboarding(onboardingOptions);
+  const agentId = generateAgentId();
+
+  const G = "\x1b[32m";
+  const D = "\x1b[2m";
+  const B = "\x1b[1m";
+  const CY = "\x1b[36m";
+  const YW = "\x1b[33m";
+  const R = "\x1b[0m";
+
+  process.stdout.write("\n");
+
+  const scaffoldFiles: Array<{ path: string; content: string }> = [
+    {
+      path: "AGENT.md",
+      content: AGENT_TEMPLATE(projectName, agentId, {
+        modelProvider: onboarding.agentModel.provider,
+        modelName: onboarding.agentModel.name,
+      }),
+    },
+    { path: "poncho.config.js", content: renderConfigFile(onboarding.config) },
+    { path: "package.json", content: await PACKAGE_TEMPLATE(projectName, projectDir) },
+    { path: "README.md", content: README_TEMPLATE(projectName) },
+    { path: ".env.example", content: options?.envExampleOverride ?? onboarding.envExample ?? ENV_TEMPLATE },
+    { path: ".gitignore", content: GITIGNORE_TEMPLATE },
+    { path: "tests/basic.yaml", content: TEST_TEMPLATE },
+    { path: "skills/starter/SKILL.md", content: SKILL_TEMPLATE },
+    { path: "skills/starter/scripts/starter-echo.ts", content: SKILL_TOOL_TEMPLATE },
+  ];
+  if (onboarding.envFile) {
+    scaffoldFiles.push({ path: ".env", content: onboarding.envFile });
+  }
+
+  for (const file of scaffoldFiles) {
+    await ensureFile(resolve(projectDir, file.path), file.content);
+    process.stdout.write(`  ${D}+${R} ${D}${file.path}${R}\n`);
+  }
+
+  if (onboarding.deployTarget !== "none") {
+    const deployFiles = await scaffoldDeployTarget(projectDir, onboarding.deployTarget);
+    for (const filePath of deployFiles) {
+      process.stdout.write(`  ${D}+${R} ${D}${filePath}${R}\n`);
+    }
+  }
+
+  await initializeOnboardingMarker(projectDir, {
+    allowIntro: !(onboardingOptions.yes ?? false),
+  });
+
+  process.stdout.write("\n");
+
+  // Install dependencies so subsequent commands (e.g. `poncho add`) succeed.
+  try {
+    await runPnpmInstall(projectDir);
+    process.stdout.write(`  ${G}✓${R} ${D}Installed dependencies${R}\n`);
+  } catch {
+    process.stdout.write(
+      `  ${YW}!${R} Could not install dependencies — run ${D}pnpm install${R} manually\n`,
+    );
+  }
+
+  const gitOk = await gitInit(projectDir);
+  if (gitOk) {
+    process.stdout.write(`  ${G}✓${R} ${D}Initialized git${R}\n`);
+  }
+
+  process.stdout.write(`  ${G}✓${R} ${B}${projectName}${R} is ready\n`);
+  process.stdout.write("\n");
+  process.stdout.write(`  ${B}Get started${R}\n`);
+  process.stdout.write("\n");
+  process.stdout.write(`    ${D}$${R} cd ${projectName}\n`);
+  process.stdout.write("\n");
+  process.stdout.write(`    ${CY}Web UI${R}          ${D}$${R} poncho dev\n`);
+  process.stdout.write(`    ${CY}CLI interactive${R}  ${D}$${R} poncho run --interactive\n`);
+  process.stdout.write("\n");
+  if (onboarding.envNeedsUserInput) {
+    process.stdout.write(
+      `  ${YW}!${R} Make sure you add your keys to the ${B}.env${R} file.\n`,
+    );
+  }
+  process.stdout.write(`  ${D}The agent will introduce itself on your first session.${R}\n`);
+  process.stdout.write("\n");
+};
+
+export const updateAgentGuidance = async (workingDir: string): Promise<boolean> => {
+  const agentPath = resolve(workingDir, "AGENT.md");
+  const content = await readFile(agentPath, "utf8");
+  const guidanceSectionPattern =
+    /\n## Configuration Assistant Context[\s\S]*?(?=\n## |\n# |$)|\n## Skill Authoring Guidance[\s\S]*?(?=\n## |\n# |$)/g;
+  const normalized = content.replace(/\s+$/g, "");
+  const updated = normalized.replace(guidanceSectionPattern, "").replace(/\n{3,}/g, "\n\n");
+  if (updated === normalized) {
+    process.stdout.write("AGENT.md does not contain deprecated embedded local guidance.\n");
+    return false;
+  }
+  await writeFile(agentPath, `${updated}\n`, "utf8");
+  process.stdout.write("Removed deprecated embedded local guidance from AGENT.md.\n");
+  return true;
+};

package/src/run-commands.ts

@@ -0,0 +1,145 @@
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import {
+  AgentHarness,
+  TelemetryEmitter,
+  createConversationStore,
+  createConversationStoreFromEngine,
+  createUploadStore,
+  ensureAgentIdentity,
+  loadPonchoConfig,
+  resolveStateConfig,
+  type PonchoConfig,
+  type ConversationStore,
+} from "@poncho-ai/harness";
+import type { FileInput, RunInput } from "@poncho-ai/sdk";
+import dotenv from "dotenv";
+import { extToMime, resolveHarnessEnvironment } from "./http-utils.js";
+
+export const runOnce = async (
+  task: string,
+  options: {
+    params: Record<string, string>;
+    json: boolean;
+    filePaths: string[];
+    workingDir?: string;
+  },
+): Promise<void> => {
+  const workingDir = options.workingDir ?? process.cwd();
+  dotenv.config({ path: resolve(workingDir, ".env") });
+  const config = await loadPonchoConfig(workingDir);
+  const uploadStore = await createUploadStore(config?.uploads, workingDir);
+  const harness = new AgentHarness({ workingDir, uploadStore });
+  const telemetry = new TelemetryEmitter(config?.telemetry);
+  await harness.initialize();
+
+  const fileInputs: FileInput[] = await Promise.all(
+    options.filePaths.map(async (filePath) => {
+      const absPath = resolve(workingDir, filePath);
+      const buf = await readFile(absPath);
+      const ext = absPath.split(".").pop()?.toLowerCase() ?? "";
+      return {
+        data: buf.toString("base64"),
+        mediaType: extToMime(ext),
+        filename: basename(filePath),
+      };
+    }),
+  );
+
+  const input: RunInput = {
+    task,
+    parameters: options.params,
+    files: fileInputs.length > 0 ? fileInputs : undefined,
+  };
+
+  if (options.json) {
+    const output = await harness.runToCompletion(input);
+    for (const event of output.events) {
+      await telemetry.emit(event);
+    }
+    process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    return;
+  }
+
+  for await (const event of harness.runWithTelemetry(input)) {
+    await telemetry.emit(event);
+    if (event.type === "model:chunk") {
+      process.stdout.write(event.content);
+    }
+    if (event.type === "run:error") {
+      process.stderr.write(`\nError: ${event.error.message}\n`);
+    }
+    if (event.type === "run:completed") {
+      process.stdout.write("\n");
+    }
+    if (event.type === "run:cancelled") {
+      process.stdout.write("\n");
+      process.stderr.write("Run cancelled.\n");
+    }
+  }
+};
+
+export const runInteractive = async (
+  workingDir: string,
+  params: Record<string, string>,
+): Promise<void> => {
+  dotenv.config({ path: resolve(workingDir, ".env") });
+  const config = await loadPonchoConfig(workingDir);
+
+  const uploadStore = await createUploadStore(config?.uploads, workingDir);
+  const harness = new AgentHarness({
+    workingDir,
+    environment: resolveHarnessEnvironment(),
+    uploadStore,
+  });
+  await harness.initialize();
+  const identity = await ensureAgentIdentity(workingDir);
+  try {
+    const { runInteractiveInk } = await import("./run-interactive-ink.js");
+    await (
+      runInteractiveInk as (input: {
+        harness: AgentHarness;
+        params: Record<string, string>;
+        workingDir: string;
+        config?: PonchoConfig;
+        conversationStore: ConversationStore;
+      }) => Promise<void>
+    )({
+      harness,
+      params,
+      workingDir,
+      config,
+      conversationStore: (() => {
+        if (!harness.storageEngine) {
+          process.stderr.write(
+            "[poncho] WARNING: harness.storageEngine is undefined. " +
+              "This usually means an outdated @poncho-ai/harness (< 0.37.0) is installed. " +
+              "Falling back to in-memory storage — conversations will NOT be persisted. " +
+              "Fix: `pnpm up @poncho-ai/harness@latest` or add a pnpm.overrides entry to force resolution.\n",
+          );
+          return createConversationStore(resolveStateConfig(config), { workingDir, agentId: identity.id });
+        }
+        return createConversationStoreFromEngine(harness.storageEngine);
+      })(),
+    });
+  } finally {
+    await harness.shutdown();
+  }
+};
+
+export const listTools = async (workingDir: string): Promise<void> => {
+  dotenv.config({ path: resolve(workingDir, ".env") });
+  const harness = new AgentHarness({ workingDir });
+  await harness.initialize();
+  const tools = harness.listTools();
+
+  if (tools.length === 0) {
+    process.stdout.write("No tools registered.\n");
+    return;
+  }
+
+  process.stdout.write("Available tools:\n");
+  for (const tool of tools) {
+    process.stdout.write(`- ${tool.name}: ${tool.description}\n`);
+  }
+};