@namzu/sandbox 24.0.0 → 26.0.0

package/local-computer/app-catalog.cjs

@@ -0,0 +1,240 @@
+const { constants, accessSync, readFileSync } = require('node:fs')
+const { join } = require('node:path')
+
+// The image is built in stages and each stage advertises only what it installed.
+// `base` is the light Pal computer; `creative` is built FROM it and adds the heavy
+// applications, so its catalogue is every application of both stages.
+const STAGES = Object.freeze(['base', 'creative'])
+
+// Application ids never become commands, paths, argv or environment variables.
+// Each stage installs its own entries and fails its build if an executable
+// or icon is absent. No id is advertised as a simulated application.
+const APPLICATIONS = Object.freeze(
+	[
+		{
+			id: 'blender',
+			stage: 'creative',
+			name: 'Blender',
+			binary: '/usr/local/bin/blender',
+			args: [],
+			desktop: ['blender.desktop'],
+			software: true,
+			required: true,
+		},
+		{
+			id: 'freecad',
+			stage: 'creative',
+			name: 'FreeCAD',
+			binary: '/usr/bin/freecad',
+			args: [],
+			desktop: ['org.freecadweb.FreeCAD.desktop', 'freecad.desktop'],
+			software: true,
+			required: true,
+		},
+		{
+			id: 'gimp',
+			stage: 'creative',
+			name: 'GIMP',
+			binary: '/usr/bin/gimp',
+			args: [],
+			desktop: ['gimp.desktop'],
+			required: true,
+		},
+		{
+			id: 'inkscape',
+			stage: 'creative',
+			name: 'Inkscape',
+			binary: '/usr/bin/inkscape',
+			args: [],
+			desktop: ['org.inkscape.Inkscape.desktop', 'inkscape.desktop'],
+			required: true,
+		},
+		{
+			id: 'draw',
+			stage: 'creative',
+			name: 'LibreOffice Draw',
+			binary: '/usr/bin/libreoffice',
+			args: ['--draw'],
+			desktop: ['libreoffice-draw.desktop'],
+			required: true,
+		},
+		{
+			id: 'editor',
+			stage: 'base',
+			name: 'Text Editor',
+			binary: '/usr/bin/mousepad',
+			args: [],
+			desktop: ['org.xfce.mousepad.desktop', 'mousepad.desktop'],
+			required: true,
+		},
+		{
+			id: 'files',
+			stage: 'base',
+			name: 'Files',
+			binary: '/usr/bin/pcmanfm',
+			args: ['/home/namzu/workspace'],
+			desktop: ['pcmanfm.desktop'],
+			required: true,
+		},
+		{
+			id: 'terminal',
+			stage: 'base',
+			name: 'Terminal',
+			binary: '/usr/bin/xterm',
+			args: [
+				'-fa',
+				'DejaVu Sans Mono',
+				'-fs',
+				'11',
+				'-bg',
+				'#171c18',
+				'-fg',
+				'#e7eee8',
+				'-cr',
+				'#76d77d',
+				'-title',
+				'Terminal',
+			],
+			desktop: ['debian-xterm.desktop', 'xterm.desktop'],
+			// The dock's own terminal glyph, not the plain xterm pixmap.
+			icon: 'utilities-terminal',
+			required: true,
+		},
+		{
+			id: 'openscad',
+			stage: 'creative',
+			name: 'OpenSCAD',
+			binary: '/usr/bin/openscad',
+			args: [],
+			desktop: ['openscad.desktop'],
+			software: true,
+		},
+		{
+			id: 'kdenlive',
+			stage: 'creative',
+			name: 'Kdenlive',
+			binary: '/usr/bin/kdenlive',
+			args: [],
+			desktop: ['org.kde.kdenlive.desktop', 'kdenlive.desktop'],
+			software: true,
+		},
+		{
+			id: 'godot',
+			stage: 'creative',
+			name: 'Godot',
+			binary: '/usr/local/bin/godot4',
+			args: ['--rendering-method', 'gl_compatibility'],
+			desktop: ['godot3.desktop'],
+			software: true,
+		},
+		{
+			id: 'solitaire',
+			stage: 'creative',
+			name: 'Solitaire',
+			binary: '/usr/games/sol',
+			args: [],
+			desktop: ['sol.desktop', 'org.gnome.Aisleriot.desktop', 'aisleriot.desktop'],
+		},
+		{
+			id: 'qgis',
+			stage: 'creative',
+			name: 'QGIS',
+			binary: '/usr/bin/qgis',
+			args: [],
+			desktop: ['org.qgis.qgis.desktop', 'qgis.desktop'],
+			software: true,
+		},
+		{
+			id: 'kicad',
+			stage: 'creative',
+			name: 'KiCad',
+			binary: '/usr/bin/kicad',
+			args: [],
+			desktop: ['org.kicad.kicad.desktop', 'kicad.desktop'],
+			software: true,
+		},
+		{
+			id: 'paraview',
+			stage: 'creative',
+			name: 'ParaView',
+			binary: '/usr/bin/paraview',
+			args: [],
+			desktop: ['paraview.desktop'],
+			software: true,
+		},
+	].map((app) =>
+		Object.freeze({ ...app, args: Object.freeze(app.args), desktop: Object.freeze(app.desktop) }),
+	),
+)
+
+/** Applications a stage installs: its own and those of every stage it is built FROM. */
+function applicationsForStage(stage) {
+	const rank = STAGES.indexOf(stage)
+	if (rank < 0) throw new Error(`Unknown image stage: ${stage}`)
+	return APPLICATIONS.filter((app) => STAGES.indexOf(app.stage) <= rank)
+}
+
+/**
+ * The stage this image was built as, written by prepare-home at build time. A tree
+ * without the marker (a source checkout, a test) is the whole catalogue.
+ */
+function activeStage(read = () => readFileSync(join(__dirname, 'stage'), 'utf8')) {
+	try {
+		const stage = read().trim()
+		return STAGES.includes(stage) ? stage : STAGES[STAGES.length - 1]
+	} catch {
+		return STAGES[STAGES.length - 1]
+	}
+}
+
+function activeApplications(read) {
+	return applicationsForStage(activeStage(read))
+}
+
+function installedApplication(
+	id,
+	access = (binary) => accessSync(binary, constants.X_OK),
+	applications = activeApplications(),
+) {
+	const app = applications.find((entry) => entry.id === id)
+	if (!app) return undefined
+	try {
+		access(app.binary)
+		return app
+	} catch {
+		return undefined
+	}
+}
+
+function applicationEnvironment(app, inherited = process.env) {
+	const env = { ...inherited }
+	for (const key of Object.keys(env))
+		if (key.startsWith('NAMZU_') || key === 'NODE_OPTIONS' || key.startsWith('LD_')) delete env[key]
+	// Chromium disables its own D-Bus use. Desktop applications still need the
+	// guest session bus or their normal local autolaunch when no bus is set.
+	if (env.DBUS_SESSION_BUS_ADDRESS === 'disabled:')
+		Reflect.deleteProperty(env, 'DBUS_SESSION_BUS_ADDRESS')
+	// Explicit guest-only values. No host display, profile or caller cwd is used.
+	env.HOME = '/home/namzu'
+	env.DISPLAY = ':99'
+	env.PATH = '/usr/local/bin:/usr/bin:/bin:/usr/games'
+	if (app.software) env.LIBGL_ALWAYS_SOFTWARE = '1'
+	if (app.id === 'blender') {
+		env.BLENDERMCP_NO_UPDATE_CHECK = '1'
+		env.BLENDER_MCP_DISABLE_TELEMETRY = '1'
+	}
+	// The isolated guest has no host audio device. SDL must not abort the editor
+	// while trying to open an unavailable ALSA default output.
+	if (app.id === 'kdenlive') env.SDL_AUDIODRIVER = 'dummy'
+	return env
+}
+
+module.exports = {
+	APPLICATIONS,
+	STAGES,
+	applicationsForStage,
+	activeStage,
+	activeApplications,
+	installedApplication,
+	applicationEnvironment,
+}

