@vibesdotdev/hq 0.0.0-stage → 1.0.0-rc.2

package/dist/svelte/report/capture-context.js

@@ -0,0 +1,100 @@
+/**
+ * Report capture: the page facts a "Report a problem" submit carries, read
+ * through the handed runtime only. Page facts come from the runtime browser
+ * host (`runtime/browser-host` `readPage`), the version from the host fact
+ * `hostVersion`, and recent errors from logging's ring-buffer reader. Nothing
+ * here reads `window`, `document` or `navigator`.
+ *
+ * `buildFrictionReportBody` produces the one parsed body the dialog previews
+ * and submits, so the preview is exactly what is sent.
+ */
+import { CapabilityError, getRuntimeBrowserHost } from '@vibesdotdev/kernel';
+import { readRecentBrowserErrors } from '@vibesdotdev/logging/browser';
+import { FRICTION_REPORT_MAX_ERRORS, FrictionReportErrorSchema } from "../../friction/schemas/report.js";
+import { FrictionReportInputSchema } from "../../friction/schemas/intake.js";
+const MESSAGE_MAX = FrictionReportErrorSchema.shape.message.maxLength ?? 2000;
+const STACK_MAX = 8000;
+/** The page URL without its query or fragment, which may carry tokens or personal data. */
+export function stripQueryAndFragment(url) {
+    const parsed = new URL(url);
+    parsed.search = '';
+    parsed.hash = '';
+    return parsed.toString();
+}
+/** Errors older than this are not this page's problem; the ring buffer keeps days of them. */
+export const REPORT_ERROR_WINDOW_MS = 60 * 60 * 1000;
+const ID_LIKE_SEGMENT = /^(?:\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-z_-]{20,}|[0-9a-f]{12,})$/i;
+/**
+ * A route template for a path when the host hands none: every id-like segment
+ * (numbers, UUIDs, long hex or opaque tokens) and anything carrying `@` or `%`
+ * becomes `[id]`, so reports on different entities group together and the
+ * route never carries an identifier the redactor does not see.
+ */
+export function routeTemplateFromPath(pathname) {
+    const segments = pathname.split('/').map(segment => (segment && (ID_LIKE_SEGMENT.test(segment) || /[@%]/.test(segment)) ? '[id]' : segment));
+    return segments.join('/') || '/';
+}
+function surfaceErrorEntry(error, at) {
+    const message = error.message?.trim() ? `${error.status}: ${error.message.trim()}` : `HTTP ${error.status}`;
+    return { message: message.slice(0, MESSAGE_MAX), at, source: 'sveltekit' };
+}
+/**
+ * Capture the current page. A host with no page facts refuses
+ * `UNAVAILABLE browser-page-unavailable`; a host with no browser host refuses
+ * `UNAVAILABLE browser-host-unavailable`. On an error surface, the surface's
+ * own error is included even when no boundary recorded it, so a signed-out
+ * visitor's report always carries its error condition.
+ */
+export async function captureReportContext(runtime, options = {}) {
+    const host = await getRuntimeBrowserHost(runtime);
+    if (!host.readPage) {
+        throw new CapabilityError('The selected browser host offers no page facts.', 'UNAVAILABLE', {
+            reason: 'browser-page-unavailable', retryable: false
+        });
+    }
+    const page = host.readPage();
+    const url = stripQueryAndFragment(page.url);
+    const now = (options.now ?? (() => new Date()))();
+    const since = new Date(now.getTime() - REPORT_ERROR_WINDOW_MS).toISOString();
+    const recorded = await readRecentBrowserErrors(runtime, { limit: FRICTION_REPORT_MAX_ERRORS, since });
+    const errors = recorded.filter(event => event.message.trim()).map(event => {
+        const entry = { message: event.message.slice(0, MESSAGE_MAX), at: event.timestamp, source: event.source };
+        if (event.stack)
+            entry.stack = event.stack.slice(0, STACK_MAX);
+        return entry;
+    });
+    const surfaceError = options.error;
+    if (surfaceError) {
+        const already = recorded.some(event => event.status === surfaceError.status && (!surfaceError.message || event.message === surfaceError.message));
+        if (!already)
+            errors.push(surfaceErrorEntry(surfaceError, now.toISOString()));
+    }
+    const capture = {
+        route: options.route?.trim() || routeTemplateFromPath(new URL(url).pathname),
+        url,
+        viewport: { width: Math.round(page.viewport.width), height: Math.round(page.viewport.height) },
+        userAgent: page.userAgent.slice(0, 500),
+        locale: page.locale.slice(0, 35),
+        errors: errors.slice(-FRICTION_REPORT_MAX_ERRORS),
+        attachments: []
+    };
+    const appVersion = runtime.localEnvironment.hostVersion?.();
+    if (appVersion)
+        capture.appVersion = appVersion;
+    return capture;
+}
+/**
+ * The one body the dialog previews and submits. It is parsed through the
+ * intake's own schema, so defaults and trimming are already applied, and a
+ * body the intake would refuse is refused here, before anything is sent.
+ */
+export function buildFrictionReportBody(form, capture, occurrenceId) {
+    return FrictionReportInputSchema.safeParse({
+        severity: form.severity,
+        observed: form.description,
+        // The intake schema trims it and drops an empty answer.
+        expected: form.expected,
+        context: capture,
+        occurrenceId
+    });
+}

