@incajs/cli 0.0.4 → 0.0.6

package/README.md

@@ -23,7 +23,10 @@ bootstrapping; it wins outright when both exist.
 ## Commands
 
 - **`inca dev`** — watches your app and opens a live-reloading window,
-  reloading on every change.
+  reloading on every change. `--experimental-hmr` (or
+  `INCA_EXPERIMENTAL_HMR=1`) opts into experimental, module-granular
+  hot reloading instead — see the
+  [HMR guide](https://tom96da.github.io/incajs/guide/hmr).
 - **`inca build`** — bundles your app for production, once, with no
   window opened.
 - **`inca package`** — builds your app, then packages it with a
@@ -57,11 +60,13 @@ once it is packaged.
 
 ## Requirements
 
-`inca`'s host binary is pulled in automatically as a platform-specific
-optional dependency (Linux and macOS on x64/arm64; Windows isn't
-supported yet) — neither Cargo nor Rust are needed. Set `INCA_HOST_BIN`
-to use a specific binary instead, e.g. on a platform with no published
-one yet, or a custom build.
+A prebuilt binary is pulled in automatically as a platform-specific
+optional dependency — neither Cargo nor Rust are needed. See
+[Host binary](https://tom96da.github.io/incajs/guide/#host-binary) for
+per-platform support.
+
+Set `INCA_HOST_BIN` to use a specific binary instead, e.g. on a
+platform with no published one yet, or a custom build.
 
 ## How it works
 

package/dist/adapter/types.d.mts

@@ -3,38 +3,6 @@ export interface Watcher {
     /** Stops watching and releases the underlying build process. */
     close(): Promise<void>;
 }
-/** Options for {@link Bundler.watch}. */
-export interface BundlerOptions {
-    /** The app's own entry point — may import `.vue` files. */
-    entry: string;
-    /** Where the build's output is written. */
-    outDir: string;
-    /**
-     * Values the built app carries for `inca-host` to read — its name, id
-     * and window. Any JSON-serializable object.
-     */
-    runtimeConfig?: unknown;
-    /** `"development"` keeps a framework's own warnings; `"production"` strips them. */
-    mode: "development" | "production";
-    /** Called after each successful (re)build, with what it wrote. */
-    onBuild: (output: BuildOutput) => void;
-    /** Called instead of `onBuild` when a (re)build fails. */
-    onError: (error: {
-        message: string;
-        stack: string | null;
-        code?: string | null;
-    }) => void;
-    /** Where the bundler's own output goes. Defaults to `process.stdout`. */
-    stdout?: NodeJS.WritableStream;
-    /** Where the bundler's warnings and errors go. Defaults to `process.stderr`. */
-    stderr?: NodeJS.WritableStream;
-    /**
-     * Drops the bundler's progress output and size report, leaving the
-     * per-build summary. Set it when the build has to stay silent: part of
-     * that output goes to the process's own stdout, not to `stdout` above.
-     */
-    quiet?: boolean;
-}
 /** Options for {@link Bundler.build}. */
 export interface BuildOptions {
     /** The app's own entry point — may import `.vue` files. */
@@ -57,6 +25,19 @@ export interface BuildOptions {
      */
     quiet?: boolean;
 }
+/** Options for {@link Bundler.watch}. */
+export interface BundlerOptions extends BuildOptions {
+    /** `"development"` keeps a framework's own warnings; `"production"` strips them. */
+    mode: "development" | "production";
+    /** Called after each successful (re)build, with what it wrote. */
+    onBuild: (output: BuildOutput) => void;
+    /** Called instead of `onBuild` when a (re)build fails. */
+    onError: (error: {
+        message: string;
+        stack: string | null;
+        code?: string | null;
+    }) => void;
+}
 /** What a build wrote — the result of {@link Bundler.build}, and every {@link BundlerOptions.onBuild} call. */
 export interface BuildOutput {
     /** Directory holding every file this build emitted. */
@@ -71,6 +52,59 @@ export interface BuildOutput {
         at: number;
     };
 }
+/**
+ * A failed HMR update's detail — the same fields a Rollup/Vite plugin
+ * error carries beyond `message`/`stack`, when it has them.
+ */
+export interface UpdateError {
+    message: string;
+    stack?: string | null;
+    plugin?: string | null;
+    id?: string | null;
+    frame?: string | null;
+    loc?: {
+        line: number;
+        column: number;
+    } | null;
+}
+/** Options for {@link Bundler.hmr}. */
+export interface HmrOptions {
+    /** The app's own entry point — may import `.vue` files. */
+    entry: string;
+    /** The app's root directory — where its dev-only scratch files are written. */
+    cwd: string;
+    /**
+     * Values the built app carries for `inca-host` to read — its name, id
+     * and window. Any JSON-serializable object.
+     */
+    runtimeConfig?: unknown;
+    /** Overrides where the synthesized entry imports `hmr-runtime.js` from. Test-only. */
+    runtimePath?: string;
+    /** Where the bundler's own output goes. Defaults to `process.stdout`. */
+    stdout?: NodeJS.WritableStream;
+    /** Where the bundler's warnings and errors go. Defaults to `process.stderr`. */
+    stderr?: NodeJS.WritableStream;
+    /** Drops per-update/reload logging; warnings and errors still surface. */
+    quiet?: boolean;
+    /** Delivers a bundler payload to the running app over the dev channel. */
+    notify: (payload: unknown) => void;
+    /** Called in place of forwarding a whole-app reload payload to the app. */
+    reload: () => void;
+    /** Called when an update the app fetched failed to compile. */
+    onError: (error: UpdateError) => void;
+    /** Called after a successful update, with the file that changed and how long it took. */
+    onUpdate?: (info: {
+        file: string;
+        took: number;
+    }) => void;
+}
+/** A running HMR session — the value {@link Bundler.hmr} resolves to. */
+export interface HmrChannel extends Watcher {
+    /** The synthesized entry `inca-host` evaluates for this session. */
+    entryFile: string;
+    /** Feeds a payload the running app sent back into the bundler's dev server. */
+    dispatch: (payload: unknown) => void;
+}
 /**
  * The contract a bundler adapter satisfies. Supporting another bundler
  * means adding a sibling adapter module and injecting its `Bundler` here —
@@ -80,4 +114,9 @@ export interface Bundler {
     watch(options: BundlerOptions): Promise<Watcher>;
     /** One-shot production build, used by `inca build` — rejects on failure. */
     build(options: BuildOptions): Promise<BuildOutput>;
+    /**
+     * Module-granular dev updates, used by `inca dev --experimental-hmr`.
+     * Optional — a bundler adapter with no HMR support simply omits it.
+     */
+    hmr?(options: HmrOptions): Promise<HmrChannel>;
 }

package/dist/adapter/vite/build.d.mts

@@ -1,5 +1,4 @@
 import { BuildOptions, BuildOutput } from '../types.mts';
-export type { BuildOptions, BuildOutput } from '../types.mts';
 /**
  * Builds `entry` into a minified, production build under `outDir` once, and
  * rejects on failure rather than reporting it through a callback. Never

package/dist/adapter/vite/captureOutput.d.mts

@@ -1,4 +1,5 @@
 import { Plugin } from 'vite';
+import { BuildOutput } from '../types.mts';
 /** What one (re)build actually wrote, relative to its own `outDir`. */
 export interface CapturedOutput {
     /** The emitted chunk marked as this build's entry. */
@@ -6,6 +7,8 @@ export interface CapturedOutput {
     /** Every emitted file, as the bundler reported it. */
     files: readonly string[];
 }
+/** Resolves `captured`'s paths against `outDir` into a {@link BuildOutput}. */
+export declare function toBuildOutput(outDir: string, captured: CapturedOutput, changed?: BuildOutput["changed"]): BuildOutput;
 /**
  * A Vite plugin reporting `sink` the files a build wrote once they land on
  * disk, via `writeBundle` — the one hook that fires uniformly for a

package/dist/adapter/vite/emitConfig.d.mts

@@ -1,6 +1,12 @@
 import { Plugin } from 'vite';
 /** The file a build writes its app's config to, beside the entry. */
 export declare const CONFIG_FILE_NAME = "inca.json";
+/**
+ * Serializes `config` the way `inca.json` is written: `undefined` for
+ * anything that shouldn't produce a file — `undefined` itself, or an
+ * object with no keys.
+ */
+export declare function serializeConfig(config: unknown): string | undefined;
 /**
  * Writes `config` to `inca.json` beside the entry, for `inca-host` to read
  * when it starts the app.

package/dist/adapter/vite/hmr.d.mts

@@ -0,0 +1,7 @@
+import { HmrChannel, HmrOptions } from '../types.mts';
+/**
+ * Starts a Vite dev server driving the app over its dev channel instead of
+ * a browser: a `"client"` environment with a custom {@link HotChannel}
+ * standing in for the WebSocket server `server.ws: false` disables.
+ */
+export declare function hmr({ entry, cwd, runtimeConfig, runtimePath, stdout, stderr, quiet, notify, reload, onError, onUpdate, }: HmrOptions): Promise<HmrChannel>;

package/dist/adapter/vite/index.d.mts

@@ -1,2 +1,3 @@
 export { build } from './build.mts';
+export { hmr } from './hmr.mts';
 export { watch } from './watch.mts';

package/dist/adapter/vite/logger.d.mts

@@ -1,7 +1,8 @@
 import { Logger } from 'vite';
 /**
  * A Vite {@link Logger} writing to the given streams: `info` to `stdout`,
- * `warn` and `error` to `stderr`. Messages arrive fully formatted and are
- * written as they are; Vite's own `LogOptions` are ignored.
+ * `warn`/`error` to `stderr`, all unfiltered by Vite's own `LogOptions` — a
+ * custom logger bypasses those. `quiet` drops `info` only; `warn`/`error`
+ * still write, since they report something broken, not just what changed.
  */
-export declare function streamLogger(stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream): Logger;
+export declare function streamLogger(stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream, quiet?: boolean): Logger;

package/dist/adapter/vite/watch.d.mts

@@ -1,5 +1,4 @@
 import { BundlerOptions, Watcher } from '../types.mts';
-export type { Watcher } from '../types.mts';
 /**
  * Builds `entry` into a build under `outDir` and rebuilds it on every
  * change, calling `onBuild` with what each rebuild wrote. Never starts,