fcdev 0.0.0-stage → 0.1.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 (71) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +81 -2
  3. package/bin/fcdev.mjs +17 -0
  4. package/package.json +38 -4
  5. package/src/build/build-plan.mjs +92 -0
  6. package/src/build/dependency-file.mjs +24 -0
  7. package/src/build/disk-builder.mjs +36 -0
  8. package/src/build/index.mjs +31 -0
  9. package/src/build/program-builder.mjs +209 -0
  10. package/src/build/source-collector.mjs +54 -0
  11. package/src/build/tool-arguments.mjs +83 -0
  12. package/src/cli/args-parser.mjs +84 -0
  13. package/src/cli/commands/build-command.mjs +34 -0
  14. package/src/cli/commands/debug-command.mjs +70 -0
  15. package/src/cli/commands/disasm-command.mjs +65 -0
  16. package/src/cli/commands/disk-command.mjs +34 -0
  17. package/src/cli/commands/info-command.mjs +33 -0
  18. package/src/cli/commands/project-info.mjs +57 -0
  19. package/src/cli/commands/run-command.mjs +68 -0
  20. package/src/cli/commands/sync-command.mjs +85 -0
  21. package/src/cli/index.mjs +100 -0
  22. package/src/config/config-loader.mjs +132 -0
  23. package/src/config/index.mjs +9 -0
  24. package/src/disasm/analysis.mjs +97 -0
  25. package/src/disasm/cdl.mjs +35 -0
  26. package/src/disasm/disassembler.mjs +114 -0
  27. package/src/disasm/index.mjs +16 -0
  28. package/src/disasm/info-writer.mjs +72 -0
  29. package/src/disasm/loaders.mjs +69 -0
  30. package/src/disasm/opcode-table.mjs +268 -0
  31. package/src/disasm/roundtrip.mjs +69 -0
  32. package/src/disasm/symbols.mjs +30 -0
  33. package/src/disasm/trace.mjs +25 -0
  34. package/src/emulator/debug-client.mjs +125 -0
  35. package/src/emulator/emulator-launcher.mjs +80 -0
  36. package/src/emulator/emulator-locator.mjs +62 -0
  37. package/src/emulator/index.mjs +11 -0
  38. package/src/packagers/fat-floppy.mjs +22 -0
  39. package/src/packagers/fat12-image.mjs +245 -0
  40. package/src/packagers/flat-binary.mjs +53 -0
  41. package/src/packagers/index.mjs +54 -0
  42. package/src/packagers/ines.mjs +38 -0
  43. package/src/shared/errors.mjs +25 -0
  44. package/src/shared/fs-utils.mjs +66 -0
  45. package/src/shared/index.mjs +11 -0
  46. package/src/shared/process.mjs +50 -0
  47. package/src/targets/index.mjs +17 -0
  48. package/src/targets/name-rules.mjs +33 -0
  49. package/src/targets/target-registry.mjs +187 -0
  50. package/src/toolchain/index.mjs +16 -0
  51. package/src/toolchain/toolchain-locator.mjs +104 -0
  52. package/targets/nes/asminc/fcnes.inc +16 -0
  53. package/targets/nes/chr/ascii-8x8.chr +0 -0
  54. package/targets/nes/chr/font8x8_basic.h +152 -0
  55. package/targets/nes/include/fcnes.h +45 -0
  56. package/targets/nes/lib/fcnes.lib +0 -0
  57. package/targets/nes/lib/nes-font.o +0 -0
  58. package/targets/nes/lib-build.json +9 -0
  59. package/targets/nes/src/fcnes.s +91 -0
  60. package/targets/nes/src/nes-font.s +12 -0
  61. package/targets/nes/target.json +27 -0
  62. package/targets/sb2000/asminc/sb2000.inc +216 -0
  63. package/targets/sb2000/include/sb2000-symbols.h +380 -0
  64. package/targets/sb2000/include/sb2000.h +52 -0
  65. package/targets/sb2000/lib/crt0.o +0 -0
  66. package/targets/sb2000/lib/sb2000.lib +0 -0
  67. package/targets/sb2000/lib-build.json +8 -0
  68. package/targets/sb2000/link.cfg +35 -0
  69. package/targets/sb2000/src/crt0.s +37 -0
  70. package/targets/sb2000/src/sb2000.s +67 -0
  71. package/targets/sb2000/target.json +28 -0