package/dist/svelte/report/report.plugin.d.ts

@@ -0,0 +1,68 @@
+/**
+ * HQ "Report a problem" on every page.
+ *
+ * Contributes the `hq.report-problem` utility to Kit's `app-shell/utility`
+ * kind (Kit renders the trigger and mounts `ReportProblemDialog`), and a
+ * `command-palette/source` entry that asks Kit to open the same utility.
+ * Visibility is Kit's `on-error` rule: signed-in viewers always see it;
+ * signed-out visitors see it only on Kit's error surface.
+ *
+ * Compose `@vibesdotdev/hq/svelte/report.plugin` into an app's browser
+ * runtime; suite apps get it through `VibesAppShell`.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { KindContext } from '@vibesdotdev/kernel/schemas/kind';
+import type { CommandPaletteResult, CommandPaletteSourceDescriptor, CommandPaletteSourceImplementation, SourceContext } from '@vibesdotdev/command-palette/schemas';
+export declare const REPORT_PROBLEM_UTILITY_ID = "hq.report-problem";
+export declare const reportProblemUtilityDescriptor: {
+    kind: "app-shell/utility";
+    id: string;
+    name: string;
+    icon: string;
+    placement: "header" | "user-menu";
+    order: number;
+    visibility: "always" | "signed-in" | "on-error";
+    enabled: boolean;
+    tags?: string[] | undefined;
+    hardware?: string[] | undefined;
+    priority?: number | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    description?: string | undefined;
+};
+/** The palette entry matches an empty query or any keyword prefix. */
+export declare function matchesReportQuery(query: string): boolean;
+/** One palette result that opens the report utility through Kit's runtime-scoped open request. */
+export declare function createReportProblemPaletteSource(runtime: RuntimeRef): CommandPaletteSourceImplementation;
+export declare class ReportProblemPaletteSource implements CommandPaletteSourceImplementation {
+    private readonly _descriptor;
+    private readonly context;
+    constructor(_descriptor: CommandPaletteSourceDescriptor, context: KindContext);
+    search(query: string, context: SourceContext): Promise<CommandPaletteResult[]>;
+}
+export declare const reportProblemPaletteSourceDescriptor: {
+    id: string;
+    kind: "command-palette/source";
+    enabled: true;
+    sourceId: string;
+    resultType: string;
+    label: string;
+    priority: number;
+    surfaces: string[];
+    name: string;
+    description: string;
+};
+export declare const reportProblemPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+export default reportProblemPlugin;
+//# sourceMappingURL=report.plugin.d.ts.map

