acrylblends 0.7.8 → 0.8.0

package/plugins/acryl-door/src/cli/acryl.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * The door's operator client: what `<app>/.acryl/bin/acryl` runs. It finds the app from the folder it is started in (the nearest
+ * `.acryl/door.json` upward, or `--dir`), never through PATH or a machine-wide registry, so it reaches only the app running from that
+ * folder. The secret is read from that file and sent as a `Bearer` header; it is never printed.
+ *
+ *   acryl brief | look | act <op> ... | plugin list|add|remove|reload | tool list|call | verbs      (--json for the raw value)
+ *   acryl control <...>   the same, the ACRYL Host form (`control snapshot`, `control click`, ... are look and act)
+ *
+ * Exit codes: 0 done, 1 the verb failed (its code and message are printed), 2 a usage error, 3 no running app in this folder.
+ */
+
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readDoorFile, STATE_DIR, DOOR_FILE } from '../host/door-file.ts'
+
+const ACT_OPS = new Set(['click', 'type', 'select', 'press', 'scroll', 'wait'])
+const VALUED = new Set(['--dir', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--tool', '--args'])
+const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--help'])
+
+export class UsageError extends Error {}
+
+export interface Invocation {
+  readonly verb: string
+  readonly args: Record<string, unknown>
+  readonly json: boolean
+  readonly dir: string | undefined
+}
+
+const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
+  brief
+  look [--cursor <n>] [--max-nodes <n>]
+  act click --ref <r>
+  act type --ref <r> --text <t> [--submit] [--no-clear]
+  act select --ref <r> --option <o>
+  act press --key <key> [--ref <r>]
+  act scroll --direction up|down|left|right [--ref <r>] [--amount <px>]
+  act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
+  plugin list | plugin add <folder> | plugin remove <name> | plugin reload
+  tool list | tool call --tool <name> [--args '<json>']
+  verbs`
+
+function integer(values: Map<string, string>, flag: string): number | undefined {
+  const raw = values.get(flag)
+  if (raw === undefined) return undefined
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 0) throw new UsageError(`${flag} must be a non-negative integer`)
+  return value
+}
+
+/** @throws UsageError. */
+export function parseInvocation(argv: readonly string[]): Invocation {
+  const words: string[] = []
+  const values = new Map<string, string>()
+  const set = new Set<string>()
+  for (let at = 0; at < argv.length; at += 1) {
+    const arg = argv[at] as string
+    if (VALUED.has(arg)) {
+      const value = argv[at + 1]
+      if (value === undefined) throw new UsageError(`${arg} needs a value`)
+      values.set(arg, value)
+      at += 1
+    } else if (FLAGS.has(arg)) set.add(arg)
+    else if (arg.startsWith('--')) throw new UsageError(`unknown option ${arg}`)
+    else words.push(arg)
+  }
+  if (set.has('--help')) throw new UsageError(USAGE)
+  if (words[0] === 'control') words.shift()
+  // The ACRYL Host form: `control snapshot` is look, `control click` is act click.
+  if (words[0] === 'snapshot') words[0] = 'look'
+  else if (words[0] !== undefined && ACT_OPS.has(words[0])) words.unshift('act')
+  const [first, second, third] = words
+  const json = set.has('--json')
+  const dir = values.get('--dir')
+  const make = (verb: string, args: Record<string, unknown> = {}): Invocation => ({ verb, args, json, dir })
+  switch (first) {
+    case 'brief': return make('brief')
+    case 'verbs': return make('verbs')
+    case 'look': {
+      const cursor = integer(values, '--cursor')
+      const maxNodes = integer(values, '--max-nodes')
+      return make('look', { ...(cursor === undefined ? {} : { cursor }), ...(maxNodes === undefined ? {} : { maxNodes }) })
+    }
+    case 'act': {
+      if (second === undefined || !ACT_OPS.has(second)) throw new UsageError(`act needs one of ${[...ACT_OPS].join(', ')}\n${USAGE}`)
+      const amount = integer(values, '--amount')
+      const timeoutMs = integer(values, '--timeout-ms')
+      const pick = (flag: string, key: string): Record<string, string> => (values.has(flag) ? { [key]: values.get(flag) as string } : {})
+      return make('act', {
+        op: second,
+        ...pick('--ref', 'ref'), ...pick('--text', 'text'), ...pick('--option', 'option'), ...pick('--key', 'key'),
+        ...pick('--direction', 'direction'), ...pick('--role', 'role'), ...pick('--name', 'name'),
+        ...(amount === undefined ? {} : { amount }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(set.has('--submit') ? { submit: true } : {}),
+        ...(set.has('--no-clear') ? { clear: false } : {}),
+        ...(set.has('--gone') ? { gone: true } : {}),
+      })
+    }
+    case 'plugin': {
+      if (second === 'list' || second === 'reload') return make(`plugin-${second}`)
+      if (second === 'add') { if (third === undefined) throw new UsageError('plugin add needs a folder, e.g. plugin add plugins/pomodoro'); return make('plugin-add', { folder: third }) }
+      if (second === 'remove') { if (third === undefined) throw new UsageError('plugin remove needs a plugin name'); return make('plugin-remove', { name: third }) }
+      throw new UsageError(`plugin needs list, add, remove or reload\n${USAGE}`)
+    }
+    case 'tool': {
+      if (second === 'list') return make('tool-list')
+      if (second === 'call') {
+        const tool = values.get('--tool')
+        if (tool === undefined) throw new UsageError('tool call needs --tool <name>')
+        const raw = values.get('--args')
+        let args: unknown = {}
+        if (raw !== undefined) {
+          try { args = JSON.parse(raw) } catch { throw new UsageError('--args must be JSON') }
+        }
+        return make('tool-call', { tool, args })
+      }
+      throw new UsageError(`tool needs list or call\n${USAGE}`)
+    }
+    default: throw new UsageError(USAGE)
+  }
+}
+
+/** The app folder: `--dir`, or the nearest folder upward from `cwd` that has `.acryl/door.json` (or at least `.acryl/`). */
+export function findApp(cwd: string, dir: string | undefined): string | undefined {
+  if (dir !== undefined) return resolve(cwd, dir)
+  let fallback: string | undefined
+  for (let at = resolve(cwd); ; at = dirname(at)) {
+    if (existsSync(join(at, STATE_DIR, DOOR_FILE))) return at
+    if (fallback === undefined && existsSync(join(at, STATE_DIR))) fallback = at
+    if (dirname(at) === at) return fallback
+  }
+}
+
+export interface Io {
+  readonly cwd: string
+  readonly out: (text: string) => void
+  readonly err: (text: string) => void
+  readonly fetch?: typeof fetch
+}
+
+/** Run one invocation. @returns the exit code. */
+export async function main(argv: readonly string[], io: Io): Promise<number> {
+  let invocation: Invocation
+  try {
+    invocation = parseInvocation(argv)
+  } catch (cause) {
+    if (cause instanceof UsageError) { io.err(`${cause.message}\n`); return 2 }
+    throw cause
+  }
+  const app = findApp(io.cwd, invocation.dir)
+  const file = app === undefined ? undefined : readDoorFile(app)
+  if (app === undefined || file === undefined) {
+    io.err(`no running app${app === undefined ? ` in ${io.cwd} or above it` : ` in ${app}`}: start it (npm run dev) in its folder, then try again\n`)
+    return 3
+  }
+  const request = io.fetch ?? fetch
+  const headers = { authorization: `Bearer ${file.secret}`, 'content-type': 'application/json' }
+  let response: Response
+  try {
+    response = invocation.verb === 'verbs'
+      ? await request(`${file.url}/api/acryl-door/verbs`, { headers })
+      : await request(`${file.url}/api/acryl-door/call`, { method: 'POST', headers, body: JSON.stringify({ verb: invocation.verb, args: invocation.args }) })
+  } catch {
+    io.err(`no running app in ${app}: ${file.url} does not answer (it stopped without removing .acryl/door.json?); start it again\n`)
+    return 3
+  }
+  if (response.status === 403) {
+    io.err(`refused by the app in ${app}: the secret did not match (the app restarted? run the command again)\n`)
+    return 1
+  }
+  const body = await response.json().catch(() => undefined) as { ok?: boolean; value?: unknown; text?: string; code?: string; message?: string; verbs?: unknown } | undefined
+  if (body === undefined) { io.err(`the app answered ${String(response.status)} with no readable body\n`); return 1 }
+  if (invocation.verb === 'verbs') {
+    io.out(invocation.json ? `${JSON.stringify(body.verbs)}\n` : `${(body.verbs as string[]).join('\n')}\n`)
+    return 0
+  }
+  if (body.ok !== true) {
+    io.err(invocation.json ? `${JSON.stringify(body)}\n` : `${body.code ?? 'error'}: ${body.message ?? JSON.stringify(body)}\n`)
+    return 1
+  }
+  io.out(invocation.json ? `${JSON.stringify(body.value)}\n` : `${body.text ?? ''}\n`)
+  return 0
+}
+
+/** True when this file is the program Node was started with (not imported by a test). */
+function isProgram(): boolean {
+  const entry = process.argv[1]
+  if (entry === undefined) return false
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return false
+  }
+}
+
+if (isProgram()) {
+  main(process.argv.slice(2), {
+    cwd: process.cwd(),
+    out: (text) => { process.stdout.write(text) },
+    err: (text) => { process.stderr.write(text) },
+  }).then((code) => { process.exitCode = code }, (cause: unknown) => {
+    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`)
+    process.exitCode = 1
+  })
+}

