@sixb/cli 0.1.21 → 0.1.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/README.md +18 -3
  2. package/dist/commands/api.d.ts.map +1 -1
  3. package/dist/commands/app.d.ts.map +1 -1
  4. package/dist/commands/build.d.ts.map +1 -1
  5. package/dist/commands/check.d.ts.map +1 -1
  6. package/dist/commands/db-migrate.d.ts.map +1 -1
  7. package/dist/commands/deploy.d.ts.map +1 -1
  8. package/dist/commands/desktop.d.ts +15 -0
  9. package/dist/commands/desktop.d.ts.map +1 -0
  10. package/dist/commands/dev-runner.d.ts +4 -0
  11. package/dist/commands/dev-runner.d.ts.map +1 -1
  12. package/dist/commands/dev.d.ts.map +1 -1
  13. package/dist/commands/init.d.ts.map +1 -1
  14. package/dist/commands/lake-check.d.ts.map +1 -1
  15. package/dist/commands/lake-cleanup.d.ts.map +1 -1
  16. package/dist/commands/login.d.ts.map +1 -1
  17. package/dist/commands/logout.d.ts.map +1 -1
  18. package/dist/commands/orchestrator.d.ts.map +1 -1
  19. package/dist/commands/profile.d.ts.map +1 -1
  20. package/dist/commands/rules.d.ts.map +1 -1
  21. package/dist/commands/scheduler.d.ts.map +1 -1
  22. package/dist/commands/service-account.d.ts.map +1 -1
  23. package/dist/commands/status.d.ts.map +1 -1
  24. package/dist/commands/token.d.ts.map +1 -1
  25. package/dist/commands/typegen.d.ts.map +1 -1
  26. package/dist/commands/worker-group.d.ts +2 -0
  27. package/dist/commands/worker-group.d.ts.map +1 -1
  28. package/dist/commands/worker.d.ts +2 -0
  29. package/dist/commands/worker.d.ts.map +1 -1
  30. package/dist/lib/command-line.d.ts +22 -2
  31. package/dist/lib/command-line.d.ts.map +1 -1
  32. package/dist/lib/deploy-release.d.ts +3 -1
  33. package/dist/lib/deploy-release.d.ts.map +1 -1
  34. package/dist/lib/desktop.d.ts +26 -0
  35. package/dist/lib/desktop.d.ts.map +1 -0
  36. package/dist/lib/dev-messages.d.ts +43 -0
  37. package/dist/lib/dev-messages.d.ts.map +1 -0
  38. package/dist/lib/dev-supervisor.d.ts +27 -0
  39. package/dist/lib/dev-supervisor.d.ts.map +1 -1
  40. package/dist/lib/open-url.d.ts +3 -0
  41. package/dist/lib/open-url.d.ts.map +1 -0
  42. package/dist/lib/role-lifecycle.d.ts.map +1 -1
  43. package/dist/lib/runtime.d.ts +2 -0
  44. package/dist/lib/runtime.d.ts.map +1 -1
  45. package/dist/lib/worker-concurrency.d.ts +11 -0
  46. package/dist/lib/worker-concurrency.d.ts.map +1 -1
  47. package/dist/lib/worker-registry.d.ts +2 -0
  48. package/dist/lib/worker-registry.d.ts.map +1 -1
  49. package/dist/ui/deploy-screens.d.ts +48 -0
  50. package/dist/ui/deploy-screens.d.ts.map +1 -0
  51. package/dist/ui/index.d.ts +28 -244
  52. package/dist/ui/index.d.ts.map +1 -1
  53. package/dist/ui/layout.d.ts +65 -0
  54. package/dist/ui/layout.d.ts.map +1 -0
  55. package/dist/ui/live/ansi.d.ts +8 -0
  56. package/dist/ui/live/ansi.d.ts.map +1 -0
  57. package/dist/ui/live/can-run-live.d.ts +6 -0
  58. package/dist/ui/live/can-run-live.d.ts.map +1 -0
  59. package/dist/ui/live/components.d.ts +17 -0
  60. package/dist/ui/live/components.d.ts.map +1 -0
  61. package/dist/ui/live/deploy.d.ts +22 -0
  62. package/dist/ui/live/deploy.d.ts.map +1 -0
  63. package/dist/ui/live/dev.d.ts +47 -0
  64. package/dist/ui/live/dev.d.ts.map +1 -0
  65. package/dist/ui/live/prompt.d.ts +30 -0
  66. package/dist/ui/live/prompt.d.ts.map +1 -0
  67. package/dist/ui/live/session.d.ts +27 -0
  68. package/dist/ui/live/session.d.ts.map +1 -0
  69. package/dist/ui/screens.d.ts +136 -0
  70. package/dist/ui/screens.d.ts.map +1 -0
  71. package/dist/ui/theme.d.ts +58 -0
  72. package/dist/ui/theme.d.ts.map +1 -0
  73. package/package.json +19 -18
  74. package/src/commands/{api.tsx → api.ts} +18 -27
  75. package/src/commands/{app.tsx → app.ts} +14 -18
  76. package/src/commands/build.ts +70 -0
  77. package/src/commands/{check.tsx → check.ts} +27 -18
  78. package/src/commands/db-migrate.ts +32 -0
  79. package/src/commands/{deploy.tsx → deploy.ts} +109 -102
  80. package/src/commands/desktop.ts +71 -0
  81. package/src/commands/{dev-runner.tsx → dev-runner.ts} +67 -33
  82. package/src/commands/{init.tsx → init.ts} +19 -8
  83. package/src/commands/lake-check.ts +36 -0
  84. package/src/commands/{lake-cleanup.tsx → lake-cleanup.ts} +17 -12
  85. package/src/commands/{login.tsx → login.ts} +36 -30
  86. package/src/commands/{logout.tsx → logout.ts} +5 -5
  87. package/src/commands/{orchestrator.tsx → orchestrator.ts} +15 -28
  88. package/src/commands/{profile.tsx → profile.ts} +38 -19
  89. package/src/commands/{rules.tsx → rules.ts} +15 -24
  90. package/src/commands/{scheduler.tsx → scheduler.ts} +14 -27
  91. package/src/commands/{service-account.tsx → service-account.ts} +37 -39
  92. package/src/commands/{status.tsx → status.ts} +8 -8
  93. package/src/commands/{token.tsx → token.ts} +19 -20
  94. package/src/commands/typegen.ts +18 -0
  95. package/src/commands/{worker-group.tsx → worker-group.ts} +40 -29
  96. package/src/commands/{worker.tsx → worker.ts} +30 -22
  97. package/src/index.tsx +22 -1
  98. package/src/lib/command-line.ts +108 -57
  99. package/src/lib/deploy-release.ts +17 -1
  100. package/src/lib/desktop.ts +52 -0
  101. package/src/lib/dev-messages.ts +44 -0
  102. package/src/lib/dev-supervisor.ts +132 -12
  103. package/src/lib/open-url.ts +15 -0
  104. package/src/lib/role-lifecycle.ts +2 -3
  105. package/src/lib/runtime.ts +4 -0
  106. package/src/lib/worker-concurrency.ts +31 -0
  107. package/src/lib/worker-registry.ts +4 -0
  108. package/src/ui/README.md +54 -0
  109. package/src/ui/deploy-screens.ts +360 -0
  110. package/src/ui/index.ts +158 -0
  111. package/src/ui/layout.ts +245 -0
  112. package/src/ui/live/ansi.ts +103 -0
  113. package/src/ui/live/can-run-live.ts +9 -0
  114. package/src/ui/live/components.tsx +81 -0
  115. package/src/ui/live/deploy.tsx +170 -0
  116. package/src/ui/live/dev.tsx +522 -0
  117. package/src/ui/live/prompt.tsx +205 -0
  118. package/src/ui/live/session.ts +103 -0
  119. package/src/ui/screens.ts +490 -0
  120. package/src/ui/theme.ts +122 -0
  121. package/dist/lib/role-view.d.ts +0 -21
  122. package/dist/lib/role-view.d.ts.map +0 -1
  123. package/src/commands/build.tsx +0 -65
  124. package/src/commands/db-migrate.tsx +0 -30
  125. package/src/commands/lake-check.tsx +0 -33
  126. package/src/commands/typegen.tsx +0 -18
  127. package/src/lib/role-view.ts +0 -49
  128. package/src/ui/index.tsx +0 -1398
  129. /package/src/commands/{dev.tsx → dev.ts} +0 -0
