@harness-fe/unplugin 3.0.0

package/dist/internal/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared types used by both the unplugin core and the native webpack plugin.
+ */
+import type { ComponentMap } from '../transform.js';
+export type PeerRole = 'vite-plugin' | 'webpack-plugin';
+export interface HarnessFEOptions {
+    /** Override projectId (defaults to package.json `name`). */
+    projectId?: string;
+    /** MCP server WebSocket URL (default: ws://127.0.0.1:47729). */
+    mcpUrl?: string;
+    /** Disable injection entirely. */
+    disabled?: boolean;
+    /**
+     * Parent project's id, used to build the project tree on the daemon.
+     * Set this on the iframe child app's plugin config when you can declare
+     * the relationship at build time. Otherwise the runtime client will
+     * auto-detect it via same-origin parent inspection.
+     */
+    parentProjectId?: string;
+    /** Human-readable name; defaults to package.json `name`. */
+    displayName?: string;
+    /**
+     * Override buildId. When omitted, the plugin resolves it from git sha
+     * (or CI env vars) and falls back to a dev-stable hash of config files.
+     */
+    buildId?: string;
+    /**
+     * Token to authenticate against the daemon when it's bound to a non-
+     * loopback host. Appended as `?token=…` to the WS URL and propagated
+     * to the runtime client via `__HARNESS_FE__`. Read from
+     * `HARNESS_FE_TOKEN` when omitted.
+     */
+    token?: string;
+    /**
+     * Vue SFC transform safety: when true (default), the plugin re-parses
+     * its own output to catch any mis-aligned attribute injection.
+     */
+    safeMode?: boolean;
+}
+/**
+ * Context handed to the MCP client. Getters keep the values fresh as the
+ * host (vite/webpack) resolves them lazily (e.g. projectRoot is only known
+ * after configResolved / afterEnvironment).
+ */
+export interface McpClientContext {
+    readonly projectId: string;
+    readonly mcpUrl: string;
+    readonly token: string | undefined;
+    readonly peerRole: PeerRole;
+    readonly parentProjectId: string | undefined;
+    readonly projectRoot: string;
+    readonly componentMap: ComponentMap;
+    getBuildId(): string;
+    getDisplayName(): string | undefined;
+}
+export interface McpClient {
+    connect(): void;
+    disconnect(): void;
+    emitEvent(name: string, payload: unknown): void;
+    readonly isActive: boolean;
+}

package/dist/internal/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types used by both the unplugin core and the native webpack plugin.
+ */
+export {};

package/dist/resolveBuildId.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Resolves the buildId for one harness-fe build (vite dev server start /
+ * webpack build / prod build). One buildId = one source-code snapshot.
+ *
+ * Stability rules:
+ *   - HMR / file edits within a dev server run → same buildId
+ *   - dev server restart → new buildId
+ *   - prod build → buildId matches git sha (or dirty-marked)
+ *
+ * Priority:
+ *   1. `userConfig` — caller-supplied via `harnessFE({ buildId })`
+ *   2. CI env vars (GITHUB_SHA / GIT_COMMIT) when present
+ *   3. `git rev-parse HEAD` + dirty marker when in a git repo
+ *   4. Fallback: `dev-<short-source-hash>-<startTs>` derived from package.json,
+ *      lockfile, and bundler config — stable for the lifetime of this process.
+ */
+export interface ResolveBuildIdOptions {
+    /** Caller override; wins over all auto-detection. */
+    userConfig?: string;
+    /** Project root (where package.json lives). */
+    root: string;
+    /** Stable timestamp to embed in the dev fallback id. Pass `Date.now()`
+     *  once at plugin init so this id doesn't change across resolve() calls. */
+    startTs?: number;
+}
+export interface ResolvedBuildId {
+    buildId: string;
+    gitSha?: string;
+    gitDirty?: boolean;
+    sourceDigest?: string;
+}
+export declare function resolveBuildId(opts: ResolveBuildIdOptions): ResolvedBuildId;

