handoff-app 1.2.0-0 → 1.2.0-2

package/src/transformers/preview/pattern/api.ts

@@ -46,6 +46,23 @@ export const writePatternSummaryApi = async (
   );
 };
 
+/**
+ * Reads the pattern list summary when present (used for partial pattern rebuilds).
+ */
+export const readPatternSummaryApi = async (handoff: Handoff): Promise<PatternListObject[] | null> => {
+  const summaryPath = path.resolve(handoff.workingPath, 'public/api/patterns.json');
+  if (!fs.existsSync(summaryPath)) {
+    return null;
+  }
+  try {
+    const raw = await fs.readFile(summaryPath, 'utf8');
+    const parsed = JSON.parse(raw) as PatternListObject[];
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
 export const syncPatternArtifacts = async (
   handoff: Handoff,
   validIds: Iterable<string>

package/src/transformers/preview/pattern/builder.ts

@@ -2,93 +2,191 @@ import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '../../../index';
 import { Logger } from '../../../utils/logger';
-import { PatternListObject } from '../types';
-import { syncPatternArtifacts, writePatternApi, writePatternHtml, writePatternSummaryApi } from './api';
+import { PatternListObject, PatternObject } from '../types';
+import { readPatternSummaryApi, syncPatternArtifacts, writePatternApi, writePatternHtml, writePatternSummaryApi } from './api';
 import { composePatternHtml } from './html';
 
+export type ProcessPatternsOptions = {
+  /** When set, only these pattern ids are recomposed; others keep existing artifacts. */
+  onlyPatternIds?: Set<string>;
+};
+
+/**
+ * Returns pattern ids whose declarations reference any of the given component ids.
+ */
+export const getPatternIdsReferencingComponents = (handoff: Handoff, componentIds: string[]): string[] => {
+  if (componentIds.length === 0) {
+    return [];
+  }
+  const idSet = new Set(componentIds);
+  const runtimePatterns = handoff.runtimeConfig?.entries?.patterns ?? {};
+  const result: string[] = [];
+
+  for (const patternId of Object.keys(runtimePatterns)) {
+    const pattern = runtimePatterns[patternId];
+    if (pattern.components?.some((ref) => idSet.has(ref.id))) {
+      result.push(patternId);
+    }
+  }
+
+  return result;
+};
+
+async function buildPattern(
+  handoff: Handoff,
+  patternId: string,
+  pattern: PatternObject,
+  componentOutputDir: string,
+  basePath: string
+): Promise<PatternListObject | null> {
+  const fragments: { componentId: string; html: string }[] = [];
+  let hasErrors = false;
+
+  for (let i = 0; i < pattern.components.length; i++) {
+    const ref = pattern.components[i];
+
+    if (ref.resolved === false && !ref.resolvedPreview) {
+      hasErrors = true;
+      continue;
+    }
+
+    const previewKey = ref.resolvedPreview || ref.preview;
+    if (!previewKey) {
+      const error =
+        `Pattern "${patternId}" component[${i}] ("${ref.id}") has no resolved preview key. Skipping.`;
+      Logger.warn(error);
+      ref.resolved = false;
+      hasErrors = true;
+      continue;
+    }
+    const htmlFileName = `${ref.id}-${previewKey}.html`;
+    const htmlFilePath = path.resolve(componentOutputDir, htmlFileName);
+
+    if (!fs.existsSync(htmlFilePath)) {
+      const error =
+        `Pattern "${patternId}" component[${i}] ("${ref.id}") preview file not found: ${htmlFileName}. ` +
+        `Ensure the component has a preview named "${previewKey}".`;
+      Logger.warn(error);
+      ref.resolved = false;
+      hasErrors = true;
+      continue;
+    }
+
+    ref.resolved = true;
+    const html = await fs.readFile(htmlFilePath, 'utf8');
+    fragments.push({ componentId: ref.id, html });
+  }
+
+  if (fragments.length === 0) {
+    Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
+    return null;
+  }
+
+  if (hasErrors) {
+    Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
+  }
+
+  const composedHtml = composePatternHtml(patternId, pattern.title, fragments, basePath);
+  const patternUrl = `${patternId}.html`;
+
+  const patternData: PatternListObject = {
+    ...pattern,
+    id: patternId,
+    url: patternUrl,
+    path: `${basePath}/api/pattern/${patternId}.json`,
+  };
+
+  await writePatternHtml(patternId, composedHtml, handoff);
+  await writePatternApi(patternId, patternData, handoff);
+
+  Logger.debug(`Built pattern: ${patternId} (${fragments.length} component(s))`);
+  return patternData;
+}
+
 /**
  * Process all pattern declarations and compose their HTML from pre-built
  * component preview files. This function must run AFTER buildComponents
  * so that all component preview HTML files already exist on disk.
  */
-export async function processPatterns(handoff: Handoff): Promise<PatternListObject[]> {
+export async function processPatterns(handoff: Handoff, options?: ProcessPatternsOptions): Promise<PatternListObject[]> {
   const runtimePatterns = handoff.runtimeConfig?.entries?.patterns ?? {};
   const patternIds = Object.keys(runtimePatterns);
-  const result: PatternListObject[] = [];
+  const onlyPatternIds = options?.onlyPatternIds;
+  const isPartial = onlyPatternIds !== undefined;
 
   if (patternIds.length === 0) {
     await syncPatternArtifacts(handoff, []);
-    await writePatternSummaryApi(handoff, result);
-    return result;
+    await writePatternSummaryApi(handoff, []);
+    return [];
   }
 
-  Logger.info(`Building ${patternIds.length} pattern(s)...`);
-
   const componentOutputDir = path.resolve(handoff.workingPath, 'public/api/component');
   const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
 
-  for (const patternId of patternIds) {
-    const pattern = runtimePatterns[patternId];
-    const fragments: { componentId: string; html: string }[] = [];
-    let hasErrors = false;
-
-    for (let i = 0; i < pattern.components.length; i++) {
-      const ref = pattern.components[i];
-
-      if (ref.resolved === false && !ref.resolvedPreview) {
-        hasErrors = true;
-        continue;
-      }
+  if (!isPartial) {
+    Logger.info(`Building ${patternIds.length} pattern(s)...`);
+    const result: PatternListObject[] = [];
 
-      const previewKey = ref.resolvedPreview || ref.preview || 'default';
-      const htmlFileName = `${ref.id}-${previewKey}.html`;
-      const htmlFilePath = path.resolve(componentOutputDir, htmlFileName);
-
-      if (!fs.existsSync(htmlFilePath)) {
-        const error =
-          `Pattern "${patternId}" component[${i}] ("${ref.id}") preview file not found: ${htmlFileName}. ` +
-          `Ensure the component has a preview named "${previewKey}".`;
-        Logger.warn(error);
-        ref.resolved = false;
-        hasErrors = true;
-        continue;
+    for (const patternId of patternIds) {
+      const pattern = runtimePatterns[patternId];
+      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+      if (built) {
+        result.push(built);
       }
-
-      ref.resolved = true;
-      const html = await fs.readFile(htmlFilePath, 'utf8');
-      fragments.push({ componentId: ref.id, html });
     }
 
-    if (fragments.length === 0) {
-      Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
-      continue;
-    }
+    await syncPatternArtifacts(handoff, result.map((p) => p.id));
+    await writePatternSummaryApi(handoff, result);
+    Logger.info(`Finished building ${result.length} pattern(s).`);
+    return result;
+  }
 
-    if (hasErrors) {
-      Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
-    }
+  if (onlyPatternIds.size === 0) {
+    const existing = await readPatternSummaryApi(handoff);
+    return existing ?? [];
+  }
 
-    const composedHtml = composePatternHtml(patternId, pattern.title, fragments, basePath);
-    const patternUrl = `${patternId}.html`;
+  const existingList = await readPatternSummaryApi(handoff);
+  if (!existingList) {
+    Logger.warn('Partial pattern rebuild requested but patterns.json is missing; rebuilding all patterns.');
+    return processPatterns(handoff);
+  }
+
+  const existingById = new Map(existingList.map((p) => [p.id, p]));
 
-    const patternData: PatternListObject = {
-      ...pattern,
-      url: patternUrl,
-      path: `${basePath}/api/pattern/${patternId}.json`,
-    };
+  Logger.info(`Rebuilding ${onlyPatternIds.size} of ${patternIds.length} pattern(s) (incremental)...`);
 
-    await writePatternHtml(patternId, composedHtml, handoff);
-    await writePatternApi(patternId, patternData, handoff);
+  for (const patternId of patternIds) {
+    if (onlyPatternIds.has(patternId)) {
+      const pattern = runtimePatterns[patternId];
+      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+      if (built) {
+        existingById.set(patternId, built);
+      } else {
+        existingById.delete(patternId);
+      }
+    } else if (!existingById.has(patternId)) {
+      const pattern = runtimePatterns[patternId];
+      const built = await buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+      if (built) {
+        existingById.set(patternId, built);
+      }
+    }
+  }
 
-    result.push(patternData);
-    Logger.debug(`Built pattern: ${patternId} (${fragments.length} component(s))`);
+  const merged: PatternListObject[] = [];
+  for (const patternId of patternIds) {
+    const entry = existingById.get(patternId);
+    if (entry) {
+      merged.push(entry);
+    }
   }
 
-  await syncPatternArtifacts(handoff, result.map((pattern) => pattern.id));
-  await writePatternSummaryApi(handoff, result);
-  Logger.info(`Finished building ${result.length} pattern(s).`);
+  await syncPatternArtifacts(handoff, merged.map((p) => p.id));
+  await writePatternSummaryApi(handoff, merged);
+  Logger.info(`Finished incremental pattern build (${onlyPatternIds.size} recomposed).`);
 
-  return result;
+  return merged;
 }
 
 export default processPatterns;

package/src/transformers/utils/vite-logger.ts

@@ -7,20 +7,20 @@ export const createViteLogger = (): ViteLogger => {
   return {
     hasWarned: false,
     info(msg: string, options?: LogOptions) {
-      Logger.info(msg);
+      Logger.info(msg, 'vite');
     },
     warn(msg: string, options?: LogOptions) {
       this.hasWarned = true;
-      Logger.warn(msg);
+      Logger.warn(msg, 'vite');
     },
     warnOnce(msg: string, options?: LogOptions) {
       if (warnedMessages.has(msg)) return;
       warnedMessages.add(msg);
       this.hasWarned = true;
-      Logger.warn(msg);
+      Logger.warn(msg, 'vite');
     },
     error(msg: string, options?: LogOptions) {
-      Logger.error(msg);
+      Logger.error(msg, undefined, 'vite');
     },
     clearScreen(type: string) {
       // No-op to preserve terminal history

package/src/transformers/vite-config.ts

@@ -1,7 +1,9 @@
 // vite.config.ts
 import { defineConfig } from 'vite';
+import { createViteLogger } from './utils/vite-logger';
 
 export default defineConfig({
+  customLogger: createViteLogger(),
   publicDir: false,
   build: {
     lib: {

package/src/utils/duration.ts

@@ -0,0 +1,3 @@
+/** Human-readable duration for CLI build logs (ms under 1s, seconds with 2 decimals otherwise). */
+export const formatDurationMs = (elapsedMs: number): string =>
+  elapsedMs < 1000 ? `${Math.round(elapsedMs)}ms` : `${(elapsedMs / 1000).toFixed(2)}s`;

package/src/utils/logger.ts

@@ -1,12 +1,78 @@
+import readline from 'readline';
+
 import chalk from 'chalk';
 
+/** Logical source of a log line — used for a fixed-width–style colored tag after the timestamp. */
+export type LogScope = 'handoff' | 'vite' | 'next';
+
+/**
+ * Env (e.g. project `.env` via `dotenv/config`):
+ * - `HANDOFF_LOG_LEVEL` — `debug` | `info` | `warn` | `error` | `silent` (default: `info`).
+ *   Controls minimum severity: at `warn`, info/success/debug lines are hidden; at `error`, only errors.
+ * - `HANDOFF_LOG_SCOPES` — comma-separated allowlist: `handoff`, `vite`, `next`. Defaults to all three if unset or empty.
+ *
+ * Programmatic `Logger.init({ debug: true })` (Handoff `debug` flag) forces debug-level verbosity unless overridden.
+ */
 export class Logger {
+  /** From Handoff constructor; enables debug lines together with env. */
   private static debugMode = false;
 
+  /** Minimum message severity to print: 0=debug, 1=info, 2=warn, 3=error. `silent` uses 99. */
+  private static severityThreshold = 1;
+
+  /** Enabled scopes; defaults to all of `handoff`, `vite`, `next`. */
+  private static scopesFilter: Set<LogScope> = new Set<LogScope>(['handoff', 'vite', 'next']);
+
   static init(options?: { debug?: boolean }) {
+    this.applyEnvConfig();
     if (options?.debug !== undefined) {
       this.debugMode = options.debug;
     }
+    if (options?.debug === true) {
+      this.severityThreshold = 0;
+    }
+  }
+
+  /** Re-read `process.env` (useful if env is loaded after first `init`). */
+  static applyEnvConfig() {
+    this.severityThreshold = 1;
+    const allScopes: LogScope[] = ['handoff', 'vite', 'next'];
+    this.scopesFilter = new Set(allScopes);
+
+    const levelRaw = process.env.HANDOFF_LOG_LEVEL?.trim().toLowerCase();
+    const levelMap: Record<string, number> = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+      silent: 99,
+    };
+    if (levelRaw && levelRaw in levelMap) {
+      this.severityThreshold = levelMap[levelRaw];
+    }
+
+    const scopesRaw = process.env.HANDOFF_LOG_SCOPES?.trim();
+    if (scopesRaw) {
+      const set = new Set<LogScope>();
+      for (const part of scopesRaw.split(',')) {
+        const s = part.trim().toLowerCase();
+        if (s === 'handoff' || s === 'vite' || s === 'next') {
+          set.add(s);
+        }
+      }
+      if (set.size > 0) {
+        this.scopesFilter = set;
+      }
+    }
+  }
+
+  private static scopeEnabled(scope: LogScope): boolean {
+    return this.scopesFilter.has(scope);
+  }
+
+  /** Message severities: debug=0, info-tier=1, warn=2, error=3 */
+  private static shouldEmit(severity: 0 | 1 | 2 | 3): boolean {
+    return severity >= this.severityThreshold;
   }
 
   private static getTimestamp(): string {
@@ -14,36 +80,97 @@ export class Logger {
     return chalk.gray(`[${now.toISOString()}]`);
   }
 
-  static log(message: string) {
-    console.log(`${this.getTimestamp()} ${message}`);
+  /** Short label shown after the timestamp so you can scan for handoff vs vite vs next. */
+  private static scopeTag(scope: LogScope): string {
+    const tags: Record<LogScope, string> = {
+      handoff: chalk.blue.bold('[handoff]'),
+      vite: chalk.magenta.bold('[vite]'),
+      next: chalk.green.bold('[next]'),
+    };
+    return tags[scope];
+  }
+
+  private static basePrefix(scope: LogScope): string {
+    return `${this.getTimestamp()} ${this.scopeTag(scope)}`;
+  }
+
+  static log(message: string, scope: LogScope = 'handoff') {
+    if (!this.scopeEnabled(scope) || !this.shouldEmit(1)) return;
+    console.log(`${this.basePrefix(scope)} ${message}`);
   }
 
-  static info(message: string) {
-    console.log(`${this.getTimestamp()} ${chalk.cyan(message)}`);
+  /**
+   * Vite often passes strings that already contain ANSI; avoid wrapping those in chalk.cyan so colors stay correct.
+   */
+  static info(message: string, scope: LogScope = 'handoff') {
+    if (!this.scopeEnabled(scope) || !this.shouldEmit(1)) return;
+    const body = scope === 'vite' ? message : chalk.cyan(message);
+    console.log(`${this.basePrefix(scope)} ${body}`);
   }
 
-  static success(message: string) {
-    console.log(`${this.getTimestamp()} ${chalk.green(message)}`);
+  static success(message: string, scope: LogScope = 'handoff') {
+    if (!this.scopeEnabled(scope) || !this.shouldEmit(1)) return;
+    console.log(`${this.basePrefix(scope)} ${chalk.green(message)}`);
   }
 
-  static warn(message: string) {
-    console.warn(`${this.getTimestamp()} ${chalk.yellow(message)}`);
+  static warn(message: string, scope: LogScope = 'handoff') {
+    if (!this.scopeEnabled(scope) || !this.shouldEmit(2)) return;
+    const body = scope === 'vite' ? message : chalk.yellow(message);
+    console.warn(`${this.basePrefix(scope)} ${body}`);
   }
 
-  static error(message: string, error?: any) {
-    console.error(`${this.getTimestamp()} ${chalk.red(message)}`);
+  static error(message: string, error?: any, scope: LogScope = 'handoff') {
+    if (!this.scopeEnabled(scope) || !this.shouldEmit(3)) return;
+    const body = scope === 'vite' ? message : chalk.red(message);
+    console.error(`${this.basePrefix(scope)} ${body}`);
     if (error) {
       console.error(error);
     }
   }
 
   static debug(message: string, data?: any) {
-    if (this.debugMode) {
-      console.log(`${this.getTimestamp()} ${chalk.gray(`[DEBUG] ${message}`)}`);
-      if (data) {
-        console.log(data);
-      }
+    if (this.severityThreshold >= 99) return;
+    if (!this.scopeEnabled('handoff')) return;
+    const allowDebug = this.debugMode || this.severityThreshold === 0;
+    if (!allowDebug) return;
+    console.log(`${this.basePrefix('handoff')} ${chalk.gray(`[DEBUG] ${message}`)}`);
+    if (data) {
+      console.log(data);
     }
   }
-}
 
+  /**
+   * Log one line from a child process with timestamp + scope tag. Child ANSI is preserved (no extra chalk on the line).
+   */
+  static childProcessLine(line: string, scope: LogScope = 'next') {
+    if (!this.scopeEnabled(scope) || !this.shouldEmit(1)) return;
+    console.log(`${this.basePrefix(scope)} ${line}`);
+  }
+
+  /**
+   * Pipe stdout/stderr from a spawned child through {@link childProcessLine}. Use with
+   * `stdio: ['inherit' | 'ignore', 'pipe', 'pipe']`.
+   */
+  static pipeChildStreams(
+    stdout: NodeJS.ReadableStream | null,
+    stderr: NodeJS.ReadableStream | null,
+    scope: LogScope = 'next'
+  ) {
+    for (const stream of [stdout, stderr]) {
+      if (!stream) continue;
+      const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+      rl.on('line', (line) => {
+        this.childProcessLine(line, scope);
+      });
+    }
+  }
+
+  /** Forward a completed child-process buffer (e.g. from `spawn.sync` with stdio pipe) line-by-line. */
+  static childProcessBuffer(buffer: Buffer | null | undefined, scope: LogScope = 'next') {
+    if (!buffer?.length) return;
+    const text = buffer.toString('utf8');
+    for (const line of text.split(/\r?\n/)) {
+      this.childProcessLine(line, scope);
+    }
+  }
+}