@harness-fe/unplugin 3.0.0

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @harness-fe/unplugin — unified build plugin.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/vite'
+ *   import { harnessFE } from '@harness-fe/unplugin/rspack'
+ *
+ * Webpack: use @harness-fe/webpack (a native plugin — see that package).
+ *
+ * Or import the raw unplugin for custom integrations:
+ *   import { unplugin, unpluginFactory } from '@harness-fe/unplugin'
+ */
+
+export { unplugin, unpluginFactory, type HarnessFEOptions } from './core.js';
+export { transformJsx, type ComponentMap, type ComponentLocation, type TransformResult } from './transform.js';
+export {
+    transformVueSFC,
+    transformVueTemplate,
+    resolveVueComponentName,
+    getTemplateLineOffset,
+    createVueTransformStats,
+    formatVueTransformReport,
+    type VueTransformOptions,
+    type VueTransformResult,
+    type VueTransformStats,
+} from './vue-transform.js';
+
+// Internal building blocks — re-exported for downstream native plugins (e.g.
+// @harness-fe/webpack) that cannot use the unplugin adapter directly.
+export { createMcpClient } from './internal/mcp-client.js';
+export { installNodeLogCapture } from './internal/log-capture.js';
+export { createBuildIdentity, appendTokenQuery } from './internal/buildIdentity.js';
+export type { McpClient, McpClientContext, PeerRole } from './internal/types.js';
+export type { BuildIdentity, BuildIdentityOptions } from './internal/buildIdentity.js';

package/src/internal/buildIdentity.ts

