handoff-app 1.2.0-0 → 1.2.0-1

package/dist/transformers/preview/pattern/builder.js

@@ -12,75 +12,156 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPatternIdsReferencingComponents = void 0;
 exports.processPatterns = processPatterns;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../../../utils/logger");
 const api_1 = require("./api");
 const html_1 = require("./html");
+/**
+ * Returns pattern ids whose declarations reference any of the given component ids.
+ */
+const getPatternIdsReferencingComponents = (handoff, componentIds) => {
+    var _a, _b, _c, _d;
+    if (componentIds.length === 0) {
+        return [];
+    }
+    const idSet = new Set(componentIds);
+    const runtimePatterns = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {};
+    const result = [];
+    for (const patternId of Object.keys(runtimePatterns)) {
+        const pattern = runtimePatterns[patternId];
+        if ((_d = pattern.components) === null || _d === void 0 ? void 0 : _d.some((ref) => idSet.has(ref.id))) {
+            result.push(patternId);
+        }
+    }
+    return result;
+};
+exports.getPatternIdsReferencingComponents = getPatternIdsReferencingComponents;
+function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const fragments = [];
+        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_1.Logger.warn(error);
+                ref.resolved = false;
+                hasErrors = true;
+                continue;
+            }
+            const htmlFileName = `${ref.id}-${previewKey}.html`;
+            const htmlFilePath = path_1.default.resolve(componentOutputDir, htmlFileName);
+            if (!fs_extra_1.default.existsSync(htmlFilePath)) {
+                const error = `Pattern "${patternId}" component[${i}] ("${ref.id}") preview file not found: ${htmlFileName}. ` +
+                    `Ensure the component has a preview named "${previewKey}".`;
+                logger_1.Logger.warn(error);
+                ref.resolved = false;
+                hasErrors = true;
+                continue;
+            }
+            ref.resolved = true;
+            const html = yield fs_extra_1.default.readFile(htmlFilePath, 'utf8');
+            fragments.push({ componentId: ref.id, html });
+        }
+        if (fragments.length === 0) {
+            logger_1.Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
+            return null;
+        }
+        if (hasErrors) {
+            logger_1.Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
+        }
+        const composedHtml = (0, html_1.composePatternHtml)(patternId, pattern.title, fragments, basePath);
+        const patternUrl = `${patternId}.html`;
+        const patternData = Object.assign(Object.assign({}, pattern), { id: patternId, url: patternUrl, path: `${basePath}/api/pattern/${patternId}.json` });
+        yield (0, api_1.writePatternHtml)(patternId, composedHtml, handoff);
+        yield (0, api_1.writePatternApi)(patternId, patternData, handoff);
+        logger_1.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.
  */
