arcane-os 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.7.0
+
+- Add `arcane dev --public`, including forwarding through
+  `npm run dev -- --app <id> --public`, to bind the selected app's existing
+  source server to all IPv4 interfaces. Keep the ordinary localhost default
+  and let an explicit `--host` select the bind address.
+- Allow explicit network hosts in the shared development server. Report usable
+  local and network application URLs, including `networkUrls` in server results
+  and lifecycle events, while preserving selected routes and cancellation.
+- Document LAN use and the browser HTTPS requirement for features that need a
+  secure context. No app-specific server, firewall rule, or tunnel is added.
+
 ## 0.6.2
 
 - Replace browser NPU setup buttons with direct browser-specific flags links

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.6.2` SDK contract. Applications pin one exact npm
+This checkout defines the `0.7.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -35,12 +35,27 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.6.2 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.7.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
 ```
 
+To open a selected app from another device on the network, append `--public`
+to the same command:
+
+```bash
+npm run dev -- --app hello-speech --public
+```
+
+Replace `hello-speech` with any app in the workspace. The server binds to
+`0.0.0.0` and prints network URLs to open on the other device. Plain `npm run dev`
+keeps its localhost default. An explicit `--host` overrides the public bind
+address, and `--port` selects the port. Network reachability depends on the
+machine's firewall and network; the command does not configure internet hosting
+or HTTPS. Browser features requiring a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts)
+need HTTPS when opened through a LAN address.
+
 Open the URL printed by the server. The generated page owns its import map and
 Arcane theme; its application module is `apps/hello-speech/modules/App.js`.
 `arcane/AI` is a managed **browser import**, not an npm-exported Node inference
@@ -363,7 +378,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.6.2 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.7.0 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -373,7 +388,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.6.2
+npm install --save-dev --save-exact arcane-os@0.7.0
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -389,7 +404,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.6.2` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.7.0` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -409,7 +424,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.6.2.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.7.0.tgz
 npm ci
 ```
 
@@ -418,7 +433,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.6.2` registry package and
+the local declaration with the exact `arcane-os@0.7.0` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -475,7 +490,7 @@ arcane new <id> [--path <directory>] [--display-name <name>] [--target <target>]
 arcane init [id] [--workspace <directory>] [--display-name <name>] [--target <target>]
 arcane doctor [--workspace <directory>] [--arcane-root <directory>]
 arcane import-map [--workspace <directory>] [--app <id>]
-arcane dev [--app <id>] [--host 127.0.0.1] [--port 8000]
+arcane dev [--app <id>] [--public] [--host <address>] [--port 8000]
 arcane test [--app <id>] [--scope app]
 arcane test --scope shared --test-file <repo-relative.test.mjs>
 arcane check [--app <id>] [--scope app] [--skip-tests]
@@ -557,7 +572,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.6.2` exposes one browser target and five explicitly paired
+Version `0.7.0` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The
@@ -683,7 +698,7 @@ read-only managed-service assessment where the host supports one. Native apps
 use an app-scoped Arcane Core and `Arcane.localAI.status()` in this SDK version.
 Ollama is optional for packaging and non-AI applications.
 
-The loopback development server serves complete selected files and does not
+The development server serves complete selected files and does not
 apply byte-count or truncation gates. Optional hardening is inactive unless the
 caller explicitly selects `secure:true`. Required credential protection,
 malformed-request rejection, and unavoidable browser or operating-system safety

package/docs/architecture.md

@@ -236,7 +236,7 @@ Packaging writes the complete schema-1 release inventory to
 `ARCANE_APP_RELEASE.json`. Ordinary development, packaging, serving, and run
 paths do not count, limit, hash, truncate, tail, clip, or identify content by
 bytes, and they do not require provenance or verification receipts. The
-loopback server reads and returns each complete selected source, runtime, or
+development server reads and returns each complete selected source, runtime, or
 packaged file. Required credential protection, malformed-input rejection,
 applicable law, unavoidable protocol rules, and operating-system or browser
 safety remain in effect.
