@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/cli/init.ts

@@ -0,0 +1,260 @@
+/**
+ * `pyric init` — scaffold a pyric project (v2, agent-first).
+ *
+ *   pyric init [dir] [--name N] [--template web|node|static|chat] [--force] [--json]
+ *              [--deps vendor|npm] [--pyric-version X]
+ *
+ * Scaffold templates and file writing live in `create-pyric`. This module
+ * adds standalone-binary vendor mode (`--deps vendor`) and `pyric vendor`.
+ */
+
+import { writeFile, readFile, mkdir, access } from 'node:fs/promises';
+import { join, basename, resolve } from 'node:path';
+import type { ParsedArgs } from './parse-args.js';
+import {
+  TEMPLATES,
+  TEMPLATE_NAMES,
+  applyDepsMode,
+  isTemplateName,
+  mergeIntoExistingPackageJson,
+  packageJsonFor,
+  normalizeBoolFlags as normalizeScaffoldBoolFlags,
+  runScaffold,
+  type ScaffoldTemplate,
+  type DepsMode,
+  type PackageJsonMerge,
+  type TemplateName,
+} from 'create-pyric';
+import {
+  isStandalone,
+  hasEmbeddedTarballs,
+  embeddedVersion,
+  materializeVendorTarballs,
+} from '../serve/standalone-assets.js';
+
+export type { DepsMode, ScaffoldTemplate };
+export { TEMPLATES, applyDepsMode, mergeIntoExistingPackageJson };
+
+export function resolveDepsMode(
+  parsed: ParsedArgs,
+  env: Record<string, string | undefined> = process.env,
+): DepsMode {
+  const flag = parsed.flags.get('deps');
+  if (flag === 'vendor' || flag === 'npm') return flag;
+  const fromEnv = env.PYRIC_INIT_DEPS;
+  if (fromEnv === 'vendor' || fromEnv === 'npm') return fromEnv;
+  return isStandalone() && hasEmbeddedTarballs() ? 'vendor' : 'npm';
+}
+
+export interface InitResult {
+  template: TemplateName;
+  dir: string;
+  depsMode: DepsMode;
+  created: string[];
+  merged: string[];
+  skipped: string[];
+  conflicts: Array<{ key: string; existing: unknown; wanted: unknown }>;
+  nextSteps: string[];
+}
+
+export interface InitDeps {
+  writeFile?: typeof writeFile;
+  readFile?: typeof readFile;
+  mkdir?: typeof mkdir;
+  exists?: (path: string) => Promise<boolean>;
+  cwd?: string;
+  stdout?: { write(s: string): void };
+  stderr?: { write(s: string): void };
+}
+
+async function defaultExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeBoolFlags(parsed: ParsedArgs): void {
+  normalizeScaffoldBoolFlags(parsed.flags, parsed.positional);
+}
+
+export async function runInit(parsed: ParsedArgs, deps: InitDeps = {}): Promise<number> {
+  const err = deps.stderr ?? process.stderr;
+
+  normalizeBoolFlags(parsed);
+
+  const templateFlag = parsed.flags.get('template');
+  const templateName = typeof templateFlag === 'string' ? templateFlag : 'web';
+  if (!isTemplateName(templateName)) {
+    err.write(
+      `pyric init: unknown template '${templateName}' (expected ${TEMPLATE_NAMES.join('|')})\n`,
+    );
+    return 1;
+  }
+
+  const depsFlag = parsed.flags.get('deps');
+  if (depsFlag !== undefined && depsFlag !== 'vendor' && depsFlag !== 'npm') {
+    err.write(`pyric init: --deps must be 'vendor' or 'npm' (got '${String(depsFlag)}')\n`);
+    return 1;
+  }
+  const depsMode = resolveDepsMode(parsed);
+  if (depsMode === 'vendor' && !(isStandalone() && hasEmbeddedTarballs())) {
+    err.write(
+      `pyric init: --deps vendor needs the standalone binary (with embedded packages). Use --deps npm.\n`,
+    );
+    return 1;
+  }
+
+  const versionFlag = parsed.flags.get('pyric-version');
+  const pinVersion =
+    typeof versionFlag === 'string' && versionFlag.length > 0
+      ? versionFlag
+      : isStandalone()
+        ? embeddedVersion()
+        : null;
+
+  const cwd = deps.cwd ?? process.cwd();
+  const dir = parsed.positional[0] ? resolve(cwd, parsed.positional[0]) : cwd;
+  const nameFlag = parsed.flags.get('name');
+  const projectName =
+    typeof nameFlag === 'string' && nameFlag.length > 0 ? nameFlag : basename(dir);
+
+  const template = TEMPLATES[templateName];
+  let effective = template;
+  const preCreated: string[] = [];
+
+  if (depsMode === 'vendor') {
+    try {
+      const vendorSpecs = await materializeVendorTarballs(dir);
+      for (const spec of Object.values(vendorSpecs)) preCreated.push(spec.replace(/^file:/, ''));
+      effective = applyDepsMode(template, 'vendor', { vendorSpecs });
+    } catch (e) {
+      err.write(
+        `pyric init: failed to vendor packages: ${e instanceof Error ? e.message : String(e)}\n`,
+      );
+      return 2;
+    }
+  } else {
+    effective = applyDepsMode(template, 'npm', { version: pinVersion });
+  }
+
+  return runScaffold(
+    {
+      dir,
+      template: templateName,
+      name: projectName,
+      force: parsed.flags.get('force') === true,
+      json: parsed.flags.get('json') === true,
+      depsMode,
+      effectiveTemplate: effective,
+      pinVersion,
+      commandLabel: 'pyric init',
+      preCreated,
+    },
+    deps,
+  );
+}
+
+export const VENDOR_TEMPLATE: ScaffoldTemplate = {
+  scripts: {},
+  dependencies: {},
+  devDependencies: { '@pyric/cli': '*' },
+  dirs: [],
+  files: () => [],
+  nextSteps: [],
+};
+
+/**
+ * `pyric vendor [dir]` — lay vendored tarballs into an existing project.
+ * Standalone-binary only.
+ */
+export async function runVendor(parsed: ParsedArgs, deps: InitDeps = {}): Promise<number> {
+  const out = deps.stdout ?? process.stdout;
+  const err = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+  const write = deps.writeFile ?? writeFile;
+  const read = deps.readFile ?? readFile;
+  const mk = deps.mkdir ?? mkdir;
+  const exists = deps.exists ?? defaultExists;
+
+  normalizeBoolFlags(parsed);
+  const json = parsed.flags.get('json') === true;
+  const report = json ? err : out;
+
+  if (!(isStandalone() && hasEmbeddedTarballs())) {
+    err.write(
+      'pyric vendor: needs the standalone binary (it carries the embedded pyric / ' +
+        '@pyric/cli tarballs). A monorepo/npm checkout has nothing to vendor; depend ' +
+        'on the packages directly instead.\n',
+    );
+    return 1;
+  }
+
+  const dir = parsed.positional[0] ? resolve(cwd, parsed.positional[0]) : cwd;
+  const projectName = basename(dir);
+
+  let vendorSpecs: Record<string, string>;
+  try {
+    await mk(dir, { recursive: true });
+    vendorSpecs = await materializeVendorTarballs(dir);
+  } catch (e) {
+    err.write(
+      `pyric vendor: failed to lay down vendor tarballs: ${e instanceof Error ? e.message : String(e)}\n`,
+    );
+    return 2;
+  }
+
+  const effective = applyDepsMode(VENDOR_TEMPLATE, 'vendor', { vendorSpecs });
+
+  const pkgPath = join(dir, 'package.json');
+  let added: string[];
+  let conflicts: PackageJsonMerge['conflicts'] = [];
+  let created = false;
+  try {
+    if (await exists(pkgPath)) {
+      const raw = String(await read(pkgPath, 'utf-8'));
+      const merge = mergeIntoExistingPackageJson(raw, projectName, effective);
+      conflicts = merge.conflicts;
+      added = merge.added;
+      if (!merge.unchanged) await write(pkgPath, merge.contents, 'utf-8');
+    } else {
+      await write(pkgPath, packageJsonFor(projectName, effective), 'utf-8');
+      added = [];
+      created = true;
+    }
+  } catch (e) {
+    err.write(
+      `pyric vendor: failed to update package.json: ${e instanceof Error ? e.message : String(e)}\n`,
+    );
+    return 2;
+  }
+
+  report.write(
+    `pyric vendor: vendored ${Object.keys(vendorSpecs).join(', ')} into ${join(dir, 'vendor')}\n`,
+  );
+  for (const spec of Object.values(vendorSpecs)) {
+    report.write(`  + ${spec.replace(/^file:/, '')}\n`);
+  }
+  if (created) {
+    report.write('  + package.json (created)\n');
+  } else if (added.length === 0) {
+    report.write('  · package.json already had the vendored deps\n');
+  } else {
+    report.write(`  ~ package.json (added: ${added.join(', ')})\n`);
+  }
+  for (const c of conflicts) {
+    report.write(
+      `  · ${c.key}: kept ${JSON.stringify(c.existing)} (pyric would set ${JSON.stringify(c.wanted)})\n`,
+    );
+  }
+  report.write('\n  next: run `bun install` (or npm/pnpm install) to install the vendored packages.\n');
+
+  if (json) {
+    out.write(
+      JSON.stringify({ dir, vendored: Object.keys(vendorSpecs), added, conflicts, created }) + '\n',
+    );
+  }
+  return 0;
+}