package/local-computer/app-native-host.cjs

@@ -0,0 +1,144 @@
+#!/usr/local/bin/node
+const { spawn } = require('node:child_process')
+const { createHash } = require('node:crypto')
+const { readFileSync } = require('node:fs')
+const { join } = require('node:path')
+const { installedApplication, applicationEnvironment } = require('./app-catalog.cjs')
+const manifest = require('./new-tab/manifest.json')
+
+const HOST_NAME = 'org.namzu.apps'
+const extensionId = [
+	...createHash('sha256').update(Buffer.from(manifest.key, 'base64')).digest().subarray(0, 16),
+]
+	.map((byte) => String.fromCharCode(97 + (byte >> 4), 97 + (byte & 15)))
+	.join('')
+const EXTENSION_ORIGIN = `chrome-extension://${extensionId}/`
+const MAX_MESSAGE = 4096
+
+function launcherMessage(message) {
+	if (!message || typeof message !== 'object' || Array.isArray(message)) return undefined
+	const keys = Object.keys(message)
+	if (message.type === 'list' && keys.length === 1) return { type: 'list' }
+	if (
+		message.type === 'launch' &&
+		keys.length === 2 &&
+		typeof message.appId === 'string' &&
+		/^[a-z]{1,20}$/.test(message.appId)
+	)
+		return { type: 'launch', appId: message.appId }
+	return undefined
+}
+
+function launchApplication(app, spawnProcess = spawn) {
+	return new Promise((resolve) => {
+		let child
+		try {
+			child = spawnProcess(app.binary, [...app.args], {
+				cwd: '/home/namzu/workspace',
+				env: applicationEnvironment(app),
+				detached: true,
+				shell: false,
+				stdio: 'ignore',
+			})
+		} catch {
+			resolve({ ok: false, error: 'launch_failed' })
+			return
+		}
+		child.once('error', () => resolve({ ok: false, error: 'launch_failed' }))
+		child.once('spawn', () => {
+			child.unref()
+			resolve({ ok: true, appId: app.id })
+		})
+	})
+}
+
+/** One bounded Chrome native message per host process. No guest HTTP port or token. */
+async function handleMessage(message, options = {}) {
+	const parsed = launcherMessage(message)
+	if (!parsed) return { ok: false, error: 'invalid_request' }
+	if (parsed.type === 'list') {
+		try {
+			const apps = JSON.parse(
+				(options.readApps ?? (() => readFileSync(join(__dirname, 'new-tab/apps.json'), 'utf8')))(),
+			)
+			if (!Array.isArray(apps)) throw new Error('Invalid catalogue')
+			return { ok: true, apps }
+		} catch {
+			return { ok: false, error: 'catalogue_unavailable' }
+		}
+	}
+	const app = installedApplication(parsed.appId, options.access)
+	if (!app) return { ok: false, error: 'application_unavailable' }
+	return await launchApplication(app, options.spawn)
+}
+
+function writeMessage(output, message) {
+	const body = Buffer.from(JSON.stringify(message), 'utf8')
+	const header = Buffer.alloc(4)
+	header.writeUInt32LE(body.length)
+	output.end(Buffer.concat([header, body]))
+}
+
+function runNativeHost(origin, input = process.stdin, output = process.stdout) {
+	if (origin !== EXTENSION_ORIGIN) {
+		writeMessage(output, { ok: false, error: 'unauthorized_origin' })
+		return
+	}
+	let body = Buffer.alloc(0)
+	let size
+	let settled = false
+	const finish = (response) => {
+		if (settled) return
+		settled = true
+		input.removeListener('data', receive)
+		input.destroy()
+		writeMessage(output, response)
+	}
+	const receive = (chunk) => {
+		if (settled) return
+		if (body.length + chunk.length > MAX_MESSAGE + 4) {
+			finish({ ok: false, error: 'invalid_request' })
+			return
+		}
+		body = Buffer.concat([body, chunk])
+		if (body.length < 4) return
+		if (size === undefined) size = body.readUInt32LE(0)
+		if (size < 1 || size > MAX_MESSAGE || body.length > size + 4) {
+			finish({ ok: false, error: 'invalid_request' })
+			return
+		}
+		if (body.length !== size + 4) return
+		let message
+		try {
+			message = JSON.parse(body.toString('utf8', 4))
+		} catch {
+			finish({ ok: false, error: 'invalid_request' })
+			return
+		}
+		settled = true
+		input.removeListener('data', receive)
+		input.destroy()
+		void handleMessage(message).then(
+			(response) => writeMessage(output, response),
+			() => writeMessage(output, { ok: false, error: 'launch_failed' }),
+		)
+	}
+	input.on('data', receive)
+	input.on('end', () => {
+		if (!settled) finish({ ok: false, error: 'invalid_request' })
+	})
+	input.on('error', () => {
+		if (!settled) finish({ ok: false, error: 'invalid_request' })
+	})
+}
+
+module.exports = {
+	EXTENSION_ORIGIN,
+	HOST_NAME,
+	MAX_MESSAGE,
+	launcherMessage,
+	launchApplication,
+	handleMessage,
+	runNativeHost,
+}
+if (require.main === module) runNativeHost(process.argv[2])

