@pygmalionjs/pygmalion 0.2.15 → 0.2.17

package/node/dev-mirror.mjs

@@ -114,12 +114,60 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * Revisions the mirror can be repointed at: local branches first, then remote
+ * tracking branches. Listing them is what lets an editor offer a choice instead
+ * of asking for a ref string.
+ */
+export async function listSourceRefs(repoRoot, remote = 'origin') {
+  const format = '%(refname:short)%09%(objectname:short=8)%09%(refname)';
+  const read = async (...patterns) => {
+    const raw = await git(repoRoot, 'for-each-ref', `--format=${format}`, ...patterns);
+    if (!raw) return [];
+    return raw
+      .split('\n')
+      .map((line) => line.split('\t'))
+      .filter((parts) => parts.length === 3 && parts[0])
+      .map(([name, commit, fullName]) => ({ name, commit, fullName }));
+  };
+  const locals = (await read('refs/heads')).map((item) => ({ ...item, kind: 'local' }));
+  const remotes = (await read(`refs/remotes/${remote}`))
+    .filter((item) => !item.name.endsWith('/HEAD'))
+    .map((item) => ({ ...item, kind: 'remote' }));
+  const seen = new Set();
+  return [...locals, ...remotes].filter((item) => {
+    if (seen.has(item.name)) return false;
+    seen.add(item.name);
+    return true;
+  });
+}
+
+/**
+ * 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 +221,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 +271,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 +397,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 +436,7 @@ export function pygmalionDevMirrorPlugin(options) {
     state: 'idle',
     commit: null,
     shortCommit: null,
+    sourceRef: ref,
     syncedAt: null,
     updated: false,
     warning: null,
@@ -510,7 +625,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 +661,7 @@ export function pygmalionDevMirrorPlugin(options) {
             state: 'ready',
             commit,
             shortCommit,
+            sourceRef: ref,
             syncedAt: new Date().toISOString(),
             updated: previous !== commit,
             warning,
@@ -578,8 +701,43 @@ export function pygmalionDevMirrorPlugin(options) {
           json(res, 200, status);
           return;
         }
+        if (url.pathname === `${control}/refs` && req.method === 'GET') {
+          try {
+            json(res, 200, {
+              refs: await listSourceRefs(repoRoot, remote),
+              sourceRef: ref,
+              defaultRef: `${remote}/${branch}`,
+              worktreeRef: PYGMALION_WORKTREE_SOURCE_REF,
+            });
+          } catch (error) {
+            json(res, 500, {
+              ok: false,
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+          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.17",
   "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;
@@ -1543,6 +1545,37 @@ export interface PygmalionProjectRuntimeOptions {
   ) => string | undefined;
 }
 
+/** One revision the mirror can be repointed at. */
+export interface PygmalionSourceRef {
+  name: string;
+  commit: string;
+  fullName: string;
+  kind: 'local' | 'remote';
+}
+
+/** Revisions available to `switchSource`, listed from the mirror repository. */
+export interface PygmalionSourceRefs {
+  refs: readonly PygmalionSourceRef[];
+  /** Revision followed when none is pinned. */
+  defaultRef: string | null;
+  /** Ref that renders uncommitted work. */
+  worktreeRef: string | null;
+}
+
+export interface SourceRefControlProps {
+  value: string | null;
+  refs: readonly PygmalionSourceRef[];
+  onChange(ref: string): void;
+  busy?: boolean;
+  defaultRef?: string | null;
+  worktreeRef?: string | null;
+  label?: string;
+  className?: string;
+}
+
+/** Selects the revision the dev mirror follows. Owned by Pygmalion, not by the host. */
+export declare function SourceRefControl(props: SourceRefControlProps): ReactElement;
+
 export interface PygmalionProjectRuntime {
   mirror: PygmalionDevMirrorStatus;
   session: PygmalionDesignSessionStatus | null;
@@ -1555,7 +1588,22 @@ 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>;
+  /**
+   * Revisions `switchSource` can be given. Empty until listed, so a host can
+   * offer a choice instead of asking for a ref string.
+   */
+  sourceRefs: PygmalionSourceRefs;
+  loadSourceRefs(): Promise<PygmalionSourceRefs>;
   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';