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

package/src/serve/state-store.ts

@@ -0,0 +1,166 @@
+/**
+ * On-disk state store for `pyric dev --persist` — the substrate side of
+ * flow doc section 3c ("persistence = an autosaved seed").
+ *
+ * The file is an ENVELOPE around two sections:
+ *   - `firestore`: the `pyric/sandbox` persistence controller's own blob
+ *     (`{version, savedAt, firestore: {path: fields}}`), stored verbatim as
+ *     parsed JSON. The page's controller wrote it and will read it back
+ *     through its own (de)serializer — wrapper types (Timestamp, Bytes, …)
+ *     live as marker shapes and re-hydrate to class instances on restore.
+ *     This store never interprets it.
+ *   - `auth`: `{users: SeedUser[]}` — what `sandbox.exportUsers` emits and
+ *     `sandbox.seedUsers` accepts.
+ *
+ * Everything is plain, diffable JSON on purpose: the persisted state
+ * doubles as a context artifact agents can read and promote to a fixture
+ * (`pyric snapshot`, plan P3).
+ *
+ * Durability stance (judgment zone 6, recorded): writes are atomic
+ * (tmp + rename, same volume) so a crash never truncates the file. A
+ * CORRUPT or version-mismatched file makes `load()` throw rather than
+ * silently discarding user data — serve fails fast and tells the user to
+ * inspect or delete it. Last-writer-wins between section writes is
+ * accepted (single serve process, sync fs — effectively serialized).
+ */
+import { copyFileSync, mkdirSync, readFileSync, renameSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { sandbox as authSandbox } from 'pyric/auth';
+
+export type ExportedUsers = ReturnType<typeof authSandbox.exportUsers>;
+
+export const STATE_FILE_VERSION = 1 as const;
+
+/** Expected inner version of the sandbox persistence controller's blob.
+ *  MIRRORS pyric's `serialize.ts` `SCHEMA_VERSION` — bump in lockstep when
+ *  pyric does (they ship together). Drift-risk noted: not importable
+ *  (pyric doesn't export it), so a check, not a re-use. */
+export const EXPECTED_CONTROLLER_BLOB_VERSION = 1;
+
+export interface PyricStateFile {
+  version: typeof STATE_FILE_VERSION;
+  /** The sandbox persistence controller's blob, verbatim. Null = never flushed. */
+  firestore: unknown | null;
+  auth: { users: ExportedUsers } | null;
+}
+
+export type StateSection = 'firestore' | 'auth';
+
+export class StateFileError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StateFileError';
+  }
+}
+
+export interface StateStore {
+  /** The project directory this store persists for (for the
+   *  promote-the-wrong-project guard). */
+  projectDir: string;
+  /** Absolute path of the state file. */
+  path: string;
+  /** Absolute path of the one-deep recovery backup (`state.json.bak`). */
+  backupPath: string;
+  /** Parsed envelope, or null when the file doesn't exist. Throws
+   *  {@link StateFileError} on corrupt JSON or version mismatch —
+   *  fail fast over silent data loss. */
+  load(): PyricStateFile | null;
+  readSection(section: StateSection): unknown | null;
+  /** Read-modify-write the envelope; atomic tmp+rename. A firestore write
+   *  that would collapse a non-empty doc set to empty first preserves the
+   *  prior file as `.bak` (pre-mortem #2). */
+  writeSection(section: StateSection, value: unknown): void;
+  exists(): boolean;
+}
+
+export const STATE_RELATIVE_PATH = join('.pyric', 'state', 'state.json');
+
+export function createStateStore(projectDir: string): StateStore {
+  const path = join(projectDir, STATE_RELATIVE_PATH);
+  const backupPath = `${path}.bak`;
+
+  const load = (): PyricStateFile | null => {
+    if (!existsSync(path)) return null;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(path, 'utf8'));
+    } catch (e) {
+      throw new StateFileError(
+        `state file at ${path} is not valid JSON (${e instanceof Error ? e.message : String(e)}). ` +
+          'Inspect or delete it to continue — pyric will not overwrite it silently.',
+      );
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new StateFileError(`state file at ${path} is not an object.`);
+    }
+    const file = parsed as PyricStateFile;
+    if (file.version !== STATE_FILE_VERSION) {
+      throw new StateFileError(
+        `state file at ${path} has version ${String(file.version)}; this @pyric/cli expects ` +
+          `${STATE_FILE_VERSION}. Delete it (or promote it with a matching @pyric/cli) to continue.`,
+      );
+    }
+    // Inner controller-blob version (pre-mortem #6): the page's
+    // `deserializeSnapshot` validates this at restore — so a pyric upgrade
+    // that bumps its SCHEMA_VERSION would otherwise fail IN THE PAGE while
+    // the banner cheerfully reports "N docs restored". Peek it server-side
+    // and fail fast here instead. (Read-only peek; the section is still
+    // never re-encoded.) EXPECTED_CONTROLLER_BLOB_VERSION mirrors pyric's
+    // serialize `SCHEMA_VERSION` and must bump in lockstep — they ship
+    // together in this monorepo.
+    const inner = (file.firestore as { version?: unknown } | null)?.version;
+    if (inner !== undefined && inner !== EXPECTED_CONTROLLER_BLOB_VERSION) {
+      throw new StateFileError(
+        `state file at ${path} holds a firestore blob of version ${String(inner)}; this ` +
+          `pyric expects ${EXPECTED_CONTROLLER_BLOB_VERSION} (pyric was likely upgraded). ` +
+          'Delete the state file or re-promote it with a matching pyric to continue.',
+      );
+    }
+    return file;
+  };
+
+  const writeAtomic = (file: PyricStateFile): void => {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf8');
+    renameSync(tmp, path); // same volume — atomic replace
+  };
+
+  return {
+    projectDir,
+    path,
+    backupPath,
+    load,
+    exists: () => existsSync(path),
+    readSection(section) {
+      return load()?.[section] ?? null;
+    },
+    writeSection(section, value) {
+      const current = load() ?? { version: STATE_FILE_VERSION, firestore: null, auth: null };
+      // Data-loss guard (flow doc section 3c / pre-mortem #2): a `sandbox.reset()`
+      // makes the persistence controller flush EMPTY firestore over the
+      // live file (pyric flushes on session_boundary by design), and the
+      // backend write can't tell that from a legitimate delete-all. Before
+      // a firestore write would collapse a NON-empty doc set to empty, keep
+      // the prior file as `.bak` (one-deep) so it's recoverable. Intent-
+      // agnostic on purpose — covers reset, agent error, and accidental
+      // delete-all uniformly.
+      if (
+        section === 'firestore' &&
+        firestoreDocCount(value) === 0 &&
+        firestoreDocCount(current.firestore) > 0 &&
+        existsSync(path)
+      ) {
+        copyFileSync(path, backupPath);
+      }
+      writeAtomic({ ...current, [section]: value } as PyricStateFile);
+    },
+  };
+}
+
+/** Doc count inside a controller firestore blob (`{…, firestore: {path:
+ *  fields}}`), 0 for null/empty/malformed. */
+export function firestoreDocCount(section: unknown): number {
+  const docs = (section as { firestore?: Record<string, unknown> } | null)?.firestore;
+  return docs && typeof docs === 'object' ? Object.keys(docs).length : 0;
+}

