@pygmalionjs/pygmalion 0.2.15 → 0.2.16

package/node/dev-mirror.mjs

@@ -114,12 +114,32 @@ 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;
 }
 
 /**
@@ -173,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);
@@ -191,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;
@@ -284,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 ||
@@ -322,6 +408,7 @@ export function pygmalionDevMirrorPlugin(options) {
     state: 'idle',
     commit: null,
     shortCommit: null,
+    sourceRef: ref,
     syncedAt: null,
     updated: false,
     warning: null,
@@ -510,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 };
@@ -539,6 +633,7 @@ export function pygmalionDevMirrorPlugin(options) {
             state: 'ready',
             commit,
             shortCommit,
+            sourceRef: ref,
             syncedAt: new Date().toISOString(),
             updated: previous !== commit,
             warning,
@@ -579,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 {
@@ -323,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.15",
+  "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

@@ -557,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';