@@ -1,11 +1,72 @@
1
1
  import { spawn } from "node:child_process"
2
2
  import { dirname, resolve } from "node:path"
3
3
  import type { DevOptions } from "../commands/dev-runner"
4
+ import { canRunLive } from "../ui/live/can-run-live"
5
+ import { loadDesktop } from "./desktop"
6
+ import { DEV_UI_ENV, type DevChildMessage } from "./dev-messages"
4
7
  import { watchDevSource } from "./dev-watch"
8
+ import { errorMessage } from "./errors"
9
+
10
+ /**
11
+ * Where the supervisor's news goes. A terminal gets the live footer (`ui/live/dev.tsx`), which
12
+ * draws the dev process's output itself; anything else gets the `[SixbDev]` lines, and the dev
13
+ * process prints its own screens.
14
+ */
15
+ export interface DevReporter {
16
+ /** `pipe` when the reporter writes the dev process's output; `inherit` lets it print. */
17
+ readonly output: "inherit" | "pipe"
18
+ /** A line the dev process wrote, when `output` is `pipe`. */
19
+ line(text: string): void
20
+ message(message: DevChildMessage, pid: number | undefined): void
21
+ restarting(filename: string | undefined): void
22
+ exited(code: number | null): void
23
+ timedOut(): void
24
+ error(text: string): void
25
+ stopping(): void
26
+ stop(): Promise<void>
27
+ }
28
+
29
+ export interface DevControls {
30
+ /** Restarts the dev process now, as a source change would. */
31
+ restart(): void
32
+ /** Stops `sixb dev`, as ctrl+c would. */
33
+ quit(): void
34
+ }
35
+
36
+ /** The lines `sixb dev` prints where no live footer can be drawn. */
37
+ export function plainDevReporter(root: string): DevReporter {
38
+ return {
39
+ output: "inherit",
40
+ line(text) {
41
+ console.log(text)
42
+ },
43
+ message(message, pid) {
44
+ if (message.type === "ready") console.log(`[SixbDev] Ready (pid ${pid}). Watching ${root}`)
45
+ },
46
+ restarting(filename) {
47
+ console.log(`[SixbDev] Source changed${filename ? `: ${filename}` : ""}. Restarting…`)
48
+ },
49
+ exited(code) {
50
+ console.error(`[SixbDev] Dev process exited (${code}). Waiting for source changes.`)
51
+ },
52
+ timedOut() {
53
+ console.error("[SixbDev] Startup timed out. Edit a source file to retry.")
54
+ },
55
+ error(text) {
56
+ console.error(`[SixbDev] ${text}`)
57
+ },
58
+ stopping() {},
59
+ async stop() {},
60
+ }
61
+ }
5
62
 
