@incajs/cli 0.0.1 → 0.0.3

package/README.md

@@ -5,104 +5,62 @@ SPDX-License-Identifier: MIT OR Apache-2.0
 
 # @incajs/cli
 
-The `inca` command. Internally it wires a bundler adapter's build watch to
-a dev-protocol client talking to `inca-host` — both live inside this
-package (`src/adapter/`, `src/dev-client/`) since neither is ever imported
-on its own.
-
-`inca dev` watches an app's entry point, starts `inca-host` once the
-first bundle lands, and reloads it on every rebuild. `inca build` runs
-the same pipeline once, with the watcher removed and production settings
-on, and never starts a host. `inca package` builds the same way, then
-pairs the bundle with a prebuilt `inca-host` into a distributable
-application. `adapter/vite` is the bundler wired in by default for all
-three — swapping it for another `Bundler` (the contract `adapter/types.mts`
-defines) is a dependency change in `defaultBundler.mts`, not an edit
-anywhere else.
+The `inca` command for building and running [Incarnative.js](https://github.com/tom96da/incajs)
+apps: `inca dev`, `inca build`, and `inca package`.
+
+## Install
+
+```sh
+npm i -D @incajs/cli
+```
 
 ## App entry
 
-No entry point is required. Drop a `src/App.vue` and that's a whole app —
-`inca` wraps it in `createIncaApp(App).mount()` (from `incajs/vue`)
-itself. Commit a `src/main.mts` instead for full control over
+No entry point is required. Drop a `src/App.vue` and that's a whole
+app. Commit a `src/main.mts` instead for full control over
 bootstrapping; it wins outright when both exist.
 
-## `inca package`
-
-Emits a platform-native application into `dist/`: a `.app` on macOS, a
-plain directory on Linux — other platforms aren't supported yet. Either
-way, the layout puts the host binary and `bundle.js` beside each other, so
-the app launches with no arguments and no terminal.
-
-It needs a release build of the host to bundle — see `resolveHostBin`
-below for how one is found.
-
-App metadata comes from the app's own `package.json`, with an optional
-`"inca"` key overriding what's derived from it:
-
-```jsonc
-{
-  "name": "click_counter",
-  "version": "1.0.0",
-  "inca": {
-    "productName": "Click Counter", // defaults to "name", scope stripped
-    "identifier": "com.example.click-counter", // defaults to a generated org.inca.<slug>
-    "icon": "assets/icon.icns" // resolved relative to the app's own directory
-  }
-}
+## Commands
+
+- **`inca dev`** — watches your app and opens a live-reloading window,
+  reloading on every change.
+- **`inca build`** — bundles your app for production, once, with no
+  window opened.
+- **`inca package`** — builds your app, then packages it with a
+  prebuilt `inca-host` into a distributable application: a `.app` on
+  macOS, a plain directory on Linux (other platforms aren't supported
+  yet).
+
+When running `inca`, it will automatically try to resolve a config file
+named `inca.config.ts` inside your app's root (other JS/JSON extensions
+are also supported), for app metadata and build settings:
+
+```ts [inca.config.ts]
+import { defineConfig } from "@incajs/cli/config";
+
+export default defineConfig({
+  // the app's display name
+  productName: "Click Counter",
+  // macOS's CFBundleIdentifier or equivalent
+  identifier: "com.example.click-counter",
+  // the packaged app's icon file
+  icon: "assets/icon.icns",
+});
 ```
 
 An `identifier` should be world-unique, so `inca package` prints a note
 when it falls back to the generated one rather than using it silently.
 
-## `dev-client`
-
-The Node end of the dev protocol: resolves and spawns `inca-host --dev
-<bundle>`, and speaks the newline-delimited JSON-RPC 2.0 channel it
-answers on.
-
-`HostClient` correlates each request it sends with the response that
-answers it and relays the host's stderr. Two notification methods carry
-meaning of their own: `ready`, whose `params.protocol` it checks against
-the revision it was built for, reporting and terminating the child on any
-mismatch; and `appError`, an app fault the host caught and kept rendering
-past, handed to its own callback rather than a generic one. Any other
-method name is routed, `params` untouched and unparsed, to whichever
-integration the caller registered for it.
-
-A line the host writes that doesn't parse as a JSON-RPC message is treated
-as stray output from a dependency, not a protocol violation: it's logged
-and the channel keeps reading.
-
-`resolveHostBin` tries, in order:
-
-1. `INCA_HOST_BIN`, if set — names the binary to spawn outright. This is
-   the escape hatch for a platform with no published binary yet, or a
-   custom-built one.
-2. The `optionalDependency` matching this OS/arch
-   (`@incajs/host-darwin-arm64`, `-darwin-x64`, `-linux-arm64`,
-   `-linux-x64` — Windows isn't supported yet), which almost every install
-   resolves through without either side ever needing Cargo or Rust.
-
-@throws if neither resolves.
-
-## `adapter/vite`
-
-Bundles an app's entry point into one self-contained bundle that
-`inca-host` can evaluate: no unresolved imports, no dependency on
-QuickJS having Node.js globals.
-
-`watch(options)` builds `options.entry` into a bundle under
-`options.outDir` — the returned `Watcher`'s `bundlePath` names the exact
-file — rebuilding it on every change and reporting each result through
-`options.onBuild`/`options.onError`. `build(options)` runs the same
-pipeline once, minified and with `outDir` cleared first, resolving with
-the bundle's path or rejecting on failure rather than reporting it
-through a callback.
-
-The template compiler is retargeted at `@vue/runtime-core` — the only Vue
-runtime package `incajs/vue` itself depends on — instead of the default
-`vue` import. `@vitejs/plugin-vue` itself still imports `vue` directly for
-its own internals, which is why it's a peer dependency of this package:
-that build-time need for `vue` never reaches an app's dependency tree or
-the bundle it produces.
+## 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.
+
+## How it works
+
+`inca dev`/`build`/`package` bundle your app with Vite, then (for `dev`
+and `package`) launch and supervise `inca-host`, the native runtime
+that renders it, as a child process.

package/dist/adapter/types.d.mts

@@ -17,7 +17,18 @@ export interface BundlerOptions {
     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 {
@@ -25,6 +36,16 @@ export interface BuildOptions {
     entry: string;
     /** Where the build's output is written. */
     outDir: 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 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;
 }
 /** What a build wrote — the result of {@link Bundler.build}, and every {@link BundlerOptions.onBuild} call. */
 export interface BuildOutput {
@@ -34,6 +55,11 @@ export interface BuildOutput {
     entryFile: string;
     /** Every file this build emitted, relative to `outDir` — may include chunks and assets besides the entry itself. */
     files: readonly string[];
+    /** The change that triggered this rebuild. Absent from a one-shot build and a watch's first build. */
+    changed?: {
+        file: string;
+        at: number;
+    };
 }
 /**
  * The contract a bundler adapter satisfies. Supporting another bundler

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

@@ -5,4 +5,4 @@ export type { BuildOptions, BuildOutput } from '../types.mts';
  * rejects on failure rather than reporting it through a callback. Never
  * starts or talks to `inca-host` — that's `dev.mts`'s job.
  */
-export declare function build({ entry, outDir }: BuildOptions): Promise<BuildOutput>;
+export declare function build({ entry, outDir, stdout, stderr, quiet, }: BuildOptions): Promise<BuildOutput>;

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

@@ -12,6 +12,12 @@ export interface ResolveConfigOptions {
     watch: boolean;
     /** Called with what each successful (re)build wrote. */
     onOutput: (output: CapturedOutput) => void;
+    /** Where Vite's own build output goes. */
+    stdout: NodeJS.WritableStream;
+    /** Where Vite's warnings and errors go. */
+    stderr: NodeJS.WritableStream;
+    /** Silences the bundler's progress output — see the `quiet` option in `../types.mts`. */
+    quiet: boolean;
 }
 /**
  * Builds the Vite config shared by `watch` and `build`, compiling `.vue`
@@ -23,4 +29,4 @@ export interface ResolveConfigOptions {
  * the entry, named by `chunkFileNames`/`assetFileNames` below, rather than
  * failing the build.
  */
-export declare function resolveViteConfig({ entry, outDir, mode, watch, onOutput, }: ResolveConfigOptions): InlineConfig;
+export declare function resolveViteConfig({ entry, outDir, mode, watch, onOutput, stdout, stderr, quiet, }: ResolveConfigOptions): InlineConfig;

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

@@ -0,0 +1,7 @@
+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.
+ */
+export declare function streamLogger(stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream): Logger;

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

@@ -0,0 +1,23 @@
+import { Plugin } from 'vite';
+/** Something an app can write that the engine can't run yet. */
+export interface UnsupportedFeature {
+    /** The `ERR_INCA_*` identifier this failure is looked up by. */
+    code: string;
+    /** The feature, named as the app's author would recognise it. */
+    name: string;
+    /** Whether a module id is a use of the feature. */
+    matches: (id: string) => boolean;
+    /** What happens instead, and what to reach for — appended to the error. */
+    hint: string;
+}
+/**
+ * Every feature a build refuses. Add an entry when the engine is found to
+ * ignore something standard, so an app hits a build error instead of a
+ * silent no-op at runtime; drop it again once the engine handles it.
+ */
+export declare const UNSUPPORTED: readonly UnsupportedFeature[];
+/**
+ * Fails the build on the first module that uses an unsupported feature,
+ * naming the file that used it.
+ */
+export declare function rejectUnsupported(features?: readonly UnsupportedFeature[]): Plugin;

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

@@ -5,4 +5,4 @@ export type { Watcher } from '../types.mts';
  * change, calling `onBuild` with what each rebuild wrote. Never starts,
  * reloads, or talks to `inca-host` — that's `dev.mts`'s job.
  */
-export declare function watch({ onBuild, onError, ...buildOptions }: BundlerOptions): Promise<Watcher>;
+export declare function watch({ onBuild, onError, stdout, stderr, quiet, ...buildOptions }: BundlerOptions): Promise<Watcher>;

package/dist/build.d.mts

@@ -1,4 +1,5 @@
 import { Bundler, BuildOutput } from './adapter/types.mts';
+import { ResolvedBuildConfig } from './config/loader.mts';
 export interface BuildAppOptions {
     /** The app's root directory. Defaults to `process.cwd()`. */
     cwd?: string;
@@ -9,6 +10,12 @@ export interface BuildAppOptions {
     entry?: string;
     /** Overrides the bundler — see {@link defaultBundler} for what's wired in by default. */
     bundler?: Bundler;
+    /** An already-resolved config — lets `packageApp` avoid loading it twice. */
+    config?: ResolvedBuildConfig;
+    /** 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;
 }
 /**
  * Builds the app once through the same bundler `dev` uses, and returns what

package/dist/chunks/__vite-optional-peer-dep_dotenv_c12-CxKvRg9-.js

@@ -0,0 +1,3 @@
+//#region __vite-optional-peer-dep:dotenv:c12
+throw Error("Could not resolve \"dotenv\" imported by \"c12\". Is it installed?");
+//#endregion

package/dist/chunks/__vite-optional-peer-dep_giget_c12-BYcrHYBM.js

@@ -0,0 +1,5 @@
+//#region __vite-optional-peer-dep:giget:c12
+var e = {};
+throw Error("Could not resolve \"giget\" imported by \"c12\". Is it installed?");
+//#endregion
+export { e as default };

package/dist/chunks/__vite-optional-peer-dep_jiti_c12-DZVJNj6v.js

@@ -0,0 +1,5 @@
+//#region __vite-optional-peer-dep:jiti:c12
+var e = {};
+throw Error("Could not resolve \"jiti\" imported by \"c12\". Is it installed?");
+//#endregion
+export { e as default };

package/dist/chunks/_format-BKs7bsc4.js

@@ -0,0 +1,98 @@
+//#region ../../node_modules/.pnpm/confbox@0.3.1/node_modules/confbox/dist/_chunks/libs/detect-indent.mjs
+var e = /^(?:( )+|\t+)/, t = "space";
+function n(e, n, r) {
+	return e && n === t && r === 1;
+}
+function r(r, a) {
+	let o = /* @__PURE__ */ new Map(), s = 0, c, l;
+	for (let u of r.split(/\n/g)) {
+		if (!u) continue;
+		let r = u.match(e);
+		if (r === null) s = 0, c = "";
+		else {
+			let e = r[0].length, u = r[1] ? t : "tab";
+			if (n(a, u, e)) continue;
+			u !== c && (s = 0), c = u;
+			let d = 1, f = 0, p = e - s;
+			if (s = e, p === 0) d = 0, f = 1;
+			else {
+				let e = Math.abs(p);
+				if (n(a, u, e)) continue;
+				l = i(u, e);
+			}
+			let m = o.get(l);
+			o.set(l, m === void 0 ? [1, 0] : [m[0] + d, m[1] + f]);
+		}
+	}
+	return o;
+}
+function i(e, n) {
+	return (e === t ? "s" : "t") + String(n);
+}
+function a(e) {
+	return {
+		type: e[0] === "s" ? t : "tab",
+		amount: Number(e.slice(1))
+	};
+}
+function o(e) {
+	let t, n = 0, r = 0;
+	for (let [i, [a, o]] of e) (a > n || a === n && o > r) && (n = a, r = o, t = i);
+	return t;
+}
+function s(e, n) {
+	return (e === t ? " " : "	").repeat(n);
+}
+function c(e) {
+	if (typeof e != "string") throw TypeError("Expected a string");
+	let t = r(e, !0);
+	t.size === 0 && (t = r(e, !1));
+	let n = o(t), i, c = 0, l = "";
+	return n !== void 0 && ({type: i, amount: c} = a(n), l = s(i, c)), {
+		amount: c,
+		type: i,
+		indent: l
+	};
+}
+//#endregion
+//#region ../../node_modules/.pnpm/confbox@0.3.1/node_modules/confbox/dist/_chunks/_format.mjs
+var l = Symbol.for("__confbox_fmt__"), u = /^(\s+)/, d = /(\s+)$/;
+function f(e) {
+	return e.charCodeAt(0) === 65279 ? e.slice(1) : e;
+}
+function p(e, t = {}) {
+	return {
+		sample: t.indent === void 0 && t.preserveIndentation !== !1 && f(e).slice(0, t?.sampleSize || 1024),
+		whiteSpace: t.preserveWhitespace === !1 ? void 0 : {
+			start: u.exec(e)?.[0] || "",
+			end: d.exec(e)?.[0] || ""
+		}
+	};
+}
+function m(e, t, n) {
+	!t || typeof t != "object" || Object.defineProperty(t, l, {
+		enumerable: !1,
+		configurable: !0,
+		writable: !0,
+		value: p(e, n)
+	});
+}
+function h(e, t) {
+	if (!e || typeof e != "object" || !(l in e)) return {
+		indent: t?.indent ?? 2,
+		whitespace: {
+			start: "",
+			end: ""
+		}
+	};
+	let n = e[l];
+	return {
+		indent: t?.indent || c(n.sample || "").indent,
+		whitespace: n.whiteSpace || {
+			start: "",
+			end: ""
+		}
+	};
+}
+//#endregion
+export { m as n, h as r, f as t };