handoff-app 1.1.3 → 1.2.0-1

package/dist/transformers/utils/csf.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCsfStoryEntries = getCsfStoryEntries;
+exports.createCsfStoryPreviews = createCsfStoryPreviews;
+const lodash_1 = require("lodash");
+function getCsfStoryEntries(moduleExports) {
+    return Object.entries(moduleExports).filter(([key, value]) => {
+        if (key === 'default' || key === '__esModule')
+            return false;
+        if (typeof value === 'function')
+            return true;
+        if (value && typeof value === 'object')
+            return true;
+        return false;
+    });
+}
+function createCsfStoryPreviews(moduleExports) {
+    const meta = (moduleExports.default || {});
+    const stories = getCsfStoryEntries(moduleExports);
+    const previews = {};
+    for (const [storyKey, storyValue] of stories) {
+        const storyObj = (typeof storyValue === 'function' ? {} : storyValue);
+        previews[storyKey] = {
+            title: storyObj.name || (0, lodash_1.startCase)(storyKey),
+            values: Object.assign(Object.assign({}, (meta.args || {})), (storyObj.args || {})),
+            url: '',
+        };
+    }
+    return previews;
+}

package/dist/transformers/utils/index.d.ts

@@ -8,5 +8,6 @@ export * from './schema';
 export * from './html';
 export * from './build';
 export * from './module';
+export * from './csf';
 export * from './handlebars';
 export * from './schema-loader';

package/dist/transformers/utils/index.js

@@ -28,6 +28,8 @@ __exportStar(require("./html"), exports);
 __exportStar(require("./build"), exports);
 // Module utilities
 __exportStar(require("./module"), exports);
+// CSF utilities
+__exportStar(require("./csf"), exports);
 // Handlebars utilities
 __exportStar(require("./handlebars"), exports);
 // Schema loader utilities

package/dist/transformers/utils/module.d.ts

@@ -6,3 +6,8 @@ import { ModuleEvaluationResult } from '../types';
  * @returns Module evaluation result with exports
  */
 export declare function buildAndEvaluateModule(entryPath: string, handoff: any): Promise<ModuleEvaluationResult>;
+/**
+ * Builds and evaluates a module synchronously using esbuild.
+ * Used by config/runtime code paths that must remain synchronous.
+ */
+export declare function buildAndEvaluateModuleSync(entryPath: string, handoff: any): ModuleEvaluationResult;

package/dist/transformers/utils/module.js

@@ -13,8 +13,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAndEvaluateModule = buildAndEvaluateModule;
+exports.buildAndEvaluateModuleSync = buildAndEvaluateModuleSync;
 const esbuild_1 = __importDefault(require("esbuild"));
 const build_1 = require("./build");
+function createModuleBuildConfig(entryPath, handoff) {
+    var _a, _b;
+    const defaultBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_SSR_BUILD_CONFIG), { entryPoints: [entryPath] });
+    return ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.ssrBuildConfig)
+        ? handoff.config.hooks.ssrBuildConfig(defaultBuildConfig)
+        : defaultBuildConfig;
+}
+function evaluateBuiltModule(code) {
+    const mod = { exports: {} };
+    const func = new Function('require', 'module', 'exports', code);
+    func(require, mod, mod.exports);
+    return mod;
+}
 /**
  * Builds and evaluates a module using esbuild
  * @param entryPath - Path to the module entry point
@@ -23,20 +37,19 @@ const build_1 = require("./build");
  */
 function buildAndEvaluateModule(entryPath, handoff) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
-        // Default esbuild configuration
-        const defaultBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_SSR_BUILD_CONFIG), { entryPoints: [entryPath] });
-        // Apply user's SSR build config hook if provided
-        const buildConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.ssrBuildConfig)
-            ? handoff.config.hooks.ssrBuildConfig(defaultBuildConfig)
-            : defaultBuildConfig;
-        // Compile the module
+        const buildConfig = createModuleBuildConfig(entryPath, handoff);
         const build = yield esbuild_1.default.build(buildConfig);
         const { text: code } = build.outputFiles[0];