@@ -279,7 +279,7 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The SDK `0.6.2` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.7.0` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

package/docs/reference/cli.md

@@ -49,6 +49,7 @@ meaning and cardinality rules:
 | `--app` | app id | Workspace/app operations except shared scope and `verify-bundle`; also the exact `mail serve` caller id. |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
 | `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to `127.0.0.1:8000`; `mail serve` defaults to `127.0.0.1:8025` and admits numeric loopback only. |
+| `--public` | flag | `dev`; binds to `0.0.0.0` unless `--host` explicitly selects another address. |
 | `--target` | target id | `new`, `init`, native diagnostics, `build`, `run` |
 | `--format` / `--signing` | target-supported values | Native diagnostics, `build`, `run` |
 | `--output-root` | directory | Native `build` and `run` |
@@ -307,9 +308,9 @@ npm exec -- arcane upgrade --workspace . --app hello-world
 
 ### Overview
 
-Starts one loopback development server for one selected app and maps the exact
-workspace/runtime routes. It is a development convenience, not a production
-security boundary.
+Starts one development server for one selected app and maps the exact
+workspace/runtime routes. It defaults to localhost; `--public` enables access
+from other devices on the network.
 
 For an external workspace, the server exposes the selected projected
 `arcane/` root, including `arcane/sdk` and `arcane/dependencies`, alongside the
@@ -318,20 +319,35 @@ The explicit live-source SDK mapping remains unchanged and does not replace the
 installed projection.
 
 ```text
-arcane dev [--app <id>] [--host 127.0.0.1] [--port 8000]
+arcane dev [--app <id>] [--public] [--host <address>] [--port 8000]
 ```
 
 ### Lifecycle
 
 The command reports acceptance before bind/start work, emits the final URL,
 owns the server until cancellation, and restores failure to the process exit.
-The default host is loopback. Exposing another interface is an explicit
-development choice and does not add authentication.
+The default host is `127.0.0.1`. `--public` selects `0.0.0.0` (all IPv4
+interfaces); an explicit `--host` takes precedence. The command prints the
+local URL and available network URLs. Use a printed network URL on the other
+device, since `localhost` refers to that device and `0.0.0.0` is a bind address.
+Network URLs come from one interface snapshot at startup and do not establish
+remote reachability through the machine's firewall or network.
+
+This option changes the listener address. It does not configure a firewall,
+router forwarding, an internet tunnel, authentication, or HTTPS. Browser
+features that require a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts)
+still require HTTPS when accessed through a LAN address.
 
 ### Example
 
 ```bash
 npm exec -- arcane dev --app hello-world --port 8000
+
+# Forward the public option through an existing dev script, for any app id.
+npm run dev -- --app hello-world --public
+
+# Equivalent direct CLI invocation, with an optional port.
+npm exec -- arcane dev --app hello-world --public --port 8000
 ```
 
 ## `arcane test`

package/docs/reference/sdk-api.md