package/plugins/acryl-door/src/host/api.ts

@@ -0,0 +1,9 @@
+/**
+ * The door's host core for another Host to build its own door on (`acryl-door/host`): the page channel and its routes, and the audit log.
+ * ACRYL's DSH Host uses it in `acryl-agent-control`, with its own tools, approval and secret.
+ */
+
+export { UiChannel, type PageStream } from './channel.ts'
+export { AuditLog, auditPath, type AuditEntry } from './audit.ts'
+export { HEARTBEAT_MS, pageChannelRoutes, type PageRoutesOptions } from './page-routes.ts'
+export { renderSnapshot } from '../page/snapshot-text.ts'

package/plugins/acryl-door/src/host/audit.ts

@@ -0,0 +1,64 @@
+/**
+ * The audit log: one JSON line per door call, append-only, in the app's own `.acryl/audit/` (moved from `acryl-agent-control`, spec 041).
+ *
+ * It is the record of what the agent did to the app. It never holds text the agent typed or values it read,
+ * only which control was touched and how the call ended.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { AuditEntry } from '../page/protocol.ts'
+
+export type { AuditEntry } from '../page/protocol.ts'
+
+const MAX_LOG_BYTES = 5 * 1024 * 1024
+
+/** The audit log below a folder the caller owns (the app's `.acryl/` here; ACRYL's app home for the DSH face). */
+export function auditPath(folder: string): string {
+  return join(folder, 'audit', 'ui-control.jsonl')
+}
+
+export class AuditLog {
+  private readonly path: string
+
+  constructor(path: string) {
+    this.path = path
+  }
+
+  /** Append one line; a failing disk never breaks the tool call. */
+  record(entry: AuditEntry): void {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true })
+      this.rotateIfLarge()
+      const fd = openSync(this.path, 'a', 0o600)
+      try {
+        writeSync(fd, `${JSON.stringify(entry)}\n`)
+      } finally {
+        closeSync(fd)
+      }
+    } catch {
+      // Best effort: the record is important, but the app must keep working.
+    }
+  }
+
+  /** The most recent entries, oldest first. */
+  recent(limit = 100): AuditEntry[] {
+    try {
+      const lines = readFileSync(this.path, 'utf8').split('\n').filter(line => line !== '').slice(-limit)
+      return lines.flatMap((line) => {
+        try { return [JSON.parse(line) as AuditEntry] } catch { return [] }
+      })
+    } catch {
+      return []
+    }
+  }
+
+  private rotateIfLarge(): void {
+    try {
+      if (statSync(this.path).size >= MAX_LOG_BYTES) renameSync(this.path, `${this.path}.1`)
+    } catch {
+      // Nothing to rotate yet.
+    }
+  }
+}
+