package/dist/svelte/report/report.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.plugin.d.ts","sourceRoot":"","sources":["../../../src/svelte/report/report.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAGpE,OAAO,KAAK,EACX,oBAAoB,EACpB,8BAA8B,EAC9B,kCAAkC,EAClC,aAAa,EACb,MAAM,sCAAsC,CAAC;AAE9C,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAE7D,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;CAQzC,CAAC;AAIH,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED,kGAAkG;AAClG,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,UAAU,GAAG,kCAAkC,CAuBxG;AAED,qBAAa,0BAA2B,YAAW,kCAAkC;IAEnF,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,WAAW,EAAE,8BAA8B,EAC3C,OAAO,EAAE,WAAW;IAGtC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;CAG9E;AAED,eAAO,MAAM,oCAAoC;;;;;;;;;;;CAWP,CAAC;AAE3C,eAAO,MAAM,mBAAmB,6CAwB9B,CAAC;AAEH,eAAe,mBAAmB,CAAC"}

package/dist/svelte/report/report.plugin.js

@@ -0,0 +1,109 @@
+/**
+ * HQ "Report a problem" on every page.
+ *
+ * Contributes the `hq.report-problem` utility to Kit's `app-shell/utility`
+ * kind (Kit renders the trigger and mounts `ReportProblemDialog`), and a
+ * `command-palette/source` entry that asks Kit to open the same utility.
+ * Visibility is Kit's `on-error` rule: signed-in viewers always see it;
+ * signed-out visitors see it only on Kit's error surface.
+ *
+ * Compose `@vibesdotdev/hq/svelte/report.plugin` into an app's browser
+ * runtime; suite apps get it through `VibesAppShell`.
+ */
+import { createRuntimePlugin, loader } from '@vibesdotdev/kernel';
+import { APP_SHELL_PLUGIN_ID, defineAppShellUtility } from '@vibesdotdev/kit/app-shell/utility';
+import frictionClientDescriptor from "../../client/friction.client.descriptor.js";
+export const REPORT_PROBLEM_UTILITY_ID = 'hq.report-problem';
+export const reportProblemUtilityDescriptor = defineAppShellUtility({
+    id: REPORT_PROBLEM_UTILITY_ID,
+    name: 'Report a problem',
+    description: 'Tell us what went wrong on this page.',
+    icon: 'lucide:bug',
+    placement: 'header',
+    order: 100,
+    visibility: 'on-error'
+});
+const PALETTE_KEYWORDS = ['report', 'problem', 'bug', 'issue', 'feedback', 'broken', 'error'];
+/** The palette entry matches an empty query or any keyword prefix. */
+export function matchesReportQuery(query) {
+    const words = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return true;
+    return words.every(word => PALETTE_KEYWORDS.some(keyword => keyword.startsWith(word) || 'report a problem'.includes(word)));
+}
+/** One palette result that opens the report utility through Kit's runtime-scoped open request. */
+export function createReportProblemPaletteSource(runtime) {
+    return {
+        async search(query, _context) {
+            if (!matchesReportQuery(query))
+                return [];
+            return [{
+                    id: REPORT_PROBLEM_UTILITY_ID,
+                    sourceId: REPORT_PROBLEM_UTILITY_ID,
+                    resultType: 'action',
+                    title: 'Report a problem',
+                    description: 'Tell us what went wrong on this page',
+                    icon: 'lucide:bug',
+                    keywords: PALETTE_KEYWORDS,
+                    action: {
+                        type: 'execute',
+                        handler: async () => {
+                            const { openAppShellUtility } = await import('@vibesdotdev/kit/app-shell/utility');
+                            // Resolves false when no mounted surface shows the utility to this viewer: a no-op by Kit's contract.
+                            await openAppShellUtility(runtime, REPORT_PROBLEM_UTILITY_ID);
+                        }
+                    }
+                }];
+        }
+    };
+}
+export class ReportProblemPaletteSource {
+    _descriptor;
+    context;
+    constructor(_descriptor, context) {
+        this._descriptor = _descriptor;
+        this.context = context;
+    }
+    search(query, context) {
+        return createReportProblemPaletteSource(this.context.runtime).search(query, context);
+    }
+}
+export const reportProblemPaletteSourceDescriptor = {
+    id: REPORT_PROBLEM_UTILITY_ID,
+    kind: 'command-palette/source',
+    enabled: true,
+    sourceId: REPORT_PROBLEM_UTILITY_ID,
+    resultType: 'action',
+    label: 'Report a problem',
+    priority: 40,
+    surfaces: ['web'],
+    name: 'Report a problem',
+    description: 'Open the HQ report dialog from the command palette'
+};
+export const reportProblemPlugin = createRuntimePlugin({
+    id: '@vibesdotdev/hq/svelte/report',
+    name: 'HQ Report a problem',
+    description: 'Adds "Report a problem" to every page through the app shell and, where composed, the command palette',
+    dependencies: [APP_SHELL_PLUGIN_ID, 'runtime-client'],
+    // The palette is optional: an app without it still gets the shell utility.
+    optionalDependencies: ['command-palette'],
+    descriptors: [reportProblemUtilityDescriptor],
+    loaders: [
+        loader(REPORT_PROBLEM_UTILITY_ID, { kind: 'app-shell/utility', scope: 'browser' }, async () => ({
+            impl: (await import('./ReportProblemDialog.svelte')).default
+        }))
+    ],
+    onRegister(runtime) {
+        // The dialog submits through the runtime's `friction` client. An app that
+        // already composes HQ's client keeps its own; any other gets it here.
+        if (runtime.query('runtime/client').withId('friction').descriptors().length === 0) {
+            runtime.registerDescriptor('runtime/client', frictionClientDescriptor);
+            runtime.registerLoader('runtime/client', 'friction', async () => ({ impl: (await import("../../client/friction/index.js")).FrictionClient }));
+        }
+        if (!runtime.hasKind('command-palette/source'))
+            return;
+        runtime.registerDescriptor('command-palette/source', reportProblemPaletteSourceDescriptor);
+        runtime.registerLoader('command-palette/source', REPORT_PROBLEM_UTILITY_ID, async () => ({ impl: ReportProblemPaletteSource }));
+    }
+});
+export default reportProblemPlugin;