6
63
  /** The parent never imports project modules: every generation gets a fresh module graph. */
7
64
  export async function runDevSupervisor(options: DevOptions): Promise<void> {
8
65
  const root = dirname(resolve(options.entry ?? "sixb.config.ts"))
66
+ // Loaded first, so a project without the package hears so before the dev server starts.
67
+ const desktop = options.desktop ? await loadDesktop(root) : null
68
+ // Opened once the app is first served, and kept open across restarts: the app reloads itself.
69
+ let desktopWindow: Promise<{ close(): void } | null> | null = null
9
70
  let child: { process: ReturnType<typeof spawn>; exited: Promise<number | null> } | null = null
10
71
  let stopping = false
11
72
  let restarting = false
@@ -19,6 +80,21 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
19
80
  const finished = new Promise<void>((resolve) => {
20
81
  complete = resolve
21
82
  })
83
+ const controls: DevControls = {
84
+ restart() {
85
+ if (stopping) return
86
+ reporter.restarting(undefined)
87
+ pending = true
88
+ clearTimeout(timer)
89
+ void restart().catch(fail)
90
+ },
91
+ quit() {
92
+ requestShutdown()
93
+ },
94
+ }
95
+ const reporter: DevReporter = canRunLive()
96
+ ? await (await import("../ui/live/dev")).startDevFooter({ root, controls })
97
+ : plainDevReporter(root)
22
98
  function terminate(current: NonNullable<typeof child>, signal: NodeJS.Signals) {
23
99
  try {
24
100
  if (process.platform !== "win32" && current.process.pid) {
@@ -41,7 +117,7 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
41
117
  // only on the deadline (or after exit) to reap any compiler/sandbox descendants too.
42
118
  current.process.kill("SIGTERM")
43
119
  const deadline = setTimeout(() => {
44
- console.error("[SixbDev] Shutdown timed out; terminating the dev process.")
120
+ reporter.error("Shutdown timed out; terminating the dev process.")
45
121
  terminate(current, "SIGKILL")
46
122
  }, 10_000)
47
123
  try {
@@ -73,10 +149,15 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
73
149
  SIXB_DEV_CHILD: "1",
74
150
  SIXB_DEV_GENERATION: crypto.randomUUID(),
75
151
  SIXB_DEV_READY: "",
152
+ [DEV_UI_ENV]: reporter.output === "pipe" ? "footer" : "",
76
153
  },
77
154
  detached: process.platform !== "win32",
78
- stdio: ["ignore", "inherit", "inherit", "ipc"],
155
+ stdio: ["ignore", reporter.output, reporter.output, "ipc"],
79
156
  })
157
+ if (reporter.output === "pipe") {
158
+ forwardLines(proc.stdout, reporter)
159
+ forwardLines(proc.stderr, reporter)
160
+ }
80
161
  const current = {
81
162
  process: proc,
82
163
  exited: new Promise<number | null>((resolve, reject) => {
@@ -86,18 +167,30 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
86
167
  }
87
168
  proc.on("message", (message: unknown) => {
88
169
  if (child !== current || !message || typeof message !== "object") return
89
- if ("type" in message && message.type === "ready") {
170
+ if (!("type" in message)) return
171
+ reporter.message(message as DevChildMessage, proc.pid)
172
+ if (message.type === "ready") {
90
173
  clearTimeout(startupTimer)
91
174
  appWatched = "watchesApp" in message && message.watchesApp === true
92
- console.log(`[SixbDev] Ready (pid ${proc.pid}). Watching ${root}`)
93
- } else if ("type" in message && message.type === "startup-error") {
175
+ const app = servedApp(message)
176
+ if (desktop && app && !desktopWindow) {
177
+ desktopWindow = desktop
178
+ .openDesktopApp({ projectRoot: root, appUrl: app.url, apiOrigin: app.apiOrigin })
179
+ .catch((error: unknown) => {
180
+ reporter.error(`Could not open the desktop window: ${errorMessage(error)}`)
181
+ // The next generation to come up tries again.
182
+ desktopWindow = null
183
+ return null
184
+ })
185
+ }
186
+ } else if (message.type === "startup-error") {
94
187
  appWatched = false
95
188
  }
96
189
  })
97
190
  child = current
98
191
  startupTimer = setTimeout(() => {
99
192
  if (child === current) {
100
- console.error("[SixbDev] Startup timed out. Edit a source file to retry.")
193
+ reporter.timedOut()
101
194
  terminate(current, "SIGKILL")
102
195
  }
103
196
  }, 60_000)
@@ -108,9 +201,7 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
108
201
  clearTimeout(startupTimer)
109
202
  child = null
110
203
  appWatched = false
111
- if (!stopping && !restarting) {
112
- console.error(`[SixbDev] Dev process exited (${code}). Waiting for source changes.`)
113
- }
204
+ if (!stopping && !restarting) reporter.exited(code)
114
205
  })
115
206
  .catch(fail)
116
207
  }
@@ -127,7 +218,7 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
127
218
  pending = true
128
219
  clearTimeout(timer)
129
220
  timer = setTimeout(() => {
130
- console.log(`[SixbDev] Source changed${filename ? `: ${filename}` : ""}. Restarting…`)
221
+ reporter.restarting(filename)
131
222
  void restart().catch(fail)
132
223
  }, 150)
133
224
  },
@@ -138,7 +229,11 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
138
229
  if (stopping) return
139
230
  stopping = true
140
231
  clearTimeout(timer)
232
+ reporter.stopping()
141
233
  try {
234
+ // First, or the window says the app is unreachable as the server stops. Not awaited: a window
235
+ // still being set up closes once it opens, and does not hold up the rest of the shutdown.
236
+ void desktopWindow?.then((opened) => opened?.close())
142
237
  await watcher.close()
143
238
  await stopChild()
144
239
  } finally {
@@ -147,10 +242,10 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
147
242
  }
148
243
 
149
244
  function fail(error: unknown) {
150
- console.error("[SixbDev]", error)
245
+ reporter.error(errorMessage(error))
151
246
  process.exitCode = 1
152
247
  void shutdown().catch((shutdownError) =>
153
- console.error("[SixbDev] Shutdown failed:", shutdownError)
248
+ reporter.error(`Shutdown failed: ${errorMessage(shutdownError)}`)
154
249
  )
155
250
  }
156
251
 
@@ -167,5 +262,30 @@ export async function runDevSupervisor(options: DevOptions): Promise<void> {
167
262
  process.off("SIGINT", requestShutdown)
168
263
  process.off("SIGTERM", requestShutdown)
169
264
  await shutdown()
265
+ await reporter.stop()
170
266
  }
171
267
  }