package/plugins/acryl-door/src/host/channel.ts

@@ -0,0 +1,142 @@
+/**
+ * The Host's side of the page channel: the connected pages of the app, and calls that go to the current one (moved from
+ * `acryl-agent-control`, spec 041).
+ *
+ * The Host cannot reach into a page, so each page opens one event stream to the Host and answers calls by POST. With several pages open,
+ * the one the user focused last is the one the agent drives. A page that reconnects with the same window id replaces its old stream.
+ */
+
+import {
+  UiControlError,
+  type ChannelToHost,
+  type ChannelToPage,
+  type UiRequest,
+  type UiResult,
+} from '../page/protocol.ts'
+
+/** The slice of a page's stream the channel needs, so tests can supply their own. */
+export interface PageStream {
+  send(data: string): void
+  close(): void
+}
+
+interface Pending {
+  readonly connection: Connection
+  readonly resolve: (value: UiResult) => void
+  readonly reject: (cause: UiControlError) => void
+  readonly timer: NodeJS.Timeout
+  readonly cleanup: () => void
+}
+
+interface Connection {
+  readonly stream: PageStream
+  readonly windowId: string
+  focused: boolean
+  /** Order of last focus (or connection), so the most recent wins. */
+  lastActive: number
+}
+
+/** How long a call may take before it is given up (a wait may take up to 10 seconds itself). */
+const DEFAULT_CALL_TIMEOUT_MS = 30_000
+
+export class UiChannel {
+  private readonly connections = new Map<string, Connection>()
+  private readonly pending = new Map<number, Pending>()
+  private nextId = 1
+  private clock = 0
+  private closed = false
+
+  /**
+   * Register a page's stream. A stream already open for the same window is closed first, and its calls settle as `disconnected`.
+   * @returns the function to call when this stream ends.
+   */
+  attach(windowId: string, focused: boolean, stream: PageStream): () => void {
+    const previous = this.connections.get(windowId)
+    if (previous !== undefined) this.drop(previous, true)
+    const connection: Connection = { stream, windowId, focused, lastActive: ++this.clock }
+    this.connections.set(windowId, connection)
+    return () => { if (this.connections.get(windowId) === connection) this.drop(connection, false) }
+  }
+
+  /** A message a page sent by POST. Only the window that was asked may answer a call, so another page cannot forge a result. */
+  receive(windowId: string, message: ChannelToHost): void {
+    const connection = this.connections.get(windowId)
+    if (connection === undefined) return
+    if (message.t === 'focus') {
+      connection.focused = message.focused
+      if (message.focused) connection.lastActive = ++this.clock
+      return
+    }
+    const entry = this.pending.get(message.id)
+    if (entry === undefined || entry.connection !== connection) return
+    if (message.t === 'result') this.settle(message.id, message.value)
+    else this.settle(message.id, undefined, new UiControlError(message.code, message.message))
+  }
+
+  /** True when at least one page is connected. */
+  get connected(): boolean {
+    return this.connections.size > 0
+  }
+
+  /** The windows currently connected, most recently active first (for diagnostics and tests). */
+  windows(): readonly { windowId: string; focused: boolean }[] {
+    return this.byRecency().map(({ windowId, focused }) => ({ windowId, focused }))
+  }
+
+  /**
+   * Ask the current page to do something.
+   * @throws UiControlError `no-window`, `timeout`, `aborted`, `unloaded`, `disconnected`, or whatever the page refused with.
+   */
+  call(request: UiRequest, options: { signal?: AbortSignal; timeoutMs?: number } = {}): Promise<UiResult> {
+    if (this.closed) return Promise.reject(new UiControlError('unloaded', 'the door was unloaded'))
+    const target = this.byRecency()[0]
+    if (target === undefined) return Promise.reject(new UiControlError('no-window', 'no page of the app is open to control'))
+    const signal = options.signal
+    if (signal?.aborted === true) return Promise.reject(new UiControlError('aborted', 'the call was cancelled'))
+    const id = this.nextId
+    this.nextId += 1
+    return new Promise<UiResult>((resolve, reject) => {
+      const timer = setTimeout(() => { this.settle(id, undefined, new UiControlError('timeout', 'the page did not answer in time')) }, options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS)
+      const onAbort = (): void => { this.settle(id, undefined, new UiControlError('aborted', 'the call was cancelled')) }
+      signal?.addEventListener('abort', onAbort, { once: true })
+      this.pending.set(id, { connection: target, resolve, reject, timer, cleanup: () => { signal?.removeEventListener('abort', onAbort) } })
+      const frame: ChannelToPage = { t: 'call', id, request }
+      try {
+        target.stream.send(JSON.stringify(frame))
+      } catch {
+        this.settle(id, undefined, new UiControlError('disconnected', 'the page could not be reached'))
+      }
+    })
+  }
+
+  /** Close every page's stream and settle every pending call as `unloaded`. */
+  close(): void {
+    this.closed = true
+    for (const id of [...this.pending.keys()]) this.settle(id, undefined, new UiControlError('unloaded', 'the door was unloaded'))
+    for (const connection of [...this.connections.values()]) connection.stream.close()
+    this.connections.clear()
+  }
+
+  private byRecency(): Connection[] {
+    return [...this.connections.values()].sort((a, b) => b.lastActive - a.lastActive)
+  }
+
+  /** Forget a connection; its calls in flight settle as `disconnected` at once rather than waiting for their timeout. */
+  private drop(connection: Connection, closeStream: boolean): void {
+    this.connections.delete(connection.windowId)
+    for (const [id, entry] of [...this.pending]) {
+      if (entry.connection === connection) this.settle(id, undefined, new UiControlError('disconnected', 'the page went away before it answered'))
+    }
+    if (closeStream) connection.stream.close()
+  }
+
+  private settle(id: number, value: UiResult | undefined, failure?: UiControlError): void {
+    const entry = this.pending.get(id)
+    if (entry === undefined) return
+    this.pending.delete(id)
+    clearTimeout(entry.timer)
+    entry.cleanup()
+    if (failure !== undefined) entry.reject(failure)
+    else if (value !== undefined) entry.resolve(value)
+  }
+}

