@8bitscript/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8BitScript contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/8bs.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// The `8bs` entry point — thin dispatch to each subcommand's own module in
+// ../src/; see each one for what it actually does. `check` runs the
+// compiler's diagnostics over files; `lsp` starts the language server on
+// stdio for an editor to drive. Both go through @8bitscript/compiler, which
+// is the point: one set of rules, reported in the terminal, in CI, and
+// under the cursor.
+const [, , command, ...rest] = process.argv;
+
+const IMPLEMENTED = new Set(['check', 'lsp', 'doctor', 'build', 'run', 'setup', 'targets']);
+const PLANNED = ['dev'];
+
+const usage = () => `Usage: 8bs <command> [options]
+
+Implemented:
+  build --target <t> [--pal] [--profile <name>]
+    [--hardware option=value,...] [entry]
+                               Compile for a target: vic20, c64, pet, c128,
+                               atari8, nes, cx16, mega65, or web. vic20/c64/
+                               c128/mega65/atari8 default to NTSC (60Hz) at
+                               run time; --pal selects the PAL (50Hz)
+                               machine model (the pet has no region: its
+                               model is hardware). --profile names the
+                               hardware fitted — a preset from the machine's
+                               catalog (8032, 130xe, reu512) or a profile the
+                               project composes in 8bs.config.ts — and
+                               --hardware sets single options on top
+                               (ram=8k, port1=mouse1351). "8bs targets"
+                               lists every option, value and preset.
+  run <target> [--pal] [--profile <name>]
+    [--hardware option=value,...] [entry]
+                               Build, then open that target's emulator
+                               (VICE for vic20/c64/pet/c128, atari800,
+                               fceux, x16emu, or Xemu for mega65) at the
+                               right machine model — or execute the .wasm
+                               and print its state (web)
+    [--screenshot <file.png>] Instead of an interactive window, capture one
+    [--frames <n>]             screenshot through the target's own emulator
+                               API (or, for atari8 only, a macOS window
+                               capture — see docs/setup/verify.md#screenshots).
+                               --frames means a different unit per target
+                               (cycles, wall-clock seconds, or exact
+                               frame-advances); omit it for a tested default.
+  targets [--json]             List every target and the hardware it can be
+                               fitted with — options, values, presets, and
+                               this project's own profiles; --json is what
+                               the editor reads
+  check <files...>             Report diagnostics for 8BitScript source files
+  doctor                       Verify the toolchains every target needs
+  setup <target>               Install/configure what a target needs beyond
+    [--rom <path>]             what doctor can offer as a single package-
+    [--c64-forever <msi>]      manager command. mega65 builds Xemu from
+    [--rom-patch <zip>]        source on macOS (Homebrew) and Arch/Manjaro
+    [--repair] [--update]      (pacman), then installs a MEGA65 ROM: --rom
+                               points at an already-generated MEGA65.ROM
+                               (the primary path); --c64-forever/--rom-patch
+                               generate one from a C64 Forever MSI instead
+                               — docs/setup/mega65.md. cx16 builds x16emu and
+                               a matching ROM from upstream source into
+                               /opt/commander-x16 (--repair fixes a broken
+                               launcher, --update rebuilds the pair —
+                               docs/setup/cx16.md)
+  lsp [--stdio]                Start the language server on stdio
+
+Planned, not implemented:
+  ${PLANNED.join(', ')}
+
+The compiler covers the first-milestone subset of the language: globals,
+functions, arithmetic, control flow, @address hardware access, and asm6502
+blocks. Constructs beyond that fail with a message. See docs/compiler.md.
+`;
+
+if (!command || command === '--help' || command === '-h') {
+  process.stdout.write(usage());
+  process.exit(command ? 0 : 1);
+}
+
+if (command === '--version' || command === '-v') {
+  const { readFileSync } = await import('node:fs');
+  const { dirname, join } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const pkg = JSON.parse(
+    readFileSync(join(dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8'),
+  );
+  process.stdout.write(`8bs ${pkg.version}\n`);
+  process.exit(0);
+}
+
+if (command === 'check') {
+  const { check } = await import('../src/check.mjs');
+  process.exit(await check(rest.filter((a) => !a.startsWith('-'))));
+}
+
+if (command === 'doctor') {
+  const { doctor } = await import('../src/doctor.mjs');
+  process.exit(await doctor());
+}
+
+if (command === 'build') {
+  const { build } = await import('../src/build.mjs');
+  process.exit(await build(rest));
+}
+
+if (command === 'run') {
+  const { run } = await import('../src/run.mjs');
+  process.exit(await run(rest));
+}
+
+if (command === 'targets') {
+  const { targets } = await import('../src/targets.mjs');
+  process.exit(await targets(rest));
+}
+
+if (command === 'setup') {
+  const { setup } = await import('../src/setup.mjs');
+  process.exit(await setup(rest));
+}
+
+if (command === 'lsp') {
+  // --stdio is accepted because every editor passes it by convention; stdio is
+  // the only transport, so there is nothing to select.
+  const { start } = await import('@8bitscript/language-server');
+  start();
+} else {
+  const known = IMPLEMENTED.has(command) || PLANNED.includes(command);
+  process.stderr.write(
+    known
+      ? `8bs ${command}: not implemented yet.\nThe compiler has no parser or backend yet, so there is nothing to ${command}.\n`
+      : `8bs: unknown command '${command}'\n\n${usage()}`,
+  );
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@8bitscript/cli",
+  "version": "0.1.0",
+  "description": "The 8bs command line interface: builds, runs, and diagnoses 8BitScript projects.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=26"
+  },
+  "bin": {
+    "8bs": "./bin/8bs.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "@8bitscript/atari8": "0.1.0",
+    "@8bitscript/backend-6502": "0.1.0",
+    "@8bitscript/backend-web": "0.1.0",
+    "@8bitscript/c128": "0.1.0",
+    "@8bitscript/c64": "0.1.0",
+    "@8bitscript/compiler": "0.1.0",
+    "@8bitscript/cx16": "0.1.0",
+    "@8bitscript/language-server": "0.1.0",
+    "@8bitscript/mega65": "0.1.0",
+    "@8bitscript/nes": "0.1.0",
+    "@8bitscript/pet": "0.1.0",
+    "@8bitscript/studio": "0.1.0",
+    "@8bitscript/vic20": "0.1.0",
+    "@8bitscript/web": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/build.mjs

@@ -0,0 +1,309 @@
+// `8bs build` — compile a program for a target.
+//
+//     8bs build --target vic20        [entry.8bs]   NTSC (60Hz), the default
+//     8bs build --target vic20 --pal  [entry.8bs]
+//     8bs build --target web          [entry.8bs]
+//     8bs build --target atari8 --profile 130xe [entry.8bs]
+//     8bs build --target vic20 --profile 16k    [entry.8bs]
+//     8bs build --target c64 --profile reu512   [entry.8bs]
+//     8bs build --target pet --profile 8032     [entry.8bs]   80 columns, 32K
+//
+// The system (vic20/c64/pet/c128/atari8/nes/cx16/mega65/web) is the target;
+// NTSC/PAL is a --pal/--ntsc option on top of it, not a separate flavor of
+// the target, because it changes the emulator's machine model at run time
+// and nothing about the build — see the comment on MODEL_ARGS in run.mjs
+// for why that still means picking a whole machine model rather than just a
+// sync-factor flag. It only applies to targets with a real region split
+// (see REGION_TARGETS below); it's silently ignored everywhere else, the
+// same as it already was for web. "NTSC (60Hz)" above is the emulator's real
+// hardware region, not the language's logical frame rate — that's a
+// separate, project-level setting (`frameRate` in 8bs.config.ts, default 60,
+// see packages/backend-6502's FRAME_SYNC and examples/borders/README.md),
+// unaffected by --pal.
+//
+// --profile names the hardware the build is for: a preset from the
+// machine package's catalog (`8032`, `130xe`, `reu512` — the community's
+// names for whole configurations) or a profile the project composes in
+// its 8bs.config.ts (`targets: { c64: { profiles: { loaded: { ram:
+// 'reu512', port1: 'mouse1351' } } } }`). --hardware option=value,...
+// sets single options on top of either. What each option changes — a
+// link symbol, a driver, an emulator flag, a fact a program can read — is
+// the catalog's to say; see packages/cli/src/hardware.mjs and
+// docs/systems.md. `8bs targets` lists every option and preset.
+//
+// The entry defaults to src/main.8bs, or to the `entry` in 8bs.config.ts when
+// the project has one — and whichever file that names, a `.<target>.8bs`
+// twin beside it (main.nes.8bs next to main.8bs) is what a build for that
+// target actually starts from; see resolveEntryPath. Output lands in dist/, named
+// <name>-<machine>[-<hardware>...][-<region>].<ext> — .prg for the Commodore/
+// CX16/MEGA65 targets, .xex (or .rom for an XEGS cartridge) for Atari 8-bit,
+// .nes for the NES, .wasm for the web — with the generated C or
+// AssemblyScript beside it so what the compiler did is never a mystery.
+// Only hardware that changes the *build* is in the name (a PET's model, a
+// VIC-20's RAM): a mouse or a REU makes the same program, so it is not.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+
+import {
+  MACHINES, isVariantPath, link, positionAt, variantOf,
+  unmetRequirements,
+} from '@8bitscript/compiler';
+
+import { loadConfig, resolveFrameRate } from './config.mjs';
+import {
+  HARDWARE_USAGE, REGION_MACHINES, hardwareArgs, listedTargets, loadCatalog, projectHardware,
+  projectProfiles, projectRequires, projectSystems, resolveHardware, whatSatisfies,
+} from './hardware.mjs';
+
+const TARGETS = new Set(MACHINES);
+
+// The targets whose frame-sync strategy has a real NTSC/PAL split, auto-
+// detected at runtime (packages/backend-6502's FRAME_SYNC 'level' machines)
+// — the only ones where --pal changes the build or a region suffix on the
+// output filename. The PET has no region at all: its refresh is the
+// model's (a hardware option — see packages/pet/package.json's catalog),
+// FRAME_SYNC.pet measures it at start-up, and `8bs run pet` says so if
+// given --pal. It is the same set `8bs targets` reports a region for, so
+// there is one of it (hardware.mjs).
+const REGION_TARGETS = REGION_MACHINES;
+
+// Diagnostics may come from any module in the import graph, so each one is
+// rendered against its own file's text, not the entry's.
+function printDiagnostics(diagnostics, sources) {
+  for (const d of diagnostics) {
+    const { line, column } = positionAt(sources.get(d.file) ?? '', d.start);
+    process.stdout.write(`${basename(d.file)}:${line}:${column}\n`);
+    process.stdout.write(`${d.severity} ${d.code}: ${d.message}\n\n`);
+  }
+}
+
+// The old target names, kept only to point people at their replacement
+// rather than failing with a bare "unknown target".
+const RETIRED_TARGET = /^(vic20|c64)-(ntsc|pal)$/;
+
+// `entry` in 8bs.config.ts is one path, shared by every target, and the
+// filename rule does the rest: a project whose entry point genuinely has to
+// differ on one machine — its execution model, its screen codes, its grid
+// — puts that machine's version beside the shared file as
+// `main.<target>.8bs`, and a build for that target starts there instead.
+// The same rule applies to every file the entry imports, so this is not a
+// special case for the entry; it is just where the CLI applies it first.
+// The rule is applied to whatever names the entry — the config, the
+// default, or an explicit argument — unless that path already names one
+// machine's version (`8bs build src/main.nes.8bs`), which is taken as is.
+//
+// `entry` may still be an object keyed by machine (`{ default, nes }`), the
+// older spelling of the same idea, kept working for projects that use it;
+// `default` covers whichever targets aren't named.
+export function resolveEntryPath(config, target, entryArg) {
+  let entry = config?.entry;
+  if (entry && typeof entry === 'object') entry = entry[target] ?? entry.default;
+  const path = resolve(entryArg ?? entry ?? 'src/main.8bs');
+  if (isVariantPath(path)) return path;
+  const variant = variantOf(path, target);
+  return existsSync(variant) ? variant : path;
+}
+
+/**
+ * Compile one entry file for one target.
+ *
+ * @param {'vic20'|'c64'|'pet'|'c128'|'atari8'|'nes'|'cx16'|'mega65'|'web'} target
+ * @param {string} [entryArg]
+ * @param {{ pal?: boolean, profile?: string, hardware?: object }} [options] `pal` selects the
+ *   real hardware/emulator region (NTSC unless true; ignored outside
+ *   REGION_TARGETS) — it does not affect the logical frame rate, which is
+ *   read from 8bs.config.ts's `frameRate` instead (default 60). `profile`
+ *   names a project profile or a catalog preset, `hardware` is option
+ *   values set on top (`--hardware`); see hardware.mjs.
+ * @returns {Promise<{ ok: boolean, outFile?: string, frameRate?: number, hardware?: object }>}
+ *   `hardware` is the resolved hardware the program was built for, for
+ *   whoever runs it next.
+ */
+export async function compile(target, entryArg, { pal = false, profile, hardware: overrides = {} } = {}) {
+  const config = await loadConfig(process.cwd(), '8bs build');
+
+  const frameRateResult = resolveFrameRate(config);
+  if (!frameRateResult.ok) {
+    process.stderr.write(`8bs build: ${frameRateResult.error}\n`);
+    return { ok: false };
+  }
+  const { frameRate } = frameRateResult;
+
+  // Nothing in a build reads the `systems` block, but a typo in one should
+  // not wait for someone to open the editor to be noticed. Said once, and
+  // not fatal: the build asked for is still the build to make.
+  const systems = projectSystems(config);
+  if (!systems.ok) process.stderr.write(`8bs build: ${systems.error}\n`);
+
+  const retired = RETIRED_TARGET.exec(target ?? '');
+  if (retired) {
+    process.stderr.write(
+      `8bs build: '${target}' is no longer a target. Use '${retired[1]}'` +
+      `${retired[2] === 'pal' ? " with '--pal'" : ' (NTSC is the default)'} instead.\n`,
+    );
+    return { ok: false };
+  }
+  if (!TARGETS.has(target)) {
+    process.stderr.write(
+      `8bs build: unknown target '${target}'. Targets: ${[...TARGETS].join(', ')}\n`,
+    );
+    return { ok: false };
+  }
+  const listed = listedTargets(config);
+  if (listed && !listed.includes(target)) {
+    process.stderr.write(
+      `8bs build: this project's 8bs.config.ts does not list '${target}' ` +
+      `(targets: ${listed.join(', ')})\n`,
+    );
+    return { ok: false };
+  }
+
+  const resolved = resolveHardware(loadCatalog(target), {
+    profile, overrides, profiles: projectProfiles(config, target), defaults: projectHardware(config, target),
+  });
+  if (!resolved.ok) {
+    process.stderr.write(`8bs build: ${resolved.error}\n`);
+    return { ok: false };
+  }
+  const { hardware } = resolved;
+
+  // What the program needs of the machine, before the machine gets a
+  // chance to disappoint it. A program that cannot run in the RAM it was
+  // given fails at the linker with an overflow measured in bytes of
+  // section; this says the same thing in the program's own terms, names
+  // what it asked for, and — the useful half — what this machine could be
+  // fitted with that would do.
+  const required = projectRequires(config);
+  if (!required.ok) {
+    process.stderr.write(`8bs build: ${required.error}\n`);
+    return { ok: false };
+  }
+  const unmet = unmetRequirements(required.requires, hardware.facts);
+  if (unmet.length > 0) {
+    const catalog = loadCatalog(target);
+    process.stderr.write(
+      `8bs build: this program asks for more than a ${hardware.label === 'stock' ? `stock ${target}` : `${target} with ${hardware.label}`} gives.\n`,
+    );
+    for (const { key, need, have } of unmet) {
+      process.stderr.write(
+        `  ${key}: needs ${need === true ? 'it' : need}, this build has ${have === true ? 'it' : have}\n`,
+      );
+      const fits = whatSatisfies(catalog, key, need, {
+        profile, overrides, profiles: projectProfiles(config, target), defaults: projectHardware(config, target),
+      });
+      process.stderr.write(fits.length > 0
+        ? `    fit one of: ${fits.join(', ')}  (--hardware, or a system in 8bs.config.ts)\n`
+        : `    no ${target} can be fitted with that; this program is not for this machine\n`);
+    }
+    return { ok: false };
+  }
+
+  const entry = resolveEntryPath(config, target, entryArg);
+  if (!existsSync(entry)) {
+    process.stderr.write(`8bs build: entry ${entry} does not exist\n`);
+    return { ok: false };
+  }
+
+  const text = await readFile(entry, 'utf8');
+
+  // The linker runs the full front end over the entry and everything it
+  // imports, then merges the graph into one program. Any error in any module
+  // means no build. The machine rides along so packages with target-
+  // conditional entries resolve to this machine's implementation, and the
+  // hardware's facts so every `#fact(...)` — the sheet @8bitscript/system
+  // declares — folds to this build's value, and the
+  // hardware's tags so a file with a `.<machine>.<tag>.8bs` twin resolves
+  // to that.
+  const { ir, diagnostics, sources } = link(text, entry, { machine: target, tags: hardware.tags, facts: hardware.facts, frameRate });
+  if (diagnostics.length > 0) {
+    printDiagnostics(diagnostics, sources);
+    process.stdout.write(`${diagnostics.length} problem(s); not building.\n`);
+    return { ok: false };
+  }
+
+  // A target's own entry file is named after it (main.nes.8bs — see
+  // resolveEntryPath); the output name carries the target once, in the
+  // same place every other target's does, so main.nes.8bs builds to
+  // main-nes.nes just as main.8bs does, not to main.nes-nes.nes.
+  let stem = basename(entry, '.8bs');
+  if (stem.endsWith(`.${target}`)) stem = stem.slice(0, -(target.length + 1));
+  if (target === 'web') {
+    const { buildWasm } = await import('@8bitscript/backend-web');
+    const outFile = resolve('dist', `${stem}.wasm`);
+    const result = await buildWasm(ir, { outFile });
+    if (!result.ok) {
+      process.stderr.write(`8bs build: ${result.error}\n`);
+      return { ok: false };
+    }
+    const { writeWebBundle } = await import('./web-runtime.mjs');
+    const webDir = resolve('dist', 'web');
+    await writeWebBundle(webDir, await readFile(outFile), { frameRate });
+    process.stdout.write(`built ${outFile}\n(generated AssemblyScript: ${result.asFile})\n`);
+    process.stdout.write(`web bundle: ${webDir}/\n`);
+    process.stdout.write(`${memoryLine(ir.memory)}\n`);
+    return { ok: true, outFile, frameRate, hardware, webDir };
+  }
+
+  const { buildPrg, outputExtension } = await import('@8bitscript/backend-6502');
+  // Hardware that changes the build is in the name (an 8032 PET, an
+  // expanded VIC-20, an XEGS cartridge); hardware that only changes the
+  // emulator is not, because the file is the same file.
+  const nameParts = [stem, target, ...hardware.buildValues];
+  if (REGION_TARGETS.has(target)) nameParts.push(pal ? 'pal' : 'ntsc');
+  const ext = outputExtension(target, hardware);
+  const outFile = resolve('dist', `${nameParts.join('-')}.${ext}`);
+  const result = await buildPrg(ir, { machine: target, hardware, outFile, frameRate });
+  if (!result.ok) {
+    process.stderr.write(`8bs build: ${result.error}\n`);
+    return { ok: false };
+  }
+  process.stdout.write(`built ${outFile}\n(generated C: ${result.cFile})\n`);
+  process.stdout.write(`${memoryLine(ir.memory, result.memory)}\n`);
+  return { ok: true, outFile, frameRate, hardware };
+}
+
+/**
+ * The memory line under "built": how much RAM the program's variables
+ * take and how much constant data it carries. Measured from the linked
+ * program when the backend could (the 6502 backend reads the ELF; a
+ * variable LLVM dropped for being unread is not counted), else as
+ * declared in the source. The machine's own limit is the toolchain's:
+ * a program that does not fit does not build, and the build says so.
+ */
+export function memoryLine(declared, measured = null) {
+  if (measured) {
+    return `memory: ${measured.variables} bytes of RAM for variables, ${measured.program} bytes of program (code and data)`;
+  }
+  return `memory: ${declared.variables} bytes of RAM for variables, ${declared.data} bytes of constant data (as declared)`;
+}
+
+/** @returns {Promise<number>} exit code */
+export async function build(args) {
+  const pal = args.includes('--pal');
+  const targetIndex = args.indexOf('--target');
+  const hw = hardwareArgs(args);
+  if (!hw.ok) {
+    process.stderr.write(`8bs build: ${hw.error}\n`);
+    return 2;
+  }
+  const positionals = args.filter((a, i) => {
+    if (targetIndex >= 0 && (i === targetIndex || i === targetIndex + 1)) return false;
+    if (hw.consumed.has(i)) return false;
+    return !a.startsWith('-');
+  });
+  const target = targetIndex >= 0 ? args[targetIndex + 1] : positionals[0];
+  const entry = targetIndex >= 0 ? positionals[0] : positionals[1];
+
+  if (!target) {
+    process.stderr.write(
+      'Usage: 8bs build --target <vic20|c64|pet|c128|atari8|nes|cx16|mega65|web>\n'
+      + '                 [--pal]\n'
+      + HARDWARE_USAGE
+      + '                 [entry.8bs]\n',
+    );
+    return 2;
+  }
+  const { ok } = await compile(target, entry, { pal, profile: hw.profile, hardware: hw.overrides });
+  return ok ? 0 : 1;
+}

package/src/check.mjs

@@ -0,0 +1,67 @@
+// `8bs check` — run the compiler's diagnostics over files and print them.
+//
+// The output format is the one the editor shows, in terminal form. Both come
+// from the same analyze() call, so a green `8bs check` and a clean editor mean
+// the same thing.
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+
+import { analyze, positionAt } from '@8bitscript/compiler';
+
+import { loadConfig, resolveFrameRate } from './config.mjs';
+
+/**
+ * @param {string[]} files
+ * @returns {Promise<number>} process exit code
+ */
+export async function check(files) {
+  if (files.length === 0) {
+    process.stderr.write('8bs check: no files given\n\nUsage: 8bs check <file.8bs> [...]\n');
+    return 2;
+  }
+
+  // The same project-level `frameRate` a build would use (8bs.config.ts,
+  // default 60) — `#frames(...)` folds against it, so a project's `8bs
+  // check` and its `8bs build` agree on what a duration means. There is no
+  // per-project config for the language server yet (no workspace-root
+  // concept to load 8bs.config.ts from), so its diagnostics still assume 60
+  // until that's picked up as follow-up work.
+  const config = await loadConfig(process.cwd(), '8bs check');
+  const frameRateResult = resolveFrameRate(config);
+  if (!frameRateResult.ok) {
+    process.stderr.write(`8bs check: ${frameRateResult.error}\n`);
+    return 2;
+  }
+  const { frameRate } = frameRateResult;
+
+  let total = 0;
+
+  for (const file of files) {
+    const path = resolve(file);
+    let text;
+    try {
+      text = await readFile(path, 'utf8');
+    } catch {
+      process.stderr.write(`8bs check: cannot read ${file}\n`);
+      total += 1;
+      continue;
+    }
+
+    const display = relative(process.cwd(), path) || file;
+    // Resolution needs the real path; the display path is only for printing.
+    for (const d of analyze(text, path, { resolveImports: true, frameRate })) {
+      const { line, column } = positionAt(text, d.start);
+      process.stdout.write(`${display}:${line}:${column}\n`);
+      process.stdout.write(`${d.severity} ${d.code}: ${d.message}\n\n`);
+      total += 1;
+    }
+  }
+
+  if (total === 0) {
+    process.stdout.write(`Checked ${files.length} file(s). No problems found.\n`);
+    return 0;
+  }
+
+  process.stdout.write(`${total} problem(s) found.\n`);
+  return 1;
+}

package/src/config.mjs

@@ -0,0 +1,46 @@
+// Shared 8bs.config.ts loading, used by both `8bs build` and `8bs check` (and,
+// through them, anything else that needs a project's config without
+// duplicating the loader).
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * The project's 8bs.config.ts, if present. Node 26 imports TypeScript with
+ * type stripping, so the config is an ordinary module, not a parsed format.
+ *
+ * @param {string} dir
+ * @param {string} [label] Prefixes a load error, e.g. "8bs build".
+ */
+export async function loadConfig(dir, label = '8bs') {
+  const path = join(dir, '8bs.config.ts');
+  if (!existsSync(path)) return null;
+  try {
+    const module = await import(pathToFileURL(path).href);
+    return module.default ?? null;
+  } catch (error) {
+    process.stderr.write(`${label}: cannot load 8bs.config.ts: ${error.message}\n`);
+    return null;
+  }
+}
+
+/**
+ * The project's logical frame rate — what `waitFrame()` runs at, the same on every target,
+ * independent of --pal (which only selects a real hardware/emulator
+ * region, not the logical rate; see packages/backend-6502's FRAME_SYNC).
+ * Defaults to 60; `#frames(...)` durations and the waitFrame() runtime are
+ * both built against whatever this resolves to.
+ *
+ * @param {object|null} config
+ * @returns {{ ok: true, frameRate: number } | { ok: false, error: string }}
+ */
+export function resolveFrameRate(config) {
+  const frameRate = config?.frameRate ?? 60;
+  if (!Number.isInteger(frameRate) || frameRate <= 0) {
+    return {
+      ok: false,
+      error: `8bs.config.ts's frameRate must be a positive integer, got ${JSON.stringify(config?.frameRate)}`,
+    };
+  }
+  return { ok: true, frameRate };
+}