@@ -3451,7 +3451,7 @@ async function useselectApp(...arguments_) {
 
 ### Overview
 
-Starts one owned browser development server with exact runtime/app route mappings and an unguessable session capability.
+Starts one owned browser development server with exact runtime/app route mappings and a caller-selected bind address.
 
 ### Signature, modes, and result
 
@@ -3464,19 +3464,23 @@ Import it from `arcane-os`. Source mode accepts
 signal, onEvent}` and serves one validated workspace application plus its
 complete SDK or integrated runtime. Packaged mode uses
 `{mode:'packaged', releaseRoot, host, port, signal, onEvent}` and serves the
-complete selected release files. `host` must be
-numeric loopback `127.0.0.1` or `::1`; port `0` asks the operating system for an
-available port.
+complete selected release files. `host` defaults to `127.0.0.1` and accepts an
+explicit network address or hostname. Use `0.0.0.0` for all IPv4 interfaces or
+`::` for the platform's IPv6 wildcard listener; port `0` asks the operating
+system for an available port.
 
 The promise settles after the listener is ready and resolves to
-`{server, mode, workspaceRoot, appId, host, port, origin, cleanUrl, url, close,
-closed, lifecycle}`. `server` is the raw Node HTTP server. `url` contains the
-unguessable bootstrap capability that establishes an HttpOnly session
-cookie; do not log, persist, or disclose it. `cleanUrl` contains no capability
-but does not bootstrap a new browser session by itself. In packaged mode,
-`workspaceRoot` and `appId` are `null`.
-
-Starting the server opens a loopback listener and emits awaited,
+`{server, mode, workspaceRoot, appId, host, port, origin, cleanUrl, url,
+networkUrls, close, closed, lifecycle}`. `server` is the raw Node HTTP server.
+`url` and `cleanUrl` are the same application URL. Wildcard listeners use
+`localhost` in that local URL; `host` retains the actual bound address.
+`networkUrls` lists application URLs for applicable non-loopback interface
+addresses discovered once at startup. These URLs are connection candidates,
+not evidence of reachability from another device. The server adds no session
+capability or authentication. In packaged mode, `workspaceRoot` and `appId`
+are `null`.
+
+Starting the server opens the selected listener and emits awaited,
 backpressured `server.starting` and `server.started` events. Request failures
 emit `server.request.failed`; shutdown emits `server.stopped` after owned
 requests and event delivery drain. Call `await result.close()` in a `finally`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/cli/main.mjs

@@ -35,6 +35,7 @@ const VALUE_OPTIONS=new Set([
 ]);
 const FLAG_OPTIONS=new Set([
     'git',
+    'public',
     'skip-tests',
     'dry-run',
     'require-local-ai',
@@ -60,7 +61,7 @@ Usage:
   ${CLI_NAME} upgrade [--workspace <directory>] [--app <id>]
   ${CLI_NAME} doctor [--workspace <directory>] [--arcane-root <directory>]
   ${CLI_NAME} import-map [--workspace <directory>] [--app <id>]
-  ${CLI_NAME} dev [--app <id>] [--host 127.0.0.1] [--port 8000] [--sdk-runtime-source <sdk-root>]
+  ${CLI_NAME} dev [--app <id>] [--public] [--host <address>] [--port 8000] [--sdk-runtime-source <sdk-root>]
   ${CLI_NAME} test [--app <id>] [--scope app]
   ${CLI_NAME} test --scope shared --test-file <repo-relative.test.mjs>
   ${CLI_NAME} check [--app <id>] [--scope app] [--skip-tests]
@@ -83,6 +84,8 @@ Usage:
   ${CLI_NAME} mail serve --profile <profile> --from <address> --app <id> --origin <origin> [--allow-to <addresses>] [--app-key-stdin] [--host 127.0.0.1] [--port 8025] [--request-timeout <ms>]
 
 Development:
+  --public                      Bind all IPv4 interfaces (0.0.0.0) and print network URLs.
+  --host <address>               Override the bind address; takes precedence over --public.
   --sdk-runtime-source <sdk-root>  Dev-only live SDK checkout; omitted preserves the workspace runtime mode.
 
 Global:
@@ -445,6 +448,9 @@ function operationOptions(command,parsed,cwd){
     if(values['sdk-runtime-source']!==undefined&&command!=='dev'){
         usage('--sdk-runtime-source is supported only by dev.');
     }
+    if(flags.has('public')&&command!=='dev'){
+        usage('--public is supported only by dev.');
+    }
     if(flags.has('overwrite')&&command!=='bundle'){
         usage('--overwrite is supported only by bundle.');
     }
@@ -506,7 +512,7 @@ function operationOptions(command,parsed,cwd){
         noExtraPositionals(command,positionals);
         return {
             ...common,
-            host:values.host??'127.0.0.1',
+            host:values.host??(flags.has('public')?'0.0.0.0':'127.0.0.1'),
             port:readPort(values.port,8000),
             ...(values['sdk-runtime-source']===undefined?{}:{
                 sdkRuntimeSourceRoot:path.resolve(cwd,values['sdk-runtime-source'])
@@ -831,6 +837,7 @@ function serverSummary(result){
         host:result.host,
         port:result.port,
         url:result.url,
+        ...(result.networkUrls===undefined?{}:{networkUrls:result.networkUrls}),
         ...(result.callerAuthentication
             ?{callerAuthentication:result.callerAuthentication}
             :{}),
@@ -841,7 +848,11 @@ function serverSummary(result){
 }
 
 async function waitForServer(result,signal,reporter){
-    reporter.emit('server.ready',serverSummary(result),`Development server ready at ${result.url}`);
+    const readyMessage=[
+        `Development server ready at ${result.url}`,
+        ...(result.networkUrls??[]).map(function networkAddress(url){return `Network: ${url}`;})
+    ].join('\n');
+    reporter.emit('server.ready',serverSummary(result),readyMessage);
     if(result.lifecycle&&is.function(result.lifecycle.then)){
         const abort=()=>{
             void Promise.resolve().then(()=>result.close?.()).catch(()=>{});

package/src/dev-server.mjs

@@ -2,6 +2,7 @@ import Is from 'strong-type';
 import {constants as FS_CONSTANTS} from 'node:fs';
 import {lstat,open,readFile,realpath} from 'node:fs/promises';
 import http from 'node:http';
+import os from 'node:os';
 import path from 'node:path';
 import {resolveWorkspace} from './workspace.mjs';
 import {createEventQueue} from './event-queue.mjs';
@@ -489,6 +490,29 @@ function listen(server,{host,port,signal}){
     });
 }
 
+function browserHostname(host){
+    return host.includes(':')?`[${host}]`:host;
+}
+
+function networkUrlsForAddress(address,startPath){
+    if(address.address==='127.0.0.1'||address.address==='::1')return [];
+    const allIPv4=address.address==='0.0.0.0';
+    const allInterfaces=address.address==='::';
+    const urls=new Set();
+    for(const entries of Object.values(os.networkInterfaces())){
+        for(const entry of entries??[]){
+            if(entry.internal)continue;
+            // Scoped IPv6 addresses need the receiving device's interface,
+            // so they cannot provide a portable browser link for another device.
+            if(entry.family==='IPv6'&&entry.scopeid)continue;
+            if(allIPv4&&entry.family!=='IPv4')continue;
+            if(!allIPv4&&!allInterfaces&&entry.address!==address.address)continue;
+            urls.add(`http://${browserHostname(entry.address)}:${address.port}${startPath}`);
+        }
+    }
+    return [...urls];
+}
+
 async function startOwnedDevServer({
     workspaceRoot=process.cwd(),
     appId,
@@ -504,8 +528,8 @@ async function startOwnedDevServer({
     if(sdkRuntimeSourceRoot!==undefined&&mode!=='source'){
         fail('sdkRuntimeSourceRoot is supported only in source development mode.','ARCANE_USAGE');
     }
-    if(host!=='127.0.0.1'&&host!=='::1'){
-        fail('Development server host must be a numeric loopback address (127.0.0.1 or ::1).','ARCANE_POLICY_DENIED');
+    if(!is.string(host)||!host.trim()){
+        fail('Development server host must be a nonempty string.','ARCANE_USAGE');
     }
     if(!is.integer(port)||port<0||port>65535)fail('port must be an integer from 0 through 65535.','ARCANE_USAGE');
     const requestedRuntimeMode=mode==='source'&&sdkRuntimeSourceRoot!==undefined
@@ -631,7 +655,9 @@ async function startOwnedDevServer({
         server.close();
         fail('Development server did not expose a TCP address.');
     }
-    const visibleHost=address.family==='IPv6'?`[${address.address}]`:address.address;
+    const visibleHost=address.address==='0.0.0.0'||address.address==='::'
+        ?'localhost'
+        :browserHostname(address.address);
     const endpoint=new URL(`http://${visibleHost}:${address.port}`);
     const origin=endpoint.origin;
     const cleanUrl=`${origin}${routeSet.startPath}`;
@@ -728,17 +754,20 @@ async function startOwnedDevServer({
         origin,
         cleanUrl,
         url,
+        networkUrls:[],
         close,
         closed:lifecycle,
         lifecycle
     };
     try{
+        result.networkUrls=networkUrlsForAddress(address,routeSet.startPath);
         await events.send({
             type:'server.started',
             mode,
             host:result.host,
             port:result.port,
             url,
+            networkUrls:result.networkUrls,
             appId:result.appId,
             ...(routeSet.runtime?{
                 runtimeMode:routeSet.runtime.mode,