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

package/src/serve/studio/routes.ts

@@ -0,0 +1,237 @@
+/**
+ * Studio storage routes — the HTTP surface for `@pyric/studio` in `local` mode.
+ * Mounted inside the `/__pyric/` namespace; the browser-side `httpWorkspace`
+ * / `httpProjectStore` clients in `packages/studio/src/clients` speak exactly
+ * these endpoints.
+ *
+ *   WORKSPACE (a single project's file tree)
+ *     GET    /__pyric/workspace?path=src/app.tsx  → file body (200) | 404
+ *     PUT    /__pyric/workspace?path=...          → write body (204)
+ *     DELETE /__pyric/workspace?path=...          → remove (204)
+ *     GET    /__pyric/workspace/list?dir=src      → WorkspaceEntry[] (200)
+ *     GET    /__pyric/workspace/watch             → SSE stream of WorkspaceChange
+ *
+ *   PROJECTS (sessions/projects)
+ *     GET    /__pyric/projects                     → ProjectMeta[] (200)
+ *     POST   /__pyric/projects   {title?}          → ProjectMeta (created) (200)
+ *     GET    /__pyric/projects/<id>                → ProjectMeta (200) | 404
+ *     PATCH  /__pyric/projects/<id>  {title?,...}  → (204)
+ *     DELETE /__pyric/projects/<id>                → (204)
+ *
+ * The `watch` stream reuses the SSE pattern already used for `/__pyric/events`
+ * (the hot-reload hub): one `text/event-stream` response per subscriber, frames
+ * are `event: change\ndata: <json>\n\n`, and the subscription is torn down on
+ * `req.close`.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+import { WorkspacePathError } from './disk-workspace.js';
+import { ProjectIdError } from './disk-project-store.js';
+import type {
+  ProjectMeta,
+  ProjectStore,
+  WorkspaceChange,
+  WorkspaceStore,
+} from './store-types.js';
+
+export interface StudioRouteOptions {
+  /** The single-project file tree served at `/__pyric/workspace`. */
+  workspace?: WorkspaceStore;
+  /** The project list served at `/__pyric/projects`. */
+  projects?: ProjectStore;
+}
+
+/** Collect the raw request body as a UTF-8 string. */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    req.setEncoding('utf8');
+    req.on('data', (c: string) => (raw += c));
+    req.on('end', () => resolve(raw));
+    req.on('error', reject);
+  });
+}
+
+/** Collect + parse the request body as JSON (null on empty/invalid). */
+async function readJson<T>(req: IncomingMessage): Promise<T | null> {
+  const raw = await readBody(req);
+  if (raw.trim() === '') return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(JSON.stringify(body));
+}
+
+function sendError(res: ServerResponse, e: unknown): void {
+  const status =
+    e instanceof WorkspacePathError || e instanceof ProjectIdError ? 400 : 500;
+  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+  res.end(e instanceof Error ? e.message : String(e));
+}
+
+async function handleWorkspace(
+  ws: WorkspaceStore,
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+): Promise<void> {
+  // ── SSE watch ────────────────────────────────────────────────────────
+  if (url.pathname === '/__pyric/workspace/watch') {
+    res.writeHead(200, {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-store',
+      connection: 'keep-alive',
+    });
+    res.write(': connected\n\n');
+    const unsub = ws.watch((change: WorkspaceChange) => {
+      // The write can race the socket teardown (page reload while a
+      // workspace change fires) — a throw here would escape into the
+      // fs.watch callback and kill the serve process.
+      try {
+        res.write(`event: change\ndata: ${JSON.stringify(change)}\n\n`);
+      } catch {
+        unsub();
+      }
+    });
+    req.on('close', () => unsub());
+    res.on('error', () => unsub());
+    return;
+  }
+
+  // ── list ─────────────────────────────────────────────────────────────
+  if (url.pathname === '/__pyric/workspace/list') {
+    if (req.method !== 'GET') {
+      res.writeHead(405, { allow: 'GET' }).end('method not allowed');
+      return;
+    }
+    const dir = url.searchParams.get('dir') ?? undefined;
+    sendJson(res, 200, await ws.list(dir));
+    return;
+  }
+
+  // ── read / write / remove a single path ──────────────────────────────
+  const path = url.searchParams.get('path');
+  if (path === null) {
+    res.writeHead(400).end('missing ?path');
+    return;
+  }
+  if (req.method === 'GET') {
+    const content = await ws.read(path);
+    if (content === null) {
+      res.writeHead(404).end('not found');
+      return;
+    }
+    res.writeHead(200, {
+      'content-type': 'application/octet-stream',
+      'cache-control': 'no-store',
+    });
+    res.end(content);
+    return;
+  }
+  if (req.method === 'PUT') {
+    const body = await readBody(req);
+    await ws.write(path, body);
+    res.writeHead(204).end();
+    return;
+  }
+  if (req.method === 'DELETE') {
+    await ws.remove(path);
+    res.writeHead(204).end();
+    return;
+  }
+  res.writeHead(405, { allow: 'GET, PUT, DELETE' }).end('method not allowed');
+}
+
+async function handleProjects(
+  store: ProjectStore,
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+): Promise<void> {
+  // /__pyric/projects/<id> | /__pyric/projects
+  const rest = url.pathname.slice('/__pyric/projects'.length);
+  const id = rest.replace(/^\//, '');
+
+  if (id === '') {
+    if (req.method === 'GET') {
+      sendJson(res, 200, await store.list());
+      return;
+    }
+    if (req.method === 'POST') {
+      const body = await readJson<{ title?: string }>(req);
+      const meta = await store.create({ title: body?.title });
+      sendJson(res, 200, meta);
+      return;
+    }
+    res.writeHead(405, { allow: 'GET, POST' }).end('method not allowed');
+    return;
+  }
+
+  // single project by id
+  if (req.method === 'GET') {
+    try {
+      const handle = await store.open(decodeURIComponent(id));
+      sendJson(res, 200, handle.meta);
+    } catch {
+      res.writeHead(404).end('not found');
+    }
+    return;
+  }
+  if (req.method === 'PATCH') {
+    const body = await readJson<Record<string, unknown>>(req);
+    // Only forward known, mutable ProjectMeta fields — never `id`.
+    const patch: Partial<Omit<ProjectMeta, 'id'>> = {};
+    if (body && typeof body.title === 'string') patch.title = body.title;
+    if (body && typeof body.createdAt === 'number') patch.createdAt = body.createdAt;
+    if (body && typeof body.updatedAt === 'number') patch.updatedAt = body.updatedAt;
+    await store.update(decodeURIComponent(id), patch);
+    res.writeHead(204).end();
+    return;
+  }
+  if (req.method === 'DELETE') {
+    await store.remove(decodeURIComponent(id));
+    res.writeHead(204).end();
+    return;
+  }
+  res
+    .writeHead(405, { allow: 'GET, PATCH, DELETE' })
+    .end('method not allowed');
+}
+
+/**
+ * Build a namespace fragment for the Studio storage routes. Returns a handler
+ * shaped like the other `/__pyric/*` fragments: it resolves `true` when it
+ * owned the request, `false` otherwise (so the caller can fall through).
+ */
+export function createStudioRoutes(opts: StudioRouteOptions) {
+  return async (
+    req: IncomingMessage,
+    res: ServerResponse,
+    url: URL,
+  ): Promise<boolean> => {
+    try {
+      if (opts.workspace && url.pathname.startsWith('/__pyric/workspace')) {
+        await handleWorkspace(opts.workspace, req, res, url);
+        return true;
+      }
+      if (opts.projects && url.pathname.startsWith('/__pyric/projects')) {
+        await handleProjects(opts.projects, req, res, url);
+        return true;
+      }
+    } catch (e) {
+      if (!res.headersSent) sendError(res, e);
+      else res.end();
+      return true;
+    }
+    return false;
+  };
+}

package/src/serve/studio/store-types.ts

@@ -0,0 +1,48 @@
+/**
+ * Studio storage port shapes — server-side MIRROR of `@pyric/studio/ports`.
+ *
+ * `@pyric/studio` is a CONSUMER of @pyric/cli' serve routes, not a dependency
+ * of it; adding a `@pyric/studio` dep here would invert the layering (and risk
+ * a cycle). So the disk impls in this directory type-check against these local
+ * copies, which are structurally identical to the port interfaces. Keep them in
+ * lockstep with `packages/studio/src/ports.ts` — that file is the contract.
+ */
+
+export interface WorkspaceEntry {
+  /** Project-relative POSIX path. */
+  path: string;
+  kind: 'file' | 'dir';
+}
+
+export interface WorkspaceChange {
+  path: string;
+  type: 'create' | 'update' | 'delete';
+}
+
+export interface WorkspaceStore {
+  read(path: string): Promise<string | null>;
+  write(path: string, content: string): Promise<void>;
+  list(dir?: string): Promise<WorkspaceEntry[]>;
+  remove(path: string): Promise<void>;
+  watch(cb: (change: WorkspaceChange) => void): () => void;
+}
+
+export interface ProjectMeta {
+  id: string;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface ProjectHandle {
+  meta: ProjectMeta;
+  workspace: WorkspaceStore;
+}
+
+export interface ProjectStore {
+  list(): Promise<ProjectMeta[]>;
+  open(id: string): Promise<ProjectHandle>;
+  create(input: { title?: string }): Promise<ProjectMeta>;
+  update(id: string, patch: Partial<Omit<ProjectMeta, 'id'>>): Promise<void>;
+  remove(id: string): Promise<void>;
+}

package/src/serve/studio/studio-storage.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Track T3 — disk-backed Studio storage + serve routes.
+ *
+ * Round-trips `diskWorkspace` / `diskProjectStore` in a temp dir (read/write/
+ * list/remove, path-traversal refusal, project CRUD) and smoke-tests the route
+ * handler by importing it directly and driving it with mock req/res (no live
+ * server).
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PassThrough } from 'node:stream';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+import {
+  diskWorkspace,
+  WorkspacePathError,
+} from './disk-workspace.js';
+import {
+  diskProjectStore,
+  slugifyProjectId,
+  ProjectIdError,
+} from './disk-project-store.js';
+import { createStudioRoutes } from './routes.js';
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'pyric-studio-'));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('diskWorkspace', () => {
+  it('write → read round-trips, creating parent dirs', async () => {
+    const ws = diskWorkspace(dir);
+    await ws.write('src/app.tsx', 'export const x = 1;');
+    expect(await ws.read('src/app.tsx')).toBe('export const x = 1;');
+    expect(existsSync(join(dir, 'src', 'app.tsx'))).toBe(true);
+  });
+
+  it('read of a missing file is null', async () => {
+    const ws = diskWorkspace(dir);
+    expect(await ws.read('nope.txt')).toBeNull();
+  });
+
+  it('list returns sorted file/dir entries (project-relative POSIX)', async () => {
+    const ws = diskWorkspace(dir);
+    await ws.write('b.txt', '2');
+    await ws.write('a.txt', '1');
+    await ws.write('sub/c.txt', '3');
+    const root = await ws.list();
+    expect(root).toEqual([
+      { path: 'a.txt', kind: 'file' },
+      { path: 'b.txt', kind: 'file' },
+      { path: 'sub', kind: 'dir' },
+    ]);
+    const sub = await ws.list('sub');
+    expect(sub).toEqual([{ path: 'sub/c.txt', kind: 'file' }]);
+  });
+
+  it('remove deletes a file and is idempotent', async () => {
+    const ws = diskWorkspace(dir);
+    await ws.write('gone.txt', 'x');
+    await ws.remove('gone.txt');
+    expect(await ws.read('gone.txt')).toBeNull();
+    await ws.remove('gone.txt'); // no throw
+  });
+
+  it('refuses path traversal outside the root', async () => {
+    const ws = diskWorkspace(dir);
+    await expect(ws.read('../escape.txt')).rejects.toBeInstanceOf(
+      WorkspacePathError,
+    );
+    await expect(ws.write('../../x', 'y')).rejects.toBeInstanceOf(
+      WorkspacePathError,
+    );
+  });
+
+  it('refuses removing the root itself', async () => {
+    const ws = diskWorkspace(dir);
+    await expect(ws.remove('')).rejects.toBeInstanceOf(WorkspacePathError);
+  });
+
+  it('watch fires on a write and unsubscribes cleanly', async () => {
+    const ws = diskWorkspace(dir);
+    const seen: string[] = [];
+    const unsub = ws.watch((c) => seen.push(`${c.type}:${c.path}`));
+    // Let the recursive watcher attach before mutating.
+    await new Promise((r) => setTimeout(r, 50));
+    await ws.write('watched.txt', 'hi');
+    // fs.watch is async; give it a tick.
+    await new Promise((r) => setTimeout(r, 250));
+    unsub();
+    // At least one change for the file should have surfaced (event coalescing
+    // varies by platform, so assert membership not exact count).
+    expect(seen.some((s) => s.includes('watched.txt'))).toBe(true);
+  });
+});
+
+describe('diskProjectStore', () => {
+  it('create → list → open → update → remove round-trips', async () => {
+    const store = diskProjectStore(dir);
+    expect(await store.list()).toEqual([]);
+
+    const meta = await store.create({ title: 'My App' });
+    expect(meta.id).toBe('my-app');
+    expect(meta.title).toBe('My App');
+    expect(meta.createdAt).toBeGreaterThan(0);
+
+    const list = await store.list();
+    expect(list.map((m) => m.id)).toEqual(['my-app']);
+
+    const handle = await store.open('my-app');
+    expect(handle.meta.title).toBe('My App');
+    await handle.workspace.write('index.html', '<h1>hi</h1>');
+    expect(await handle.workspace.read('index.html')).toBe('<h1>hi</h1>');
+
+    await store.update('my-app', { title: 'Renamed' });
+    expect((await store.open('my-app')).meta.title).toBe('Renamed');
+
+    await store.remove('my-app');
+    expect(await store.list()).toEqual([]);
+  });
+
+  it('disambiguates ids when titles collide', async () => {
+    const store = diskProjectStore(dir);
+    const a = await store.create({ title: 'Dup' });
+    const b = await store.create({ title: 'Dup' });
+    expect(a.id).toBe('dup');
+    expect(b.id).toBe('dup-2');
+  });
+
+  it('open of a missing project rejects', async () => {
+    const store = diskProjectStore(dir);
+    await expect(store.open('ghost')).rejects.toThrow(/not found/);
+  });
+
+  it('rejects unsafe ids', async () => {
+    const store = diskProjectStore(dir);
+    await expect(store.open('../evil')).rejects.toBeInstanceOf(ProjectIdError);
+  });
+
+  it('slugifyProjectId is filesystem-safe', () => {
+    expect(slugifyProjectId('Hello, World!')).toBe('hello-world');
+    expect(slugifyProjectId('  spaced  out  ')).toBe('spaced-out');
+  });
+});
+
+// ── Route smoke tests (handler imported directly) ─────────────────────────
+
+interface MockRes {
+  res: ServerResponse;
+  statusCode: number;
+  body: string;
+  headers: Record<string, unknown>;
+  done: Promise<void>;
+}
+
+function mockReq(method: string): IncomingMessage {
+  const req = new PassThrough() as unknown as IncomingMessage;
+  (req as unknown as { method: string }).method = method;
+  return req;
+}
+
+function mockRes(): MockRes {
+  const state: MockRes = {
+    res: undefined as unknown as ServerResponse,
+    statusCode: 0,
+    body: '',
+    headers: {},
+    done: undefined as unknown as Promise<void>,
+  };
+  let resolveDone!: () => void;
+  state.done = new Promise<void>((r) => (resolveDone = r));
+  const res = {
+    headersSent: false,
+    writeHead(code: number, headers?: Record<string, unknown>) {
+      state.statusCode = code;
+      if (headers) state.headers = headers;
+      (res as { headersSent: boolean }).headersSent = true;
+      return res;
+    },
+    write(chunk: string) {
+      state.body += chunk;
+      return true;
+    },
+    end(chunk?: string) {
+      if (chunk) state.body += chunk;
+      resolveDone();
+      return res;
+    },
+  } as unknown as ServerResponse;
+  state.res = res;
+  return state;
+}
+
+describe('createStudioRoutes', () => {
+  it('GET /__pyric/projects lists, POST creates', async () => {
+    const routes = createStudioRoutes({ projects: diskProjectStore(dir) });
+
+    const listRes = mockRes();
+    const handled = await routes(
+      mockReq('GET'),
+      listRes.res,
+      new URL('http://x/__pyric/projects'),
+    );
+    await listRes.done;
+    expect(handled).toBe(true);
+    expect(listRes.statusCode).toBe(200);
+    expect(JSON.parse(listRes.body)).toEqual([]);
+
+    const postReq = mockReq('POST');
+    const postRes = mockRes();
+    const p = routes(postReq, postRes.res, new URL('http://x/__pyric/projects'));
+    postReq.emit('data', JSON.stringify({ title: 'Via Route' }));
+    postReq.emit('end');
+    await p;
+    await postRes.done;
+    expect(postRes.statusCode).toBe(200);
+    expect(JSON.parse(postRes.body).title).toBe('Via Route');
+  });
+
+  it('PUT then GET /__pyric/workspace round-trips a file', async () => {
+    const routes = createStudioRoutes({ workspace: diskWorkspace(dir) });
+
+    const putReq = mockReq('PUT');
+    const putRes = mockRes();
+    const p = routes(
+      putReq,
+      putRes.res,
+      new URL('http://x/__pyric/workspace?path=note.txt'),
+    );
+    putReq.emit('data', 'hello');
+    putReq.emit('end');
+    await p;
+    await putRes.done;
+    expect(putRes.statusCode).toBe(204);
+    expect(await readFile(join(dir, 'note.txt'), 'utf8')).toBe('hello');
+
+    const getRes = mockRes();
+    await routes(
+      mockReq('GET'),
+      getRes.res,
+      new URL('http://x/__pyric/workspace?path=note.txt'),
+    );
+    await getRes.done;
+    expect(getRes.statusCode).toBe(200);
+    expect(getRes.body).toBe('hello');
+  });
+
+  it('GET /__pyric/workspace/list returns entries', async () => {
+    const ws = diskWorkspace(dir);
+    await ws.write('a.txt', '1');
+    const routes = createStudioRoutes({ workspace: ws });
+    const res = mockRes();
+    await routes(
+      mockReq('GET'),
+      res.res,
+      new URL('http://x/__pyric/workspace/list'),
+    );
+    await res.done;
+    expect(JSON.parse(res.body)).toEqual([{ path: 'a.txt', kind: 'file' }]);
+  });
+
+  it('returns 400 on path traversal', async () => {
+    const routes = createStudioRoutes({ workspace: diskWorkspace(dir) });
+    const res = mockRes();
+    await routes(
+      mockReq('GET'),
+      res.res,
+      new URL('http://x/__pyric/workspace?path=../escape'),
+    );
+    await res.done;
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('returns false for unrelated /__pyric/* paths', async () => {
+    const routes = createStudioRoutes({ workspace: diskWorkspace(dir) });
+    const handled = await routes(
+      mockReq('GET'),
+      mockRes().res,
+      new URL('http://x/__pyric/init.json'),
+    );
+    expect(handled).toBe(false);
+  });
+});

package/src/serve/vite-ai-config.ts

@@ -0,0 +1,77 @@
+import type { AIOptions } from 'pyric/ai';
+import path from 'node:path';
+import { loadEnv } from 'vite';
+import type { AiEngineConfigWire } from './worker/protocol.js';
+
+const AI_PROXY_PATH = '/__pyric/ai-proxy';
+
+/** Declarative AI engines that can cross Vite's page/SharedWorker boundary. */
+export type PyricAiEngineConfig = Extract<NonNullable<AIOptions['engine']>, { kind: string }>;
+
+export interface PyricAiOptions {
+  /** Simple OpenAI-compatible model selection through Pyric's same-origin proxy. */
+  model?: string;
+  /** Advanced declarative engine configuration. */
+  engine?: PyricAiEngineConfig;
+  /** OpenAI-compatible upstream used by the same-origin proxy. */
+  proxyUpstream?: string;
+}
+
+export interface ResolvedViteAiConfig {
+  engineWire: AiEngineConfigWire | undefined;
+  proxyUpstream: string | undefined;
+}
+
+/** Load env using Vite's `envDir`-relative-to-root convention. */
+export function loadViteAiEnv(
+  mode: string,
+  root: string | undefined,
+  envDir: string | undefined,
+): Record<string, string> {
+  const resolvedRoot = path.resolve(root ?? process.cwd());
+  const resolvedEnvDir = envDir === undefined
+    ? resolvedRoot
+    : path.resolve(resolvedRoot, envDir);
+  return loadEnv(mode, resolvedEnvDir, '');
+}
+
+/** Convert a public declarative engine into the JSON-safe worker wire shape. */
+export function engineConfigToWire(engine: PyricAiEngineConfig): AiEngineConfigWire {
+  if (engine.kind === 'openai') {
+    return {
+      kind: 'openai',
+      baseUrl: engine.baseUrl ?? AI_PROXY_PATH,
+      ...(engine.model !== undefined ? { model: engine.model } : {}),
+      ...(engine.modelMap !== undefined ? { modelMap: engine.modelMap } : {}),
+    };
+  }
+  return {
+    kind: 'scripted',
+    ...(engine.script !== undefined
+      ? { script: engine.script as unknown as Array<Record<string, unknown>> }
+      : {}),
+  };
+}
+
+/** Resolve the plugin's explicit-options-over-Vite-env AI convention. */
+export function resolveViteAiConfig(
+  options: PyricAiOptions | undefined,
+  env: Record<string, string | undefined>,
+): ResolvedViteAiConfig {
+  if (options?.model !== undefined && options.engine !== undefined) {
+    throw new Error('@pyric/cli/vite: Choose either ai.model or ai.engine, not both.');
+  }
+
+  const model = options?.model?.trim() || env.PYRIC_AI_MODEL?.trim();
+  const engineWire = options?.engine
+    ? engineConfigToWire(options.engine)
+    : model
+      ? engineConfigToWire({ kind: 'openai', baseUrl: AI_PROXY_PATH, model })
+      : undefined;
+
+  return {
+    engineWire,
+    proxyUpstream:
+      options?.proxyUpstream?.trim() || env.PYRIC_AI_PROXY_UPSTREAM?.trim() || undefined,
+  };
+}