-        // Evaluate the compiled code
-        const mod = { exports: {} };
-        const func = new Function('require', 'module', 'exports', code);
-        func(require, mod, mod.exports);
-        return mod;
+        return evaluateBuiltModule(code);
     });
 }
+/**
+ * Builds and evaluates a module synchronously using esbuild.
+ * Used by config/runtime code paths that must remain synchronous.
+ */
+function buildAndEvaluateModuleSync(entryPath, handoff) {
+    const buildConfig = createModuleBuildConfig(entryPath, handoff);
+    const build = esbuild_1.default.buildSync(buildConfig);
+    const { text: code } = build.outputFiles[0];
+    return evaluateBuiltModule(code);
+}

package/dist/transformers/utils/usage.d.ts

@@ -0,0 +1,23 @@
+import { SlotMetadata } from '../preview/component';
+/**
+ * Extracts the PascalCase component name from a file path.
+ * e.g. `/path/to/Button.tsx` -> `Button`
+ */
+export declare function extractComponentName(filePath: string): string;
+export interface GenerateUsageSnippetOptions {
+    componentName: string;
+    properties: Record<string, SlotMetadata>;
+    previewValues: Record<string, any>;
+    /** Template filename for the import path (e.g. "Button.tsx") */
+    templateFileName?: string;
+    importStatement?: string;
+}
+/**
+ * Generates a JSX usage snippet showing how to consume a React component
+ * with the given preview values.
+ *
+ * Iterates over the union of preview values and schema properties so that
+ * props not present in the preview are still represented when they carry
+ * a meaningful default or are required.
+ */
+export declare function generateUsageSnippet(options: GenerateUsageSnippetOptions): string;

package/dist/transformers/utils/usage.js