package/src/serve/studio/disk-project-store.ts

@@ -0,0 +1,185 @@
+/**
+ * `diskProjectStore(root)` — a {@link ProjectStore} where each project is a
+ * subdirectory of `root` carrying a small metadata file (`.pyric-project.json`,
+ * shape {@link ProjectMeta}). `open(id)` hands back a {@link ProjectHandle}
+ * whose `workspace` is a {@link diskWorkspace} rooted at that subdirectory.
+ *
+ * Project ids ARE the directory names; they're slugged from the title (or
+ * generated) and validated to a safe charset so an id can never traverse out of
+ * `root`. The metadata file lives alongside the project's working tree — it's
+ * skipped by `diskWorkspace.list` callers only by convention (the file tree
+ * shows it; that's acceptable for a `.pyric-*` dotfile).
+ */
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { diskWorkspace } from './disk-workspace.js';
+import type {
+  ProjectHandle,
+  ProjectMeta,
+  ProjectStore,
+} from './store-types.js';
+
+const META_FILE = '.pyric-project.json';
+
+/** Thrown when an id isn't a safe single path segment. */
+export class ProjectIdError extends Error {
+  constructor(id: string) {
+    super(`invalid project id: '${id}'`);
+    this.name = 'ProjectIdError';
+  }
+}
+
+/** Slug a title into a filesystem-safe id segment. */
+export function slugifyProjectId(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+  return slug;
+}
+
+/** A safe id is a single non-dot path segment of `[a-z0-9-_]`. */
+function assertSafeId(id: string): void {
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(id) || id.includes('/') || id.includes('..')) {
+    throw new ProjectIdError(id);
+  }
+}
+
+export function diskProjectStore(rootDir: string): ProjectStore {
+  const root = resolve(rootDir);
+
+  function projectDir(id: string): string {
+    assertSafeId(id);
+    return join(root, id);
+  }
+
+  async function readMeta(id: string): Promise<ProjectMeta | null> {
+    try {
+      const raw = await readFile(join(projectDir(id), META_FILE), 'utf8');
+      const parsed = JSON.parse(raw) as Partial<ProjectMeta>;
+      const now = Date.now();
+      return {
+        id,
+        title: typeof parsed.title === 'string' ? parsed.title : id,
+        createdAt: typeof parsed.createdAt === 'number' ? parsed.createdAt : now,
+        updatedAt: typeof parsed.updatedAt === 'number' ? parsed.updatedAt : now,
+      };
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+      throw e;
+    }
+  }
+
+  async function writeMeta(meta: ProjectMeta): Promise<void> {
+    const dir = projectDir(meta.id);
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, META_FILE),
+      JSON.stringify(meta, null, 2) + '\n',
+      'utf8',
+    );
+  }
+
+  return {
+    async list() {
+      let names: string[];
+      try {
+        names = await readdir(root);
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code === 'ENOENT') return [];
+        throw e;
+      }
+      const metas: ProjectMeta[] = [];
+      for (const name of names) {
+        if (name.startsWith('.')) continue;
+        let isDir = false;
+        try {
+          isDir = (await stat(join(root, name))).isDirectory();
+        } catch {
+          continue;
+        }
+        if (!isDir) continue;
+        try {
+          const meta = await readMeta(name);
+          // A directory without a meta file is still a project — synthesize.
+          metas.push(
+            meta ?? {
+              id: name,
+              title: name,
+              createdAt: 0,
+              updatedAt: 0,
+            },
+          );
+        } catch (e) {
+          if (e instanceof ProjectIdError) continue; // not a valid project dir
+          throw e;
+        }
+      }
+      metas.sort((a, b) => b.updatedAt - a.updatedAt);
+      return metas;
+    },
+
+    async open(id) {
+      const dir = projectDir(id);
+      let meta = await readMeta(id);
+      if (meta === null) {
+        // Allow opening a bare directory that exists but lacks metadata.
+        try {
+          if ((await stat(dir)).isDirectory()) {
+            meta = { id, title: id, createdAt: Date.now(), updatedAt: Date.now() };
+          }
+        } catch {
+          /* fall through to throw */
+        }
+      }
+      if (meta === null) {
+        throw new Error(`project not found: '${id}'`);
+      }
+      const handle: ProjectHandle = {
+        meta,
+        workspace: diskWorkspace(dir),
+      };
+      return handle;
+    },
+
+    async create(input) {
+      const title = input.title?.trim() || 'untitled';
+      const base = slugifyProjectId(title) || 'project';
+      // Disambiguate against existing dirs.
+      let id = base;
+      let n = 1;
+      while (true) {
+        try {
+          await stat(join(root, id));
+          id = `${base}-${++n}`;
+        } catch {
+          break; // free
+        }
+      }
+      const now = Date.now();
+      const meta: ProjectMeta = { id, title, createdAt: now, updatedAt: now };
+      await writeMeta(meta);
+      return meta;
+    },
+
+    async update(id, patch) {
+      const existing = await readMeta(id);
+      if (existing === null) throw new Error(`project not found: '${id}'`);
+      const next: ProjectMeta = {
+        ...existing,
+        ...patch,
+        id, // id is immutable
+        updatedAt: Date.now(),
+      };
+      await writeMeta(next);
+    },
+
+    async remove(id) {
+      const dir = projectDir(id);
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}