package/plugins/acryl-door/src/host/chat-tools.ts

@@ -0,0 +1,39 @@
+/**
+ * The door in the built-in chat: each verb registered in the app's `tools` registry (the one the chat's agent reads), as
+ * `door_<verb>`. A tool answers the verb's text, what an agent reads in a terminal; a failed verb throws with its code, as the operator
+ * client prints it.
+ */
+
+import { UiControlError } from '../page/protocol.ts'
+import { DoorError, type Door, type ToolsPort } from './door.ts'
+import { chatToolName, VERB_SPECS, VERBS } from './verbs.ts'
+
+/** Register every verb. @returns the function that removes them all; it also aborts the calls still running. */
+export function registerChatTools(tools: ToolsPort, door: Door): () => void {
+  const running = new AbortController()
+  const removers: Array<() => void> = []
+  const removeAll = (): void => {
+    running.abort()
+    for (const remove of removers.splice(0).reverse()) remove()
+  }
+  try {
+    for (const verb of VERBS) {
+      removers.push(tools.register(chatToolName(verb), {
+        description: VERB_SPECS[verb].description,
+        run: async (input: unknown) => {
+          try {
+            return (await door.run(verb, input ?? {}, running.signal)).text
+          } catch (cause) {
+            if (cause instanceof DoorError || cause instanceof UiControlError) throw new Error(`${cause.code}: ${cause.message}`, { cause })
+            throw cause
+          }
+        },
+      }))
+    }
+  } catch (cause) {
+    // A name already taken: leave nothing half registered.
+    removeAll()
+    throw cause
+  }
+  return removeAll
+}

