@incajs/cli 0.0.2 → 0.0.4

package/dist/config/defaults.d.mts

@@ -28,7 +28,8 @@ export declare function unscopedName(name: string): string;
  *
  * @param name - e.g. a `productName`
  * @returns `name` lowercased, with runs of non-`[a-z0-9]` collapsed to a
- * single `-` and trimmed from both ends
+ * single `-` and trimmed from both ends; `"app"` for a name that holds
+ * none of those characters
  */
 export declare function slugify(name: string): string;
 /**

package/dist/config/loader.d.mts

@@ -1,3 +1,4 @@
+import { WindowConfig } from './types.mts';
 /** `entry`/`outDir` only — what `build()`/`dev()` need, with no `package.json` requirement. */
 export interface ResolvedBuildConfig {
     /** Absolute path, if `inca.config.ts` set one. */
@@ -14,9 +15,21 @@ export interface ResolvedAppConfig extends ResolvedBuildConfig {
     version: string;
     /** Absolute path, if the app declared one. */
     icon?: string;
+    /** What the app declared about its window, if anything. */
+    window?: WindowConfig;
     /** package.json's `"inca"` key is deprecated; callers warn when this is true. */
     usedPackageJsonKey: boolean;
 }
+/**
+ * What a built app carries for its host to read: the name the platform
+ * shows it under, the id it is known by, and its window. Each field is
+ * absent unless the app's config sets it.
+ */
+export interface RuntimeConfig {
+    name?: string;
+    identifier?: string;
+    window?: WindowConfig;
+}
 /**
  * Loads just `entry`/`outDir` from `inca.config.ts`, with derived defaults.
  * Never touches `package.json`.
@@ -35,3 +48,19 @@ export declare function resolveBuildConfig(cwd: string): Promise<ResolvedBuildCo
  * `productName`, or an `icon` doesn't resolve to a real file
  */
 export declare function resolveAppConfig(cwd: string): Promise<ResolvedAppConfig>;
+/**
+ * Narrows a full config down to what a build carries for the host.
+ *
+ * @param config - a config {@link resolveAppConfig} returned
+ * @returns its name, id and window
+ */
+export declare function runtimeConfigOf(config: ResolvedAppConfig): RuntimeConfig;
+/**
+ * Loads {@link RuntimeConfig} for an app that may name itself nowhere.
+ * An app with no `package.json`, or none that gives it a name, still gets
+ * whatever window settings it declared.
+ *
+ * @param cwd - the app's root directory
+ * @returns the config, or `undefined` when the app declares none of it
+ */
+export declare function resolveRuntimeConfig(cwd: string): Promise<RuntimeConfig | undefined>;

package/dist/config/types.d.mts

@@ -32,4 +32,35 @@ export interface IncaConfig {
      * @default "dist"
      */
     outDir?: string;
+    /** The window the app opens in. */
+    window?: WindowConfig;
+}
+/** What an app declares about its window — see {@link IncaConfig.window}. */
+export interface WindowConfig {
+    /**
+     * Initial width, in pixels. Falls back to the width the app's root
+     * element declares, then to this default.
+     * @default 800
+     */
+    width?: number;
+    /**
+     * Initial height, in pixels. Falls back to the height the app's root
+     * element declares, then to this default.
+     * @default 600
+     */
+    height?: number;
+    /**
+     * The window's title.
+     * @default the app's productName
+     */
+    title?: string;
+    /**
+     * Whether a user can resize the window.
+     * @default false
+     */
+    resizable?: boolean;
+    /** Smallest width the window can be, in pixels. It opens at least this wide. */
+    minWidth?: number;
+    /** Smallest height the window can be, in pixels. It opens at least this tall. */
+    minHeight?: number;
 }

package/dist/config.js

@@ -1,4 +1,4 @@
-import { a as e, t } from "./chunks/defaults-EWjAFeZ3.js";
+import { a as e, t } from "./chunks/defaults-DNvHueCI.js";
 //#region src/config/index.mts
 var n = e();
 //#endregion

package/dist/dev-client/hostClient.d.mts

@@ -17,6 +17,11 @@ export interface HostClientOptions {
     onReady?: () => void;
     /** An app's own event listener threw; the host caught it and kept rendering. */
     onAppError?: (error: AppErrorParams) => void;
+    /**
+     * The host exited on its own — its window was closed, or it crashed.
+     * Not called for the exit `stop()` asks for.
+     */
+    onExit?: (code: number | null, signal: NodeJS.Signals | null) => void;
     /**
      * Handlers for notification `method`s this package doesn't implement
      * itself (e.g. a future Vite integration), keyed by method name —

package/dist/dev-lock.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Claims `cwd` for this process. Two `inca dev`s on one app watch the same
+ * files and interleave their output on one terminal, and an orphan left by
+ * an earlier run stays invisible until this says so. A lock whose pid is
+ * gone is taken over.
+ *
+ * @returns a function releasing the lock.
+ * @throws if another live `inca dev` holds `cwd`.
+ */
+export declare function acquireDevLock(cwd: string): Promise<() => Promise<void>>;

package/dist/dev.d.mts

@@ -9,7 +9,10 @@ export interface DevOptions {
     entry?: string;
     /** Overrides the bundler — see {@link defaultBundler} for what's wired in by default. */
     bundler?: Bundler;
-    /** Overrides host binary resolution — passed straight through to `HostClient`. */
+    /**
+     * Overrides host binary resolution. On macOS this is the binary the
+     * app bundle wraps; elsewhere it is launched directly.
+     */
     hostBin?: string;
     /** Defaults to `process.stdout`. */
     stdout?: NodeJS.WritableStream;
@@ -20,6 +23,9 @@ export interface DevOptions {
 }
 /**
  * Builds the app, starts `inca-host` once the first build lands, and
- * reloads it on every rebuild — until `options.signal` aborts.
+ * reloads it on every rebuild — until `options.signal` aborts or the host
+ * exits on its own.
+ *
+ * @throws if another `inca dev` is already running for this app.
  */
 export declare function dev(options: DevOptions): Promise<void>;

package/dist/error.d.mts

@@ -0,0 +1,11 @@
+/**
+ * A failure the CLI raises itself, identified by an `ERR_INCA_*` code the
+ * way Node's own errors carry one. The code is what a user searches for
+ * and what `printFault` names alongside the message, so every distinct
+ * cause gets its own.
+ */
+export declare class IncaError extends Error {
+    readonly code: string;
+    readonly name = "IncaError";
+    constructor(code: string, message: string);
+}

package/dist/log.d.mts

@@ -0,0 +1,28 @@
+/** Shared by {@link log} and {@link printFault}. */
+export interface LogOptions {
+    /** Prefixes the line with `HH:MM:SS`, the way Vite's dev server stamps its own. */
+    timestamp?: boolean;
+}
+/** Writes one `[inca] <message>` line to `stream`. */
+export declare function log(stream: NodeJS.WritableStream, message: string, options?: LogOptions): void;
+/** A failure reduced to the message and stack worth printing. */
+export interface Fault {
+    message: string;
+    stack: string | null;
+    /** An `ERR_INCA_*` identifier, when the failure has one to look up. */
+    code?: string | null;
+}
+/**
+ * Reduces an error a bundler re-wrapped: its text is kept whole — the
+ * excerpt a compiler points at is the useful part — while the error class
+ * and any `ERR_INCA_*` marker are lifted off the first line, the latter
+ * into the fault's code.
+ */
+export declare function bundlerFault(message: string): Fault;
+/** Reduces a thrown value to a {@link Fault}. A `HostError` carries the host process's stack. */
+export declare function toFault(error: unknown): Fault;
+/**
+ * Writes `[inca] <label> (<code>): <message>` to `stream` — the code only
+ * when the failure carries one — followed by the stack when there is one.
+ */
+export declare function printFault(stream: NodeJS.WritableStream, label: string, fault: Fault, options?: LogOptions): void;

package/dist/macos-app.d.mts

@@ -0,0 +1,47 @@
+/** The app metadata a `.app` bundle's `Info.plist` carries. */
+export interface MacosAppMetadata {
+    /** The name macOS shows in the Dock, the menu bar and the Finder. */
+    productName: string;
+    /** A reverse-DNS-style unique id, written as `CFBundleIdentifier`. */
+    identifier: string;
+    /** The app's version, written as both `CFBundleVersion` and `CFBundleShortVersionString`. */
+    version: string;
+    /** Absolute path to an icon file, copied into `Contents/Resources`. */
+    icon?: string;
+}
+/** Options for {@link writeMacosApp}. */
+export interface WriteMacosAppOptions {
+    /** Where the `.app` directory is written. An existing one there is replaced. */
+    appPath: string;
+    /** What the bundle's `Info.plist` describes. */
+    metadata: MacosAppMetadata;
+    /** The `inca-host` binary the bundle's executable is made from. */
+    hostBin: string;
+    /**
+     * Hard-links the executable to `hostBin` rather than copying it, and
+     * copies when the two paths are on different filesystems. Set it where
+     * the bundle is rebuilt often and holds no files of its own.
+     */
+    link?: boolean;
+}
+/** The paths {@link writeMacosApp} created. */
+export interface MacosApp {
+    /** The `.app` directory itself. */
+    appPath: string;
+    /** The bundle's executable, at `Contents/MacOS/<productName>`. */
+    executablePath: string;
+    /** `Contents/Resources`, where an app's own files belong. */
+    resourcesDir: string;
+}
+/**
+ * Writes a macOS `.app` bundle around the `inca-host` binary:
+ * `Contents/MacOS` holding the executable, `Contents/Resources` left empty
+ * apart from the icon, and `Info.plist`/`PkgInfo` beside them. macOS reads
+ * the app's name, icon and identifier from the bundle, so an executable
+ * launched from one carries them wherever the platform shows an app.
+ *
+ * @param options - where to write, what to describe, and which binary to use
+ * @returns the bundle's own path, its executable, and its resources directory
+ * @throws if any part of the bundle can't be written
+ */
+export declare function writeMacosApp(options: WriteMacosAppOptions): Promise<MacosApp>;

package/dist/package.d.mts

@@ -24,8 +24,10 @@ export interface PackageAppOptions {
      * process is running on.
      */
     target?: PackageTarget;
-    /** Where progress notes go. Defaults to `process.stdout`. */
+    /** Where progress notes and the bundler's own output go. Defaults to `process.stdout`. */
     stdout?: NodeJS.WritableStream;
+    /** Where the bundler's warnings and errors go. Defaults to `process.stderr`. */
+    stderr?: NodeJS.WritableStream;
 }
 /** The result of a successful {@link packageApp} call. */
 export interface PackageResult {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@incajs/cli",
-  "version": "0.0.2",
-  "description": "The inca CLI: watches an app's entry point through a bundler adapter, starts inca-host once the first bundle lands, and reloads it on every rebuild.",
+  "version": "0.0.4",
+  "description": "Dev server, bundler, and packager for Incarnative.js apps.",
   "keywords": [
     "bundler",
     "cli",
@@ -68,9 +68,9 @@
     }
   },
   "optionalDependencies": {
-    "@incajs/host-darwin-arm64": "0.0.2",
-    "@incajs/host-linux-arm64": "0.0.2",
-    "@incajs/host-linux-x64": "0.0.2"
+    "@incajs/host-darwin-arm64": "0.0.4",
+    "@incajs/host-linux-arm64": "0.0.4",
+    "@incajs/host-linux-x64": "0.0.4"
   },
   "engines": {
     "node": ">=22.18"

package/dist/fault.d.mts

@@ -1,6 +0,0 @@
-export interface Fault {
-    message: string;
-    stack: string | null;
-}
-export declare function toFault(error: unknown): Fault;
-export declare function printFault(stream: NodeJS.WritableStream, label: string, fault: Fault): void;