@@ -0,0 +1,294 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractComponentName = extractComponentName;
+exports.generateUsageSnippet = generateUsageSnippet;
+const path_1 = __importDefault(require("path"));
+const component_1 = require("../preview/component");
+const CHILDREN_PROP = 'children';
+const INDENT = '  ';
+function isValidIdentifier(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key);
+}
+/**
+ * Formats a prop value as a JSX attribute string.
+ * Returns the right-hand side only (e.g. `"hello"`, `{42}`, `{true}`).
+ */
+function formatPropValue(value, type) {
+    if (value === undefined || value === null) {
+        return '{undefined}';
+    }
+    switch (type) {
+        case component_1.SlotType.BOOLEAN:
+            return typeof value === 'boolean' ? `{${value}}` : `{${Boolean(value)}}`;
+        case component_1.SlotType.NUMBER:
+            return `{${Number(value)}}`;
+        case component_1.SlotType.FUNCTION:
+            return '{() => { /* handler */ }}';
+        case component_1.SlotType.OBJECT:
+            return `{${formatObjectLiteral(value)}}`;
+        case component_1.SlotType.ARRAY:
+            return `{${formatArrayLiteral(value)}}`;
+        case component_1.SlotType.TEXT:
+        case component_1.SlotType.IMAGE:
+        case component_1.SlotType.BUTTON:
+        case component_1.SlotType.ENUM:
+        default:
+            if (typeof value === 'string') {
+                return `"${escapeJsxString(value)}"`;
+            }
+            if (typeof value === 'boolean') {
+                return `{${value}}`;
+            }
+            if (typeof value === 'number') {
+                return `{${value}}`;
+            }
+            if (typeof value === 'object') {
+                return `{${JSON.stringify(value, null, 2)}}`;
+            }
+            return `"${escapeJsxString(String(value))}"`;
+    }
+}
+function escapeJsxString(str) {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function formatObjectLiteral(value) {
+    if (typeof value !== 'object' || value === null) {
+        return JSON.stringify(value);
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return '{}';
+    if (entries.length <= 3) {
+        const inline = entries
+            .map(([k, v]) => `${isValidIdentifier(k) ? k : JSON.stringify(k)}: ${JSON.stringify(v)}`)
+            .join(', ');
+        if (inline.length <= 60)
+            return `{ ${inline} }`;
+    }
+    return JSON.stringify(value, null, 2);
+}
+function formatArrayLiteral(value) {
+    if (!Array.isArray(value))
+        return JSON.stringify(value);
+    if (value.length === 0)
+        return '[]';
+    const inline = JSON.stringify(value);
+    if (inline.length <= 60)
+        return inline;
+    return JSON.stringify(value, null, 2);
+}
+/**
+ * Determines whether a prop value matches its declared default and can be omitted.
+ */
+function matchesDefault(value, slotDefault) {
+    if (slotDefault === undefined || slotDefault === null)
+        return false;
+    if (typeof value === typeof slotDefault && value === slotDefault)
+        return true;
+    // SlotMetadata.default is typed as `string | undefined`, but runtime values
+    // may be numbers or booleans. Do a loose string comparison as a fallback.
+    if (String(value) === String(slotDefault))
+        return true;
+    return false;
+}
+/**
+ * Extracts the PascalCase component name from a file path.
+ * e.g. `/path/to/Button.tsx` -> `Button`
+ */
+function extractComponentName(filePath) {
+    const basename = path_1.default.basename(filePath);
+    const ext = path_1.default.extname(basename);
+    return basename.slice(0, basename.length - ext.length);
+}
+/**
+ * Generates a JSX usage snippet showing how to consume a React component
+ * with the given preview values.
+ *
+ * Iterates over the union of preview values and schema properties so that
+ * props not present in the preview are still represented when they carry
+ * a meaningful default or are required.
+ */
+function generateUsageSnippet(options) {
+    var _a;
+    const { componentName, properties, previewValues, templateFileName, importStatement } = options;
+    const importPath = `./${templateFileName ? path_1.default.basename(templateFileName, path_1.default.extname(templateFileName)) : componentName}`;
+    const attrs = [];
+    let childrenValue = undefined;
+    let hasChildren = false;
+    // Merge all known prop keys: preview values first (preserve order), then
+    // any additional keys from the property schema that weren't in the preview.
+    const allKeys = new Set([...Object.keys(previewValues), ...Object.keys(properties)]);
+    for (const key of allKeys) {
+        const slot = properties[key];
+        const inPreview = key in previewValues;
+        const value = inPreview ? previewValues[key] : resolveSchemaValue(slot);
+        // Nothing to show for this prop
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (key === CHILDREN_PROP) {
+            hasChildren = true;
+            childrenValue = value;
+            continue;
+        }
+        // Skip function props that weren't explicitly provided in preview values
+        if (!inPreview && (slot === null || slot === void 0 ? void 0 : slot.type) === component_1.SlotType.FUNCTION) {
+            continue;
+        }
+        // Omit props that match their declared default
+        if (slot && matchesDefault(value, slot.default)) {
+            continue;
+        }
+        const type = (_a = slot === null || slot === void 0 ? void 0 : slot.type) !== null && _a !== void 0 ? _a : inferSlotType(value);
+        // Boolean true → JSX shorthand: <Comp disabled />
+        if (type === component_1.SlotType.BOOLEAN && value === true) {
+            attrs.push(key);
+            continue;
+        }
+        // Boolean false → omit (implicit JSX default)
+        if (type === component_1.SlotType.BOOLEAN && value === false) {
+            continue;
+        }
+        attrs.push(`${key}=${formatPropValue(value, type)}`);
+    }
+    const lines = [];
+    lines.push(importStatement || `import ${componentName} from '${importPath}';`);
+    lines.push('');
+    if (hasChildren && childrenValue !== undefined && childrenValue !== null && childrenValue !== '') {
+        const openTag = attrs.length > 0 ? `<${componentName} ${attrs.join(' ')}>` : `<${componentName}>`;
+        const childStr = typeof childrenValue === 'string'
+            ? childrenValue
+            : typeof childrenValue === 'number' || typeof childrenValue === 'boolean'
+                ? String(childrenValue)
+                : '{/* children */}';
+        if (childStr.length <= 40 && !childStr.includes('\n')) {
+            lines.push(`${openTag}${childStr}</${componentName}>`);
+        }
+        else {
+            lines.push(openTag);
+            for (const childLine of childStr.split('\n')) {
+                lines.push(`${INDENT}${childLine}`);
+            }
+            lines.push(`</${componentName}>`);
+        }
+    }
+    else {
+        if (attrs.length === 0) {
+            lines.push(`<${componentName} />`);
+        }
+        else if (attrs.length <= 3 && attrs.join(' ').length <= 60) {
+            lines.push(`<${componentName} ${attrs.join(' ')} />`);
+        }
+        else {
+            lines.push(`<${componentName}`);
+            for (const attr of attrs) {
+                lines.push(`${INDENT}${attr}`);
+            }
+            lines.push('/>');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolves a display value for a schema-only property (not present in preview values).
+ *
+ * - Uses the declared default when available and non-trivial.
+ * - For required props without a default, generates a type-appropriate placeholder.
+ * - Returns `undefined` for optional props with no useful default (they are skipped).
+ */
+function resolveSchemaValue(slot) {
+    var _a;
+    if (!slot)
+        return undefined;
+    // Use explicit default if it's non-trivial
+    if (slot.default !== undefined && slot.default !== null && slot.default !== '') {
+        return coerceDefault(slot.default, slot.type);
+    }
+    // Required props must appear even without a default
+    if ((_a = slot.rules) === null || _a === void 0 ? void 0 : _a.required) {
+        return getPlaceholder(slot);
+    }
+    // Optional with no default → omit
+    return undefined;
+}
+/**
+ * Coerces a string default from SlotMetadata into the appropriate JS type
+ * for code-generation purposes.
+ */
+function coerceDefault(value, type) {
+    if (typeof value !== 'string')
+        return value;
+    switch (type) {
+        case component_1.SlotType.BOOLEAN:
+            return value === 'true';
+        case component_1.SlotType.NUMBER: {
+            const n = Number(value);
+            return Number.isNaN(n) ? value : n;
+        }
+        default:
+            return value;
+    }
+}
+/**
+ * Generates a type-appropriate placeholder value for required props
+ * that have no default and no preview value.
+ */
+function getPlaceholder(slot) {
+    switch (slot.type) {
+        case component_1.SlotType.ENUM: {
+            const member = extractFirstEnumMember(slot);
+            return member !== null && member !== void 0 ? member : 'value';
+        }
+        case component_1.SlotType.TEXT:
+        case component_1.SlotType.IMAGE:
+            return '...';
+        case component_1.SlotType.NUMBER:
+            return 0;
+        case component_1.SlotType.BOOLEAN:
+            return true;
+        case component_1.SlotType.ARRAY:
+            return [];
+        case component_1.SlotType.OBJECT:
+            return {};
+        case component_1.SlotType.FUNCTION:
+            return undefined; // handled separately
+        default:
+            return '...';
+    }
+}
+/**
+ * Attempts to extract the first enum member from a SlotMetadata's deepType
+ * (e.g. `"primary"` from `'primary' | 'secondary' | 'danger'`).
+ */
+function extractFirstEnumMember(slot) {
+    var _a, _b;
+    // deepType.members contains the enum values when available
+    if (((_a = slot.deepType) === null || _a === void 0 ? void 0 : _a.kind) === 'enum' && ((_b = slot.deepType.members) === null || _b === void 0 ? void 0 : _b.length)) {
+        const raw = slot.deepType.members[0];
+        // Members are stored as quoted strings like `"primary"` — strip quotes
+        return typeof raw === 'string' ? raw.replace(/^["']|["']$/g, '') : undefined;
+    }
+    // Fall back to parsing the generic display string (e.g. `"primary" | "secondary"`)
+    if (slot.generic) {
+        const match = slot.generic.match(/["']([^"']+)["']/);
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+function inferSlotType(value) {
+    if (typeof value === 'boolean')
+        return component_1.SlotType.BOOLEAN;
+    if (typeof value === 'number')
+        return component_1.SlotType.NUMBER;
+    if (typeof value === 'function')
+        return component_1.SlotType.FUNCTION;
+    if (Array.isArray(value))
+        return component_1.SlotType.ARRAY;
+    if (typeof value === 'object' && value !== null)
+        return component_1.SlotType.OBJECT;
+    return component_1.SlotType.TEXT;
+}

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/types/config.d.ts

@@ -3,7 +3,7 @@ import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
-import { ComponentListObject, TransformComponentTokensResult } from '../transformers/preview/types';
+import { ComponentListObject, PatternListObject, TransformComponentTokensResult } from '../transformers/preview/types';
 import { ValidationResult } from './preview';
 export interface ImageStyle {
     name: string;
@@ -65,13 +65,19 @@ export interface NextAppConfig {
     theme?: string;
     title: string;
     client: string;
-    google_tag_manager: string | null | undefined;
-    type_copy: string;
-    type_sort: string[];
-    color_sort: string[];
+    google_tag_manager?: string | null | undefined;
+    googleTagManager?: string | null | undefined;
+    type_copy?: string;
+    typeCopy?: string;
+    type_sort?: string[];
+    typeSort?: string[];
+    color_sort?: string[];
+    colorSort?: string[];
     breakpoints: Breakpoints;
-    component_sort: string[];
-    base_path: string;
+    component_sort?: string[];
+    componentSort?: string[];
+    base_path?: string;
+    basePath?: string;
     attribution: boolean;
     ports?: {
         app: number;
@@ -80,7 +86,9 @@ export interface NextAppConfig {
 }
 export interface Config {
     dev_access_token?: string | null | undefined;
+    devAccessToken?: string | null | undefined;
     figma_project_id?: string | null | undefined;
+    figmaProjectId?: string | null | undefined;
     exportsOutputDirectory?: string;
     sitesOutputDirectory?: string;
     useVariables?: boolean;
@@ -123,6 +131,12 @@ export interface Config {
          * @example ["components/button", "components/input"]
          */
         components?: string[];
+        /**
+         * Array of pattern paths to be included in the build.
+         * Patterns compose multiple component previews into single-page views.
+         * @example ["patterns/hero-section", "patterns"]
+         */
+        patterns?: string[];
     };
     /**
      * Configuration for asset zip file download links
@@ -140,6 +154,10 @@ export interface Config {
          */
         logos?: string;
     };
+    assetsZipLinks?: {
+        icons?: string;
+        logos?: string;
+    };
     /**
      * Configuration hooks for extending functionality
      */
@@ -278,6 +296,10 @@ export interface RuntimeConfigComponentOptions {
         };
     };
 }
+export interface ConfigFileEntry {
+    kind: string;
+    entityId: string;
+}
 export interface RuntimeConfig {
     entries?: {
         scss?: string;
@@ -286,6 +308,9 @@ export interface RuntimeConfig {
         components: {
             [id: string]: ComponentListObject;
         };
+        patterns: {
+            [id: string]: PatternListObject;
+        };
     };
     options: {
         [key: string]: RuntimeConfigComponentOptions;

package/dist/types/preview.d.ts

@@ -54,6 +54,7 @@ export interface PreviewObject {
                 [key: string]: string;
             };
             url: string;
+            usage?: string;
         };
     };
     properties?: {
@@ -61,6 +62,7 @@ export interface PreviewObject {
     };
     code: string;
     html?: string;
+    usage?: string;
     format: string;
     variant?: Record<string, string>;
     options?: {

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;
 }