Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

feat(view): add LAN CLI and API core plumbing [H19]

Corey Olsona9e8de444e99
diff --git a/src/api.js b/src/api.js
index a7d7135d..37903017 100644
--- a/src/api.js
+++ b/src/api.js
@@ -1,3 +1,4 @@
+import { isIP } from 'node:net';
/** The local API v1: the CLI's moves, persistent board identities and live events (A2). */
import {
createHash,
@@ -872,9 +873,9 @@ function credentialMatches(candidate, expected) {
}
/** Share the local router with the person's view and other local transports; the standalone API explicitly denies person authority.
- * @param {{ secret: string | Buffer, getPort: () => number, runCommand: Function, projects?: () => any[], scope?: { projectRoot: string }, isMain?: boolean, allowedOrigins?: string[], onStateBuild?: Function, onItemBuild?: Function, personChannel?: string, stateDetail?: string, sessionCookie?: {name:string,value:string} }} [options]
+ * @param {{ secret: string | Buffer, getPort: () => number, runCommand: Function, projects?: () => any[], scope?: { projectRoot: string }, isMain?: boolean, allowedOrigins?: string[], allowedHosts?: string[], onStateBuild?: Function, onItemBuild?: Function, personChannel?: string, stateDetail?: string, sessionCookie?: {name:string,value:string} }} [options]
*/
-export function createLocalApiHandler({ secret, getPort, runCommand, projects = listApiProjects, scope, isMain, allowedOrigins = [], onStateBuild, onItemBuild, personChannel = 'view', stateDetail = 'full', sessionCookie } = {}) {
+export function createLocalApiHandler({ secret, getPort, runCommand, projects = listApiProjects, scope, isMain, allowedOrigins = [], allowedHosts = [], onStateBuild, onItemBuild, personChannel = 'view', stateDetail = 'full', sessionCookie } = {}) {
if (typeof getPort !== 'function') throw new TypeError('createLocalApiHandler needs a bound-port getter');
if (typeof runCommand !== 'function') throw new TypeError('createLocalApiHandler needs the actual CLI entry point as runCommand');
// A page that still reads each item's detail from the state keeps full items until it opts in.
@@ -896,6 +897,11 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =
const cookieName = sessionCookie?.name;
const cookieKey = sessionCookie === undefined ? null : Buffer.from(sessionCookie.value);
const permittedOrigins = new Set(allowedOrigins);
+ // A transport may name exact literal interface addresses; DNS names, ports and wildcards are not authority.
+ if (!Array.isArray(allowedHosts) || allowedHosts.some(host => typeof host !== 'string' || isIP(host) !== 4 || host === '0.0.0.0')) {
+ throw new TypeError('createLocalApiHandler allowedHosts needs literal IPv4 addresses, without ports or wildcard binds');
+ }
+ const permittedHosts = [...new Set(allowedHosts)];
const stateCache = new Map();
// Each board's item details by item id, and each board's spec-approval view (#1040).
const detailCache = new Map();
@@ -1111,7 +1117,8 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =
const authorization = String(req.headers.authorization ?? '');
const given = Buffer.from(String(req.headers['x-pullboard-key'] ?? (authorization.startsWith('Bearer ') ? authorization.slice(7) : url.searchParams.get('k') ?? '')));
const bound = getPort();
- const ownHost = req.headers.host === ADDRESS + ':' + bound || req.headers.host === 'localhost:' + bound;
+ const ownHost = req.headers.host === ADDRESS + ':' + bound || req.headers.host === 'localhost:' + bound
+ || permittedHosts.some(host => req.headers.host === host + ':' + bound);
const validKey = credentialMatches(given, key);
const cookieValue = cookieKey ? requestCookie(req.headers.cookie, cookieName) : null;
const givenCookie = Buffer.from(cookieValue ?? '');
diff --git a/src/background-view.js b/src/background-view.js
index 5923b33d..a73bceb6 100644
--- a/src/background-view.js
+++ b/src/background-view.js
@@ -47,9 +47,11 @@ export function stopCommand(pid) {
/** Print a live or reused view link and the exact stop action for its owning process. */
export function reportView(io, view) {
- io.result?.({ url: view.url, port: view.port, pid: view.pid, boundAt: view.boundAt, reused: view.reused });
+ io.result?.({ url: view.url, port: view.port, pid: view.pid, boundAt: view.boundAt, reused: view.reused, ...(view.lan ? { lan: true } : {}) });
io.say(`Pullboard view: ${view.url}`);
- io.say(`Only this machine can reach it, and only with that link. To stop it: ${stopCommand(view.pid)}`);
+ io.say(view.lan
+ ? `Devices on the local network can reach it using this private link. To stop it: ${stopCommand(view.pid)}`
+ : `Only this machine can reach it, and only with that link. To stop it: ${stopCommand(view.pid)}`);
}
/**
@@ -108,11 +110,12 @@ function release(child) {
* @param {any} io
* @param {number} port
* @param {string} [projectRoot]
+ * @param {{lan?: boolean}} [options] Explicit LAN mode is never inherited by automatic init/resume startup.
* @returns {Promise<number>}
*/
-export async function launchBackgroundView(io, port, projectRoot) {
+export async function launchBackgroundView(io, port, projectRoot, { lan = false } = {}) {
const { child, view } = await startDetachedView({
- args: [...(projectRoot ? ['--project'] : []), '--port', String(port)],
+ args: [...(projectRoot ? ['--project'] : []), ...(lan ? ['--lan'] : []), '--port', String(port)],
cwd: projectRoot ?? io.cwd,
stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
});
diff --git a/src/cli-main.js b/src/cli-main.js
index 5f9b3d99..483c5dc2 100644
--- a/src/cli-main.js
+++ b/src/cli-main.js
@@ -50,6 +50,7 @@ const OPTIONS = {
project: { type: 'boolean' },
export: { type: 'string' },
'no-open': { type: 'boolean' },
+ lan: { type: 'boolean' },
'no-permissions': { type: 'boolean' },
note: { type: 'string' },
infra: { type: 'string' },
diff --git a/src/commands/view.js b/src/commands/view.js
index aab937c4..e9a76827 100644
--- a/src/commands/view.js
+++ b/src/commands/view.js
@@ -62,14 +62,15 @@ import {
*/
export async function viewHere(io, values) {
if (values.export !== undefined) {
- if (values.project) throw new Refused('USAGE', 'choose either --project for a live scoped view or --export for a static snapshot');
+ if (values.project || values.lan) throw new Refused('USAGE', 'choose either a live view with --project or --lan, or --export for a static snapshot');
const exported = await exportView(io.cwd, resolve(io.cwd, values.export));
io.result?.(exported);
io.say(`wrote snapshot ${exported.path}`);
return 0;
}
const projectRequested = Boolean(values.project);
- const port = values.port === undefined ? (projectRequested ? 0 : defaultViewPort()) : Number(values.port);
+ const lan = Boolean(values.lan);
+ const port = values.port === undefined ? (projectRequested || lan ? 0 : defaultViewPort()) : Number(values.port);
if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Refused('USAGE', '--port is a number from 0 to 65535; 0 picks a free one');
let projectRoot;
let scopeCommonDir;
@@ -98,7 +99,7 @@ export async function viewHere(io, values) {
const internalForeground = process.env.PULLBOARD_VIEW_BACKGROUND_CHILD === '1'
|| process.env.PULLBOARD_VIEW_FOREGROUND === '1';
if (!internalForeground) {
- const existing = port ? await runningView(port, scopeCommonDir) : null;
+ const existing = !lan && port ? await runningView(port, scopeCommonDir) : null;
if (existing) {
if (info && existsSync(join(info.root, CONFIG_FILE))) {
const ctx = context(io);
@@ -107,23 +108,24 @@ export async function viewHere(io, values) {
reportView(io, { ...existing, reused: true });
return 0;
}
- if (process.env.AI_AGENT !== undefined || !io.physicalStdoutIsTTY) return await launchBackgroundView(io, port, projectRoot);
+ if (process.env.AI_AGENT !== undefined || !io.physicalStdoutIsTTY) return await launchBackgroundView(io, port, projectRoot, { lan });
}
let view;
try {
// The adapter override is carried only by the in-process command streams, for private CLI fixtures.
- view = await (io.serveView ?? serveView)({ port, isMain: codeIsFromMain(), ...(projectRoot ? { projectRoot } : {}) });
+ view = await (io.serveView ?? serveView)({ port, isMain: codeIsFromMain(), ...(lan ? { lan: true } : {}), ...(projectRoot ? { projectRoot } : {}) });
const sentinel = startServeSentinel({ projectRoot });
const boundAt = new Date().toISOString();
const closeServer = view.close;
view = {
...view,
+ ...(lan ? { lan: true } : {}),
pid: process.pid,
boundAt,
- close: async () => { await sentinel.close(); forgetView(view.port); await closeServer(); },
+ close: async () => { await sentinel.close(); if (!lan) forgetView(view.port); await closeServer(); },
};
try {
- rememberView({ port: view.port, secret: new URL(view.url).searchParams.get('k'), pid: process.pid, boundAt,
+ if (!lan) rememberView({ port: view.port, secret: new URL(view.url).searchParams.get('k'), pid: process.pid, boundAt,
...(scopeCommonDir ? { scopeCommonDir } : {}) }, { rememberPort: port === 0 && !scopeCommonDir });
} catch (error) {
throw new Refused('VIEW_STATE', `could not save the private view session: ${error.message}`);
@@ -152,7 +154,7 @@ export async function viewHere(io, values) {
}
reportView(io, { ...view, reused: false });
if (process.env.PULLBOARD_VIEW_BACKGROUND_CHILD === '1' && process.send) {
- process.send({ type: 'ready', url: view.url, port: view.port, pid: process.pid, boundAt: view.boundAt });
+ process.send({ type: 'ready', url: view.url, port: view.port, pid: process.pid, boundAt: view.boundAt, ...(lan ? { lan: true } : {}) });
}
io.flush?.(0);
if (!values['no-open'] && process.env.PULLBOARD_VIEW_BACKGROUND_CHILD !== '1') {
diff --git a/src/help.js b/src/help.js
index 93f31957..522a5db0 100644
--- a/src/help.js
+++ b/src/help.js
@@ -45,6 +45,7 @@ Set up
register SSH test capacity; no runner sign-in; root defaults to ~/.pullboard-runner
pullboard runner list each runner's registered slots and browsers, which it runs at
pullboard view [--project] [--port N] [--no-open] every project on this machine in your browser; default http://127.0.0.1:${DEFAULT_VIEW_PORT}
+ pullboard view --lan a private link for a phone on the local IPv4 network
items, shouts, doctrine, agents and activity; --port 0 chooses a free port
--project limits this view to the registered project for this repository
add items, shout and hold lanes from it