package/src/cli/mcp-proxy.ts

@@ -0,0 +1,196 @@
+/**
+ * `pyric mcp-proxy` — a stdio MCP server that relays to a RUNNING
+ * `pyric dev --bridge`'s HTTP MCP endpoint.
+ *
+ * Why this exists: a Claude Code plugin can only declare a STATIC MCP URL in
+ * `.mcp.json`, but serve's endpoint is `http://localhost:<PORT>/__pyric/mcp`
+ * with a runtime port (scan-forward / AirPlay). So the plugin declares a
+ * STDIO server that runs this proxy; the proxy discovers the live serve and
+ * forwards the protocol. No manual `claude mcp add`, no fixed port.
+ * (design rationale)
+ *
+ * Relay is at the TRANSPORT level via the MCP SDK's own transports — we do
+ * NOT re-implement JSON-RPC/SSE/session framing. `StdioServerTransport`
+ * talks to Claude Code; `StreamableHTTPClientTransport` talks to serve; each
+ * transport's `onmessage` is piped to the other's `send`.
+ *
+ * Two hardening layers sit on top of that pipe:
+ *
+ *   IDENTITY — the discovery pointer records the bridge's `instanceId`; the
+ *     proxy accepts a server only if its `/health` reports the SAME id. Two
+ *     sandboxes can collide on one port across loopback families (IPv4 `*:P`
+ *     + IPv6 `[::1]:P`); without this, the proxy locks onto whichever family
+ *     answers first while the browser is on the other — split-brain.
+ *   TIMEOUT — every relayed request is failed with a JSON-RPC error after
+ *     REQUEST_TIMEOUT_MS instead of hanging Claude Code forever (a killed
+ *     server can leave a half-open keep-alive socket that never FINs). A
+ *     `settled` set swallows a late real response so the client never sees a
+ *     duplicate after the timeout already failed the call.
+ *
+ * (Auto-reconnect on serve restart is deliberately NOT here — it needs a
+ * live-restart test harness; the timeout makes a stale connection fail fast,
+ * and the user restarts the MCP connection.)
+ *
+ * Discovery preference: the `.pyric/serve.json` pointer serve writes in the
+ * project cwd (exact + project-correct), then a health probe across the scan
+ * window as a fallback. Degrades LEGIBLY: if no serve is found, or the pointed
+ * server's identity can't be matched, we report it — never a silent hang.
+ */
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { ParsedArgs } from './parse-args.js';
+import { discoverServe, SCAN_PORTS } from '../serve/discovery.js';
+
+// Discovery (pointer + identity-pinned health probing) lives in
+// `serve/discovery.ts` — shared with the Node remote-sandbox client
+// (`remote/index.ts`). Re-exported here for existing consumers.
+export { discoverServe } from '../serve/discovery.js';
+
+/** A relayed request with no response within this window is failed with a
+ *  JSON-RPC error rather than hanging forever. Sits just above the bridge's
+ *  own 30s `callTimeoutMs` so a legitimately-slow tool still completes. */
+const REQUEST_TIMEOUT_MS = 35_000;
+/** JSON-RPC error code for proxy-synthesized failures (server-defined range). */
+const PROXY_ERROR_CODE = -32001;
+
+// ── JSON-RPC shape helpers (relay-level; no SDK runtime import) ──────────────
+function msgId(m: JSONRPCMessage): string | number | null {
+  return 'id' in m && (m as { id?: unknown }).id != null ? (m as { id: string | number }).id : null;
+}
+/** A request expects a response (has both `id` and `method`). */
+function isRequest(m: JSONRPCMessage): boolean {
+  return 'method' in m && msgId(m) != null;
+}
+/** A response/error answers a request (has `id`, no `method`). */
+function isResponse(m: JSONRPCMessage): boolean {
+  return !('method' in m) && msgId(m) != null;
+}
+
+/** Injectable seams for testing the attach-vs-headless selection. */
+export interface McpProxyDeps {
+  discover?: typeof discoverServe;
+  headless?: (cwd: string) => Promise<number>;
+}
+
+export async function runMcpProxy(
+  _parsed: ParsedArgs,
+  cwd: string = process.cwd(),
+  deps: McpProxyDeps = {},
+): Promise<number> {
+  // NB: stdout is the MCP stdio channel — diagnostics go to stderr ONLY.
+  const log = (m: string): void => {
+    process.stderr.write(`[pyric mcp-proxy] ${m}\n`);
+  };
+
+  const found = await (deps.discover ?? discoverServe)(cwd, log);
+  if (!found) {
+    // Hybrid mode (design rationale): no dev server to attach to, so host the
+    // sandbox IN this process. Zero setup, no browser tab required. A running
+    // `pyric dev --bridge` upgrades to the shared-live experience on reconnect.
+    log(
+      'no running `pyric dev --bridge` found (looked for .pyric/serve.json and ports ' +
+        `${SCAN_PORTS.join(', ')}); starting a headless in-process sandbox (zero-setup).\n` +
+        '  Data persists to .pyric/state/headless.json. For a shared-live Studio\n' +
+        '  session, start `pyric dev --bridge` BEFORE connecting the agent (a dev server\n' +
+        '  started mid-session does not yet adopt this headless data).',
+    );
+    const headless =
+      deps.headless ??
+      ((c: string) => import('../bridge/server/headless.js').then((m) => m.runHeadlessMcp(c)));
+    return await headless(cwd);
+  }
+  log(`relaying stdio ↔ ${found.mcpUrl} (via ${found.source}; attached to a running serve)`);
+
+  // Late, dynamic imports: the SDK is heavy and only needed here.
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+  const { StreamableHTTPClientTransport } = await import(
+    '@modelcontextprotocol/sdk/client/streamableHttp.js'
+  );
+
+  const http = new StreamableHTTPClientTransport(new URL(found.mcpUrl));
+  const stdio = new StdioServerTransport();
+
+  return await new Promise<number>((resolveExit) => {
+    let closing = false;
+    /** In-flight relayed requests → their timeout timers. */
+    const pending = new Map<string | number, ReturnType<typeof setTimeout>>();
+    /** Ids already failed by a timeout — used to SWALLOW a late real response so
+     *  Claude Code never sees a duplicate (error frame, then result frame). */
+    const settled = new Set<string | number>();
+
+    const sendStdio = (m: JSONRPCMessage): void => {
+      void stdio.send(m).catch((e) => log(`→client send failed: ${e}`));
+    };
+    const failRequest = (id: string | number, message: string): void => {
+      const timer = pending.get(id);
+      if (timer) clearTimeout(timer);
+      pending.delete(id);
+      settled.add(id);
+      sendStdio({ jsonrpc: '2.0', id, error: { code: PROXY_ERROR_CODE, message } } as JSONRPCMessage);
+    };
+
+    const shutdown = (code: number): void => {
+      if (closing) return; // re-entrancy guard: close() fires onclose → shutdown → …
+      closing = true;
+      process.stdin.off('end', onStdinEnd);
+      for (const t of pending.values()) clearTimeout(t);
+      pending.clear();
+      void Promise.allSettled([stdio.close(), http.close()]).then(() => resolveExit(code));
+    };
+
+    // ── relay: stdio (Claude Code) → http (serve) ──
+    stdio.onmessage = (msg) => {
+      if (isRequest(msg)) {
+        const id = msgId(msg)!;
+        const timer = setTimeout(() => {
+          failRequest(
+            id,
+            `pyric mcp-proxy: no response from serve within ${REQUEST_TIMEOUT_MS / 1000}s ` +
+              `(the server may have stopped, or no browser tab is connected). ` +
+              `Reopen the dev URL and retry.`,
+          );
+        }, REQUEST_TIMEOUT_MS);
+        pending.set(id, timer);
+      }
+      void http.send(msg).catch((e) => {
+        log(`→serve send failed: ${e}`);
+        const id = msgId(msg);
+        if (id != null && pending.has(id)) failRequest(id, 'pyric mcp-proxy: failed to reach serve — retry.');
+      });
+    };
+
+    // ── relay: http (serve) → stdio (Claude Code) ──
+    http.onmessage = (msg) => {
+      if (isResponse(msg)) {
+        const id = msgId(msg)!;
+        const timer = pending.get(id);
+        if (timer) {
+          clearTimeout(timer);
+          pending.delete(id);
+        } else if (settled.has(id)) {
+          // A response that lost the race to its timeout — already failed to the
+          // client. Swallow it so the client never sees a duplicate frame.
+          settled.delete(id);
+          return;
+        }
+      }
+      sendStdio(msg);
+    };
+
+    http.onerror = (e) => log(`serve transport error: ${e instanceof Error ? e.message : String(e)}`);
+    http.onclose = () => {
+      log('serve closed the connection (did serve stop?)');
+      shutdown(0);
+    };
+    stdio.onclose = () => shutdown(0); // Claude Code disconnected
+    const onStdinEnd = (): void => shutdown(0);
+    process.stdin.once('end', onStdinEnd);
+
+    process.once('SIGINT', () => shutdown(0));
+    process.once('SIGTERM', () => shutdown(0));
+
+    Promise.all([http.start(), stdio.start()]).catch((e) => {
+      log(`failed to start relay: ${e instanceof Error ? e.message : String(e)}`);
+      shutdown(1);
+    });
+  });
+}