package/src/serve/studio/disk-workspace.ts

@@ -0,0 +1,162 @@
+/**
+ * `diskWorkspace(dir)` — a {@link WorkspaceStore} over a real filesystem
+ * directory (the Studio `local` mode's project file tree, served at
+ * `/__pyric/workspace`).
+ *
+ * Paths are project-relative POSIX strings (`src/app.tsx`, `firestore.rules`).
+ * Every op resolves the path inside `dir` and REFUSES anything that escapes the
+ * root (`..` traversal, absolute paths) — the same posture the static server
+ * takes for `publicDir`. `watch(cb)` uses a recursive `fs.watch` and reports
+ * create/update/delete as {@link WorkspaceChange} events.
+ */
+import {
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import { existsSync, mkdirSync, watch as fsWatch, type FSWatcher } from 'node:fs';
+import { dirname, join, posix, relative, resolve, sep } from 'node:path';
+
+import type {
+  WorkspaceChange,
+  WorkspaceEntry,
+  WorkspaceStore,
+} from './store-types.js';
+
+/** Thrown when a request path escapes the workspace root. */
+export class WorkspacePathError extends Error {
+  constructor(path: string) {
+    super(`workspace path escapes root: '${path}'`);
+    this.name = 'WorkspacePathError';
+  }
+}
+
+/**
+ * Resolve a project-relative POSIX path to an absolute OS path inside `root`,
+ * or throw {@link WorkspacePathError} if it would escape. Leading slashes are
+ * stripped (treated as project-root-relative); empty / `.` resolves to the
+ * root itself.
+ */
+export function resolveWorkspacePath(root: string, rel: string): string {
+  const cleaned = rel.replace(/^\/+/, '');
+  // Normalize via POSIX semantics first so `a/../b` collapses predictably,
+  // then map separators to the host OS.
+  const normalized = posix.normalize(cleaned === '' ? '.' : cleaned);
+  if (normalized === '..' || normalized.startsWith('../')) {
+    throw new WorkspacePathError(rel);
+  }
+  const abs = resolve(root, normalized.split('/').join(sep));
+  if (abs !== root && !abs.startsWith(root + sep)) {
+    throw new WorkspacePathError(rel);
+  }
+  return abs;
+}
+
+/** Convert an absolute OS path under `root` to a project-relative POSIX path. */
+function toPosixRel(root: string, abs: string): string {
+  return relative(root, abs).split(sep).join('/');
+}
+
+export function diskWorkspace(dir: string): WorkspaceStore {
+  const root = resolve(dir);
+
+  return {
+    async read(path) {
+      const abs = resolveWorkspacePath(root, path);
+      try {
+        return await readFile(abs, 'utf8');
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+        // A directory read errors as EISDIR — treat as "no file content".
+        if ((e as NodeJS.ErrnoException).code === 'EISDIR') return null;
+        throw e;
+      }
+    },
+
+    async write(path, content) {
+      const abs = resolveWorkspacePath(root, path);
+      await mkdir(dirname(abs), { recursive: true });
+      await writeFile(abs, content, 'utf8');
+    },
+
+    async list(dir) {
+      const abs = resolveWorkspacePath(root, dir ?? '');
+      let names: string[];
+      try {
+        names = await readdir(abs);
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code === 'ENOENT') return [];
+        throw e;
+      }
+      const entries: WorkspaceEntry[] = [];
+      for (const name of names) {
+        const childAbs = join(abs, name);
+        let isDir = false;
+        try {
+          isDir = (await stat(childAbs)).isDirectory();
+        } catch {
+          continue; // raced away between readdir and stat
+        }
+        entries.push({
+          path: toPosixRel(root, childAbs),
+          kind: isDir ? 'dir' : 'file',
+        });
+      }
+      entries.sort((a, b) => a.path.localeCompare(b.path));
+      return entries;
+    },
+
+    async remove(path) {
+      const abs = resolveWorkspacePath(root, path);
+      if (abs === root) throw new WorkspacePathError(path); // never nuke the root
+      await rm(abs, { recursive: true, force: true });
+    },
+
+    watch(cb) {
+      if (!existsSync(root)) {
+        try {
+          // best-effort: ensure the dir exists so the watcher can attach.
+          mkdirSync(root, { recursive: true });
+        } catch {
+          /* watcher just won't fire */
+        }
+      }
+      let watcher: FSWatcher | null = null;
+      try {
+        watcher = fsWatch(root, { recursive: true }, (_event, filename) => {
+          if (filename == null) return;
+          const relPath = String(filename).split(sep).join('/');
+          // fs.watch doesn't tell us create vs update vs delete reliably across
+          // platforms; derive it from current existence.
+          let abs: string;
+          try {
+            abs = resolveWorkspacePath(root, relPath);
+          } catch {
+            return; // ignore anything outside the root
+          }
+          const type: WorkspaceChange['type'] = existsSync(abs)
+            ? 'update'
+            : 'delete';
+          cb({ path: relPath, type });
+        });
+      } catch {
+        // Recursive watch unsupported here — degrade to no live updates.
+        return () => {};
+      }
+      // Watcher failure (EMFILE, root renamed) must not surface as an
+      // unhandled 'error' event — that would kill the serve process.
+      // Degrade to no live updates instead.
+      watcher.on('error', () => {
+        watcher?.close();
+        watcher = null;
+      });
+      return () => {
+        watcher?.close();
+        watcher = null;
+      };
+    },
+  };
+}

package/src/serve/studio/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Studio storage (Track T3) — disk-backed `WorkspaceStore` / `ProjectStore`
+ * impls + the `/__pyric/workspace` and `/__pyric/projects` serve routes that
+ * `@pyric/studio`'s `local` mode talks to. See the design rationale.
+ */
+export { diskWorkspace, resolveWorkspacePath, WorkspacePathError } from './disk-workspace.js';
+export {
+  diskProjectStore,
+  slugifyProjectId,
+  ProjectIdError,
+} from './disk-project-store.js';
+export { createStudioRoutes, type StudioRouteOptions } from './routes.js';
+export type {
+  ProjectHandle,
+  ProjectMeta,
+  ProjectStore,
+  WorkspaceChange,
+  WorkspaceEntry,
+  WorkspaceStore,
+} from './store-types.js';