package/dist/svelte/report/severity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The dialog's severity choices, each mapped to exactly one friction
+ * severity. The reporter picks how the problem affects them; the stored
+ * signal carries the friction severity that promotion reads.
+ */
+import type { FrictionSeverity } from '../../friction/schemas/signal.ts';
+export interface ReportSeverityOption {
+    /** The friction severity this choice records. */
+    readonly severity: FrictionSeverity;
+    readonly label: string;
+    readonly hint: string;
+}
+/** In display order; the default is `annoyance`, matching the intake's default. */
+export declare const REPORT_SEVERITY_OPTIONS: readonly [{
+    readonly severity: "blocker";
+    readonly label: "It's stopping me";
+    readonly hint: "I can't finish what I was doing.";
+}, {
+    readonly severity: "annoyance";
+    readonly label: "It's getting in my way";
+    readonly hint: "Something is broken, but I can work around it.";
+}, {
+    readonly severity: "confusion";
+    readonly label: "I'm not sure what happened";
+    readonly hint: "Something was unclear or unexpected.";
+}, {
+    readonly severity: "nice-to-have";
+    readonly label: "It could be better";
+    readonly hint: "An idea or a small improvement.";
+}];
+export declare const DEFAULT_REPORT_SEVERITY: FrictionSeverity;
+//# sourceMappingURL=severity.d.ts.map

package/dist/svelte/report/severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.d.ts","sourceRoot":"","sources":["../../../src/svelte/report/severity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,MAAM,WAAW,oBAAoB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,mFAAmF;AACnF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;EAKgB,CAAC;AAErD,eAAO,MAAM,uBAAuB,EAAE,gBAA8B,CAAC"}

package/dist/svelte/report/severity.js

