conductor-remote 1.7.0 → 1.8.0

package/README.md

@@ -23,6 +23,15 @@ npm i -g conductor-remote
 conductor-remote service install    # run on login; prints your phone URL
 ```
 
+**Private tailnet only?** Pass `--expose tailnet` to skip public Funnel, so the URL
+is reachable only from devices logged into your tailnet:
+
+```bash
+conductor-remote service install --expose tailnet
+```
+
+The choice is remembered across re-deploys; see **Reachability** below for the trade-off.
+
 Or the one-liner (checks Node, offers `brew install node` if missing, installs,
 registers the service):
 
@@ -35,12 +44,24 @@ on your machine, so `npm i -g` finishes in about a second. `service install`
 prints a phone URL with an embedded token; open it and **Add to Home Screen**.
 Manage the service with `conductor-remote service status|restart|uninstall`.
 
-**Reachability (`EXPOSE`).** By default the URL is exposed publicly via
+**Install flags.** `service install` takes flags for the install-time knobs (each
+also settable via the env var in brackets — the flag wins when both are given).
+Run `conductor-remote --help` for the full list. The common ones:
+
+| Flag | Env | Purpose |
+| --- | --- | --- |
+| `--expose public\|tailnet` | `EXPOSE` | Reachability (public Funnel default, or tailnet-only) |
+| `--port <n>` | `RELAY_PORT` | Listen port (default `8787`) |
+| `--token <secret>` | `RELAY_TOKEN` | Pin the shared secret (default: generated + persisted) |
+| `--write-strategy <s>` | `WRITE_STRATEGY` | `applescript` (default) or `sidecar` |
+
+**Reachability (`--expose`).** By default the URL is exposed publicly via
 [Tailscale Funnel](https://tailscale.com/kb/1223/funnel) — reachable from any
 browser, gated by the embedded 128-bit token (so the phone needs **no** Tailscale
 app). Funnel must be enabled once for your tailnet (Admin console). To keep it
 tailnet-only instead (devices logged into your tailnet, via `tailscale serve`),
-install with `EXPOSE=tailnet`. The choice is remembered across re-deploys.
+install with `--expose tailnet` (or `EXPOSE=tailnet`). The choice is remembered
+across re-deploys.
 
 ## Architecture
 
@@ -131,16 +152,21 @@ so the home-screen URL stays valid across restarts and reboots. Logs land in
 and the AppleScript write path needs Accessibility permission granted to that
 `node` binary (System Settings ▸ Privacy & Security ▸ Accessibility).
 
-### Config (env)
-
-| Var | Default | Purpose |
-| --- | --- | --- |
-| `RELAY_PORT` | `8787` | Listen port |
-| `RELAY_HOST` | auto (Tailscale `100.x`, else `127.0.0.1`) | Bind address |
-| `RELAY_TOKEN` | persisted (auto-generated, reused across restarts) | Override the shared secret |
-| `WRITE_STRATEGY` | `applescript` | `applescript` (focused session) or `sidecar` (precise per-session — see below) |
-| `CONDUCTOR_DB` | `~/Library/Application Support/com.conductor.app/conductor.db` | State DB |
-| `CONDUCTOR_WORKSPACES` | `~/conductor/workspaces` | Worktree root |
+### Config (env / flags)
+
+Each knob is an env var (honored by `yarn start` and `service install`) and, for
+`service install`, the CLI flag in the second column. A flag wins over the ambient
+env. `EXPOSE`/`--expose` is documented under Install above.
+
+| Var | Flag | Default | Purpose |
+| --- | --- | --- | --- |
+| `RELAY_PORT` | `--port` | `8787` | Listen port |
+| `RELAY_HOST` | `--host` | auto (Tailscale `100.x`, else `127.0.0.1`) | Bind address |
+| `RELAY_TOKEN` | `--token` | persisted (auto-generated, reused across restarts) | Override the shared secret |
+| `WRITE_STRATEGY` | `--write-strategy` | `applescript` | `applescript` (focused session) or `sidecar` (precise per-session — see below) |
+| `AUTO_UPDATE` | `--auto-update` | `auto` | Self-update mode: `auto` / `check` / `off` |
+| `CONDUCTOR_DB` | `--db` | `~/Library/Application Support/com.conductor.app/conductor.db` | State DB |
+| `CONDUCTOR_WORKSPACES` | `--workspaces` | `~/conductor/workspaces` | Worktree root |
 
 The token is auto-generated once and persisted, so the home-screen icon keeps
 working across restarts without any env var. To pin a specific secret (e.g. to

package/bin/cli.js

@@ -37,7 +37,17 @@ function usage() {
 			'  conductor-remote service <subcommand>    manage the login LaunchAgent',
 			'      install | uninstall | restart | status',
 			'',
-			'Env: RELAY_HOST, RELAY_PORT, RELAY_TOKEN, WRITE_STRATEGY, AUTO_UPDATE, CONDUCTOR_DB, CONDUCTOR_WORKSPACES'
+			'Install flags (each also settable via the env var in [brackets]):',
+			'  --expose public|tailnet   reachability: public Funnel (default) or tailnet-only  [EXPOSE]',
+			'  --port <n>                listen port (default 8787)                             [RELAY_PORT]',
+			'  --host <addr>             bind address (default 127.0.0.1)                       [RELAY_HOST]',
+			'  --token <secret>          pin the shared secret (default: generated + persisted) [RELAY_TOKEN]',
+			'  --write-strategy <s>      applescript (default) | sidecar                        [WRITE_STRATEGY]',
+			'  --auto-update <mode>      auto (default) | check | off                           [AUTO_UPDATE]',
+			'  --db <path>               Conductor state DB                                     [CONDUCTOR_DB]',
+			'  --workspaces <path>       worktree root                                          [CONDUCTOR_WORKSPACES]',
+			'',
+			'e.g.  conductor-remote service install --expose tailnet --port 9000'
 		].join('\n')
 	)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "conductor-remote",
-	"version": "1.7.0",
+	"version": "1.8.0",
 	"type": "module",
 	"packageManager": "yarn@4.15.0",
 	"description": "Phone control panel for local Conductor agents. Reads ride SQLite + git; prompts ride Conductor's own dispatch path.",

package/scripts/service.ts

@@ -21,6 +21,45 @@ const logDir = path.join(os.homedir(), 'Library', 'Logs', 'conductor-remote')
 const uid = process.getuid?.() ?? 0
 const domain = `gui/${uid}`
 
+/**
+ * Install-time knobs are accepted as documented CLI flags OR the matching env var — a flag wins over the
+ * ambient env. Parsed flags are folded back into process.env so everything downstream (and the plist we
+ * bake) keeps reading a single source. Runs before any module-level env read below.
+ */
+const FLAG_ENV: Record<string, string> = {
+	'--expose': 'EXPOSE',
+	'--port': 'RELAY_PORT',
+	'--host': 'RELAY_HOST',
+	'--token': 'RELAY_TOKEN',
+	'--write-strategy': 'WRITE_STRATEGY',
+	'--auto-update': 'AUTO_UPDATE',
+	'--db': 'CONDUCTOR_DB',
+	'--workspaces': 'CONDUCTOR_WORKSPACES'
+}
+
+function applyFlags(argv: string[]): void {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		if (!arg.startsWith('--')) continue
+		const eq = arg.indexOf('=')
+		const name = eq === -1 ? arg : arg.slice(0, eq)
+		const envKey = FLAG_ENV[name]
+		if (!envKey) {
+			console.error(`unknown flag: ${name}\n  known: ${Object.keys(FLAG_ENV).join(', ')}`)
+			process.exit(1)
+		}
+		const value = eq === -1 ? argv[++i] : arg.slice(eq + 1)
+		if (value === undefined) {
+			console.error(`flag ${name} needs a value (e.g. ${name} <value>)`)
+			process.exit(1)
+		}
+		process.env[envKey] = value
+	}
+}
+
+// argv[2] is the subcommand (see bottom); flags follow it.
+applyFlags(process.argv.slice(3))
+
 function xml(s: string): string {
 	return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
 }
@@ -95,6 +134,8 @@ function buildPlist(): string {
 	if (process.env.RELAY_HOST) envEntries.push(['RELAY_HOST', process.env.RELAY_HOST])
 	if (process.env.RELAY_PORT) envEntries.push(['RELAY_PORT', process.env.RELAY_PORT])
 	if (process.env.AUTO_UPDATE) envEntries.push(['AUTO_UPDATE', process.env.AUTO_UPDATE])
+	if (process.env.CONDUCTOR_DB) envEntries.push(['CONDUCTOR_DB', process.env.CONDUCTOR_DB])
+	if (process.env.CONDUCTOR_WORKSPACES) envEntries.push(['CONDUCTOR_WORKSPACES', process.env.CONDUCTOR_WORKSPACES])
 	const envXml = envEntries.map(([k, v]) => `\t\t<key>${xml(k)}</key>\n\t\t<string>${xml(v)}</string>`).join('\n')
 	return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -132,20 +173,36 @@ function distBuilt(): boolean {
 	return fs.existsSync(path.join(projectDir, 'dist', 'index.html'))
 }
 
+function tokenStorePath(): string {
+	return path.join(os.homedir(), 'Library', 'Application Support', 'conductor-remote', 'token')
+}
+
 /** Read the persisted token (or env override) purely to print the phone URL — never mints one. */
 function currentToken(): string | null {
 	if (process.env.RELAY_TOKEN) return process.env.RELAY_TOKEN
 	try {
-		return (
-			fs
-				.readFileSync(path.join(os.homedir(), 'Library', 'Application Support', 'conductor-remote', 'token'), 'utf8')
-				.trim() || null
-		)
+		return fs.readFileSync(tokenStorePath(), 'utf8').trim() || null
 	} catch {
 		return null
 	}
 }
 
+/**
+ * A pinned token (`--token` / `RELAY_TOKEN`) is persisted to the token file, not baked into the plist —
+ * the launchd daemon has no such env, so it resolves the secret from this file (config.ts ▸ resolveToken).
+ * Writing it here keeps the daemon, the printed URL, and later `status` all in agreement.
+ */
+function persistPinnedToken(): void {
+	const token = process.env.RELAY_TOKEN
+	if (!token) return
+	try {
+		fs.mkdirSync(path.dirname(tokenStorePath()), { recursive: true })
+		fs.writeFileSync(tokenStorePath(), token, { mode: 0o600 })
+	} catch (err) {
+		console.info(`  ⚠ could not persist --token (${err instanceof Error ? err.message : err})`)
+	}
+}
+
 const RELAY_PORT = process.env.RELAY_PORT ?? '8787'
 
 /** Locate the tailscale CLI: PATH first, then the common macOS install locations. Null if absent. */
@@ -354,6 +411,7 @@ function install(): void {
 		console.error('✗ dist/ not built. Run `yarn build` first (or use `yarn deploy`, which builds).')
 		process.exit(1)
 	}
+	persistPinnedToken()
 	fs.mkdirSync(path.dirname(plistPath), { recursive: true })
 	fs.mkdirSync(logDir, { recursive: true })
 	fs.writeFileSync(plistPath, buildPlist())
@@ -418,6 +476,10 @@ switch (cmd) {
 		status()
 		break
 	default:
-		console.error(`unknown command: ${cmd}\nusage: service.ts <install|uninstall|restart|status>`)
+		console.error(
+			`unknown command: ${cmd}\n` +
+				'usage: service.ts <install|uninstall|restart|status> [flags]\n' +
+				`  flags (install): ${Object.keys(FLAG_ENV).join(', ')}`
+		)
 		process.exit(1)
 }