package/local-computer/browser-home.cjs

@@ -0,0 +1,249 @@
+const { spawn } = require('node:child_process')
+const { randomBytes } = require('node:crypto')
+const { writeFileSync } = require('node:fs')
+const { activeApplications } = require('./app-catalog.cjs')
+const { EXTENSION_ORIGIN } = require('./app-native-host.cjs')
+
+const HOME_URL = `${EXTENSION_ORIGIN}home.html`
+const NEW_TAB_URL = 'chrome://newtab/'
+const MARKER_BASE = 'http://127.0.0.1:9222/namzu-home-bootstrap?id='
+const READY_FILE = '/tmp/namzu-browser-home-ready'
+const PRESENTED_HOME = `({url:location.href,ready:document.readyState,apps:document.getElementById('apps')?.children.length||0,clock:!!document.getElementById('clock')})`
+
+class BrowserHomeError extends Error {
+	constructor(code) {
+		super(code)
+		this.code = code
+	}
+}
+
+function pause(signal) {
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) return reject(new BrowserHomeError('home-startup-aborted'))
+		const finish = (error) => {
+			clearTimeout(timer)
+			signal.removeEventListener('abort', abort)
+			if (error) reject(error)
+			else resolve()
+		}
+		const abort = () => finish(new BrowserHomeError('home-startup-aborted'))
+		const timer = setTimeout(() => finish(), 100)
+		signal.addEventListener('abort', abort, { once: true })
+	})
+}
+
+async function listTargets(signal) {
+	const response = await fetch('http://127.0.0.1:9222/json/list', { signal })
+	if (!response.ok) throw new BrowserHomeError('browser-not-ready')
+	const text = await response.text()
+	if (text.length > 1024 * 1024) throw new BrowserHomeError('browser-target-list-too-large')
+	const targets = JSON.parse(text)
+	if (!Array.isArray(targets) || targets.length > 1000)
+		throw new BrowserHomeError('browser-target-list-invalid')
+	return targets
+}
+
+function request(target, method, params, signal) {
+	let url
+	try {
+		url = new URL(target.webSocketDebuggerUrl)
+	} catch {
+		return Promise.reject(new BrowserHomeError('browser-target-invalid'))
+	}
+	if (
+		url.protocol !== 'ws:' ||
+		url.hostname !== '127.0.0.1' ||
+		url.port !== '9222' ||
+		url.username ||
+		url.password ||
+		url.pathname !== `/devtools/page/${target.id}` ||
+		url.search ||
+		url.hash
+	)
+		return Promise.reject(new BrowserHomeError('browser-target-invalid'))
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) return reject(new BrowserHomeError('home-startup-aborted'))
+		const socket = new WebSocket(url)
+		let settled = false
+		const finish = (error, result) => {
+			if (settled) return
+			settled = true
+			signal.removeEventListener('abort', abort)
+			socket.removeEventListener('open', open)
+			socket.removeEventListener('message', message)
+			socket.removeEventListener('error', lost)
+			socket.removeEventListener('close', lost)
+			// Undici reports closing an opening socket as an error event.
+			socket.addEventListener('error', () => {}, { once: true })
+			socket.close()
+			if (error) reject(error)
+			else resolve(result)
+		}
+		const abort = () => finish(new BrowserHomeError('home-startup-aborted'))
+		const lost = () => finish(new BrowserHomeError('browser-target-disconnected'))
+		const open = () => {
+			try {
+				socket.send(JSON.stringify({ id: 1, method, params }))
+			} catch {
+				finish(new BrowserHomeError('browser-command-refused'))
+			}
+		}
+		const message = (event) => {
+			try {
+				const text = String(event.data)
+				if (text.length > 65536) throw new Error('Bounded response required')
+				const reply = JSON.parse(text)
+				if (reply.id !== 1) return
+				if (reply.error) finish(new BrowserHomeError('browser-command-refused'))
+				else finish(undefined, reply.result)
+			} catch {
+				finish(new BrowserHomeError('browser-response-invalid'))
+			}
+		}
+		signal.addEventListener('abort', abort, { once: true })
+		socket.addEventListener('open', open, { once: true })
+		socket.addEventListener('message', message)
+		socket.addEventListener('error', lost, { once: true })
+		socket.addEventListener('close', lost, { once: true })
+	})
+}
+
+/** Bootstrap only the unique tab created by this launcher, never a restored tab. */
+async function bootstrapBrowserHome(marker, options = {}) {
+	if (!/^http:\/\/127\.0\.0\.1:9222\/namzu-home-bootstrap\?id=[a-f0-9]{32}$/.test(marker))
+		throw new BrowserHomeError('browser-marker-invalid')
+	const signal = options.signal ?? AbortSignal.timeout(15000)
+	const list = options.listTargets ?? listTargets
+	const command = options.request ?? request
+	const delay = options.pause ?? pause
+	let id
+	let navigated = false
+	let nativeNewTab = false
+	while (!signal.aborted) {
+		let targets
+		try {
+			targets = await list(signal)
+		} catch {
+			await delay(signal)
+			continue
+		}
+		const target = targets.find((entry) =>
+			id ? entry.type === 'page' && entry.id === id : entry.type === 'page' && entry.url === marker,
+		)
+		if (!target) {
+			if (id) throw new BrowserHomeError('owned-home-tab-closed')
+			await delay(signal)
+			continue
+		}
+		id ??= target.id
+		if (![marker, NEW_TAB_URL, HOME_URL].includes(target.url))
+			throw new BrowserHomeError('owned-home-tab-navigated-away')
+		if (navigated) {
+			const result = await command(
+				target,
+				'Runtime.evaluate',
+				{ expression: PRESENTED_HOME, returnByValue: true },
+				signal,
+			)
+			const value = result?.result?.value
+			if (
+				value?.url === HOME_URL &&
+				value.ready === 'complete' &&
+				value.clock === true &&
+				value.apps === activeApplications().length
+			) {
+				if (nativeNewTab) return
+				// Activate this trusted extension, then use Chromium's native route
+				// for its New Tab virtual URL rather than leaving a literal address.
+				await command(target, 'Page.navigate', { url: NEW_TAB_URL }, signal)
+				nativeNewTab = true
+				await delay(signal)
+				continue
+			}
+			if (value?.url === HOME_URL) {
+				await delay(signal)
+				continue
+			}
+		}
+		await command(target, 'Page.navigate', { url: nativeNewTab ? NEW_TAB_URL : HOME_URL }, signal)
+		navigated = true
+		await delay(signal)
+	}
+	throw new BrowserHomeError('home-startup-aborted')
+}
+
+function browserLaunchArguments(args, nonce = randomBytes(16).toString('hex')) {
+	if (!/^[a-f0-9]{32}$/.test(nonce)) throw new BrowserHomeError('browser-marker-invalid')
+	const homeRequested = args.at(-1) === NEW_TAB_URL
+	const marker = `${MARKER_BASE}${nonce}`
+	return { homeRequested, marker, args: homeRequested ? [...args.slice(0, -1), marker] : [...args] }
+}
+
+async function runBrowser(args) {
+	const { homeRequested, marker, args: actualArgs } = browserLaunchArguments(args)
+	const controller = new AbortController()
+	const deadline = homeRequested ? setTimeout(() => controller.abort(), 15000) : undefined
+	const child = spawn('/usr/bin/chromium', actualArgs, { stdio: 'inherit' })
+	let ended = false
+	const closed = new Promise((resolve, reject) => {
+		child.once('error', () => {
+			ended = true
+			controller.abort()
+			reject(new BrowserHomeError('browser-start-failed'))
+		})
+		child.once('close', (code) => {
+			ended = true
+			if (code !== 0) controller.abort()
+			resolve(code ?? 1)
+		})
+	})
+	void closed.catch(() => {})
+	const stop = () => {
+		controller.abort()
+		if (!ended) child.kill('SIGTERM')
+	}
+	process.on('SIGTERM', stop)
+	process.on('SIGINT', stop)
+	try {
+		if (homeRequested) {
+			await bootstrapBrowserHome(marker, { signal: controller.signal })
+			clearTimeout(deadline)
+			if (process.env.NAMZU_BROWSER_HOME_READY === '1')
+				writeFileSync(READY_FILE, 'ready\n', { flag: 'wx', mode: 0o600 })
+		}
+		return await closed
+	} catch (error) {
+		if (!ended) child.kill('SIGTERM')
+		const retirement = setTimeout(() => {
+			if (!ended) child.kill('SIGKILL')
+		}, 2000)
+		await closed.catch(() => {})
+		clearTimeout(retirement)
+		throw error
+	} finally {
+		clearTimeout(deadline)
+		process.removeListener('SIGTERM', stop)
+		process.removeListener('SIGINT', stop)
+	}
+}
+
+module.exports = {
+	HOME_URL,
+	NEW_TAB_URL,
+	MARKER_BASE,
+	READY_FILE,
+	bootstrapBrowserHome,
+	browserLaunchArguments,
+	request,
+}
+if (require.main === module)
+	void runBrowser(process.argv.slice(2)).then(
+		(code) => {
+			process.exitCode = code
+		},
+		(error) => {
+			const reason = error instanceof BrowserHomeError ? error.code : 'home-startup-failed'
+			process.stderr.write(`Namzu browser home startup failed: ${reason}\n`)
+			process.exitCode = 1
+		},
+	)