@@ -0,0 +1,13 @@
+/**
+ * The dialog's severity choices, each mapped to exactly one friction
+ * severity. The reporter picks how the problem affects them; the stored
+ * signal carries the friction severity that promotion reads.
+ */
+/** In display order; the default is `annoyance`, matching the intake's default. */
+export const REPORT_SEVERITY_OPTIONS = [
+    { severity: 'blocker', label: "It's stopping me", hint: "I can't finish what I was doing." },
+    { severity: 'annoyance', label: "It's getting in my way", hint: 'Something is broken, but I can work around it.' },
+    { severity: 'confusion', label: "I'm not sure what happened", hint: 'Something was unclear or unexpected.' },
+    { severity: 'nice-to-have', label: 'It could be better', hint: 'An idea or a small improvement.' }
+];
+export const DEFAULT_REPORT_SEVERITY = 'annoyance';

package/dist/tools/applet/applet.schemas.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export from @vibesdotdev/applets — ownership moved in Tranche 3 Task 3.4.
+ * Kept as a local shim so existing HQ-internal imports don't all change at once.
+ */
+export { AppletSourceFormatSchema, AppletOwnerSchema, AppletStoreSchema, AppletAdoptionSchema, AppletActionInputSchema, AppletSummarySchema, AppletTemplateSummarySchema, AppletActionOutputSchema, type AppletActionInput, type AppletActionOutput, type AppletSummary, type AppletTemplateSummary, type AppletOwner, type AppletStore, type AppletAdoption, type SurfaceArtifactInput } from '@vibesdotdev/applets/tools';
+//# sourceMappingURL=applet.schemas.d.ts.map

package/dist/tools/applet/applet.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applet.schemas.d.ts","sourceRoot":"","sources":["../../../src/tools/applet/applet.schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACN,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,MAAM,4BAA4B,CAAC"}

package/dist/tools/applet/applet.schemas.js

@@ -0,0 +1,6 @@
+/**
+ * Re-export from @vibesdotdev/applets — ownership moved in Tranche 3 Task 3.4.
+ * Kept as a local shim so existing HQ-internal imports don't all change at once.
+ */
+export { AppletSourceFormatSchema, AppletOwnerSchema, AppletStoreSchema, AppletAdoptionSchema, AppletActionInputSchema, AppletSummarySchema, AppletTemplateSummarySchema, AppletActionOutputSchema } from '@vibesdotdev/applets/tools';
+//# sourceMappingURL=applet.schemas.js.map

package/dist/tools/applet/applet.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applet.schemas.js","sourceRoot":"","sources":["../../../src/tools/applet/applet.schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACN,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,wBAAwB,EASxB,MAAM,4BAA4B,CAAC"}

package/dist/utils/exec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * hq's process-spawn composition the `runtime/execution` kind does not
+ * offer: run a command with inherited stdio and await its exit code.
+ * Capture and command discovery come straight from
+ * `@vibesdotdev/kernel/execution` (`runCapture`, `whichCommand`); nothing
+ * here duplicates them (hq PROPOSAL X8).
+ */
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+import { type ExecutionEnvironmentMode } from '@vibesdotdev/kernel/execution';
+export type RunInheritOptions = {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    envMode: ExecutionEnvironmentMode;
+    inheritReason?: string;
+};
+/**
+ * Spawn a command with stdout/stderr inherited and await its exit code.
+ * A signal kill (no exit code) answers -1. A launch failure rejects with
+ * the execution owner's typed refusal.
+ */
+export declare function runInherit(runtime: RuntimeRef, cmd: string, args: readonly string[], options: RunInheritOptions): Promise<number>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/utils/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAEN,KAAK,wBAAwB,EAC7B,MAAM,+BAA+B,CAAC;AAEvC,MAAM,MAAM,iBAAiB,GAAG;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,EAAE,wBAAwB,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,UAAU,CAC/B,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAAC,MAAM,CAAC,CAqBjB"}

package/dist/utils/exec.js