package/src/cli/parse-args.ts

@@ -0,0 +1,80 @@
+/**
+ * Minimal CLI argument parser shared across subcommands.
+ *
+ * Intentionally tiny — no `commander` / `yargs` dependency. The parser
+ * is biased toward Firebase-style flag syntax (`--flag value` and
+ * `--flag=value`); short flags are single-char booleans. Anything
+ * beyond a "command + positionals + flags" model belongs in a
+ * dedicated subcommand handler, not here.
+ */
+
+export interface ParsedArgs {
+  subcommand: string | null;
+  flags: Map<string, FlagValue>;
+  positional: string[];
+  /** Everything after a bare `--`, verbatim (e.g. `pyric dev -- npm start`).
+   *  Optional so hand-built ParsedArgs literals stay valid. */
+  passthrough?: string[];
+}
+
+export type FlagValue = string | boolean | Array<string | boolean>;
+
+// Flags whose command contract is boolean must not consume a following
+// positional. Value-bearing flags retain the Firebase-style `--flag value`
+// form, while explicit boolean values remain available as `--json=true`.
+const BOOLEAN_FLAGS = new Set(['json']);
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const flags = new Map<string, FlagValue>();
+  const positional: string[] = [];
+  const passthrough: string[] = [];
+  let subcommand: string | null = null;
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === undefined) {
+      i += 1;
+      continue;
+    }
+    if (arg === '--') {
+      // Everything after a bare `--` belongs to the child command, verbatim
+      // — never parsed as flags (`pyric dev -- npm start --port 3000`).
+      passthrough.push(...argv.slice(i + 1).filter((a): a is string => a !== undefined));
+      break;
+    }
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq !== -1) {
+        setFlag(flags, arg.slice(2, eq), arg.slice(eq + 1));
+      } else {
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        if (!BOOLEAN_FLAGS.has(key) && next && !next.startsWith('-')) {
+          setFlag(flags, key, next);
+          i += 1;
+        } else {
+          setFlag(flags, key, true);
+        }
+      }
+    } else if (arg.startsWith('-')) {
+      setFlag(flags, arg.slice(1), true);
+    } else if (subcommand === null) {
+      subcommand = arg;
+    } else {
+      positional.push(arg);
+    }
+    i += 1;
+  }
+  return { subcommand, flags, positional, passthrough };
+}
+
+function setFlag(flags: Map<string, FlagValue>, key: string, value: string | boolean): void {
+  const current = flags.get(key);
+  if (current === undefined) {
+    flags.set(key, value);
+  } else if (Array.isArray(current)) {
+    current.push(value);
+  } else {
+    flags.set(key, [current, value]);
+  }
+}