@@ -0,0 +1,66 @@
+/**
+ * Lazy resolvers for build-time identity metadata (buildId, displayName).
+ *
+ * Both are deferred until first read because the host bundler may not have
+ * resolved `projectRoot` at plugin instantiation time.
+ */
+
+import { createRequire } from 'node:module';
+import { resolveBuildId } from '../resolveBuildId.js';
+
+const require = createRequire(import.meta.url);
+
+export interface BuildIdentityOptions {
+    userBuildId?: string;
+    userDisplayName?: string;
+    /** Captured once so dev-mode fallback ids stay stable across re-reads. */
+    startTs?: number;
+}
+
+export interface BuildIdentity {
+    getBuildId(root: string): string;
+    getDisplayName(root: string): string | undefined;
+}
+
+export function createBuildIdentity(opts: BuildIdentityOptions = {}): BuildIdentity {
+    const startTs = opts.startTs ?? Date.now();
+    let resolvedBuild: ReturnType<typeof resolveBuildId> | undefined;
+    let resolvedDisplayName: string | undefined = opts.userDisplayName;
+    let displayNameResolved = opts.userDisplayName !== undefined;
+
+    return {
+        getBuildId(root: string): string {
+            if (resolvedBuild) return resolvedBuild.buildId;
+            resolvedBuild = resolveBuildId({
+                userConfig: opts.userBuildId,
+                root,
+                startTs,
+            });
+            return resolvedBuild.buildId;
+        },
+        getDisplayName(root: string): string | undefined {
+            if (displayNameResolved) return resolvedDisplayName;
+            displayNameResolved = true;
+            try {
+                const pkg = JSON.parse(
+                    require('node:fs').readFileSync(
+                        require('node:path').join(root, 'package.json'),
+                        'utf-8',
+                    ),
+                ) as { name?: string };
+                resolvedDisplayName = pkg.name;
+            } catch {
+                resolvedDisplayName = undefined;
+            }
+            return resolvedDisplayName;
+        },
+    };
+}
+
+/** Append `?token=…` (or `&token=…`) onto a URL, idempotent on empty token. */
+export function appendTokenQuery(url: string, token: string | undefined): string {
+    if (!token) return url;
+    if (/[?&]token=/.test(url)) return url;
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}token=${encodeURIComponent(token)}`;
+}

package/src/internal/log-capture.ts

@@ -0,0 +1,26 @@
+/**
+ * Intercepts `process.stdout.write` and `process.stderr.write` to emit
+ * `'node:log'` / `'node:err'` events to the MCP server.
+ *
+ * Returns a cleanup function that restores the original write methods.
+ */
+export function installNodeLogCapture(
+    emitEvent: (name: string, payload: unknown) => void,
+): () => void {
+    const origOut = process.stdout.write.bind(process.stdout);
+    const origErr = process.stderr.write.bind(process.stderr);
+
+    (process.stdout as any).write = (chunk: any, ...args: any[]) => {
+        emitEvent('node:log', { text: String(chunk) });
+        return origOut(chunk, ...args);
+    };
+    (process.stderr as any).write = (chunk: any, ...args: any[]) => {
+        emitEvent('node:err', { text: String(chunk) });
+        return origErr(chunk, ...args);
+    };
+
+    return () => {
+        (process.stdout as any).write = origOut;
+        (process.stderr as any).write = origErr;
+    };
+}

package/src/internal/mcp-client.ts

@@ -0,0 +1,181 @@
+/**
+ * MCP WebSocket client + command dispatch loop, factored out of the unplugin
+ * core so the native webpack plugin can reuse it without depending on the
+ * unplugin webpack adapter (which carries circular references via the plugin
+ * instance and breaks thread-loader serialization).
+ *
+ * The componentMap is supplied by the caller — vite/rspack pass their shared
+ * map; the webpack plugin passes its shared-state map keyed by pluginId.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { WebSocket } from 'ws';
+import {
+    COMMAND,
+    type CommandFrame,
+    type EventFrame,
+    type Frame,
+    type HelloFrame,
+    type ResponseFrame,
+    frameSchema,
+} from '@harness-fe/protocol';
+import type { McpClient, McpClientContext } from './types.js';
+
+function newId(): string {
+    const g = globalThis as { crypto?: { randomUUID?: () => string } };
+    return g.crypto?.randomUUID ? g.crypto.randomUUID() : `${Date.now()}-${Math.random()}`;
+}
+
+export function createMcpClient(ctx: McpClientContext): McpClient {
+    let ws: WebSocket | undefined;
+    let isActive = false;
+
+    function send(frame: EventFrame | HelloFrame | ResponseFrame): void {
+        if (!ws || ws.readyState !== WebSocket.OPEN) return;
+        try {
+            ws.send(JSON.stringify(frame));
+        } catch {
+            /* swallow */
+        }
+    }
+
+    async function runCommand(command: string, args: unknown): Promise<unknown> {
+        switch (command) {
+            case COMMAND.PROJECT_SOURCE: {
+                const a = args as { file?: string; component?: string };
+                let file = a.file;
+                if (!file && a.component) {
+                    const locs = ctx.componentMap.get(a.component);
+                    if (!locs?.length) {
+                        throw new Error(
+                            `project.source: component "${a.component}" not found in the scan`,
+                        );
+                    }
+                    file = locs[0].file;
+                }
+                if (!file) {
+                    throw new Error('project.source: pass either `file` or `component`');
+                }
+                const abs = resolve(ctx.projectRoot, file);
+                if (!abs.startsWith(ctx.projectRoot)) {
+                    throw new Error(
+                        `project.source: refusing to read outside project root: ${file}`,
+                    );
+                }
+                const content = readFileSync(abs, 'utf-8');
+                return { file, content };
+            }
+            case COMMAND.PROJECT_WHERE_IS: {
+                const a = args as { component: string };
+                const locs = ctx.componentMap.get(a.component);
+                if (!locs?.length) {
+                    throw new Error(`project.where_is: component "${a.component}" not found`);
+                }
+                return { component: a.component, locations: locs };
+            }
+            case COMMAND.PROJECT_MODULE_GRAPH: {
+                const components: Record<string, Array<{ file: string; line: number; col: number }>> = {};
+                for (const [name, locs] of ctx.componentMap.entries()) {
+                    components[name] = locs;
+                }
+                return {
+                    components,
+                    totalFiles: new Set(
+                        [...ctx.componentMap.values()].flat().map((l) => l.file),
+                    ).size,
+                };
+            }
+            default:
+                throw new Error(`harness-fe: unhandled command "${command}"`);
+        }
+    }
+
+    async function handleCommand(frame: CommandFrame): Promise<void> {
+        let response: ResponseFrame;
+        try {
+            const result = await runCommand(frame.command, frame.args);
+            response = { type: 'response', id: frame.id, ok: true, result };
+        } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            response = { type: 'response', id: frame.id, ok: false, error: { message } };
+        }
+        send(response);
+    }
+
+    function connect(): void {
+        if (isActive) return;
+        isActive = true;
+        connectInternal();
+    }
+
+    function connectInternal(): void {
+        try {
+            const headers: Record<string, string> = {};
+            if (ctx.token) headers.authorization = `Bearer ${ctx.token}`;
+            ws = new WebSocket(ctx.mcpUrl, { headers });
+            ws.on('open', () => {
+                const hello: HelloFrame = {
+                    type: 'hello',
+                    id: newId(),
+                    role: ctx.peerRole,
+                    projectId: ctx.projectId,
+                    parentProjectId: ctx.parentProjectId,
+                    displayName: ctx.getDisplayName(),
+                    buildId: ctx.getBuildId(),
+                };
+                send(hello);
+            });
+            ws.on('message', (raw) => {
+                let parsed: unknown;
+                try {
+                    parsed = JSON.parse(raw.toString());
+                } catch {
+                    return;
+                }
+                const result = frameSchema.safeParse(parsed);
+                if (!result.success) return;
+                const frame = result.data as Frame;
+                if (frame.type === 'command') void handleCommand(frame);
+            });
+            ws.on('error', () => {
+                // Server may not be running — best-effort metadata only.
+            });
+            ws.on('close', () => {
+                setTimeout(() => {
+                    if (isActive) connectInternal();
+                }, 2000);
+            });
+        } catch {
+            /* swallow */
+        }
+    }
+
+    function disconnect(): void {
+        isActive = false;
+        ws?.close();
+        ws = undefined;
+    }
+
+    function emitEvent(name: string, payload: unknown): void {
+        const event: EventFrame = {
+            type: 'event',
+            id: newId(),
+            projectId: ctx.projectId,
+            buildId: ctx.getBuildId(),
+            name,
+            ts: Date.now(),
+            payload,
+        };
+        send(event);
+    }
+
+    return {
+        connect,
+        disconnect,
+        emitEvent,
+        get isActive() {
+            return isActive;
+        },
+    };
+}

package/src/internal/types.ts

@@ -0,0 +1,66 @@
+/**
+ * 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/src/resolveBuildId.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveBuildId } from './resolveBuildId.js';
+
+describe('resolveBuildId', () => {
+    let root: string;
+    const origEnv = { ...process.env };
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), 'rbid-'));
+        // Strip CI env vars so tests aren't influenced by the host env.
+        delete process.env.GITHUB_SHA;
+        delete process.env.GIT_COMMIT;
+        delete process.env.CI_COMMIT_SHA;
+        delete process.env.BUILDKITE_COMMIT;
+    });
+
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+        process.env = { ...origEnv };
+    });
+
+    it('userConfig wins over all auto-detection', () => {
+        process.env.GITHUB_SHA = 'aaaaaaaaaa';
+        const out = resolveBuildId({ root, userConfig: 'explicit-id-99' });
+        expect(out.buildId).toBe('explicit-id-99');
+        expect(out.gitSha).toBeUndefined();
+    });
+
+    it('falls back to dev hash + startTs when neither git nor CI is available', () => {
+        // No package.json, no git → pure fallback path
+        const out = resolveBuildId({ root, startTs: 1700000000000 });
+        // dev-<8-char-hash>-<base36-ts>
+        expect(out.buildId).toMatch(/^dev-[a-f0-9]{8}-[a-z0-9]+$/);
+        expect(out.sourceDigest).toBeDefined();
+        expect(out.gitSha).toBeUndefined();
+    });
+
+    it('two consecutive resolves with the same root + startTs produce the same buildId', () => {
+        writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'fixture' }));
+        const a = resolveBuildId({ root, startTs: 42 });
+        const b = resolveBuildId({ root, startTs: 42 });
+        expect(a.buildId).toBe(b.buildId);
+    });
+
+    it('changing package.json changes the dev hash component', () => {
+        writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'a' }));
+        const a = resolveBuildId({ root, startTs: 1 });
+        writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'b' }));
+        const b = resolveBuildId({ root, startTs: 1 });
+        expect(a.buildId).not.toBe(b.buildId);
+    });
+
+    it('reads GITHUB_SHA when present', () => {
+        process.env.GITHUB_SHA = '0123456789abcdef0123';
+        const out = resolveBuildId({ root });
+        expect(out.buildId).toBe('0123456789ab-ci');
+        expect(out.gitSha).toBe('0123456789abcdef0123');
+        expect(out.gitDirty).toBe(false);
+    });
+});

package/src/resolveBuildId.ts

@@ -0,0 +1,125 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * 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 function resolveBuildId(opts: ResolveBuildIdOptions): ResolvedBuildId {
+    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: string[], cwd: string): string | undefined {
+    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: string): string {
+    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/src/resolveProjectId.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fc from 'fast-check';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { resolveProjectId } from './resolveProjectId.js';
+
+// Cleanup temp dirs after each test
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+    for (const dir of tempDirs.splice(0)) {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+
+async function makeTempDir(): Promise<string> {
+    const dir = await mkdtemp(join(tmpdir(), 'harness-test-'));
+    tempDirs.push(dir);
+    return dir;
+}
+
+// Feature: persistence, Property 1: Project ID resolution priority
+describe('Property 1: Project ID resolution priority', () => {
+    it('resolveProjectId respects priority: userConfig > file > generated UUID', async () => {
+        // Validates: Requirements 1.1, 1.2, 1.3
+        await fc.assert(
+            fc.asyncProperty(
+                fc.tuple(fc.option(fc.uuidV(4)), fc.boolean()),
+                async ([userConfig, filePresent]) => {
+                    const root = await makeTempDir();
+                    const idFilePath = join(root, '.harness-id');
+                    const fileUuid = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee';
+
+                    if (filePresent) {
+                        await writeFile(idFilePath, fileUuid, 'utf-8');
+                    }
+
+                    const result = await resolveProjectId(root, userConfig ?? undefined);
+
+                    if (userConfig !== null) {
+                        // Priority 1: userConfig wins regardless of file presence
+                        expect(result).toBe(userConfig);
+                    } else if (filePresent) {
+                        // Priority 2: file content used when userConfig absent
+                        expect(result).toBe(fileUuid);
+                    } else {
+                        // Priority 3: freshly generated UUID — must be a valid UUID v4
+                        expect(result).toMatch(
+                            /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+                        );
+                        // And it must have been written to the file
+                        const written = await readFile(idFilePath, 'utf-8');
+                        expect(written.trim()).toBe(result);
+                    }
+                }
+            ),
+            { numRuns: 100 }
+        );
+    });
+});
+
+// Feature: persistence, Property 2: .harness-id file format round-trip
+describe('Property 2: .harness-id file format round-trip', () => {
+    it('UUID written to .harness-id round-trips exactly with no extra characters', async () => {
+        // Validates: Requirements 1.5
+        await fc.assert(
+            fc.asyncProperty(
+                fc.uuidV(4),
+                async (_uuid) => {
+                    // We call resolveProjectId with no userConfig and no existing file,
+                    // so it generates a fresh UUID and writes it to .harness-id.
+                    // We then verify the file content matches the returned UUID exactly.
+                    const root = await makeTempDir();
+                    const idFilePath = join(root, '.harness-id');
+
+                    const returned = await resolveProjectId(root, undefined);
+
+                    const fileContent = await readFile(idFilePath, 'utf-8');
+
+                    // Trimming whitespace must produce the exact same UUID
+                    expect(fileContent.trim()).toBe(returned);
+
+                    // No BOM (UTF-8 BOM is \uFEFF)
+                    expect(fileContent.charCodeAt(0)).not.toBe(0xfeff);
+
+                    // No trailing newline or extra whitespace — file contains only the UUID
+                    expect(fileContent).toBe(returned);
+
+                    // Must be a valid UUID v4
+                    expect(returned).toMatch(
+                        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+                    );
+                }
+            ),
+            { numRuns: 100 }
+        );
+    });
+});