@@ -0,0 +1,38 @@
+/**
+ * hq's process-spawn composition the `runtime/execution` kind does not
+ * offer: run a command with inherited stdio and await its exit code.
+ * Capture and command discovery come straight from
+ * `@vibesdotdev/kernel/execution` (`runCapture`, `whichCommand`); nothing
+ * here duplicates them (hq PROPOSAL X8).
+ */
+import { getRuntimeExecution } from '@vibesdotdev/kernel/execution';
+/**
+ * Spawn a command with stdout/stderr inherited and await its exit code.
+ * A signal kill (no exit code) answers -1. A launch failure rejects with
+ * the execution owner's typed refusal.
+ */
+export async function runInherit(runtime, cmd, args, options) {
+    const execution = await getRuntimeExecution(runtime);
+    const env = {};
+    const unsetEnv = [];
+    for (const [key, value] of Object.entries(options.env ?? {})) {
+        if (value === undefined)
+            unsetEnv.push(key);
+        else
+            env[key] = value;
+    }
+    const handle = await execution.spawn({
+        command: cmd,
+        args: [...args],
+        cwd: options.cwd,
+        env,
+        unsetEnv,
+        envMode: options.envMode,
+        inheritReason: options.inheritReason,
+        stdout: 'inherit',
+        stderr: 'inherit'
+    });
+    const { code } = await handle.exited;
+    return code ?? -1;
+}
+//# sourceMappingURL=exec.js.map

package/dist/utils/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACN,mBAAmB,EAEnB,MAAM,+BAA+B,CAAC;AASvC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC/B,OAAmB,EACnB,GAAW,EACX,IAAuB,EACvB,OAA0B;IAE1B,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;;YACvC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC;QACpC,OAAO,EAAE,GAAG;QACZ,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG;QACH,QAAQ;QACR,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;KACjB,CAAC,CAAC;IACH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC;IACrC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/dist/utils/fs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a path exists as a regular file (`Bun.file(p).exists()`
+ * replacement), through the runtime's unbound `filesystem/adapter`: these
+ * are host-home paths, not workspace paths. Matches Bun's semantics:
+ * false for directories and for missing paths. Only confirmed absence
+ * answers false; every other failure propagates whole.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+export declare function fileExists(runtime: RuntimeRef, path: string): Promise<boolean>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/utils/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGjG,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBpF"}

package/dist/utils/fs.js

@@ -0,0 +1,25 @@
+/**
+ * Whether a path exists as a regular file (`Bun.file(p).exists()`
+ * replacement), through the runtime's unbound `filesystem/adapter`: these
+ * are host-home paths, not workspace paths. Matches Bun's semantics:
+ * false for directories and for missing paths. Only confirmed absence
+ * answers false; every other failure propagates whole.
+ */
+import { CapabilityError, settle, valueFreeFailure } from '@vibesdotdev/kernel';
+import { resolveFileSystemAdapter } from '@vibesdotdev/filesystem';
+export async function fileExists(runtime, path) {
+    if (!runtime.hasKind('filesystem/adapter')) {
+        throw new CapabilityError("fileExists has no filesystem backend: no 'filesystem/adapter' is registered", 'UNAVAILABLE', { reason: 'file-exists-no-filesystem' });
+    }
+    const fs = await resolveFileSystemAdapter(runtime, { binding: false });
+    // Settle the real stat: only confirmed absence answers false, even if the
+    // path vanishes mid-read; every other failure propagates whole.
+    const stated = await settle(() => fs.stat(path));
+    if (stated.ok)
+        return stated.value.kind === 'file';
+    const code = valueFreeFailure(stated.cause).code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return false;
+    throw stated.cause;
+}
+//# sourceMappingURL=fs.js.map

package/dist/utils/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,EAAmB,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAmB,EAAE,IAAY;IACjE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,eAAe,CACxB,6EAA6E,EAC7E,aAAa,EACb,EAAE,MAAM,EAAE,2BAA2B,EAAE,CACvC,CAAC;IACH,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,wBAAwB,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACvE,0EAA0E;IAC1E,gEAAgE;IAChE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;IACnD,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;IACjD,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,MAAM,CAAC,KAAK,CAAC;AACpB,CAAC"}