package/plugins/acryl-door/src/host/door-file.ts

@@ -0,0 +1,94 @@
+/**
+ * The door's connection file, `<app>/.acryl/door.json`: where the running app listens and this run's secret, for the operator client in
+ * the same folder. The secret is never on a command line or in an environment variable another process can read.
+ *
+ * Protection: on macOS and Linux the folder is `0700` and the file `0600`, so only the OS user who started the app can read it. On
+ * Windows file modes mean nothing; the file is protected by where it lives, the app folder in the user's profile, whose ACL gives access
+ * to that user, SYSTEM and Administrators only. The door does not widen it. The folder also carries its own `.gitignore` of `*`, so
+ * `git add -A` never stages the secret even in an app whose `.gitignore` lacks the `.acryl/` line.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The folder of the door's state below the app folder. */
+export const STATE_DIR = '.acryl'
+export const DOOR_FILE = 'door.json'
+
+export interface DoorFile {
+  readonly version: 1
+  /** The origin the operator reaches, on a loopback address. */
+  readonly url: string
+  readonly secret: string
+  /** The process that wrote it; a file whose process is gone is stale. */
+  readonly pid: number
+}
+
+export function stateDir(appRoot: string): string {
+  return join(appRoot, STATE_DIR)
+}
+
+export function doorFilePath(appRoot: string): string {
+  return join(stateDir(appRoot), DOOR_FILE)
+}
+
+/** A fresh secret for this run; a restart rotates it. */
+export function newSecret(): string {
+  return randomBytes(24).toString('hex')
+}
+
+/** The state folder, private, with its own `.gitignore`. */
+export function ensureStateDir(appRoot: string): string {
+  const dir = stateDir(appRoot)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  if (process.platform !== 'win32') chmodSync(dir, 0o700)
+  const ignore = join(dir, '.gitignore')
+  if (!existsSync(ignore)) writeFileSync(ignore, '# The door\'s state: this run\'s secret and the audit. Never commit it.\n*\n')
+  return dir
+}
+
+/** The connection file as written, or undefined when there is none or it does not parse. */
+export function readDoorFile(appRoot: string): DoorFile | undefined {
+  try {
+    const value = JSON.parse(readFileSync(doorFilePath(appRoot), 'utf8')) as Partial<DoorFile>
+    if (value.version === 1 && typeof value.url === 'string' && typeof value.secret === 'string' && typeof value.pid === 'number') return value as DoorFile
+  } catch {
+    // Missing or unreadable: there is no door to reach.
+  }
+  return undefined
+}
+
+/** True while the process is alive (a process of another user still counts: `EPERM`). */
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/**
+ * Write this run's connection file, replacing a stale one.
+ * @throws when another live process already serves this folder's door: two apps from one folder would race for one file.
+ */
+export function writeDoorFile(appRoot: string, url: string, secret: string): string {
+  const dir = ensureStateDir(appRoot)
+  const existing = readDoorFile(appRoot)
+  if (existing !== undefined && existing.pid !== process.pid && alive(existing.pid)) {
+    throw new Error(`acryl-door: another process (pid ${String(existing.pid)}) serves the door of ${appRoot}; stop it first`)
+  }
+  const file = doorFilePath(appRoot)
+  const temporary = join(dir, `${DOOR_FILE}.${String(process.pid)}.tmp`)
+  const content: DoorFile = { version: 1, url, secret, pid: process.pid }
+  writeFileSync(temporary, `${JSON.stringify(content)}\n`, { mode: 0o600 })
+  if (process.platform !== 'win32') chmodSync(temporary, 0o600)
+  renameSync(temporary, file)
+  return file
+}
+
+/** Remove the connection file, only when it is this run's: a newer run's file is left alone. */
+export function removeDoorFile(appRoot: string, secret: string): void {
+  if (readDoorFile(appRoot)?.secret === secret) rmSync(doorFilePath(appRoot), { force: true })
+}