package/dist/resolveBuildId.js

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function resolveBuildId(opts) {
+    if (opts.userConfig && opts.userConfig.length > 0) {
+        return { buildId: opts.userConfig };
+    }
+    // CI env vars take precedence over git so docker/CI builds with shallow
+    // checkouts still get a meaningful id even when git isn't available.
+    const ciSha = process.env.GITHUB_SHA ||
+        process.env.GIT_COMMIT ||
+        process.env.CI_COMMIT_SHA ||
+        process.env.BUILDKITE_COMMIT ||
+        undefined;
+    if (ciSha) {
+        return {
+            buildId: `${ciSha.slice(0, 12)}-ci`,
+            gitSha: ciSha,
+            gitDirty: false,
+        };
+    }
+    // Try git locally.
+    const gitSha = runGit(['rev-parse', 'HEAD'], opts.root);
+    if (gitSha) {
+        const dirty = runGit(['status', '--porcelain'], opts.root);
+        const gitDirty = dirty !== undefined && dirty.length > 0;
+        return {
+            buildId: `${gitSha.slice(0, 12)}${gitDirty ? '-dirty' : ''}`,
+            gitSha,
+            gitDirty,
+        };
+    }
+    // No git, no CI: derive a stable digest from the project's config files
+    // and stamp it with the dev-server start timestamp.
+    const startTs = opts.startTs ?? Date.now();
+    const sourceDigest = hashConfigFiles(opts.root);
+    return {
+        buildId: `dev-${sourceDigest.slice(0, 8)}-${startTs.toString(36)}`,
+        sourceDigest,
+    };
+}
+function runGit(args, cwd) {
+    try {
+        const out = spawnSync('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 1500,
+        });
+        if (out.status !== 0)
+            return undefined;
+        return out.stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Hash the contents of the few config files that, when changed, mean a fresh
+ * build artifact. Avoids reading every source file — that work belongs to the
+ * bundler's own incremental cache.
+ */
+function hashConfigFiles(root) {
+    const candidates = [
+        'package.json',
+        'pnpm-lock.yaml',
+        'package-lock.json',
+        'yarn.lock',
+        'vite.config.ts',
+        'vite.config.js',
+        'webpack.config.ts',
+        'webpack.config.js',
+        'webpack.config.cjs',
+        'tsconfig.json',
+    ];
+    const h = createHash('sha256');
+    for (const name of candidates) {
+        try {
+            h.update(name);
+            h.update(readFileSync(join(root, name)));
+        }
+        catch {
+            // missing file → contribute the name only (still affects hash)
+        }
+    }
+    return h.digest('hex');
+}

package/dist/resolveProjectId.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves the project ID for a given project root directory.
+ *
+ * Priority:
+ * 1. `userConfig` — if provided, return immediately without touching `.harness-id`
+ * 2. Read `{root}/.harness-id` — if readable, return trimmed content
+ * 3. Generate UUID v4, write to `{root}/.harness-id` (UTF-8, no BOM, no trailing whitespace), return it
+ */
+export declare function resolveProjectId(root: string, userConfig?: string): Promise<string>;

package/dist/resolveProjectId.js

@@ -0,0 +1,44 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+const HARNESS_ID_FILE = '.harness-id';
+/**
+ * Resolves the project ID for a given project root directory.
+ *
+ * Priority:
+ * 1. `userConfig` — if provided, return immediately without touching `.harness-id`
+ * 2. Read `{root}/.harness-id` — if readable, return trimmed content
+ * 3. Generate UUID v4, write to `{root}/.harness-id` (UTF-8, no BOM, no trailing whitespace), return it
+ */
+export async function resolveProjectId(root, userConfig) {
+    // Priority 1: explicit user config value
+    if (userConfig !== undefined && userConfig !== '') {
+        return userConfig;
+    }
+    const idFilePath = join(root, HARNESS_ID_FILE);
+    // Priority 2: read existing .harness-id file
+    try {
+        const content = await readFile(idFilePath, 'utf-8');
+        const trimmed = content.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    catch (err) {
+        // ENOENT or other read error — fall through to generate a new UUID
+        const code = err.code;
+        if (code !== 'ENOENT') {
+            // Log unexpected errors but still proceed to generate a new ID
+            console.warn(`[harness] Could not read ${idFilePath}: ${err.message}`);
+        }
+    }
+    // Priority 3: generate UUID v4, write to .harness-id, return it
+    const newId = randomUUID();
+    try {
+        await writeFile(idFilePath, newId, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        console.warn(`[harness] Could not write ${idFilePath}: ${err.message}`);
+    }
+    return newId;
+}

package/dist/rollup.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rollup-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/rollup'
+ */
+export type { HarnessFEOptions } from './core.js';
+export declare const harnessFE: (options?: import("./core.js").HarnessFEOptions | undefined) => import("rollup").Plugin<any> | import("rollup").Plugin<any>[];
+export default harnessFE;

package/dist/rollup.js

@@ -0,0 +1,9 @@
+/**
+ * Rollup-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/rollup'
+ */
+import { unplugin } from './core.js';
+export const harnessFE = unplugin.rollup;
+export default harnessFE;

package/dist/rspack.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rspack-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/rspack'
+ */
+export type { HarnessFEOptions } from './core.js';
+export declare const harnessFE: (options?: import("./core.js").HarnessFEOptions | undefined) => RspackPluginInstance;
+export default harnessFE;

package/dist/rspack.js

@@ -0,0 +1,9 @@
+/**
+ * Rspack-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/rspack'
+ */
+import { unplugin } from './core.js';
+export const harnessFE = unplugin.rspack;
+export default harnessFE;

package/dist/transform.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JSX transform: parse a .tsx / .jsx file and inject:
+ *   - `data-morphix-loc="<relPath>:<line>:<col>"` on every JSX opening element
+ *   - `data-morphix-comp="<ComponentName>"` on JSX opening elements that are
+ *     enclosed (transitively) by a top-level component definition. The
+ *     component name comes from the nearest enclosing function/class/variable
+ *     declaration whose name starts with an uppercase letter (PascalCase).
+ *
+ * Output is the original source with the attribute strings spliced in via
+ * MagicString — keeps source maps intact and avoids re-generating the file.
+ *
+ * Side effect: every successfully scanned file contributes entries to the
+ * supplied `componentMap`: name → list of locations (file:line:col).
+ */
+export interface ComponentLocation {
+    file: string;
+    line: number;
+    col: number;
+}
+export type ComponentMap = Map<string, ComponentLocation[]>;
+export interface TransformResult {
+    code: string;
+    map?: object;
+    /** Number of JSX elements that got attributes. */
+    taggedCount: number;
+}
+export declare function transformJsx(source: string, relPath: string, componentMap: ComponentMap): TransformResult | null;

package/dist/transform.js

@@ -0,0 +1,150 @@
+/**
+ * JSX transform: parse a .tsx / .jsx file and inject:
+ *   - `data-morphix-loc="<relPath>:<line>:<col>"` on every JSX opening element
+ *   - `data-morphix-comp="<ComponentName>"` on JSX opening elements that are
+ *     enclosed (transitively) by a top-level component definition. The
+ *     component name comes from the nearest enclosing function/class/variable
+ *     declaration whose name starts with an uppercase letter (PascalCase).
+ *
+ * Output is the original source with the attribute strings spliced in via
+ * MagicString — keeps source maps intact and avoids re-generating the file.
+ *
+ * Side effect: every successfully scanned file contributes entries to the
+ * supplied `componentMap`: name → list of locations (file:line:col).
+ */
+import { parse } from '@babel/parser';
+import traverseDefault from '@babel/traverse';
+import * as t from '@babel/types';
+import MagicString from 'magic-string';
+// @babel/traverse exposes its default as `default` only when published as ESM
+// in older versions; later versions also expose a named export. Pick whichever
+// is callable.
+const traverse = typeof traverseDefault === 'function'
+    ? traverseDefault
+    : (traverseDefault.default ?? traverseDefault);
+const ATTR_COMP = 'data-morphix-comp';
+const ATTR_LOC = 'data-morphix-loc';
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9]*$/;
+export function transformJsx(source, relPath, componentMap) {
+    let ast;
+    try {
+        ast = parse(source, {
+            sourceType: 'module',
+            plugins: ['jsx', 'typescript'],
+            errorRecovery: true,
+        });
+    }
+    catch {
+        return null;
+    }
+    const magic = new MagicString(source);
+    let taggedCount = 0;
+    traverse(ast, {
+        JSXOpeningElement(path) {
+            const node = path.node;
+            const start = node.start;
+            if (start == null)
+                return;
+            // Position attribute insertion right after the tag name token.
+            const name = node.name;
+            const nameEnd = name.end;
+            if (nameEnd == null)
+                return;
+            const loc = node.loc?.start;
+            if (!loc)
+                return;
+            const locValue = `${relPath}:${loc.line}:${loc.column}`;
+            const enclosingName = findEnclosingComponentName(path);
+            const explicitName = getStringAttribute(node, ATTR_COMP);
+            const attrs = [];
+            if (!hasAttribute(node, ATTR_LOC)) {
+                attrs.push(`${ATTR_LOC}="${escapeAttr(locValue)}"`);
+            }
+            if (!hasAttribute(node, ATTR_COMP) && enclosingName) {
+                attrs.push(`${ATTR_COMP}="${escapeAttr(enclosingName)}"`);
+            }
+            // Register every name that ends up on this element into the map —
+            // both enclosing component (so e.g. App resolves) and any
+            // hand-written tag (so IncrementBtn / EchoInput resolve too).
+            const names = new Set();
+            if (enclosingName)
+                names.add(enclosingName);
+            if (explicitName)
+                names.add(explicitName);
+            for (const name of names) {
+                const entries = componentMap.get(name) ?? [];
+                entries.push({ file: relPath, line: loc.line, col: loc.column });
+                componentMap.set(name, entries);
+            }
+            if (!attrs.length)
+                return;
+            // Insert: <Foo ATTRS … >
+            magic.appendLeft(nameEnd, ' ' + attrs.join(' '));
+            taggedCount++;
+        },
+    });
+    if (taggedCount === 0)
+        return null;
+    return {
+        code: magic.toString(),
+        map: magic.generateMap({ hires: true, source: relPath, includeContent: true }),
+        taggedCount,
+    };
+}
+function getStringAttribute(node, name) {
+    for (const attr of node.attributes) {
+        if (attr.type === 'JSXAttribute' &&
+            attr.name.type === 'JSXIdentifier' &&
+            attr.name.name === name &&
+            attr.value &&
+            attr.value.type === 'StringLiteral') {
+            return attr.value.value;
+        }
+    }
+    return undefined;
+}
+function hasAttribute(node, name) {
+    for (const attr of node.attributes) {
+        if (attr.type === 'JSXAttribute' &&
+            attr.name.type === 'JSXIdentifier' &&
+            attr.name.name === name) {
+            return true;
+        }
+    }
+    return false;
+}
+function findEnclosingComponentName(path) {
+    let current = path.parentPath;
+    while (current) {
+        const node = current.node;
+        // function Foo() { return <jsx/> }
+        if (t.isFunctionDeclaration(node) && node.id && PASCAL_CASE.test(node.id.name)) {
+            return node.id.name;
+        }
+        // const Foo = (...) => <jsx/>
+        // const Foo = function (...) { return <jsx/> }
+        if ((t.isArrowFunctionExpression(node) || t.isFunctionExpression(node)) &&
+            current.parentPath &&
+            t.isVariableDeclarator(current.parentPath.node) &&
+            t.isIdentifier(current.parentPath.node.id) &&
+            PASCAL_CASE.test(current.parentPath.node.id.name)) {
+            return current.parentPath.node.id.name;
+        }
+        // class Foo extends Component { render() { return <jsx/> } }
+        if (t.isClassDeclaration(node) && node.id && PASCAL_CASE.test(node.id.name)) {
+            return node.id.name;
+        }
+        // export default function Foo() ...
+        if (t.isExportDefaultDeclaration(node) &&
+            t.isFunctionDeclaration(node.declaration) &&
+            node.declaration.id &&
+            PASCAL_CASE.test(node.declaration.id.name)) {
+            return node.declaration.id.name;
+        }
+        current = current.parentPath;
+    }
+    return undefined;
+}
+function escapeAttr(value) {
+    return value.replace(/"/g, '&quot;');
+}

package/dist/vite.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vite-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/vite'
+ *   export default defineConfig({ plugins: [harnessFE()] })
+ */
+export type { HarnessFEOptions } from './core.js';
+export declare const harnessFE: (options?: import("./core.js").HarnessFEOptions | undefined) => import("unplugin").VitePlugin<any> | import("unplugin").VitePlugin<any>[];
+export default harnessFE;

package/dist/vite.js

@@ -0,0 +1,10 @@
+/**
+ * Vite-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/vite'
+ *   export default defineConfig({ plugins: [harnessFE()] })
+ */
+import { unplugin } from './core.js';
+export const harnessFE = unplugin.vite;
+export default harnessFE;

package/dist/vue-transform.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Vue SFC transform: parse a .vue file and inject:
+ *   - `data-morphix-loc="<relPath>:<line>:<col>"` on every template element
+ *   - `data-morphix-comp="<ComponentName>"` on every template element
+ *
+ * Uses @vue/compiler-sfc to parse the SFC and @vue/compiler-dom to walk the
+ * template AST. MagicString splices attributes into the original source to
+ * preserve source maps.
+ *
+ * Side effect: every successfully scanned file contributes entries to the
+ * supplied `componentMap`: name → list of locations (file:line:col).
+ */
+import type { ComponentMap } from './transform.js';
+export interface VueTransformResult {
+    code: string;
+    map?: object;
+    taggedCount: number;
+    componentName: string | undefined;
+}
+/**
+ * Counters maintained across calls — populated even in dry-run mode. The
+ * unplugin core attaches a single instance per dev-server lifetime and
+ * dumps it on process exit so users can see how many Vue 2-era files were
+ * skipped (filter syntax, functional templates, malformed offsets, …).
+ */
+export interface VueTransformStats {
+    filesAttempted: number;
+    filesInjected: number;
+    elementsTagged: number;
+    skippedSfcError: number;
+    skippedTemplateError: number;
+    skippedWalkError: number;
+    skippedSelfCheck: number;
+    /** Sample of skipped file paths (capped at 50 to bound memory). */
+    skippedPaths: string[];
+}
+export declare function createVueTransformStats(): VueTransformStats;
+export interface VueTransformOptions {
+    /**
+     * When true (default), the transform re-parses its own output before
+     * returning it. Catches MagicString offset bugs against malformed Vue
+     * 2-era syntax before vue-loader ever sees them.
+     */
+    safeMode?: boolean;
+    /**
+     * When true, walk the AST and populate the componentMap as usual, but
+     * always return null (no source injection). Used by the dry-run
+     * coverage report.
+     */
+    dryRun?: boolean;
+    /** Counters to update; ignored if omitted. */
+    stats?: VueTransformStats;
+}
+/**
+ * Inject `data-morphix-*` attributes into a raw Vue template HTML fragment.
+ *
+ * Used by the webpack pipeline to handle the `*.vue?vue&type=template` virtual
+ * sub-module emitted by vue-loader. vue-loader's `templateLoader` will then
+ * compile the (now-tagged) template into a render function, preserving the
+ * attributes on every element vnode.
+ *
+ * `lineOffset` is added to every element's reported line number — pass the
+ * 1-based line index where this template appears in the original `.vue` file
+ * (so locations remain file-relative, not template-relative).
+ */
+export declare function transformVueTemplate(templateSource: string, relPath: string, componentName: string | undefined, componentMap: ComponentMap, lineOffset?: number, options?: VueTransformOptions): {
+    code: string;
+    map?: object;
+    taggedCount: number;
+} | null;
+/**
+ * Resolve the component name from a raw .vue source (used by webpack pipeline
+ * where we only see the template sub-module and need to look up the parent's
+ * component name from disk).
+ */
+export declare function resolveVueComponentName(source: string, relPath: string): string | undefined;
+/**
+ * Compute the 0-based line offset where the `<template>` *content* begins in
+ * the original .vue file. Adding this to template-relative line numbers gives
+ * file-relative numbers suitable for `data-morphix-loc`.
+ *
+ * Returns 0 if the SFC cannot be parsed or has no template block.
+ */
+export declare function getTemplateLineOffset(source: string, relPath: string): number;
+export declare function transformVueSFC(source: string, relPath: string, componentMap: ComponentMap, options?: VueTransformOptions): VueTransformResult | null;
+/**
+ * Format the stats counter for a human-readable shutdown report. Used by
+ * the unplugin core's process-exit handler.
+ */
+export declare function formatVueTransformReport(stats: VueTransformStats): string;