268
+
269
+ /** Hands the reporter each whole line a stream writes. */
270
+ function forwardLines(stream: NodeJS.ReadableStream | null, reporter: DevReporter): void {
271
+ if (!stream) return
272
+ let buffered = ""
273
+ stream.setEncoding("utf8")
274
+ stream.on("data", (chunk: string) => {
275
+ buffered += chunk
276
+ const lines = buffered.split("\n")
277
+ buffered = lines.pop() ?? ""
278
+ for (const line of lines) reporter.line(line.replace(/\r$/, ""))
279
+ })
280
+ stream.on("end", () => {
281
+ if (buffered) reporter.line(buffered)
282
+ buffered = ""
283
+ })
284
+ }
285
+
286
+ /** Where the dev process serves the app, from its ready message; `null` when it serves none. */
287
+ function servedApp(message: object): { readonly url: string; readonly apiOrigin: string } | null {
288
+ if (!("app" in message) || typeof message.app !== "object" || message.app === null) return null
289
+ const { url, apiOrigin } = message.app as { readonly url?: unknown; readonly apiOrigin?: unknown }
290
+ return typeof url === "string" && typeof apiOrigin === "string" ? { url, apiOrigin } : null
291
+ }
@@ -0,0 +1,15 @@
1
+ /** Opens a URL in the default browser. A failure is quiet: the URL is already on screen. */
2
+ export async function openUrl(url: string): Promise<void> {
3
+ const command =
4
+ process.platform === "darwin"
5
+ ? ["open", url]
6
+ : process.platform === "win32"
7
+ ? ["cmd.exe", "/c", "start", "", url]
8
+ : ["xdg-open", url]
9
+ try {
10
+ const opened = Bun.spawn({ cmd: command, stdout: "ignore", stderr: "ignore" })
11
+ await opened.exited
12
+ } catch {
13
+ // Nothing to open it with; the URL was printed.
14
+ }
15
+ }
@@ -10,9 +10,8 @@ export async function stopQuietly(stopFn: (() => Promise<void>) | undefined | nu
10
10
 
11
11
  export async function runUntilSignal(onShutdown: () => Promise<void>): Promise<void> {
12
12
  // Test-only readiness hook: e2e tests detect that a long-running role finished
13
- // starting by watching for this marker. It avoids depending on Ink's rendered
14
- // output, which is suppressed when stdout is not a TTY (e.g. under CI). Unset in
15
- // production, so this is a no-op there.
13
+ // starting by watching for this marker, rather than on the wording of what the
14
+ // role prints. Unset in production, so this is a no-op there.
16
15
  const readyLog = process.env.SIXB_CLI_TEST_READY_LOG
17
16
  if (readyLog) {
18
17
  appendFileSync(readyLog, `${JSON.stringify({ type: "role:ready" })}\n`, "utf-8")
@@ -63,6 +63,8 @@ export interface StartSixbRuntimeOptions {
63
63
  readonly agentTurnTimeoutMs?: number
64
64
  readonly workerConcurrency?: WorkerConcurrency
65
65
  readonly vectorConcurrency?: number
66
+ readonly subagentConcurrency?: number
67
+ readonly subagentConcurrencyPerRun?: number
66
68
  }
67
69
 
68
70
  export interface RuntimeApiServer {
@@ -291,6 +293,8 @@ export async function startSixbRuntime(
291
293
  : undefined,
292
294
  concurrency: options.workerConcurrency?.agent,
293
295
  turnTimeoutMs: options.agentTurnTimeoutMs,
296
+ subagentConcurrency: options.subagentConcurrency,
297
+ subagentConcurrencyPerRun: options.subagentConcurrencyPerRun,
294
298
  })
295
299
  }
296
300
 
@@ -58,6 +58,37 @@ export function resolveVectorConcurrency(value: string | undefined): number | un
58
58
  return parseConcurrency(configured, "--vector-concurrency or SIXB_VECTOR_CONCURRENCY")
59
59
  }
60
60
 
61
+ /**
62
+ * Resolve the agent worker's child agents: at once in this process, and at once for one turn.
63
+ * `undefined` leaves the worker's built-in defaults in authority.
64
+ */
65
+ export function resolveSubagentConcurrency(input: {
66
+ readonly perWorker: string | undefined
67
+ readonly perRun: string | undefined
68
+ }): { readonly subagentConcurrency?: number; readonly subagentConcurrencyPerRun?: number } {
69
+ const perWorker = input.perWorker?.trim() ?? nonblank(process.env.SIXB_SUBAGENT_CONCURRENCY)
70
+ const perRun = input.perRun?.trim() ?? nonblank(process.env.SIXB_SUBAGENT_CONCURRENCY_PER_RUN)
71
+
72
+ return {
73
+ ...(perWorker === undefined
74
+ ? {}
75
+ : {
76
+ subagentConcurrency: parseConcurrency(
77
+ perWorker,
78
+ "--subagent-concurrency or SIXB_SUBAGENT_CONCURRENCY"
79
+ ),
80
+ }),
81
+ ...(perRun === undefined
82
+ ? {}
83
+ : {
84
+ subagentConcurrencyPerRun: parseConcurrency(
85
+ perRun,
86
+ "--subagent-concurrency-per-run or SIXB_SUBAGENT_CONCURRENCY_PER_RUN"
87
+ ),
88
+ }),
89
+ }
90
+ }
91
+
61
92
  function parseWorkerConcurrencyEntry(value: string): {
62
93
  readonly workerType: WorkerType
63
94
  readonly concurrency: number
@@ -20,6 +20,8 @@ export interface WorkerCreationOptions {
20
20
  readonly agentTurnTimeoutMs?: number
21
21
  readonly workerConcurrency?: WorkerConcurrency
22
22
  readonly vectorConcurrency?: number
23
+ readonly subagentConcurrency?: number
24
+ readonly subagentConcurrencyPerRun?: number
23
25
  }
24
26
 
25
27
  interface WorkerFactory {
@@ -53,6 +55,8 @@ const workerFactories: Record<WorkerType, WorkerFactory> = {
53
55
  : undefined,
54
56
  concurrency: options.workerConcurrency?.agent,
55
57
  turnTimeoutMs: options.agentTurnTimeoutMs,
58
+ subagentConcurrency: options.subagentConcurrency,
59
+ subagentConcurrencyPerRun: options.subagentConcurrencyPerRun,
56
60
  }),
57
61
  unmetRequirement: (options, agentApiRequired) =>
58
62
  !agentApiRequired || agentApiBaseUrl(options.agentApiBaseUrl) ? null : AGENT_ORIGIN_REQUIRED,
@@ -0,0 +1,54 @@
1
+ # CLI output
2
+
3
+ Two ways to draw, chosen per command.
4
+
5
+ | | Printed screens | Live screens |
6
+ |---|---|---|
7
+ | Files | `theme.ts`, `layout.ts`, `screens.ts`, `deploy-screens.ts`, `index.ts` | `live/` |
8
+ | What | Strings written once with `renderStatic` | An OpenTUI footer pinned under scrolling output |
9
+ | Used by | Help, errors, results, role startup, spinners (`startTask`) | `sixb dev`, a deploy in progress, prompts |
10
+ | Loads | Nothing beyond Bun | `@opentui/core`, `@opentui/react`, React, a native library |
11
+
12
+ Printed screens keep the terminal's own foreground for body text and use color only for status,
13
+ so they read on light and dark terminals. `colorLevel()` drops color for pipes, `NO_COLOR`, and
14
+ dumb terminals, and steps 24-bit colors down to 256 or 16 where the terminal says it must.
15
+ Piped output never wraps, so a log line stays one line.
16
+
17
+ Every screen follows the same rules:
18
+
19
+ - It opens with `▰ sixb <command>`, shows its details, and ends with the outcome. A command with
20
+ one thing to say (`build`, `typegen`, `db migrate`) says it on one line instead.
21
+ - Bold is for the outcome and the command name. Section titles stay muted.
22
+ - Blue means live, or something to open or run: a ready dot, a URL, a command. A fix written in
23
+ prose is led by a faint `→`, never blue.
24
+ - URLs are terminal hyperlinks where the terminal takes them (`link` in `theme.ts`).
25
+ - Content stops at about 100 columns, however wide the terminal.
26
+
27
+ Live screens load only behind `canRunLive()` (`live/can-run-live.ts`, which imports nothing), and
28
+ only through `await import(...)`. Nothing a role or a printed command imports may reach `live/`:
29
+ a renderer holds tens of MB for the life of the process, and `prod-roles.e2e.ts` checks that
30
+ `sixb app` outside a terminal loads none of it.
31
+
32
+ ## Split footer
33
+
34
+ `live/session.ts` starts OpenTUI in `split-footer` mode: the footer owns the bottom rows and
35
+ everything else is committed to the scrollback above it, where it stays after the footer goes.
36
+
37
+ - Write above the footer with `footer.print`. It takes SGR-colored text (`live/ansi.ts` turns it
38
+ into OpenTUI styled text); OpenTUI shows any raw escape it is handed as text.
39
+ - While a footer is up, `console.*` is routed through `print`: Bun's console writes past
40
+ `process.stdout.write` and would draw over the footer.
41
+ - Print a command's last screen through `print` before `stop()`, not after: what follows a
42
+ stopped footer lands one row low.
43
+ - Raw mode turns ctrl+c into a key. Each live screen decides what it means.
44
+
45
+ ## `sixb dev`
46
+
47
+ The supervisor (`lib/dev-supervisor.ts`) outlives every restart, so it owns the screen. It picks a
48
+ `DevReporter`: the footer (`live/dev.tsx`) in a terminal, `[SixbDev]` lines otherwise.
49
+
50
+ With the footer, the dev process runs with `SIXB_DEV_UI=footer` and its stdout and stderr piped.
51
+ It prints nothing of its own; it reports over IPC instead (`lib/dev-messages.ts`): each startup
52
+ step, the ready view, or the startup failure. The supervisor forwards its output line by line.
53
+ Without the footer the dev process inherits the terminal and prints its own screens, as any
54
+ command does.