-function processPatterns(handoff) {
+function processPatterns(handoff, options) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d;
         const runtimePatterns = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {};
         const patternIds = Object.keys(runtimePatterns);
-        const result = [];
+        const onlyPatternIds = options === null || options === void 0 ? void 0 : options.onlyPatternIds;
+        const isPartial = onlyPatternIds !== undefined;
         if (patternIds.length === 0) {
             yield (0, api_1.syncPatternArtifacts)(handoff, []);
-            yield (0, api_1.writePatternSummaryApi)(handoff, result);
-            return result;
+            yield (0, api_1.writePatternSummaryApi)(handoff, []);
+            return [];
         }
-        logger_1.Logger.info(`Building ${patternIds.length} pattern(s)...`);
         const componentOutputDir = path_1.default.resolve(handoff.workingPath, 'public/api/component');
         const basePath = (_d = process.env.HANDOFF_APP_BASE_PATH) !== null && _d !== void 0 ? _d : '';
+        if (!isPartial) {
+            logger_1.Logger.info(`Building ${patternIds.length} pattern(s)...`);
+            const result = [];
+            for (const patternId of patternIds) {
+                const pattern = runtimePatterns[patternId];
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                if (built) {
+                    result.push(built);
+                }
+            }
+            yield (0, api_1.syncPatternArtifacts)(handoff, result.map((p) => p.id));
+            yield (0, api_1.writePatternSummaryApi)(handoff, result);
+            logger_1.Logger.info(`Finished building ${result.length} pattern(s).`);
+            return result;
+        }
+        if (onlyPatternIds.size === 0) {
+            const existing = yield (0, api_1.readPatternSummaryApi)(handoff);
+            return existing !== null && existing !== void 0 ? existing : [];
+        }
+        const existingList = yield (0, api_1.readPatternSummaryApi)(handoff);
+        if (!existingList) {
+            logger_1.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]));
+        logger_1.Logger.info(`Rebuilding ${onlyPatternIds.size} of ${patternIds.length} pattern(s) (incremental)...`);
         for (const patternId of patternIds) {
-            const pattern = runtimePatterns[patternId];
-            const fragments = [];
-            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 (onlyPatternIds.has(patternId)) {
+                const pattern = runtimePatterns[patternId];
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                if (built) {
+                    existingById.set(patternId, built);
                 }
-                const previewKey = ref.resolvedPreview || ref.preview || 'default';
-                const htmlFileName = `${ref.id}-${previewKey}.html`;
-                const htmlFilePath = path_1.default.resolve(componentOutputDir, htmlFileName);
-                if (!fs_extra_1.default.existsSync(htmlFilePath)) {
-                    const error = `Pattern "${patternId}" component[${i}] ("${ref.id}") preview file not found: ${htmlFileName}. ` +
-                        `Ensure the component has a preview named "${previewKey}".`;
-                    logger_1.Logger.warn(error);
-                    ref.resolved = false;
-                    hasErrors = true;
-                    continue;
+                else {
+                    existingById.delete(patternId);
                 }
-                ref.resolved = true;
-                const html = yield fs_extra_1.default.readFile(htmlFilePath, 'utf8');
-                fragments.push({ componentId: ref.id, html });
             }
-            if (fragments.length === 0) {
-                logger_1.Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
-                continue;
+            else if (!existingById.has(patternId)) {
+                const pattern = runtimePatterns[patternId];
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                if (built) {
+                    existingById.set(patternId, built);
+                }
             }
-            if (hasErrors) {
-                logger_1.Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
+        }
+        const merged = [];
+        for (const patternId of patternIds) {
+            const entry = existingById.get(patternId);
+            if (entry) {
+                merged.push(entry);
             }
-            const composedHtml = (0, html_1.composePatternHtml)(patternId, pattern.title, fragments, basePath);
-            const patternUrl = `${patternId}.html`;
-            const patternData = Object.assign(Object.assign({}, pattern), { url: patternUrl, path: `${basePath}/api/pattern/${patternId}.json` });
-            yield (0, api_1.writePatternHtml)(patternId, composedHtml, handoff);
-            yield (0, api_1.writePatternApi)(patternId, patternData, handoff);
-            result.push(patternData);
-            logger_1.Logger.debug(`Built pattern: ${patternId} (${fragments.length} component(s))`);
         }
-        yield (0, api_1.syncPatternArtifacts)(handoff, result.map((pattern) => pattern.id));
-        yield (0, api_1.writePatternSummaryApi)(handoff, result);
-        logger_1.Logger.info(`Finished building ${result.length} pattern(s).`);
-        return result;
+        yield (0, api_1.syncPatternArtifacts)(handoff, merged.map((p) => p.id));
+        yield (0, api_1.writePatternSummaryApi)(handoff, merged);
+        logger_1.Logger.info(`Finished incremental pattern build (${onlyPatternIds.size} recomposed).`);
+        return merged;
     });
 }
 exports.default = processPatterns;

package/dist/transformers/utils/vite-logger.js

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

package/dist/transformers/vite-config.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 // vite.config.ts
 const vite_1 = require("vite");
