fcdev 0.6.0 → 0.8.0

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 (51) hide show
  1. package/CHANGELOG.md +61 -32
  2. package/README.md +17 -16
  3. package/docs/{02- → 01-}/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +14 -12
  4. package/docs/02-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +89 -0
  5. package/docs/{06- → 03-}/345/217/215/346/261/207/347/274/226.md +13 -47
  6. package/docs/{07- → 04-}/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +1 -15
  7. package/docs/nes/{01-NES/347/233/256/346/240/207.md → 01-/345/274/200/345/217/221/346/214/207/345/215/227.md} +4 -9
  8. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +25 -30
  9. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +4 -4
  10. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +5 -5
  11. package/package.json +5 -2
  12. package/src/build/bank-link-config.mjs +1 -1
  13. package/src/build/build-plan.mjs +1 -1
  14. package/src/build/program-builder.mjs +10 -5
  15. package/src/build/source-charset.mjs +111 -0
  16. package/src/cli/args-parser.mjs +1 -1
  17. package/src/cli/commands/debug-command.mjs +20 -58
  18. package/src/cli/commands/docs-command.mjs +2 -2
  19. package/src/cli/commands/run-command.mjs +36 -39
  20. package/src/cli/index.mjs +5 -5
  21. package/src/config/config-loader.mjs +2 -2
  22. package/src/disasm/disassembler.mjs +1 -1
  23. package/src/disasm/trace.mjs +4 -3
  24. package/src/docs/doc-index.mjs +1 -1
  25. package/src/docs/doc-topics.mjs +32 -38
  26. package/src/docs/index.mjs +1 -1
  27. package/src/emulator/debug-cli.mjs +48 -0
  28. package/src/emulator/emulator-launcher.mjs +107 -29
  29. package/src/emulator/emulator-locator.mjs +7 -7
  30. package/src/emulator/index.mjs +4 -3
  31. package/src/emulator/sb2000-session.mjs +104 -0
  32. package/src/targets/target-registry.mjs +9 -1
  33. package/targets/nes/lib/fcnes.lib +0 -0
  34. package/targets/nes/lib/nes-font.o +0 -0
  35. package/targets/nes/target.json +1 -1
  36. package/targets/sb2000/api-reference.md +2 -1
  37. package/targets/sb2000/examples-source.md +1330 -0
  38. package/targets/sb2000/lib/crt0.o +0 -0
  39. package/targets/sb2000/lib/sb2000.lib +0 -0
  40. package/targets/sb2000/symbols-reference.md +670 -0
  41. package/targets/sb2000/target.json +2 -1
  42. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -163
  43. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +0 -123
  44. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +0 -50
  45. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +0 -92
  46. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +0 -72
  47. package/docs/09-/345/217/221/345/270/203.md +0 -70
  48. package/docs/10-VS Code/346/211/251/345/261/225.md" +0 -131
  49. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +0 -47
  50. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +0 -10
  51. package/src/emulator/debug-client.mjs +0 -125