@@ -0,0 +1,209 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:program-builder.mjs
3
+ // 说明:构建一个程序:逐个编译与汇编源文件,链接,再交给打包器;支持增量构建。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:某个目标文件比源文件和依赖文件新就不重编;目标、选项、fcdev 或工具链版本变化时全部重编(指纹存在 stamp.json)。
8
+ // ------------------------------------------------------------------------
9
+ import { createHash } from 'node:crypto';
10
+ import { readFileSync, rmSync, writeFileSync } from 'node:fs';
11
+ import path from 'node:path';
12
+ import { fileURLToPath } from 'node:url';
13
+ import { ensureDirectory, FcdevError, getModifiedTime, readJsonFile } from '../shared/index.mjs';
14
+ import { getPackager } from '../packagers/index.mjs';
15
+ import { resolveTargetPath } from '../targets/index.mjs';
16
+ import { getToolchainVersion, runTool } from '../toolchain/index.mjs';
17
+ import { parseDependencyFile } from './dependency-file.mjs';
18
+ import { getSourceLanguage } from './source-collector.mjs';
19
+ import { buildAssemblerArguments, buildCompilerArguments, buildLinkerArguments } from './tool-arguments.mjs';
20
+
21
+ /** 主包自身的 package.json,用于取版本号 */
22
+ const PACKAGE_JSON_FILE = fileURLToPath(new URL('../../package.json', import.meta.url));
23
+
24
+ /**
25
+ * @typedef {object} Reporter
26
+ * @property {(message: string) => void} log 进度信息
27
+ * @property {(text: string) => void} write 工具的原始输出,原样透传
28
+ */
29
+
30
+ /**
31
+ * @typedef {object} BuildResult
32
+ * @property {string} programName 程序名
33
+ * @property {string} outputFile 产物路径
34
+ * @property {number} size 产物大小
35
+ * @property {number} compiled 本次重新编译的源文件数
36
+ * @property {number} reused 沿用上次结果的源文件数
37
+ */
38
+
39
+ /** 不输出任何信息的汇报器 */
40
+ const SILENT_REPORTER = { log() {}, write() {} };
41
+
42
+ /**
43
+ * 计算增量构建的指纹。
44
+ * @param {import('./build-plan.mjs').BuildPlan} plan 构建计划
45
+ * @param {string} toolchainVersion 工具链版本
46
+ * @returns {string} 指纹
47
+ */
48
+ function computeFingerprint(plan, toolchainVersion) {
49
+ const fcdevVersion = readJsonFile(PACKAGE_JSON_FILE).version;
50
+ const content = {
51
+ fcdevVersion,
52
+ toolchainVersion,
53
+ target: plan.target,
54
+ targetOptions: plan.targetOptions,
55
+ optimize: plan.config.optimize,
56
+ define: plan.config.define,
57
+ include: plan.config.include,
58
+ sources: plan.sources.map((source) => path.relative(plan.sourceBase, source)),
59
+ };
60
+ return createHash('sha256').update(JSON.stringify(content)).digest('hex');
61
+ }
62
+
63
+ /**
64
+ * 读取上次构建记录的指纹。
65
+ * @param {string} stampFile 指纹文件
66
+ * @returns {string|null} 指纹;没有记录或文件损坏时为 null
67
+ */
68
+ function readStamp(stampFile) {
69
+ try {
70
+ return JSON.parse(readFileSync(stampFile, 'utf8')).fingerprint ?? null;
71
+ } catch {
72
+ return null;
73
+ }
74
+ }
75
+
76
+ /**
77
+ * 判断目标文件是否比源文件和依赖文件都新。
78
+ * @param {string} objectFile 目标文件
79
+ * @param {string} sourceFile 源文件
80
+ * @param {string} dependencyFile 依赖文件
81
+ * @returns {boolean} 不需要重编时为 true
82
+ */
83
+ function isUpToDate(objectFile, sourceFile, dependencyFile) {
84
+ const objectTime = getModifiedTime(objectFile);
85
+ const dependencyText = getModifiedTime(dependencyFile) === null ? null : readFileSync(dependencyFile, 'utf8');
86
+ if (objectTime === null || dependencyText === null) return false;
87
+ const inputs = [sourceFile, ...parseDependencyFile(dependencyText)];
88
+ return inputs.every((input) => {
89
+ const time = getModifiedTime(input);
90
+ return time !== null && time <= objectTime;
91
+ });
92
+ }
93
+
94
+ /**
95
+ * 运行一个工具;失败时透传输出并抛错。
96
+ * @param {import('../toolchain/index.mjs').Toolchain} toolchain 工具链
97
+ * @param {string} tool 工具名
98
+ * @param {string[]} args 参数
99
+ * @param {Reporter} reporter 汇报器
100
+ * @param {string} failureMessage 失败时的说明
101
+ * @returns {Promise<import('../shared/index.mjs').ProcessResult>} 运行结果
102
+ * @throws {FcdevError} 工具以非零退出码结束
103
+ */
104
+ async function runChecked(toolchain, tool, args, reporter, failureMessage) {
105
+ const result = await runTool(toolchain, tool, args);
106
+ const text = `${result.stdout}${result.stderr}`;
107
+ if (text !== '') reporter.write(text.endsWith('\n') ? text : `${text}\n`);
108
+ if (result.code !== 0) throw new FcdevError(failureMessage, { code: 'TOOL_FAILED', hint: describeToolFailure(text) });
109
+ return result;
110
+ }
111
+
112
+ /**
113
+ * 根据链接器的输出给出常见问题的提示。
114
+ * @param {string} output 工具输出
115
+ * @returns {string} 提示;没有可提示的内容时为空
116
+ */
117
+ function describeToolFailure(output) {
118
+ if (/Unresolved external[^\w]*_?main\b/i.test(output)) return '没有找到 main:C 程序要定义 main,汇编程序要 .export _main';
119
+ if (/Duplicate external identifier[^\w]*_?main\b/i.test(output)) return '目录里有多个 main;若要单独构建一个程序,请指定文件名';
120
+ return '';
121
+ }
122
+
123
+ /**
124
+ * 编译或汇编一个源文件,得到目标文件。
125
+ * @param {object} context 构建上下文
126
+ * @param {string} source 源文件
127
+ * @param {string} objectFile 目标文件
128
+ * @returns {Promise<void>}
129
+ */
130
+ async function compileSource(context, source, objectFile) {
131
+ const { toolchain, settings, reporter } = context;
132
+ const base = objectFile.slice(0, -'.o'.length);
133
+ if (getSourceLanguage(source) === 'c') {
134
+ const asmFile = `${base}.s`;
135
+ await runChecked(toolchain, 'cc65', buildCompilerArguments(settings, { source, output: asmFile, dependencyFile: `${base}.d` }), reporter, `编译失败:${source}`);
136
+ await runChecked(toolchain, 'ca65', buildAssemblerArguments(settings, { source: asmFile, output: objectFile, dependencyFile: `${base}.asm.d` }), reporter, `汇编失败:${asmFile}`);
137
+ } else {
138
+ await runChecked(toolchain, 'ca65', buildAssemblerArguments(settings, { source, output: objectFile, dependencyFile: `${base}.d` }), reporter, `汇编失败:${source}`);
139
+ }
140
+ }
141
+
142
+ /**
143
+ * 构建一个程序。
144
+ * @param {import('./build-plan.mjs').BuildPlan} plan 构建计划
145
+ * @param {import('../toolchain/index.mjs').Toolchain} toolchain 工具链
146
+ * @param {Reporter} [reporter] 汇报器
147
+ * @returns {Promise<BuildResult>} 构建结果
148
+ * @throws {FcdevError} 编译、链接或打包失败
149
+ */
150
+ export async function buildProgram(plan, toolchain, reporter = SILENT_REPORTER) {
151
+ const { target, config } = plan;
152
+ const toTargetPaths = (values) => values.map((value) => resolveTargetPath(target, value, toolchain.home));
153
+ const settings = {
154
+ cc65Target: target.cc65Target,
155
+ cpu: target.cpu,
156
+ optimize: config.optimize,
157
+ includeDirs: [...toTargetPaths(target.include), ...config.include, plan.sourceBase],
158
+ asmIncludeDirs: [...toTargetPaths(target.asminclude), ...config.include, plan.sourceBase],
159
+ defines: { ...target.defines, ...config.define },
160
+ };
161
+
162
+ ensureDirectory(plan.objectDir);
163
+ ensureDirectory(path.dirname(plan.outputFile));
164
+
165
+ const stampFile = path.join(plan.objectDir, 'stamp.json');
166
+ const fingerprint = computeFingerprint(plan, await getToolchainVersion(toolchain));
167
+ if (readStamp(stampFile) !== fingerprint) {
168
+ // 指纹变了:删掉旧的中间文件再重编
169
+ rmSync(plan.objectDir, { recursive: true, force: true });
170
+ ensureDirectory(plan.objectDir);
171
+ }
172
+
173
+ const context = { toolchain, settings, reporter };
174
+ const objects = [];
175
+ let compiled = 0;
176
+ let reused = 0;
177
+ for (const source of plan.sources) {
178
+ const relative = path.relative(plan.sourceBase, source);
179
+ const objectName = `${relative.slice(0, relative.length - path.extname(relative).length).split(path.sep).join('__')}.o`;
180
+ const objectFile = path.join(plan.objectDir, objectName);
181
+ objects.push(objectFile);
182
+ if (isUpToDate(objectFile, source, `${objectFile.slice(0, -2)}.d`)) {
183
+ reused += 1;
184
+ continue;
185
+ }
186
+ reporter.log(`编译 ${relative}`);
187
+ await compileSource(context, source, objectFile);
188
+ compiled += 1;
189
+ }
190
+
191
+ const binaryFile = path.join(plan.objectDir, `${plan.programName}.bin`);
192
+ const optionObjects = Object.entries(plan.targetOptions)
193
+ .filter(([key, value]) => value === true && target.options[key])
194
+ .flatMap(([key]) => target.options[key].links);
195
+ reporter.log('链接');
196
+ await runChecked(toolchain, 'ld65', buildLinkerArguments({
197
+ linkConfig: resolveTargetPath(target, target.linkConfig, toolchain.home),
198
+ binaryFile,
199
+ mapFile: path.join(plan.objectDir, `${plan.programName}.map`),
200
+ debugFile: path.join(plan.objectDir, `${plan.programName}.dbg`),
201
+ objects: [...toTargetPaths(target.startup), ...objects, ...toTargetPaths(optionObjects)],
202
+ libraries: toTargetPaths(target.libraries),
203
+ forceImports: target.forceImports,
204
+ }), reporter, `链接失败:${plan.programName}`);
205
+
206
+ const packaged = getPackager(target.packager)({ binaryFile, outputFile: plan.outputFile, options: target.packagerOptions });
207
+ writeFileSync(stampFile, JSON.stringify({ fingerprint }));
208
+ return { programName: plan.programName, outputFile: packaged.outputFile, size: packaged.size, compiled, reused };
209
+ }
@@ -0,0 +1,54 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:source-collector.mjs
3
+ // 说明:收集目录下的源文件,以及判断源文件的语言。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:递归收集 .c、.s、.asm;跳过输出目录 build、node_modules 与以 . 开头的目录。
8
+ // ------------------------------------------------------------------------
9
+ import { readdirSync } from 'node:fs';
10
+ import path from 'node:path';
11
+ import { FcdevError } from '../shared/index.mjs';
12
+
13
+ /** 递归收集时跳过的目录名 */
14
+ const SKIPPED_DIRECTORIES = new Set(['build', 'node_modules']);
15
+
16
+ /**
17
+ * 判断源文件的语言。
18
+ * @param {string} file 文件路径
19
+ * @returns {'c'|'asm'|null} c、asm,或不是源文件时为 null
20
+ */
21
+ export function getSourceLanguage(file) {
22
+ const extension = path.extname(file).toLowerCase();
23
+ if (extension === '.c') return 'c';
24
+ if (extension === '.s' || extension === '.asm') return 'asm';
25
+ return null;
26
+ }
27
+
28
+ /**
29
+ * 递归收集目录下的全部源文件。
30
+ * @param {string} dir 目录的绝对路径
31
+ * @param {string[]} [excludedDirs] 额外跳过的目录(绝对路径,如配置的输出目录)
32
+ * @returns {string[]} 源文件的绝对路径,按相对路径排序
33
+ * @throws {FcdevError} 目录下没有任何源文件
34
+ */
35
+ export function collectSources(dir, excludedDirs = []) {
36
+ const excluded = new Set(excludedDirs.map((item) => path.resolve(item)));
37
+ const found = [];
38
+ const walk = (current) => {
39
+ for (const entry of readdirSync(current, { withFileTypes: true })) {
40
+ const full = path.join(current, entry.name);
41
+ if (entry.isDirectory()) {
42
+ if (!SKIPPED_DIRECTORIES.has(entry.name) && !entry.name.startsWith('.') && !excluded.has(full)) walk(full);
43
+ } else if (getSourceLanguage(entry.name)) {
44
+ found.push(full);
45
+ }
46
+ }
47
+ };
48
+ walk(dir);
49
+ found.sort((left, right) => path.relative(dir, left).localeCompare(path.relative(dir, right)));
50
+ if (found.length === 0) {
51
+ throw new FcdevError(`目录 ${dir} 下没有 .c、.s 或 .asm 源文件`, { code: 'NO_SOURCES' });
52
+ }
53
+ return found;
54
+ }
@@ -0,0 +1,83 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:tool-arguments.mjs
3
+ // 说明:生成 cc65、ca65、ld65 的命令行参数:只拼参数,不运行,便于测试。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:一律带 -g 输出调试信息;依赖文件用 --create-dep 生成,供增量构建判断。
8
+ // ------------------------------------------------------------------------
9
+
10
+ /**
11
+ * 预定义宏转成 -D 参数。
12
+ * @param {Record<string, string|number>} defines 宏表
13
+ * @returns {string[]} 参数列表
14
+ */
15
+ function defineArguments(defines) {
16
+ return Object.entries(defines).flatMap(([name, value]) => ['-D', `${name}=${value}`]);
17
+ }
18
+
19
+ /**
20
+ * @typedef {object} CompileSettings
21
+ * @property {string} cc65Target 目标名
22
+ * @property {string} cpu CPU 型号
23
+ * @property {boolean} optimize 是否优化
24
+ * @property {string[]} includeDirs C 头文件目录
25
+ * @property {string[]} asmIncludeDirs 汇编引入目录
26
+ * @property {Record<string, string|number>} defines 预定义宏
27
+ */
28
+
29
+ /**
30
+ * cc65 编译一个 C 文件的参数。
31
+ * @param {CompileSettings} settings 编译设置
32
+ * @param {{source: string, output: string, dependencyFile: string}} files 源文件、输出的汇编文件与依赖文件
33
+ * @returns {string[]} 参数列表
34
+ */
35
+ export function buildCompilerArguments(settings, files) {
36
+ return [
37
+ '-t', settings.cc65Target,
38
+ '--cpu', settings.cpu,
39
+ '-g',
40
+ ...(settings.optimize ? ['-Oirs'] : []),
41
+ ...settings.includeDirs.flatMap((dir) => ['-I', dir]),
42
+ ...defineArguments(settings.defines),
43
+ '--create-dep', files.dependencyFile,
44
+ '-o', files.output,
45
+ files.source,
46
+ ];
47
+ }
48
+
49
+ /**
50
+ * ca65 汇编一个文件的参数。
51
+ * @param {CompileSettings} settings 编译设置
52
+ * @param {{source: string, output: string, dependencyFile: string}} files 源文件、输出的目标文件与依赖文件
53
+ * @returns {string[]} 参数列表
54
+ */
55
+ export function buildAssemblerArguments(settings, files) {
56
+ return [
57
+ '-t', settings.cc65Target,
58
+ '--cpu', settings.cpu,
59
+ '-g',
60
+ ...settings.asmIncludeDirs.flatMap((dir) => ['-I', dir, '--bin-include-dir', dir]),
61
+ ...defineArguments(settings.defines),
62
+ '--create-dep', files.dependencyFile,
63
+ '-o', files.output,
64
+ files.source,
65
+ ];
66
+ }
67
+
68
+ /**
69
+ * ld65 链接的参数。
70
+ * @param {{linkConfig: string, binaryFile: string, mapFile: string, debugFile: string, objects: string[], libraries: string[], forceImports?: string[]}} input 链接配置、输出文件、目标文件、库与强制引入的符号
71
+ * @returns {string[]} 参数列表
72
+ */
73
+ export function buildLinkerArguments(input) {
74
+ return [
75
+ '-C', input.linkConfig,
76
+ '-m', input.mapFile,
77
+ '--dbgfile', input.debugFile,
78
+ '-o', input.binaryFile,
79
+ ...(input.forceImports ?? []).flatMap((symbol) => ['-u', symbol]),
80
+ ...input.objects,
81
+ ...input.libraries,
82
+ ];
83
+ }
@@ -0,0 +1,84 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:args-parser.mjs
3
+ // 说明:解析命令行参数:命令、位置参数与通用选项。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:debug 命令把命令名之后的全部参数原样交给调试服务,不再解析选项。
8
+ // ------------------------------------------------------------------------
9
+ import { FcdevError } from '../shared/index.mjs';
10
+
11
+ /** 不解析选项、参数原样传递的命令 */
12
+ const RAW_COMMANDS = new Set(['debug']);
13
+
14
+ /** 带一个字符串值的选项:选项名到 options 里的字段 */
15
+ const VALUE_OPTIONS = {
16
+ '--format': 'format',
17
+ '--base': 'base',
18
+ '--cdl': 'cdl',
19
+ '--trace': 'trace',
20
+ '--symbols': 'symbols',
21
+ '--out': 'out',
22
+ };
23
+
24
+ /**
25
+ * @typedef {object} ParsedArguments
26
+ * @property {string|null} command 命令名;没有给命令时为 null
27
+ * @property {string[]} positionals 位置参数
28
+ * @property {{target?: string, port?: number, debug: boolean, verbose: boolean, json: boolean, help: boolean, version: boolean, format?: string, base?: string, cdl?: string, trace?: string, symbols?: string, out?: string, entries: string[]}} options 选项
29
+ */
30
+
31
+ /**
32
+ * 解析 process.argv 去掉前两项之后的参数。
33
+ * @param {string[]} argv 命令行参数
34
+ * @returns {ParsedArguments} 解析结果
35
+ * @throws {FcdevError} 出现未知选项,或选项缺少值
36
+ */
37
+ export function parseArguments(argv) {
38
+ const options = { debug: false, verbose: false, json: false, help: false, version: false, entries: [] };
39
+ const positionals = [];
40
+ let command = null;
41
+ for (let index = 0; index < argv.length; index += 1) {
42
+ const token = argv[index];
43
+ if (command !== null && RAW_COMMANDS.has(command)) {
44
+ positionals.push(token);
45
+ } else if (token === '--help' || token === '-h') {
46
+ options.help = true;
47
+ } else if (token === '--version' || token === '-v') {
48
+ options.version = true;
49
+ } else if (token === '--verbose') {
50
+ options.verbose = true;
51
+ } else if (token === '--json') {
52
+ options.json = true;
53
+ } else if (token === '--debug') {
54
+ options.debug = true;
55
+ } else if (token === '--entry' || token.startsWith('--entry=')) {
56
+ const value = token === '--entry' ? argv[(index += 1)] : token.slice('--entry='.length);
57
+ if (!value) throw new FcdevError('--entry 缺少地址', { code: 'ARGUMENT_INVALID' });
58
+ options.entries.push(value);
59
+ } else if (VALUE_OPTIONS[token.split('=')[0]]) {
60
+ const name = token.split('=')[0];
61
+ const value = token.includes('=') ? token.slice(name.length + 1) : argv[(index += 1)];
62
+ if (!value) throw new FcdevError(`${name} 缺少值`, { code: 'ARGUMENT_INVALID' });
63
+ options[VALUE_OPTIONS[name]] = value;
64
+ } else if (token === '--port' || token.startsWith('--port=')) {
65
+ const value = token === '--port' ? argv[(index += 1)] : token.slice('--port='.length);
66
+ const port = Number(value);
67
+ if (!Number.isInteger(port) || port < 1 || port > 65535) {
68
+ throw new FcdevError(`--port 需要 1 到 65535 之间的整数,实际为“${value ?? ''}”`, { code: 'ARGUMENT_INVALID' });
69
+ }
70
+ options.port = port;
71
+ } else if (token === '--target' || token.startsWith('--target=')) {
72
+ const value = token === '--target' ? argv[(index += 1)] : token.slice('--target='.length);
73
+ if (!value) throw new FcdevError('--target 缺少目标名', { code: 'ARGUMENT_INVALID' });
74
+ options.target = value;
75
+ } else if (token.startsWith('-')) {
76
+ throw new FcdevError(`未知的选项:${token}`, { code: 'ARGUMENT_INVALID', hint: '用 fcdev --help 查看可用的选项' });
77
+ } else if (command === null) {
78
+ command = token;
79
+ } else {
80
+ positionals.push(token);
81
+ }
82
+ }
83
+ return { command, positionals, options };
84
+ }
@@ -0,0 +1,34 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:build-command.mjs
3
+ // 说明:build 命令:按路径构建一个程序,输出进度与结果。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:工具(cc65、ca65、ld65)的输出原样写到标准错误,格式保持不变,供问题匹配器使用。
8
+ // ------------------------------------------------------------------------
9
+ import path from 'node:path';
10
+ import { buildPath } from '../../build/index.mjs';
11
+ import { FcdevError } from '../../shared/index.mjs';
12
+
13
+ /**
14
+ * 执行 build 命令。
15
+ * @param {{positionals: string[], options: {target?: string, verbose: boolean}, context: import('../index.mjs').CliContext}} input 参数与运行环境
16
+ * @returns {Promise<number>} 退出码
17
+ * @throws {FcdevError} 位置参数多于一个,或构建失败
18
+ */
19
+ export async function runBuildCommand({ positionals, options, context }) {
20
+ if (positionals.length > 1) {
21
+ throw new FcdevError('build 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev build [目录或文件]' });
22
+ }
23
+ const reporter = {
24
+ log: (message) => context.stdout.write(`${message}\n`),
25
+ write: (text) => context.stderr.write(text),
26
+ };
27
+ const { plan, result } = await buildPath(
28
+ { pathArg: positionals[0], cwd: context.cwd, targetOverride: options.target, env: context.env },
29
+ reporter,
30
+ );
31
+ const shown = path.relative(context.cwd, result.outputFile) || result.outputFile;
32
+ context.stdout.write(`已生成 ${shown}(${result.size} 字节,目标 ${plan.target.name},重新编译 ${result.compiled} 个文件,沿用 ${result.reused} 个)\n`);
33
+ return 0;
34
+ }
@@ -0,0 +1,70 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:debug-command.mjs
3
+ // 说明:debug 命令:把命令原样转发给模拟器的调试服务并打印应答。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:模拟器的工作目录与终端不同,命令里的相对路径(shot、disk、trace 等)先换成绝对路径;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699。
8
+ // ------------------------------------------------------------------------
9
+ import path from 'node:path';
10
+ import { DEFAULT_DEBUG_PORT, DebugClient } from '../../emulator/index.mjs';
11
+ import { FcdevError } from '../../shared/index.mjs';
12
+
13
+ /** 耗时长的命令使用的应答超时,单位毫秒 */
14
+ const LONG_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
15
+
16
+ /** 耗时长的命令 */
17
+ const LONG_COMMANDS = new Set(['run', 'step']);
18
+
19
+ /** 命令里路径参数的位置(命令名之后的第几个词,从 1 起);disk 的路径可含空格,取剩余全部 */
20
+ const PATH_POSITIONS = {
21
+ shot: 1,
22
+ disk: 1,
23
+ trace: 1,
24
+ io: 1,
25
+ disklog: 1,
26
+ calllog: 1,
27
+ savestate: 1,
28
+ loadstate: 1,
29
+ };
30
+
31
+ /**
32
+ * 把命令里的相对路径换成绝对路径。
33
+ * @param {string[]} tokens 命令的各个词
34
+ * @param {string} cwd 终端当前目录
35
+ * @returns {string[]} 处理后的词
36
+ */
37
+ export function resolveCommandPaths(tokens, cwd) {
38
+ const [name, ...rest] = tokens;
39
+ if (name === 'cdl' && rest[0] === 'save' && rest[1]) {
40
+ return [name, rest[0], path.resolve(cwd, rest[1]), ...rest.slice(2)];
41
+ }
42
+ const position = PATH_POSITIONS[name];
43
+ if (position === undefined || rest.length < position || rest[position - 1] === 'off') return tokens;
44
+ if (name === 'disk') return [name, path.resolve(cwd, rest.join(' '))];
45
+ const resolved = [...rest];
46
+ resolved[position - 1] = path.resolve(cwd, rest[position - 1]);
47
+ return [name, ...resolved];
48
+ }
49
+
50
+ /**
51
+ * 执行 debug 命令。
52
+ * @param {{positionals: string[], context: import('../index.mjs').CliContext}} input 调试命令的各个词与运行环境
53
+ * @returns {Promise<number>} 应答为 OK 时 0,否则 1
54
+ * @throws {FcdevError} 没有给命令,或无法连接调试服务
55
+ */
56
+ export async function runDebugCommand({ positionals, context }) {
57
+ if (positionals.length === 0) {
58
+ throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:fcdev debug status、fcdev debug run 60、fcdev debug shot out.png' });
59
+ }
60
+ const port = Number(context.env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
61
+ const tokens = resolveCommandPaths(positionals, context.cwd);
62
+ const client = await DebugClient.connect({ port });
63
+ try {
64
+ const reply = await client.send(tokens.join(' '), { timeoutMs: LONG_COMMANDS.has(tokens[0]) ? LONG_COMMAND_TIMEOUT_MS : undefined });
65
+ context.stdout.write(`${[reply.head, ...reply.lines].join('\n')}\n`);
66
+ return reply.ok ? 0 : 1;
67
+ } finally {
68
+ client.close();
69
+ }
70
+ }
@@ -0,0 +1,65 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:disasm-command.mjs
3
+ // 说明:disasm 命令:把 NES 程序或平铺二进制反汇编成 ca65 源码,并回读校验。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:iNES 文件读取 PRG 与中断向量,自动加入 NES 的 PPU 寄存器符号;平铺二进制必须指定加载地址与入口。
8
+ // ------------------------------------------------------------------------
9
+ import path from 'node:path';
10
+ import { disassemble } from '../../disasm/index.mjs';
11
+ import { loadProjectConfig } from '../../config/index.mjs';
12
+ import { FcdevError } from '../../shared/index.mjs';
13
+ import { BUILTIN_TARGETS_DIR } from '../../targets/index.mjs';
14
+ import { locateToolchain } from '../../toolchain/index.mjs';
15
+
16
+ /** 十六进制地址:可带 $ 或 0x 前缀,最多 4 位 */
17
+ const ADDRESS = /^(?:\$|0[xX])?([0-9A-Fa-f]{1,4})$/;
18
+
19
+ /**
20
+ * 解析命令行里的地址。
21
+ * @param {string} text 地址文本,如 8000、$8000、0x8000
22
+ * @param {string} option 选项名,用于出错提示
23
+ * @returns {number} 地址
24
+ * @throws {FcdevError} 不是合法的 16 位十六进制地址
25
+ */
26
+ export function parseAddress(text, option) {
27
+ const match = ADDRESS.exec(text);
28
+ if (!match) throw new FcdevError(`${option} 需要 16 位十六进制地址,实际为“${text}”`, { code: 'ARGUMENT_INVALID' });
29
+ return Number.parseInt(match[1], 16);
30
+ }
31
+
32
+ /**
33
+ * 执行 disasm 命令。
34
+ * @param {{positionals: string[], options: {format?: string, base?: string, cdl?: string, trace?: string, symbols?: string, out?: string, entries: string[]}, context: import('../index.mjs').CliContext}} input 参数与运行环境
35
+ * @returns {Promise<number>} 退出码
36
+ * @throws {FcdevError} 参数不合法、找不到工具链,或回读校验不一致
37
+ */
38
+ export async function runDisasmCommand({ positionals, options, context }) {
39
+ if (positionals.length !== 1) {
40
+ throw new FcdevError('disasm 需要一个输入文件', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--symbols 文件] [--out 目录]' });
41
+ }
42
+ const inputFile = path.resolve(context.cwd, positionals[0]);
43
+ const config = loadProjectConfig(context.cwd, context.cwd);
44
+ const toolchain = locateToolchain({ configured: config.toolchain, env: context.env });
45
+ const nesRegisters = path.join(BUILTIN_TARGETS_DIR, 'nes', 'asminc', 'fcnes.inc');
46
+
47
+ const report = await disassemble({
48
+ inputFile,
49
+ format: options.format,
50
+ base: options.base === undefined ? undefined : parseAddress(options.base, '--base'),
51
+ entries: options.entries.map((entry) => parseAddress(entry, '--entry')),
52
+ cdlFile: options.cdl === undefined ? undefined : path.resolve(context.cwd, options.cdl),
53
+ traceFile: options.trace === undefined ? undefined : path.resolve(context.cwd, options.trace),
54
+ symbolsFile: options.symbols === undefined ? undefined : path.resolve(context.cwd, options.symbols),
55
+ outDir: path.resolve(context.cwd, options.out ?? path.join('build', 'disasm', path.basename(inputFile, path.extname(inputFile)))),
56
+ toolchain,
57
+ includes: [nesRegisters],
58
+ });
59
+
60
+ for (const warning of report.warnings.slice(0, 10)) context.stderr.write(`警告:${warning}\n`);
61
+ if (report.warnings.length > 10) context.stderr.write(`警告:还有 ${report.warnings.length - 10} 条,省略\n`);
62
+ context.stdout.write(`${report.description}:${report.size} 字节,指令 ${report.instructions} 条(${report.codeBytes} 字节),其余 ${report.size - report.codeBytes} 字节按数据处理\n`);
63
+ context.stdout.write(`回读校验通过:重新汇编的结果与原映像逐字节一致\n已生成 ${path.relative(context.cwd, report.sourceFile) || report.sourceFile}\n`);
64
+ return 0;
65
+ }
@@ -0,0 +1,34 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:disk-command.mjs
3
+ // 说明:disk 命令:构建程序并把它放进磁盘镜像。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:只有声明了磁盘能力的目标可用;镜像生成在程序产物旁边。
8
+ // ------------------------------------------------------------------------
9
+ import path from 'node:path';
10
+ import { buildDiskImage, buildPath } from '../../build/index.mjs';
11
+ import { FcdevError } from '../../shared/index.mjs';
12
+
13
+ /**
14
+ * 执行 disk 命令。
15
+ * @param {{positionals: string[], options: {target?: string}, context: import('../index.mjs').CliContext}} input 参数与运行环境
16
+ * @returns {Promise<number>} 退出码
17
+ * @throws {FcdevError} 位置参数多于一个、目标不支持磁盘镜像,或构建失败
18
+ */
19
+ export async function runDiskCommand({ positionals, options, context }) {
20
+ if (positionals.length > 1) {
21
+ throw new FcdevError('disk 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev disk [目录或文件]' });
22
+ }
23
+ const reporter = {
24
+ log: (message) => context.stdout.write(`${message}\n`),
25
+ write: (text) => context.stderr.write(text),
26
+ };
27
+ const { plan, result } = await buildPath(
28
+ { pathArg: positionals[0], cwd: context.cwd, targetOverride: options.target, env: context.env },
29
+ reporter,
30
+ );
31
+ const { imageFile, size } = buildDiskImage(plan, result);
32
+ context.stdout.write(`已生成 ${path.relative(context.cwd, imageFile) || imageFile}(${size} 字节,含 ${path.basename(result.outputFile)})\n`);
33
+ return 0;
34
+ }
@@ -0,0 +1,33 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:info-command.mjs
3
+ // 说明:info 命令:显示当前项目的目标、工具链与头文件目录,--json 时输出机器可读格式。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:无
8
+ // ------------------------------------------------------------------------
9
+ import { describeProject } from './project-info.mjs';
10
+
11
+ /**
12
+ * 执行 info 命令。
13
+ * @param {{options: {target?: string, json: boolean}, context: import('../index.mjs').CliContext}} input 选项与运行环境
14
+ * @returns {Promise<number>} 退出码
15
+ */
16
+ export async function runInfoCommand({ options, context }) {
17
+ const info = await describeProject({ cwd: context.cwd, targetOverride: options.target, env: context.env });
18
+ if (options.json) {
19
+ context.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
20
+ return 0;
21
+ }
22
+ const lines = [
23
+ `项目根目录:${info.root}`,
24
+ `配置文件:${info.configFile ?? '(无)'}`,
25
+ `目标:${info.target.name}(${info.target.title})`,
26
+ `工具链:${info.toolchain.home}(${info.toolchain.source},${info.toolchain.version})`,
27
+ `输出目录:${info.outDir}`,
28
+ `头文件目录:\n ${info.includeDirs.join('\n ')}`,
29
+ `汇编引入目录:\n ${info.asmIncludeDirs.join('\n ')}`,
30
+ ];
31
+ context.stdout.write(`${lines.join('\n')}\n`);
32
+ return 0;
33
+ }