+const vite_logger_1 = require("./utils/vite-logger");
 exports.default = (0, vite_1.defineConfig)({
+    customLogger: (0, vite_logger_1.createViteLogger)(),
     publicDir: false,
     build: {
         lib: {

package/dist/utils/duration.d.ts

@@ -0,0 +1,2 @@
+/** Human-readable duration for CLI build logs (ms under 1s, seconds with 2 decimals otherwise). */
+export declare const formatDurationMs: (elapsedMs: number) => string;

package/dist/utils/duration.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDurationMs = void 0;
+/** Human-readable duration for CLI build logs (ms under 1s, seconds with 2 decimals otherwise). */
+const formatDurationMs = (elapsedMs) => elapsedMs < 1000 ? `${Math.round(elapsedMs)}ms` : `${(elapsedMs / 1000).toFixed(2)}s`;
+exports.formatDurationMs = formatDurationMs;

package/dist/utils/logger.d.ts

@@ -1,13 +1,50 @@
+/** 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 declare class Logger {
+    /** From Handoff constructor; enables debug lines together with env. */
     private static debugMode;
+    /** Minimum message severity to print: 0=debug, 1=info, 2=warn, 3=error. `silent` uses 99. */
+    private static severityThreshold;
+    /** Enabled scopes; defaults to all of `handoff`, `vite`, `next`. */
+    private static scopesFilter;
     static init(options?: {
         debug?: boolean;
     }): void;
+    /** Re-read `process.env` (useful if env is loaded after first `init`). */
+    static applyEnvConfig(): void;
+    private static scopeEnabled;
+    /** Message severities: debug=0, info-tier=1, warn=2, error=3 */
+    private static shouldEmit;
     private static getTimestamp;
-    static log(message: string): void;
-    static info(message: string): void;
-    static success(message: string): void;
-    static warn(message: string): void;
-    static error(message: string, error?: any): void;
+    /** Short label shown after the timestamp so you can scan for handoff vs vite vs next. */
+    private static scopeTag;
+    private static basePrefix;
+    static log(message: string, scope?: LogScope): void;
+    /**
+     * Vite often passes strings that already contain ANSI; avoid wrapping those in chalk.cyan so colors stay correct.
+     */
+    static info(message: string, scope?: LogScope): void;
+    static success(message: string, scope?: LogScope): void;
+    static warn(message: string, scope?: LogScope): void;
+    static error(message: string, error?: any, scope?: LogScope): void;
     static debug(message: string, data?: any): void;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    /** 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): void;
 }

package/dist/utils/logger.js

@@ -4,43 +4,163 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Logger = void 0;
+const readline_1 = __importDefault(require("readline"));
 const chalk_1 = __importDefault(require("chalk"));
+/**
+ * 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.
+ */
 class Logger {
     static init(options) {
+        this.applyEnvConfig();
         if ((options === null || options === void 0 ? void 0 : options.debug) !== undefined) {
             this.debugMode = options.debug;
         }
+        if ((options === null || options === void 0 ? void 0 : options.debug) === true) {
+            this.severityThreshold = 0;
+        }
+    }
+    /** Re-read `process.env` (useful if env is loaded after first `init`). */
+    static applyEnvConfig() {
+        var _a, _b;
+        this.severityThreshold = 1;
+        const allScopes = ['handoff', 'vite', 'next'];
+        this.scopesFilter = new Set(allScopes);
+        const levelRaw = (_a = process.env.HANDOFF_LOG_LEVEL) === null || _a === void 0 ? void 0 : _a.trim().toLowerCase();
+        const levelMap = {
+            debug: 0,
+            info: 1,
+            warn: 2,
+            error: 3,
+            silent: 99,
+        };
+        if (levelRaw && levelRaw in levelMap) {
+            this.severityThreshold = levelMap[levelRaw];
+        }
+        const scopesRaw = (_b = process.env.HANDOFF_LOG_SCOPES) === null || _b === void 0 ? void 0 : _b.trim();
+        if (scopesRaw) {
+            const set = new Set();
+            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;
+            }
+        }
+    }
+    static scopeEnabled(scope) {
+        return this.scopesFilter.has(scope);
+    }
+    /** Message severities: debug=0, info-tier=1, warn=2, error=3 */
+    static shouldEmit(severity) {
+        return severity >= this.severityThreshold;
     }
     static getTimestamp() {
         const now = new Date();
         return chalk_1.default.gray(`[${now.toISOString()}]`);
     }
-    static log(message) {
-        console.log(`${this.getTimestamp()} ${message}`);
+    /** Short label shown after the timestamp so you can scan for handoff vs vite vs next. */
+    static scopeTag(scope) {
+        const tags = {
+            handoff: chalk_1.default.blue.bold('[handoff]'),
+            vite: chalk_1.default.magenta.bold('[vite]'),
+            next: chalk_1.default.green.bold('[next]'),
+        };
+        return tags[scope];
     }
-    static info(message) {
-        console.log(`${this.getTimestamp()} ${chalk_1.default.cyan(message)}`);
+    static basePrefix(scope) {
+        return `${this.getTimestamp()} ${this.scopeTag(scope)}`;
     }
-    static success(message) {
-        console.log(`${this.getTimestamp()} ${chalk_1.default.green(message)}`);
+    static log(message, scope = 'handoff') {
+        if (!this.scopeEnabled(scope) || !this.shouldEmit(1))
+            return;
+        console.log(`${this.basePrefix(scope)} ${message}`);
     }
-    static warn(message) {
-        console.warn(`${this.getTimestamp()} ${chalk_1.default.yellow(message)}`);
+    /**
+     * Vite often passes strings that already contain ANSI; avoid wrapping those in chalk.cyan so colors stay correct.
+     */
+    static info(message, scope = 'handoff') {
+        if (!this.scopeEnabled(scope) || !this.shouldEmit(1))
+            return;
+        const body = scope === 'vite' ? message : chalk_1.default.cyan(message);
+        console.log(`${this.basePrefix(scope)} ${body}`);
     }
-    static error(message, error) {
-        console.error(`${this.getTimestamp()} ${chalk_1.default.red(message)}`);
+    static success(message, scope = 'handoff') {
+        if (!this.scopeEnabled(scope) || !this.shouldEmit(1))
+            return;
+        console.log(`${this.basePrefix(scope)} ${chalk_1.default.green(message)}`);
+    }
+    static warn(message, scope = 'handoff') {
+        if (!this.scopeEnabled(scope) || !this.shouldEmit(2))
+            return;
+        const body = scope === 'vite' ? message : chalk_1.default.yellow(message);
+        console.warn(`${this.basePrefix(scope)} ${body}`);
+    }
+    static error(message, error, scope = 'handoff') {
+        if (!this.scopeEnabled(scope) || !this.shouldEmit(3))
+            return;
+        const body = scope === 'vite' ? message : chalk_1.default.red(message);
+        console.error(`${this.basePrefix(scope)} ${body}`);
         if (error) {
             console.error(error);
         }
     }
     static debug(message, data) {
-        if (this.debugMode) {
-            console.log(`${this.getTimestamp()} ${chalk_1.default.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_1.default.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, scope = '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, stderr, scope = 'next') {
+        for (const stream of [stdout, stderr]) {
+            if (!stream)
+                continue;
+            const rl = readline_1.default.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, scope = 'next') {
+        if (!(buffer === null || buffer === void 0 ? void 0 : buffer.length))
+            return;
+        const text = buffer.toString('utf8');
+        for (const line of text.split(/\r?\n/)) {
+            this.childProcessLine(line, scope);
         }
     }
 }
 exports.Logger = Logger;
+/** From Handoff constructor; enables debug lines together with env. */
 Logger.debugMode = false;
+/** Minimum message severity to print: 0=debug, 1=info, 2=warn, 3=error. `silent` uses 99. */
+Logger.severityThreshold = 1;
+/** Enabled scopes; defaults to all of `handoff`, `vite`, `next`. */
+Logger.scopesFilter = new Set(['handoff', 'vite', 'next']);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.2.0-0",
+  "version": "1.2.0-1",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",