@pygmalionjs/pygmalion 0.2.14 → 0.2.16

package/node/design-session.mjs

@@ -7,6 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { normalizeViteMode } from './dev-mirror.mjs';
 import { writeStyleEdit, writeTextEdit } from './inspect-plugin.mjs';
 import { createUnifiedDiff } from './source-diff.mjs';
 import { writeSourceOperations } from './source-operations.mjs';
@@ -289,6 +290,9 @@ export function pygmalionDesignSessionPlugin(options) {
     options.previewConfig ?? fileURLToPath(new URL('./dev-view.vite.mjs', import.meta.url)),
   );
   const viteConfig = path.resolve(options.viteConfig ?? path.join(mirrorAppRoot, 'vite.config.ts'));
+  // Session previews are separate Vite processes too, so they need the same
+  // host-declared mode as the mirror or a session would render a different app.
+  const previewMode = normalizeViteMode(options.previewMode);
   const sourceDirectory = (options.sourceDirectory ?? 'src').replace(/^\.?\//, '').replace(/\/$/, '') || '.';
   const dependencies = options.dependencies ?? {};
   const inspect = options.inspect ?? {};
@@ -503,7 +507,17 @@ export function pygmalionDesignSessionPlugin(options) {
 
     const child = spawn(
       process.execPath,
-      [viteBin, '--config', wrapperConfig, '--host', '127.0.0.1', '--port', String(port), '--strictPort'],
+      [
+        viteBin,
+        '--config',
+        wrapperConfig,
+        ...(previewMode ? ['--mode', previewMode] : []),
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '--strictPort',
+      ],
       {
         cwd: sessionAppRoot,
         env: {

package/node/dev-mirror.mjs

@@ -114,12 +114,50 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * Renders the current working tree, uncommitted changes included, instead of a
+ * committed ref. Resolved to a throwaway commit at sync time.
+ */
+export const PYGMALION_WORKTREE_SOURCE_REF = 'worktree';
+
 function normalizeLocalSourceRef(value) {
   if (value == null) return null;
   if (typeof value !== 'string' || value.trim() === '') {
     throw new Error('Pygmalion source.ref must be a non-empty string');
   }
-  return value.trim();
+  const ref = value.trim();
+  // The ref reaches git as an argument, so a leading dash would be read as a
+  // flag and whitespace or control characters would split it.
+  if (ref.startsWith('-')) {
+    throw new Error('Pygmalion source.ref must not start with "-"');
+  }
+  if (/[\s\u0000-\u001f\u007f]/u.test(ref)) {
+    throw new Error(
+      'Pygmalion source.ref must not contain whitespace or control characters',
+    );
+  }
+  if (ref.length > 256) {
+    throw new Error('Pygmalion source.ref is too long');
+  }
+  return ref;
+}
+
+/**
+ * The mode becomes an argv entry for the spawned preview Vite, so it is
+ * restricted to the identifier shape Vite mode names actually use. Anything
+ * else could smuggle a second flag into that command line.
+ */
+export function normalizeViteMode(value) {
+  if (value == null) return null;
+  if (typeof value !== 'string' || !/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new Error(
+      'Pygmalion preview.mode must be a Vite mode name ([A-Za-z0-9._-]+)',
+    );
+  }
+  if (value.startsWith('-')) {
+    throw new Error('Pygmalion preview.mode must not start with "-"');
+  }
+  return value;
 }
 
 function normalizeManagedOutputPaths(value) {
@@ -155,6 +193,38 @@ function normalizeManagedOutputPaths(value) {
   ];
 }
 
+const MAX_REFRESH_BODY_BYTES = 4096;
+
+/**
+ * Reads an optional `{ ref }` from a refresh request. Returns undefined when the
+ * body is empty so a plain refresh keeps re-syncing the ref already in use.
+ */
+async function readRefFromRequest(req) {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of req) {
+    bytes += chunk.length;
+    if (bytes > MAX_REFRESH_BODY_BYTES) {
+      throw new Error('refresh body is too large');
+    }
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('refresh body must be JSON');
+  }
+  if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('refresh body must be a JSON object');
+  }
+  if (!('ref' in parsed) || parsed.ref == null) return undefined;
+  // normalizeLocalSourceRef enforces the git-argument safety rules.
+  return normalizeLocalSourceRef(parsed.ref);
+}
+
 async function restoreManagedOutputs(mirrorRoot, managedPaths) {
   if (managedPaths.length === 0) return;
   const trackedRaw = await git(mirrorRoot, 'ls-files', '-z', '--', ...managedPaths);
@@ -173,13 +243,46 @@ async function restoreManagedOutputs(mirrorRoot, managedPaths) {
   await git(mirrorRoot, 'clean', '-fd', '--', ...managedPaths);
 }
 
+/**
+ * Turns the current working tree into a commit the mirror can check out, so
+ * uncommitted edits can be previewed without polluting any branch.
+ *
+ * `git stash create` writes a dangling commit and leaves the working tree and
+ * the index untouched. It records tracked changes only — untracked files stay
+ * out, which the caller reports as a warning.
+ */
+async function resolveWorktreeSourceCommit(repoRoot, onWarning) {
+  const created = await git(repoRoot, 'stash', 'create');
+  if (!created) {
+    // Nothing uncommitted — HEAD already is the working tree.
+    return git(repoRoot, 'rev-parse', '--verify', '--end-of-options', 'HEAD^{commit}');
+  }
+  const untracked = await git(
+    repoRoot,
+    'ls-files',
+    '--others',
+    '--exclude-standard',
+  );
+  if (untracked) {
+    const count = untracked.split('\n').filter(Boolean).length;
+    onWarning?.(
+      `working tree preview excludes ${count} untracked file(s); commit or stage them to include`,
+    );
+  }
+  return created;
+}
+
 export async function syncDevMirrorWorktree(options) {
   const repoRoot = path.resolve(options.repoRoot);
   const mirrorRoot = path.resolve(options.mirrorRoot);
   const branch = options.branch ?? 'dev';
   const remote = options.remote ?? 'origin';
   const remoteRef = `${remote}/${branch}`;
-  const localRef = normalizeLocalSourceRef(options.ref);
+  const requestedRef = normalizeLocalSourceRef(options.ref);
+  const worktreeMode = requestedRef === PYGMALION_WORKTREE_SOURCE_REF;
+  const localRef = worktreeMode
+    ? await resolveWorktreeSourceCommit(repoRoot, options.onWarning)
+    : requestedRef;
   const managedPaths = normalizeManagedOutputPaths(options.managedPaths);
   let warning = null;
   let switchTarget = null;
@@ -266,7 +369,8 @@ export function pygmalionDevMirrorPlugin(options) {
   const repoRoot = path.resolve(options.projectRoot ?? path.resolve(editorRoot, '..'));
   const branch = options.branch ?? 'dev';
   const remote = options.remote ?? 'origin';
-  const ref = options.ref;
+  // Mutable so the editor can repoint the mirror without a server restart.
+  let ref = normalizeLocalSourceRef(options.ref);
   const appDirectory = options.appDirectory ?? path.relative(repoRoot, editorRoot);
   const mirrorRoot = path.resolve(
     process.env.PYGMALION_DEV_WORKTREE ||
@@ -278,6 +382,10 @@ export function pygmalionDevMirrorPlugin(options) {
     options.previewConfig ?? fileURLToPath(new URL('./dev-view.vite.mjs', import.meta.url)),
   );
   const viteConfig = path.resolve(options.viteConfig ?? path.join(mirrorAppRoot, 'vite.config.ts'));
+  // The mirror is a separate Vite process, so the editor's own `--mode` never
+  // reaches it. Hosts whose captured screens need a specific env file (a feature
+  // flag a screen depends on, a mock profile) declare that mode here.
+  const previewMode = normalizeViteMode(options.previewMode);
   const inventory = options.inventory;
   const inventoryOutputs = normalizeManagedOutputPaths(inventory?.outputs);
   const managedPaths = normalizeManagedOutputPaths(
@@ -300,6 +408,7 @@ export function pygmalionDevMirrorPlugin(options) {
     state: 'idle',
     commit: null,
     shortCommit: null,
+    sourceRef: ref,
     syncedAt: null,
     updated: false,
     warning: null,
@@ -450,6 +559,7 @@ export function pygmalionDevMirrorPlugin(options) {
         viteBin,
         '--config',
         wrapperConfig,
+        ...(previewMode ? ['--mode', previewMode] : []),
         '--host',
         '127.0.0.1',
         '--port',
@@ -487,7 +597,14 @@ export function pygmalionDevMirrorPlugin(options) {
     await waitUntilReady(previewPort, mirrorAppRoot, prefix);
   };
 
-  const syncMirror = async () => {
+  const syncMirror = async (nextRef) => {
+    if (nextRef !== undefined) {
+      const normalized = normalizeLocalSourceRef(nextRef);
+      // A ref change invalidates the mirror checkout, so it must not land while
+      // a sync is already materializing the previous one.
+      if (syncPromise) await syncPromise.catch(() => undefined);
+      ref = normalized;
+    }
     if (syncPromise) return syncPromise;
     syncPromise = (async () => {
       status = { ...status, state: 'syncing', error: null, warning: null };
@@ -516,6 +633,7 @@ export function pygmalionDevMirrorPlugin(options) {
             state: 'ready',
             commit,
             shortCommit,
+            sourceRef: ref,
             syncedAt: new Date().toISOString(),
             updated: previous !== commit,
             warning,
@@ -556,7 +674,26 @@ export function pygmalionDevMirrorPlugin(options) {
           return;
         }
         if (url.pathname === `${control}/refresh` && req.method === 'POST') {
-          const nextStatus = await syncMirror();
+          let requestedRef;
+          try {
+            requestedRef = await readRefFromRequest(req);
+          } catch (error) {
+            json(res, 400, {
+              ok: false,
+              error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+          }
+          let nextStatus;
+          try {
+            nextStatus = await syncMirror(requestedRef);
+          } catch (error) {
+            json(res, 400, {
+              ok: false,
+              error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+          }
           json(res, nextStatus.state === 'ready' ? 200 : 409, nextStatus);
           return;
         }

package/node/vite.mjs

@@ -2,6 +2,7 @@ import path from 'node:path';
 import {
   PYGMALION_DEV_CONTROL,
   PYGMALION_DEV_PREFIX,
+  PYGMALION_WORKTREE_SOURCE_REF,
   pygmalionDevMirrorPlugin,
 } from './dev-mirror.mjs';
 import {
@@ -267,6 +268,7 @@ export function createPygmalionVitePlugins(config) {
         previewConfig: project.preview.configFile,
         viteConfig: project.preview.viteConfig,
         viteBin: project.preview.viteBin,
+        previewMode: project.preview.mode,
         previewPort: project.mirror.previewPort ?? project.preview.mirrorPort,
         prefix: normalizeEndpoint(
           project.mirror.prefix,
@@ -298,6 +300,7 @@ export function createPygmalionVitePlugins(config) {
         previewConfig: project.preview.configFile,
         viteConfig: project.preview.viteConfig,
         viteBin: project.preview.viteBin,
+        previewMode: project.preview.mode,
         previewPort:
           project.sessions.previewPort ?? project.preview.sessionPort,
         worktreesRoot: project.sessions.worktreesRoot,
@@ -321,6 +324,7 @@ export function createPygmalionVitePlugins(config) {
 export {
   PYGMALION_DEV_CONTROL,
   PYGMALION_DEV_PREFIX,
+  PYGMALION_WORKTREE_SOURCE_REF,
   PYGMALION_INSPECT_CONTROL,
   PYGMALION_SESSION_CONTROL,
   PYGMALION_SESSION_PREFIX,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {

package/types.d.ts

@@ -1455,6 +1455,8 @@ export interface PygmalionDevMirrorStatus {
   state: 'idle' | 'syncing' | 'ready' | 'error';
   commit: string | null;
   shortCommit: string | null;
+  /** Git ref the mirror is tracking, or null when it follows the source branch. */
+  sourceRef: string | null;
   syncedAt: string | null;
   updated: boolean;
   warning: string | null;
@@ -1555,7 +1557,16 @@ export interface PygmalionProjectRuntime {
    * namespaces from it instead of parsing previewRevision themselves.
    */
   previewSourceRevision: string;
-  refresh(manual?: boolean): Promise<void>;
+  refresh(manual?: boolean, sourceRef?: string): Promise<void>;
+  /**
+   * Repoints the mirror at another git ref without restarting the dev server.
+   * Pass PYGMALION_WORKTREE_SOURCE_REF to preview uncommitted work.
+   * The artifact cache is keyed by source SHA, so a switch invalidates it.
+   */
+  switchSource(
+    sourceRef: string,
+    options?: { discardEdits?: boolean },
+  ): Promise<void>;
   previewVisual(payload: InspectApplyPayload): Promise<InspectPreviewResult>;
   inspectImpact(componentFiles: string[]): Promise<InspectImpactResult>;
   applyVisual(payload: InspectApplyPayload): Promise<InspectApplyResult>;

package/vite.d.ts

@@ -60,6 +60,15 @@ export interface PygmalionPreviewConfig {
   configFile?: string;
   viteConfig?: string;
   viteBin?: string;
+  /**
+   * Vite mode for the mirror and session preview servers.
+   *
+   * Those run as separate Vite processes, so the editor's own `--mode` never
+   * reaches the previewed application. Set this when a captured screen depends
+   * on a specific env file — for example a feature flag that has to be off for
+   * the screen to exist at all. Defaults to Vite's own default mode.
+   */
+  mode?: string;
   mirrorPort?: number;
   sessionPort?: number;
   artifactFile?: string;
@@ -548,3 +557,6 @@ export declare function findAffectedSourceFiles(
   componentFiles: string[],
   options?: PygmalionSourceGraphOptions,
 ): Promise<string[]>;
+
+/** source.ref value that previews the current working tree, uncommitted changes included. */
+export declare const PYGMALION_WORKTREE_SOURCE_REF: 'worktree';