@ekrooh/bare 0.1.0 → 0.3.0

package/README.md

@@ -206,6 +206,24 @@ npm run build       # core bundle + web assets
 
 `./gradlew build` additionally runs the host library's JUnit tests.
 
+### Consuming the published AAR
+
+`io.github.anderscan.ekrooh:bare-host` is published to **Maven Central** (no auth) on the same
+tag as the npm package — pin it to your `@ekrooh/bare` version:
+
+```gradle
+repositories {
+  mavenCentral() // default in modern Gradle; no credentials needed
+}
+
+dependencies {
+  implementation "io.github.anderscan.ekrooh:bare-host:<version>"
+}
+```
+
+GitHub Packages (`maven.pkg.github.com/AndersCan/ekrooh`) remains a fallback
+but requires a `read:packages` PAT — prefer Maven Central.
+
 ## iOS build
 
 Prerequisites: Xcode (macOS), Bare Kit prebuilds, and `xcodegen`.

package/dist/plugins.d.mts

@@ -1,5 +1,5 @@
 import { A as CapabilityDescriptor, G as PluginInvokeRequestHeader, K as PluginInvokeResponseHeader, Y as RuntimeTarget, q as PluginManifest } from "./index-DjulYFJL.mjs";
-import { t as LoopbackServer } from "./static-file-server-CxeI_mQr.mjs";
+import { n as LoopbackServer } from "./static-file-server-DY9EKEVf.mjs";
 //#region plugins/discovery/plugin.d.ts
 type DiscoveryPluginDeps = {
   listBareCapabilities: () => Array<{

package/dist/runtime.d.mts

@@ -1,5 +1,5 @@
-import { A as CapabilityDescriptor, G as PluginInvokeRequestHeader, K as PluginInvokeResponseHeader, d as MessageProtocol, t as BareRuntimeContext, v as createPluginRegistry, y as createPluginRouter } from "./index-DjulYFJL.mjs";
-import { n as createLoopbackServer, t as LoopbackServer } from "./static-file-server-CxeI_mQr.mjs";
+import { A as CapabilityDescriptor, G as PluginInvokeRequestHeader, K as PluginInvokeResponseHeader, V as MessageHeader, d as MessageProtocol, q as PluginManifest, t as BareRuntimeContext, v as createPluginRegistry, y as createPluginRouter } from "./index-DjulYFJL.mjs";
+import { i as createLoopbackServer, n as LoopbackServer, r as collectRequestBody, t as LoopbackRouteHandler } from "./static-file-server-DY9EKEVf.mjs";
 //#region core/messages/host-ipc.d.ts
 type BareIpcLike = {
   write(data: Uint8Array | Buffer | string): boolean;
@@ -14,6 +14,13 @@ declare function createHostIpcBridge(config: {
 };
 //#endregion
 //#region core/server/websocket-server.d.ts
+/** Envelope encoder bound to a loopback server's connected protocol socket —
+ * the server-initiated (backend → web) push seam. */
+type LoopbackPush = (header: MessageHeader, payload?: Uint8Array | ArrayBuffer | null) => boolean;
+/** Builds the push seam for the server's connected protocol socket: encodes a
+ * `DISPATCH`-style envelope and writes it, mirroring how `attachWebSocketProtocol`
+ * writes responses. Returns false when no socket is connected. */
+declare function createLoopbackPush(server: LoopbackServer, protocol: MessageProtocol): LoopbackPush;
 /**
  * Attaches the framed-protocol socket to the unified loopback server. The
  * server owns the WebSocket upgrade (origin check, cookie/token auth, single
@@ -44,8 +51,23 @@ declare function getIPC(): BareIPC;
  * arguments. On-device hosts pass `["<webAssets>", "<storage>", "<cache>"]`,
  * landing at `Bare.argv[0..2]`; the Bare CLI (dev) passes the binary and the
  * script path instead, so a missing/absent config means dev mode (auth off,
- * fixed port, no handoff file). */
+ * fixed port, no handoff file). Falls back to the labeled CLI token syntax
+ * (see `resolveCliConfig`) when the positional shape doesn't match, so the
+ * same entry works for both device and dev runs. */
 declare function resolveWorkletConfig(): WorkletRuntimeOptions;
+/**
+ * Parses the dev/CLI labeled-token configuration from bare CLI arguments:
+ * `webassets=<dir>`, `storage=<dir>`, `cache=<dir>`, `host=<addr>`,
+ * `port=<n>`, `auth=<on|off|true|false|1|0>` — a single `key=value` separator.
+ * Unknown labels (e.g. `bootstrap=127.0.0.1:49737`) are ignored and stay
+ * consumer-owned.
+ *
+ * Returns the equivalent `WorkletRuntimeOptions` in **dev mode**: `deviceMode:
+ * false` (so a `storage=` token does not flip auth on or make the port
+ * ephemeral), `auth: false`, `port: 8080`, each overridable by a token. When
+ * no labeled tokens are present it returns `{}` (plain dev defaults).
+ */
+declare function resolveCliConfig(argv?: readonly string[]): WorkletRuntimeOptions;
 type WorkletRuntimeOptions = {
   /** Directory to serve at `/` (the built web app). */
   webAssets?: string;
@@ -60,6 +82,13 @@ type WorkletRuntimeOptions = {
   port?: number;
   /** Require the per-session token/cookie. Defaults to on in device mode. */
   auth?: boolean;
+  /** Explicit device-mode override. Defaults to on whenever `storage` is set
+   * (the on-device 3-arg contract); `resolveCliConfig` resolves it to false so
+   * a dev backend keeps auth off + fixed port even with a storage dir. */
+  deviceMode?: boolean;
+  /** Additional plugin manifests to register after the canonical defaults
+   * (consumer product plugins, e.g. `app.photos`). */
+  plugins?: PluginManifest[];
   /** Idle timeout (ms) after which an authenticated WebSocket is dropped. */
   wsIdleTimeoutMs?: number;
 };
@@ -93,4 +122,4 @@ interface WorkletRuntime {
  */
 declare function createWorkletRuntime(options?: WorkletRuntimeOptions): WorkletRuntime;
 //#endregion
-export { type LoopbackServer, WorkletRuntime, WorkletRuntimeConfig, WorkletRuntimeOptions, attachWebSocketProtocol, createLoopbackServer, createWorkletRuntime, getIPC, resolveWorkletConfig };
+export { type LoopbackPush, type LoopbackRouteHandler, type LoopbackServer, WorkletRuntime, WorkletRuntimeConfig, WorkletRuntimeOptions, attachWebSocketProtocol, collectRequestBody, createLoopbackPush, createLoopbackServer, createWorkletRuntime, getIPC, resolveCliConfig, resolveWorkletConfig };

package/dist/runtime.mjs

@@ -13,7 +13,7 @@ import crypto from "bare-crypto";
 * In Bare (Sidecar), it uses Bare.IPC.
 */
 function getIPC() {
-	const IPC = typeof BareKit !== "undefined" ? BareKit.IPC : Bare.IPC;
+	const IPC = typeof BareKit !== "undefined" ? BareKit.IPC : typeof Bare !== "undefined" ? Bare.IPC : void 0;
 	if (IPC && typeof IPC.resume === "function") IPC.resume();
 	return IPC;
 }
@@ -219,6 +219,7 @@ function createLoopbackServer(options = {}) {
 	const wsIdleTimeoutMs = options.wsIdleTimeoutMs ?? 6e4;
 	const fileMounts = /* @__PURE__ */ new Map();
 	const dirMounts = /* @__PURE__ */ new Map();
+	const routeHandlers = /* @__PURE__ */ new Map();
 	const connectionHandlers = [];
 	let token = options.token ?? null;
 	let boundOrigin = "";
@@ -375,6 +376,19 @@ function createLoopbackServer(options = {}) {
 				writeError(res, 400, "Bad request");
 				return;
 			}
+			const route = routeHandlers.get(`${req.method} ${cleanPath}`);
+			if (route) {
+				if (!isAuthorized(headers, query)) {
+					writeError(res, 401, "Unauthorized");
+					return;
+				}
+				try {
+					route(req, res);
+				} catch (err) {
+					writeError(res, 500, err instanceof Error ? err.message : String(err));
+				}
+				return;
+			}
 			const mount = resolveMount(cleanPath);
 			if (!(mount !== null && mount.kind === "dir") && !isAuthorized(headers, query)) {
 				writeError(res, 401, "Unauthorized");
@@ -471,6 +485,18 @@ function createLoopbackServer(options = {}) {
 		onConnection(handler) {
 			connectionHandlers.push(handler);
 		},
+		registerRoute(method, path, handler) {
+			routeHandlers.set(`${method.toUpperCase()} ${path}`, handler);
+		},
+		push(frame) {
+			if (!activeSocket) return false;
+			try {
+				activeSocket.write(frame);
+				return true;
+			} catch {
+				return false;
+			}
+		},
 		close(cb) {
 			if (activeSocket) try {
 				activeSocket.destroy();
@@ -486,6 +512,15 @@ function toUint8Array$1(data) {
 	if (data instanceof ArrayBuffer) return new Uint8Array(data);
 	throw new Error("Expected Uint8Array or ArrayBuffer from socket data");
 }
+/** Builds the push seam for the server's connected protocol socket: encodes a
+* `DISPATCH`-style envelope and writes it, mirroring how `attachWebSocketProtocol`
+* writes responses. Returns false when no socket is connected. */
+function createLoopbackPush(server, protocol) {
+	return (header, payload = null) => {
+		const frame = protocol.encode(MessageType.ENVELOPE, header, payload);
+		return server.push(frame);
+	};
+}
 /**
 * Attaches the framed-protocol socket to the unified loopback server. The
 * server owns the WebSocket upgrade (origin check, cookie/token auth, single
@@ -512,13 +547,18 @@ function attachWebSocketProtocol(server, context) {
 }
 //#endregion
 //#region core/runtime.ts
+function readBareArgv() {
+	return typeof Bare !== "undefined" && Array.isArray(Bare.argv) ? Bare.argv : [];
+}
 /** Resolves the host-provided worklet configuration from `start(...)`
 * arguments. On-device hosts pass `["<webAssets>", "<storage>", "<cache>"]`,
 * landing at `Bare.argv[0..2]`; the Bare CLI (dev) passes the binary and the
 * script path instead, so a missing/absent config means dev mode (auth off,
-* fixed port, no handoff file). */
+* fixed port, no handoff file). Falls back to the labeled CLI token syntax
+* (see `resolveCliConfig`) when the positional shape doesn't match, so the
+* same entry works for both device and dev runs. */
 function resolveWorkletConfig() {
-	const argv = typeof Bare !== "undefined" && Array.isArray(Bare.argv) ? Bare.argv : [];
+	const argv = readBareArgv();
 	const webAssets = argv[0];
 	const storage = argv[1];
 	const cache = argv[2];
@@ -534,7 +574,57 @@ function resolveWorkletConfig() {
 			};
 		}
 	} catch {}
-	return {};
+	return resolveCliConfig(argv);
+}
+/**
+* Parses the dev/CLI labeled-token configuration from bare CLI arguments:
+* `webassets=<dir>`, `storage=<dir>`, `cache=<dir>`, `host=<addr>`,
+* `port=<n>`, `auth=<on|off|true|false|1|0>` — a single `key=value` separator.
+* Unknown labels (e.g. `bootstrap=127.0.0.1:49737`) are ignored and stay
+* consumer-owned.
+*
+* Returns the equivalent `WorkletRuntimeOptions` in **dev mode**: `deviceMode:
+* false` (so a `storage=` token does not flip auth on or make the port
+* ephemeral), `auth: false`, `port: 8080`, each overridable by a token. When
+* no labeled tokens are present it returns `{}` (plain dev defaults).
+*/
+function resolveCliConfig(argv = readBareArgv()) {
+	const parsed = {};
+	let matched = false;
+	for (const token of argv) {
+		const m = /^([A-Za-z][A-Za-z0-9]*)=(.*)$/.exec(token);
+		if (!m) continue;
+		const [, key, value] = m;
+		matched = true;
+		switch (key) {
+			case "webassets":
+				parsed.webAssets = value;
+				break;
+			case "storage":
+				parsed.storage = value;
+				break;
+			case "cache":
+				parsed.cache = value;
+				break;
+			case "host":
+				parsed.host = value;
+				break;
+			case "port": {
+				const n = Number(value);
+				if (Number.isInteger(n) && n >= 0 && n <= 65535) parsed.port = n;
+				else console.warn(`[bare] ignoring invalid port= token: "${value}"`);
+				break;
+			}
+			case "auth": parsed.auth = value !== "off" && value !== "false" && value !== "0";
+		}
+	}
+	if (!matched) return {};
+	return {
+		deviceMode: false,
+		auth: false,
+		port: 8080,
+		...parsed
+	};
 }
 function toUint8Array(data) {
 	if (data instanceof Uint8Array) return data;
@@ -552,7 +642,7 @@ function writeIpc(ipc, bytes) {
 * wire p2p". Mirrors the reference wiring in `core/main.core.ts`.
 */
 function createWorkletRuntime(options = {}) {
-	const deviceMode = options.storage !== void 0;
+	const deviceMode = options.deviceMode ?? options.storage !== void 0;
 	const auth = options.auth ?? deviceMode;
 	const port = options.port ?? (deviceMode ? 0 : 8080);
 	const protocol = new MessageProtocol({
@@ -582,6 +672,7 @@ function createWorkletRuntime(options = {}) {
 		staticServer: server,
 		invokeOnHost: (header, payload) => hostBridge?.invokeOnHost(header, payload) ?? Promise.resolve(null)
 	})) pluginRegistry.register(plugin);
+	for (const plugin of options.plugins ?? []) pluginRegistry.register(plugin);
 	const pluginRouter = createPluginRouter(pluginRegistry, "bare", { delegateToHost: (header, payload) => hostBridge?.invokeOnHost(header, payload) ?? Promise.resolve(null) });
 	if (ipc) ipc.on("data", async (data) => {
 		try {
@@ -607,7 +698,7 @@ function createWorkletRuntime(options = {}) {
 			pluginRouter
 		});
 		const credentials = await server.credentials();
-		if (deviceMode && options.storage) try {
+		if (auth && options.storage) try {
 			fs.writeFileSync(path.join(options.storage, "handoff.json"), JSON.stringify(credentials));
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
@@ -634,4 +725,4 @@ function createWorkletRuntime(options = {}) {
 	};
 }
 //#endregion
-export { attachWebSocketProtocol, createLoopbackServer, createWorkletRuntime, getIPC, resolveWorkletConfig };
+export { attachWebSocketProtocol, collectRequestBody, createLoopbackPush, createLoopbackServer, createWorkletRuntime, getIPC, resolveCliConfig, resolveWorkletConfig };

package/dist/{static-file-server-CxeI_mQr.d.mts → static-file-server-DY9EKEVf.d.mts}

@@ -1,5 +1,10 @@
-import "bare-http1";
+import { HTTPIncomingMessage, HTTPServerResponse } from "bare-http1";
 //#region core/server/static-file-server.d.ts
+/** Accumulates an HTTP request body into a UTF-8 string. Node http emits
+ * Buffers, bare-http1 emits Uint8Arrays, and a setEncoding'd stream emits
+ * strings — `String(uint8array)` would join bytes with commas, so decode
+ * explicitly (the `/login` token body must match byte-for-byte). */
+declare function collectRequestBody(req: HTTPIncomingMessage): Promise<string>;
 type WebSocketLike = {
   on(event: 'data', listener: (chunk: unknown) => void): unknown;
   on(event: 'close', listener: () => void): unknown;
@@ -7,6 +12,8 @@ type WebSocketLike = {
   write(data: unknown): boolean;
   destroy(): void;
 };
+/** Handler for a registered HTTP route on the loopback server. */
+type LoopbackRouteHandler = (req: HTTPIncomingMessage, res: HTTPServerResponse) => void;
 /** Minimal shape of the HTTP request object handed to WS upgrade handlers. */
 type LoopbackRequest = {
   url?: string;
@@ -54,6 +61,13 @@ interface LoopbackServer {
   /** Registers a handler for authenticated, handshaken WebSocket connections
    * (the protocol socket). */
   onConnection(handler: LoopbackConnectionHandler): void;
+  /** Registers an HTTP route. `handler` runs before mount resolution, after
+   * the auth gate (device mode requires the session cookie/token). The route
+   * body is read with `collectRequestBody`. */
+  registerRoute(method: string, path: string, handler: LoopbackRouteHandler): void;
+  /** Writes a raw frame to the connected protocol socket (if any) — the
+   * server-initiated push seam (e.g. a `photos.changed` dispatch). */
+  push(frame: Uint8Array): boolean;
   /** Stops accepting connections and closes the server. */
   close(cb?: (err?: Error | null) => void): void;
 }
@@ -71,4 +85,4 @@ interface LoopbackServer {
  */
 declare function createLoopbackServer(options?: LoopbackServerOptions): LoopbackServer;
 //#endregion
-export { createLoopbackServer as n, LoopbackServer as t };
+export { createLoopbackServer as i, LoopbackServer as n, collectRequestBody as r, LoopbackRouteHandler as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekrooh/bare",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "One soul, many platforms — the boring bootstrap for cross-platform apps on the Bare runtime: wire protocol, plugin kernel, RPC messenger, transports, and native host bridges.",
   "license": "MIT",
@@ -10,7 +10,9 @@
   },
   "workspaces": [
     "examples/*",
-    "e2e"
+    "examples/consumer-basic",
+    "e2e",
+    "apps/*"
   ],
   "exports": {
     ".": "./dist/index.mjs",
@@ -30,10 +32,15 @@
   "scripts": {
     "check": "vp check",
     "lint": "vp fmt . --fix",
+    "docs:dev": "vp run docs#dev",
+    "docs:build": "vp run docs#build",
+    "docs:preview": "vp run docs#preview",
+    "docs:check": "node scripts/docs-check.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "vp test && npm run test:e2e:web && npm run test:e2e:harness",
+    "test": "vp test && npm run test:e2e:web && npm run test:e2e:harness && npm run test:e2e:consumer",
     "test:unit": "vp test",
     "test:e2e:web": "node scripts/playwright-local-browsers.mjs test",
+    "test:e2e:consumer": "node scripts/playwright-local-browsers.mjs test --config examples/consumer-basic/playwright.config.ts",
     "dev": "concurrently \"vp -C examples/web dev\" \"npm run dev:bare\"",
     "predev": "npm run build:pkg",
     "dev:bare": "node scripts/dev-bare.mjs",
@@ -82,7 +89,7 @@
   },
   "dependencies": {
     "@mantaq/core": "^0.2.0",
-    "@mantaq/sugar": "^0.2.0",
+    "@mantaq/sugar": "^0.3.0",
     "bare-crypto": "^1.15.3",
     "bare-encoding": "^1.0.3",
     "bare-env": "^3.0.0",