@@ -1,131 +0,0 @@
1
- # VS Code 扩展
2
-
3
- 扩展放在仓库的 `vscode/` 目录,包名 `fcdev`,显示名“fcdev 6502 开发”。首版做 ca65 汇编的语法高亮,以及 ca65 汇编与 cc65 的 C 的智能感知。扩展不内置编译器,只经 `node_modules` 里的 `fcdev` 命令行读取项目信息。
4
-
5
- ## 1. 范围
6
-
7
- 首版包含:
8
-
9
- - ca65 汇编(`.s`、`.asm`、`.inc`)的悬停、补全、转到定义、文档符号。
10
- - C 代码的智能感知:自动运行 `fcdev sync`,让 C/C++ 扩展与 clangd 找到 cc65 的头文件与宏。
11
- - 头文件里符号与函数的文档注释(`/** */`),悬停时显示。
12
- - ca65 汇编的语法高亮(TextMate 语法)。C 用 VS Code 内置的 C 语法,不另提供。
13
-
14
- 首版不含,登记在 [待办备忘](待办备忘.md):任务与问题匹配器、构建与运行命令、新建项目、调试。
15
-
16
- ## 2. 语言支持的分工
17
-
18
- | 语言 | 由谁提供 | 做法 |
19
- | --- | --- | --- |
20
- | C | VS Code 的 C/C++ 扩展或 clangd | 本扩展运行 `fcdev sync`,生成 `.vscode/c_cpp_properties.json` 与 `compile_flags.txt`,里面有头文件目录与预定义宏 |
21
- | 汇编 | 本扩展 | 自己解析 ca65 源码,不依赖其他扩展 |
22
-
23
- 本扩展的 `package.json` 用 `extensionPack` 带上 C/C++ 扩展(`ms-vscode.cpptools`),安装本扩展时一并安装;用户仍可单独卸载它,改用 clangd。
24
-
25
- C 的头文件注释用 Doxygen 的 `/** */` 写法,C/C++ 扩展与 clangd 都会在悬停时显示;`sb2000-symbols.h` 里每个常量宏上方的注释由 `tools/gen-sb2000-header.mjs` 从 `sb2000.inc` 的行尾注释生成。
26
-
27
- ### 2.1 C 的配置同步
28
-
29
- | 触发 | 行为 |
30
- | --- | --- |
31
- | 扩展激活(工作区里有 `fcdev.json`) | 同步所有工作区文件夹里的 fcdev 项目 |
32
- | 工作区文件夹增减 | 同步 |
33
- | `fcdev.json` 新建或修改 | 丢弃该项目的信息缓存,合并 500 毫秒内的连续变化后同步该项目 |
34
- | 命令“fcdev:同步 C/C++ 智能感知配置” | 手动同步,带进度,结束后弹出结果;没有 fcdev 项目时提示 |
35
-
36
- 自动同步只写日志,失败也不弹提示;日志在“输出”面板的 fcdev 通道。设置 `fcdev.intelliSense.autoSync`(默认开启)可关闭自动同步。
37
-
38
- `fcdev sync` 的预定义宏里带 `__fastcall__`、`__cdecl__` 两个空宏:cc65 的头文件用它们标注调用约定,C/C++ 扩展与 clangd 不认识,不定义会报语法错误。这两个宏只出现在 `info` 与 `sync` 的输出里,不参与构建。
39
-
40
- #### 提示选择配置
41
-
42
- C/C++ 扩展用哪个配置,只保存在它自己的工作区状态里,其他扩展无法读写,所以本扩展不能自动切换到 `fcdev` 配置。`.vscode/c_cpp_properties.json` 里除 `fcdev` 外还有其他配置时(例如名为 `Win32` 的默认配置),C/C++ 扩展可能选的不是 `fcdev`,这时 cc65 的头文件不会生效。扩展在同步成功后检查这个文件,条件满足时弹出提示:
43
-
44
- - 提示带“选择配置”按钮,点击后运行 C/C++ 扩展的命令 `C_Cpp.ConfigurationSelect`,由用户在列表里点选 `fcdev`。
45
- - 只在安装了 C/C++ 扩展(`ms-vscode.cpptools`)时提示;只用 clangd 的项目不受影响。
46
- - 每个项目每次 VS Code 会话只提示一次;在同一次同步里有多个项目时合并成一条。
47
- - 设置 `fcdev.intelliSense.promptConfigurationSelection`(默认开启)可关闭提示。
48
- - 只检查同步成功的项目;读取配置文件出错只写日志,不影响同步。
49
-
50
- ### 2.2 汇编
51
-
52
- | 功能 | 行为 |
53
- | --- | --- |
54
- | 悬停 | 6502 指令:功能、影响的标志位、寻址方式的写法与字节数;ca65 伪指令:写法与说明;符号:定义写法、种类、常量的值(同时给出十进制、十六进制与二进制)、源码里的说明注释、所在分组与文件行号 |
55
- | 补全 | 指令助记符、伪指令(输入 `.` 触发)、局部标签(输入 `@` 触发)、可见的符号 |
56
- | 转到定义 | 标签、常量、宏等符号跳到定义处;同名定义在同一范围内有多处时全部列出 |
57
- | 文档符号 | 大纲与面包屑里列出标签、常量、`.define`、宏、`.proc`、`.scope`、`.struct`、`.enum` |
58
-
59
- 可见的符号来自:
60
-
61
- 1. 当前文件,含局部标签与未保存的修改;名字重名时优先取这里的定义。
62
- 2. 当前文件 `.include` 的文件,最多展开 8 层;路径先按当前文件所在目录找,再按 `fcdev info --json` 给出的汇编引入目录找(含目标的 `asminclude`,所以 `sb2000.inc` 的符号能直接看到)。
63
- 3. 工作区里其他汇编文件里的非局部符号。
64
-
65
- 后两项读自磁盘并缓存;汇编文件变化时,丢弃该文件的解析缓存与工作区文件列表。扩展不理解条件汇编的取舍,`.if` 里的符号都会被收集。
66
-
67
- ### 2.3 汇编的语法高亮
68
-
69
- 语法文件是 `syntaxes/ca65.tmLanguage.json`,作用域名 `source.ca65`,对 `.s`、`.asm`、`.inc` 生效。它按行匹配,不理解上下文,所以只靠行首位置和固定词表分类。
70
-
71
- | 内容 | 作用域 |
72
- | --- | --- |
73
- | `;` 注释 | `comment.line.semicolon.ca65` |
74
- | `"..."`、`'...'` 字符串(行尾自动结束,字符串里的分号不算注释) | `string.quoted.double.ca65`、`string.quoted.single.ca65` |
75
- | 行首的标签定义(`name:`、`@local:`、`name::`),行首的 `:` 匿名标签 | `entity.name.function.label.ca65`、`entity.name.function.label.anonymous.ca65` |
76
- | 行首的常量定义(`NAME = 值`、`NAME := 值`) | `variable.other.constant.ca65` |
77
- | `.proc`、`.macro` 后的名字;`.scope`、`.struct`、`.enum` 后的名字 | `entity.name.function.ca65`、`entity.name.type.ca65` |
78
- | `.if` 系列、`.else`、`.elseif`、`.endif` | `keyword.control.conditional.ca65` |
79
- | 伪函数(`.defined`、`.sizeof`、`.lobyte` 等) | `support.function.pseudo.ca65` |
80
- | 其他以 `.` 开头的汇编指令 | `keyword.other.directive.ca65` |
81
- | 分支、跳转、返回指令(`bcc`、`jmp`、`jsr`、`rts`、`brk` 等) | `keyword.control.flow.ca65` |
82
- | 其他 6502 指令 | `keyword.other.mnemonic.ca65` |
83
- | `asl a` 等的累加器、`,x`、`,y` | `variable.language.register.ca65` |
84
- | `$` 十六进制、`%` 二进制、十进制数 | `constant.numeric.hex.ca65`、`constant.numeric.binary.ca65`、`constant.numeric.decimal.ca65` |
85
- | `#` 立即数标记 | `keyword.operator.immediate.ca65` |
86
- | `@name` 局部标签引用、`:+`、`:-` 匿名标签引用 | `variable.other.local.ca65`、`variable.other.anonymous.ca65` |
87
-
88
- - 指令与汇编指令不分大小写。
89
- - 标签定义要求冒号紧跟在名字后面,行首 `bne :+` 因此不会被当成标签。
90
- - 宏的调用与不在词表里的标识符不着色,因为单行匹配无法区分它们与符号。
91
- - 指令词表与 `vscode/src/shared/assembly/instruction-reference.ts`、`vscode/src/shared/assembly/directive-reference.ts` 的覆盖,由 `test/syntaxes/ca65-grammar.test.ts` 逐条检查。
92
-
93
- ## 3. 项目信息的来源
94
-
95
- 扩展经 `node <项目根>/node_modules/fcdev/bin/fcdev.mjs` 调用命令行,不经 shell,不依赖全局安装。
96
-
97
- | 命令 | 用途 |
98
- | --- | --- |
99
- | `fcdev info --json` | 读取目标、头文件目录、汇编引入目录与预定义宏;每个项目缓存一份,`fcdev.json` 变化后失效 |
100
- | `fcdev sync` | 生成 C/C++ 扩展的配置 |
101
-
102
- 项目没有安装 `fcdev` 或命令失败时,汇编智能感知只用当前文件与工作区里的源码,引入目录里的符号看不到;原因写在日志里,不弹提示。
103
-
104
- ## 4. 目录与分层
105
-
106
- 按分层组织,层内再按功能分目录,具体类只在组装根创建:
107
-
108
- | 目录 | 职责 |
109
- | --- | --- |
110
- | `src/contracts` | 接口:汇编智能感知服务、汇编源文件存取、C 配置同步服务、C/C++ 配置检查器、命令行执行器、项目信息提供者 |
111
- | `src/shared` | 纯函数与数据:ca65 解析、行内词法、数字格式、指令与伪指令参考、悬停文字、项目信息与 c_cpp_properties.json 的解析 |
112
- | `src/logic` | 业务:符号解析(含 `.include` 展开)、汇编智能感知服务、C 配置同步服务 |
113
- | `src/infra` | 与外部交互:读工作区文件、调用命令行、查找项目、读取 c_cpp_properties.json |
114
- | `src/entry` | VS Code 入口:四个汇编提供者、命令与文件监视器 |
115
- | `src/platform` | 日志(输出通道) |
116
- | `src/bootstrap` | 组装根 `extension.ts` |
117
- | `syntaxes` | ca65 的 TextMate 语法文件(静态资源,不经分层) |
118
-
119
- - 层之间的依赖方向、文件头、注释宽度与 `package.json` 声明和代码的一致性,由 `test/structure.test.ts` 检查。
120
- - 各层之间只经 `contracts` 里的接口协作;只有 `entry`、`platform`、`infra` 可以引用 `vscode`。
121
-
122
- ## 5. 构建、测试与打包
123
-
124
- 在 `vscode/` 目录运行:
125
-
126
- | 命令 | 用途 |
127
- | --- | --- |
128
- | `npm run check` | 类型检查、oxlint、测试、构建 |
129
- | `npm run package` | 生成 `.vsix`(不入库);发布到应用市场需要发布者账号,由用户操作 |
130
-
131
- 测试在 Node 环境里运行,`vscode` 模块用 `test/support/vscode-mock.ts` 替代;入口层的测试验证提供者与命令的行为,真实 VS Code 里的显示效果要手动打开项目核对。语法文件的测试用开发依赖 `vscode-textmate` 与 `vscode-oniguruma` 真实加载语法并分词,不依赖 VS Code;颜色由用户的主题决定,只检查作用域名。
@@ -1,47 +0,0 @@
1
- # 待办备忘
2
-
3
- 已确定以后再做的事项。做完一项,就把它写进对应的文档,并从本文删掉。
4
-
5
- ## 1. 发布
6
-
7
- | 事项 | 说明 |
8
- | --- | --- |
9
- | 发布四个 npm 包 | 由用户登录 npm 后按 [09-发布](09-发布.md) 的顺序执行 |
10
-
11
- ## 2. VS Code 扩展
12
-
13
- 扩展的智能感知与 ca65 语法高亮已完成,见 [10-VS Code扩展](10-VS%20Code扩展.md)。发布到 VS Code 市场需要发布者账号,由用户操作,本仓库只负责生成 `.vsix`。下面是还没做的功能:
14
-
15
- | 功能 | 说明 |
16
- | --- | --- |
17
- | 任务 | 任务提供者 `fcdev`:构建、运行;问题匹配器识别 `cc65`、`ca65` 的 `文件(行): Error: 信息`,报错可跳转到源码行 |
18
- | 命令 | 新建项目(调用 `create-fcdev`)、构建当前文件、构建当前目录、构建项目、运行、切换目标;状态栏显示当前目标 |
19
- | 找工具 | 项目里没有安装 `fcdev` 时提示一键安装;现在只在日志里写明原因 |
20
- | 调试 | 首版不做;调试适配器协议(DAP)另写设计 |
21
- | 真实 VS Code 里的显示效果 | 扩展已做完,类型检查、测试与构建通过;悬停、补全、高亮在真实 VS Code 里的显示效果待用户核对 |
22
-
23
- ## 3. 模拟器
24
-
25
- | 事项 | 说明 |
26
- | --- | --- |
27
- | 内核集成进 VS Code 面板 | 只要调试服务协议不变,`fcdev` 不用改 |
28
- | 外设读数与真机对齐 | `hwtest` 在真机与模拟器上仍有差异的读数(`$4015` 位 4、`$4022` 开机值、`$4026`、`$4016`、`$4017`、`$4033` 位 6、`$3FFF`),具体数值见 [03-硬件说明](sb2000/03-硬件说明.md) 的“真机与模拟器仍有差异的行为”;程序不应依赖这些值,是否对齐由用户决定。|
29
- | `runnes` 与 `play` 的 DMA 写法 | 两个程序借用程序窗口 2(`$A000`)做 DMA 目的,真机上失败,模拟器对齐真机后也失败(`runnes` 现在用库函数 `sb_dma_to_cpu`,目的在窗口时函数直接返回出错、不复制);改成先 DMA 到 ERAM 缓冲再用 CPU 搬(参考 `apps/sb2000/bbk-loader`) |
30
-
31
- ## 4. 目标
32
-
33
- | 事项 | 说明 |
34
- | --- | --- |
35
- | 步步高、裕兴的目标 | 缺少资料,动手前先用资料与模拟器确认程序格式、内存布局、系统调用与固件要求 |
36
- | NES 的其他映射器 | 现在只支持 `nes.cfg` 的 NROM |
37
- | SB2000 的退出码 | `main` 的返回值没有实现为退出码:`$6308` 是运行库显示消息用的 `LIB_GROUP`,DOS 外壳不读取程序返回时的它,系统里没有退出码这个约定;要不要提供自己的约定(如写到某个 ERAM 单元)以后再定 |
38
- | SB2000 没封装的系统调用 | 见 [api-reference.md](../targets/sb2000/api-reference.md) 末尾的覆盖表与 `api-unwrapped.json`:文件系统内部步骤、`$41`-`$44`、`$31`、`$34`、`$66`、`$65` 与 `$6D` 的部分子功能、`$74`/`$75` 的 NMI 发送与播放列表等;有需要时再封装并补测试 |
39
-
40
- ## 5. 反汇编
41
-
42
- | 事项 | 说明 |
43
- | --- | --- |
44
- | 其他映射器 | 现在只支持 NROM 与平铺二进制;其他映射器需要目标提供地址映射 |
45
- | 跳转表识别 | 已识别 `LDA 表,X` 加间接 `JMP`、`PHA`/`RTS` 的表和 `JMP (地址)` 指向的表;例程内联的跳转表(`JSR` 之后紧跟地址表)、立即数拼出的分发指针还追不到,这部分按数据输出;补全覆盖靠运行记录:模拟器 `trace ... unique` 在步步高机型上可用,CDL 只对 SB2K 映射器有效,对步步高 RAM 里的程序没用。立即数拼出的指针可以让 `fcdev` 列出“可能的入口”供人工确认,还没做 |
46
- | 地址表与字符串识别 | 现在没追到的字节都是 `ByteTable` |
47
- | SB2000 固件页的 CDL 验证 | 没有做;模拟器自带 CDL 只对 SB2K 映射器有效 |
@@ -1,10 +0,0 @@
1
- # 缺陷记录
2
-
3
- 发现的缺陷及修复情况。发现缺陷时先登记,修复后填写修复说明。
4
-
5
- | 编号 | 发现日期 | 缺陷 | 影响 | 状态 | 修复说明 |
6
- | --- | --- | --- | --- | --- | --- |
7
- | B001 | 2026-11-10 | 根 `.gitignore` 的 `build/` 规则把 `packages/fcdev/src/build/`(构建核心的 7 个源文件)排除在版本库之外,`git ls-files` 里没有它们 | 已提交的仓库缺少构建核心,别人克隆后无法使用 `fcdev build`;发布时因为 `files` 白名单仍会打进包,所以现有包内容不受影响 | 已修复 | 把 `.gitignore` 里的 `build/` 改为只忽略仓库根的 `/build/` 与各包根目录下的 `packages/*/build/`;修改后 `git check-ignore` 不再匹配 `packages/fcdev/src/build/`,该目录显示为未跟踪,需要用户自己暂存并提交 |
8
- | B002 | 2026-11-10 | `virtuanes/README.md` 的目录图根写成 `emulator/`,一处链接指向不存在的文件 | 链接失效,目录图与实际不符 | 已修复 | 目录图改为 `virtuanes/`,删掉失效链接与不属于本仓库的说明 |
9
- | B003 | 2026-11-10 | `fcdev` 接受 `--verbose` 选项,但没有任何命令使用它 | 选项无效果;文档与帮助文字都没有提到它 | 待修复 | |
10
- | B004 | 2026-11-12 | `npm run check` 里需要启动模拟器的 SB2000 测试(`sb2000-library.test.mjs`)偶发失败:有时报“调试命令 run 300 超过 120000 毫秒没有应答”,有时报“等待调试服务就绪超时”,失败的用例每次不同;单独重跑通过 | 全量检查偶发 1 个失败,与代码改动无关 | 待修复 | |
@@ -1,125 +0,0 @@
1
- // ------------------------------------------------------------------------
2
- // 名称:debug-client.mjs
3
- // 说明:模拟器调试服务的客户端:连接本机端口,发送一行命令,读取以单独的“.”行结束的应答。
4
- // 作者:sungbin
5
- // 邮箱:sungbin@3578.cn
6
- // 日期:2026-11-10
7
- // 备注:协议见 virtuanes/README.md;服务只监听 127.0.0.1,一次只处理一条命令。
8
- // ------------------------------------------------------------------------
9
- import net from 'node:net';
10
- import { FcdevError } from '../shared/index.mjs';
11
-
12
- /** fcdev 的调试服务默认端口 */
13
- export const DEFAULT_DEBUG_PORT = 5699;
14
-
15
- /** 连接调试服务的超时,单位毫秒 */
16
- const CONNECT_TIMEOUT_MS = 5_000;
17
-
18
- /** 一条命令默认的应答超时,单位毫秒 */
19
- const COMMAND_TIMEOUT_MS = 30_000;
20
-
21
- /**
22
- * @typedef {object} DebugReply
23
- * @property {boolean} ok 应答首行以 OK 开头
24
- * @property {string} head 应答首行
25
- * @property {string[]} lines 首行之后的各行
26
- */
27
-
28
- /**
29
- * 解析不含结尾“.”行的应答文本。
30
- * @param {string} text 应答文本
31
- * @returns {DebugReply} 解析结果
32
- */
33
- export function parseReply(text) {
34
- const lines = text.split('\n').filter((line) => line.length > 0);
35
- const head = lines[0] ?? '';
36
- return { ok: head.startsWith('OK'), head, lines: lines.slice(1) };
37
- }
38
-
39
- /** 调试服务客户端 */
40
- export class DebugClient {
41
- #socket;
42
- #buffer = '';
43
- #waiter = null;
44
-
45
- /**
46
- * @param {net.Socket} socket 已连接的套接字
47
- */
48
- constructor(socket) {
49
- this.#socket = socket;
50
- socket.setEncoding('utf8');
51
- socket.on('data', (chunk) => {
52
- this.#buffer += chunk;
53
- this.#deliver();
54
- });
55
- socket.on('close', () => {
56
- this.#waiter?.reject(new FcdevError('调试连接已关闭', { code: 'DEBUG_CONNECTION_CLOSED' }));
57
- this.#waiter = null;
58
- });
59
- }
60
-
61
- /**
62
- * 连接本机调试服务。
63
- * @param {{port?: number, timeoutMs?: number}} [options] 端口与连接超时
64
- * @returns {Promise<DebugClient>} 客户端
65
- * @throws {FcdevError} 连接失败或超时
66
- */
67
- static connect({ port = DEFAULT_DEBUG_PORT, timeoutMs = CONNECT_TIMEOUT_MS } = {}) {
68
- return new Promise((resolve, reject) => {
69
- const socket = net.connect({ host: '127.0.0.1', port });
70
- const timer = setTimeout(() => {
71
- socket.destroy();
72
- reject(new FcdevError(`连接调试服务(端口 ${port})超时`, { code: 'DEBUG_CONNECT_FAILED' }));
73
- }, timeoutMs);
74
- socket.once('connect', () => {
75
- clearTimeout(timer);
76
- resolve(new DebugClient(socket));
77
- });
78
- socket.once('error', (error) => {
79
- clearTimeout(timer);
80
- reject(new FcdevError(`无法连接调试服务(端口 ${port})`, {
81
- code: 'DEBUG_CONNECT_FAILED',
82
- hint: '先用 npx fcdev run --debug 启动模拟器,或检查端口是否一致',
83
- cause: error,
84
- }));
85
- });
86
- });
87
- }
88
-
89
- /** 如果缓冲区里已经有完整应答,交给等待者 */
90
- #deliver() {
91
- if (!this.#waiter) return;
92
- const end = this.#buffer.indexOf('\n.\n');
93
- if (end < 0) return;
94
- const reply = parseReply(this.#buffer.slice(0, end + 1));
95
- this.#buffer = this.#buffer.slice(end + 3);
96
- const { resolve, timer } = this.#waiter;
97
- clearTimeout(timer);
98
- this.#waiter = null;
99
- resolve(reply);
100
- }
101
-
102
- /**
103
- * 发送一条命令并等待应答;应答为 ERR 时不抛错,由调用者看 ok。
104
- * @param {string} command 命令文本,不含换行
105
- * @param {{timeoutMs?: number}} [options] 应答超时
106
- * @returns {Promise<DebugReply>} 应答
107
- * @throws {FcdevError} 上一条命令未返回、连接关闭或超时
108
- */
109
- send(command, { timeoutMs = COMMAND_TIMEOUT_MS } = {}) {
110
- if (this.#waiter) throw new FcdevError('上一条调试命令尚未返回', { code: 'DEBUG_BUSY' });
111
- return new Promise((resolve, reject) => {
112
- const timer = setTimeout(() => {
113
- this.#waiter = null;
114
- reject(new FcdevError(`调试命令“${command}”超过 ${timeoutMs} 毫秒没有应答`, { code: 'DEBUG_TIMEOUT' }));
115
- }, timeoutMs);
116
- this.#waiter = { resolve, reject, timer };
117
- this.#socket.write(`${command}\n`);
118
- });
119
- }
120
-
121
- /** 关闭连接 */
122
- close() {
123
- this.#socket.end();
124
- }
125
- }