The best way to control Claude Code, Codex and more from any computer or phone

main
ts 136 lines 5.75 KB
Raw
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 };