The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { AppId, TerminalTab as Pane } from "../shared/types.ts"; |
| 2 | |
| 3 | export type { Pane }; |
| 4 | |
| 5 | export interface Term { |
| 6 | /** Enter a command into a tab (it appears at once) and press Enter. */ |
| 7 | type(pane: Pane, command: string): Promise<void>; |
| 8 | /** Press a key in a tab, e.g. `Enter`. */ |
| 9 | key(pane: Pane, key: string): Promise<void>; |
| 10 | /** Run a command in a tab and wait for it to finish (or for `until`). Returns the tab text. */ |
| 11 | run(pane: Pane, command: string, opts?: { until?: RegExp; timeout?: number }): Promise<string>; |
| 12 | /** Switch to the dev tab and wait until `alchemy dev` has settled after a change. */ |
| 13 | waitDev(opts?: { timeout?: number }): Promise<void>; |
| 14 | /** Wait until a tab shows `pattern`. */ |
| 15 | waitFor(pane: Pane, pattern: RegExp, opts?: { timeout?: number }): Promise<string>; |
| 16 | /** Current text of a tab, including scrollback. */ |
| 17 | text(pane: Pane): Promise<string>; |
| 18 | sleep(ms: number): Promise<void>; |
| 19 | } |
| 20 | |
| 21 | /** A single code edit: takes the file's current text, returns the next. */ |
| 22 | export type Edit = (code: string) => string; |
| 23 | |
| 24 | /** |
| 25 | * What a chapter scene can do. Every call has a real effect on the project |
| 26 | * folder, the terminal or the network, and is also recorded as a beat for |
| 27 | * the video: patched files are written to disk before the next terminal |
| 28 | * beat, terminal commands run in a real tmux session, and pages are real |
| 29 | * captures. At the end of the scene every project file must match |
| 30 | * `chapters/<chapter>`, so the edits can't drift from the tested code. |
| 31 | */ |
| 32 | export interface SceneContext { |
| 33 | /** Absolute path of the project folder the demo builds. */ |
| 34 | readonly dir: string; |
| 35 | /** Values passed to later scenes (e.g. a deployed URL). */ |
| 36 | readonly state: Record<string, string>; |
| 37 | /** Copy every file of this scene's chapter into the project, except the ones edited on screen. */ |
| 38 | sync(opts?: { except?: string[] }): Promise<void>; |
| 39 | /** |
| 40 | * Lines of a file as it is at the end of this chapter: `L(3, 8)` is lines |
| 41 | * 3–8 (1-based, inclusive) with a trailing newline. Handy for building |
| 42 | * patches that end exactly at the real code. |
| 43 | */ |
| 44 | chapterLines(file: string): Promise<(from: number, to?: number) => string>; |
| 45 | /** Override the caption at the bottom of the screen (by default each step's title is its caption). */ |
| 46 | caption(text: string): void; |
| 47 | /** A full-screen transition slide, as its own step, before building a significant piece. */ |
| 48 | slide(heading: string, opts?: { eyebrow?: string; subtitle?: string; notes?: string }): void; |
| 49 | /** Start a new presenter step; it plays when the presenter presses →. Its title is shown as the caption. */ |
| 50 | step(title: string, notes?: string): void; |
| 51 | editor: { |
| 52 | /** Open a file in a tab (or switch to its tab). */ |
| 53 | open(file: string): Promise<void>; |
| 54 | /** One edit to a file, as its own presenter step, shown as a green/red diff. `title` is its caption. */ |
| 55 | patch(file: string, title: string, edit: Edit, notes?: string): Promise<void>; |
| 56 | /** The file's whole change to the chapter's version, as one patch step. */ |
| 57 | show(file: string, title?: string): Promise<void>; |
| 58 | /** Delete a file (closes its tab). */ |
| 59 | remove(file: string): Promise<void>; |
| 60 | }; |
| 61 | /** Drive the terminal; everything inside is shown in the terminal window. */ |
| 62 | terminal<T>(fn: (t: Term) => Promise<T>): Promise<T>; |
| 63 | /** Show alchemy dev picking up the change, then the architecture read from Alchemy's state. */ |
| 64 | diagram(opts: { stage: string; nodes?: string[]; edges?: string[] }): Promise<void>; |
| 65 | browser: { |
| 66 | /** Load `url` in a real browser and show it. */ |
| 67 | open(url: string, opts?: { waitFor?: RegExp }): Promise<void>; |
| 68 | /** Re-capture the open page once it shows `waitFor` (live updates). */ |
| 69 | update(opts: { waitFor: RegExp }): Promise<void>; |
| 70 | /** Type `text` into a field, as a user would (shown with the pointer). */ |
| 71 | fill(selector: string, text: string): Promise<void>; |
| 72 | /** Click an element and wait for the page to show `waitFor`. */ |
| 73 | click(selector: string, opts?: { waitFor?: RegExp }): Promise<void>; |
| 74 | }; |
| 75 | /** Cmd-Tab to a window without doing anything in it. */ |
| 76 | focus(app: AppId): void; |
| 77 | /** Hold on the current picture. */ |
| 78 | pause(seconds: number): void; |
| 79 | } |
| 80 | |
| 81 | export interface SceneDefinition { |
| 82 | title: string; |
| 83 | notes?: string; |
| 84 | /** Folder under `chapters/` this scene ends at. */ |
| 85 | chapter: string; |
| 86 | run(s: SceneContext): Promise<void>; |
| 87 | } |
| 88 | |
| 89 | export const defineScene = (scene: SceneDefinition): SceneDefinition => scene; |
| 90 | |
| 91 | const locate = (code: string, anchor: string) => { |
| 92 | const at = code.indexOf(anchor); |
| 93 | if (at < 0) throw new Error(`edit anchor not found:\n${anchor}\n--- in ---\n${code}`); |
| 94 | if (code.indexOf(anchor, at + 1) >= 0) throw new Error(`edit anchor is ambiguous:\n${anchor}`); |
| 95 | return at; |
| 96 | }; |
| 97 | |
| 98 | /** Edit helpers. Anchors must match exactly once, so a stale edit fails loudly. */ |
| 99 | export const edit = { |
| 100 | /** Replace the whole file. */ |
| 101 | set: |
| 102 | (text: string): Edit => |
| 103 | () => |
| 104 | text, |
| 105 | /** Add text at the end of the file. */ |
| 106 | append: |
| 107 | (text: string): Edit => |
| 108 | (code) => |
| 109 | code + text, |
| 110 | /** Insert `text` right after `anchor`. */ |
| 111 | after: |
| 112 | (anchor: string, text: string): Edit => |
| 113 | (code) => { |
| 114 | const at = locate(code, anchor) + anchor.length; |
| 115 | return code.slice(0, at) + text + code.slice(at); |
| 116 | }, |
| 117 | /** Insert `text` right before `anchor`. */ |
| 118 | before: |
| 119 | (anchor: string, text: string): Edit => |
| 120 | (code) => { |
| 121 | const at = locate(code, anchor); |
| 122 | return code.slice(0, at) + text + code.slice(at); |
| 123 | }, |
| 124 | /** Replace `anchor` with `text`. */ |
| 125 | replace: |
| 126 | (anchor: string, text: string): Edit => |
| 127 | (code) => { |
| 128 | const at = locate(code, anchor); |
| 129 | return code.slice(0, at) + text + code.slice(at + anchor.length); |
| 130 | }, |
| 131 | /** Apply several edits as one patch. */ |
| 132 | all: |
| 133 | (...edits: Edit[]): Edit => |
| 134 | (code) => |
| 135 | edits.reduce((acc, e) => e(acc), code), |
| 136 | }; |