c64bridge 0.5.0

package/dist/rag/retriever.js

@@ -0,0 +1,74 @@
+/*
+C64 Bridge - Local RAG Retriever
+GPL-2.0-only
+*/
+import { cosineSimilarity } from "./embeddings.js";
+const BASIC_SIGNAL_RE = /(^\s*\d{1,5}\s)|\b(PRINT|POKE|GOTO|GOSUB|RESTORE|READ|DATA|INPUT|CHR\$|TI\$|TAB\()/im;
+const ASM_SIGNAL_RE = /(^\s*(?:[A-Z_][\w]*:)?\s*(?:\.?[A-Z]{2,4})\b)|\$[0-9A-F]{2,4}/im;
+export class LocalRagRetriever {
+    constructor(model, opts) {
+        this.model = model;
+        this.basic = opts.basic;
+        this.asm = opts.asm;
+        this.mixed = opts.mixed;
+        this.hardware = opts.hardware;
+        this.other = opts.other;
+    }
+    updateIndexes(opts) {
+        this.basic = opts.basic;
+        this.asm = opts.asm;
+        this.mixed = opts.mixed;
+        this.hardware = opts.hardware;
+        this.other = opts.other;
+    }
+    async retrieve(query, topK = 3, filterLanguage) {
+        const qv = await this.model.embed(query);
+        const candidates = [];
+        const consider = (index) => {
+            if (!index)
+                return;
+            for (const rec of index.records) {
+                const matchesBasic = BASIC_SIGNAL_RE.test(rec.text);
+                const matchesAsm = ASM_SIGNAL_RE.test(rec.text);
+                if (normalized === "basic" && !matchesBasic) {
+                    continue;
+                }
+                if (normalized === "asm" && !matchesAsm) {
+                    continue;
+                }
+                let score = cosineSimilarity(qv, new Float32Array(rec.vector));
+                if (normalized === "basic" && matchesBasic) {
+                    score += 0.05;
+                }
+                else if (normalized === "asm" && matchesAsm) {
+                    score += 0.05;
+                }
+                candidates.push({ score, text: rec.text });
+            }
+        };
+        const normalized = filterLanguage;
+        const seen = new Set();
+        const push = (index) => {
+            if (!index || seen.has(index))
+                return;
+            seen.add(index);
+            consider(index);
+        };
+        if (!normalized || normalized === "basic")
+            push(this.basic);
+        if (!normalized || normalized === "asm")
+            push(this.asm);
+        if (!normalized || normalized === "mixed")
+            push(this.mixed);
+        if (normalized === "basic" && (!this.basic || this.basic.records.length === 0))
+            push(this.mixed);
+        if (normalized === "asm" && (!this.asm || this.asm.records.length === 0))
+            push(this.mixed);
+        if (!normalized || normalized === "hardware")
+            push(this.hardware);
+        if (!normalized || normalized === "other")
+            push(this.other);
+        candidates.sort((a, b) => b.score - a.score);
+        return candidates.slice(0, topK).map((c) => c.text);
+    }
+}

package/dist/rag/sources.csv

@@ -0,0 +1,31 @@
+type,description,link,depth
+assembly,C64 ASM Book Listings,https://github.com/64kramsystem/c64_asm_book_listings/tree/master/machine_code_games_routines_for_the_commodore_64,10
+assembly,Assorted C64 assembly samples (Make builds PRG),https://github.com/jarrodparkes/c64-examples,10
+assembly,C64 Users Guide ML examples (ACME asm),https://github.com/lacerto/c64_users_guide_examples,10
+assembly,CHIP-8 interpreter for C64 (includes D64/PRG),https://github.com/kschuetz/c64-chip8,10
+assembly,Elite (C64) fully documented sources + D64 builds,https://github.com/markmoxon/elite-source,10
+assembly,Examples in 61002 assembly (PRG build via Make),https://github.com/digitsensitive/c64,10
+#assembly,Fully commented ROM disassembly (master .txt sources),https://github.com/lagomorph/c64rom,10
+assembly,Fully commented ROM disassembly (text),https://www.zimmers.net/anonftp/pub/cbm/src/c64/c64_rom_disassembly.txt,2
+#assembly,Kernel disassembly (text),https://raw.githubusercontent.com/androdev4u/c64rom/refs/heads/master/c64disasm/c64disasm_cbm.txt,1
+#assembly,Original C64 BASIC+KERNAL source (buildable),https://github.com/mist64/c64rom,10
+assembly,Sample programs using Kick Assembler,https://github.com/nealvis/c64_samples_kick,10
+assembly,Simple ASM tutorial series (multiple examples),https://github.com/Ziagl/C64-Assembler,10
+assembly,Starfield demo including PRG,https://github.com/Starcross/starfield,10
+assembly,Various small assembly programs (ACME/PRG),https://github.com/cslarsen/c64-examples,10
+assembly,Machine Language for the Commodore 64,https://www.retro-commodore.eu/files/development/c64-development/Butterfield_Machine_Language_for_the_Commodore_64_and_other_Commodore_Computers.ocr.txt,1
+assembly,C64 Programmer’s Reference Guide (text dump),https://www.zimmers.net/cbmpics/cbm/c64/c64prg.txt,1
+basic,Assorted C64 BASIC sources and PRGs,https://github.com/spiroharvey/c64,10
+basic,BASIC demo PRGs,https://www.zimmers.net/anonftp/pub/cbm/c64/demos/generic/poor/,2
+basic,C64 type-in programs from Compute!/Gazette (includes .prg and .bas),https://github.com/xopowoparvo/C64-type-in-programs,10
+basic,Collection of BASIC programs (PRG + ASCII),https://github.com/robfromoz/C64-BASIC,10
+#basic,Compute!'s Gazette disks (.d64) – complete archive,https://archive.org/details/computes.gazette,1
+#basic,Misc BASIC programs by Howard Feldman (miscprog.txt),https://www.zimmers.net/anonftp/pub/cbm/c64/utilities/miscprog.lnx.gz,1
+basic,Simple C64 BASIC and Assembly examples,https://github.com/cslarsen/c64-examples,10
+basic,Snake clone in pure C64 BASIC (snake.bas),https://github.com/StefanHolmes/C64-Snake,10
+hardware,Ultimate C64 Reference Guide,https://github.com/mist64/c64ref,10
+hardware,61002 CPU notes (text),https://raw.githubusercontent.com/androdev4u/c64rom/refs/heads/master/61002/cpu_61002.txt,1
+hardware,Mapping the C64,https://www.zimmers.net/anonftp/pub/cbm/c64/manuals/mapping-c64.txt,1
+hardware,C64 Service Manual (text),https://www.zimmers.net/cbmpics/cbm/c64/C64ServiceManual.txt,1
+hardware,Commodore 64 memory map (text),https://www.zimmers.net/anonftp/pub/cbm/maps/C64.MemoryMap.txt,1
+hardware,VIC-II controller documentation (text),https://www.zimmers.net/cbmpics/cbm/c64/vic-ii.txt,1

package/dist/rag/types.js

@@ -0,0 +1,5 @@
+/*
+C64 Bridge - Local RAG Types
+GPL-2.0-only
+*/
+export {};

package/dist/rag/urlUtils.js

@@ -0,0 +1,38 @@
+/*
+C64 Bridge - URL/domain utilities
+GPL-2.0-only
+*/
+import { URL } from 'node:url';
+/**
+ * Very small public-suffix-like heuristic to derive the registered domain.
+ * Avoids extra deps; not perfect but works for common TLDs.
+ */
+export function getRegisteredDomain(hostname) {
+    const parts = hostname.toLowerCase().split('.');
+    if (parts.length <= 2)
+        return hostname.toLowerCase();
+    const tld = parts.slice(-2).join('.');
+    // Handle some common multi-part TLDs
+    const multi = new Set([
+        'co.uk', 'ac.uk', 'gov.uk', 'org.uk', 'co.jp', 'com.au', 'net.au', 'org.au',
+    ]);
+    if (multi.has(parts.slice(-3).join('.'))) {
+        return parts.slice(-3).join('.');
+    }
+    return tld;
+}
+export function parseUrlSafe(input) {
+    try {
+        return new URL(input);
+    }
+    catch {
+        return null;
+    }
+}
+export function sameRegisteredDomain(a, b) {
+    const ua = parseUrlSafe(a);
+    const ub = parseUrlSafe(b);
+    if (!ua || !ub)
+        return false;
+    return getRegisteredDomain(ua.hostname) === getRegisteredDomain(ub.hostname);
+}

package/dist/sidplayRunner.js

@@ -0,0 +1,240 @@
+/*
+ * sidplayfp Runner Utility for converting SID files to WAV output.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+export class SidplayExecutionError extends Error {
+    constructor(options) {
+        const first = options.stderr.subarray(0, 1000).toString("utf8");
+        const last = options.stderr.length > 1000
+            ? options.stderr.subarray(options.stderr.length - 1000).toString("utf8")
+            : "";
+        super(`${options.message}\n` +
+            `command: ${options.command}\n` +
+            `exitCode: ${String(options.exitCode)}\n` +
+            `stderr(first 1000):\n${first}\n` +
+            (last ? `stderr(last 1000):\n${last}\n` : "") +
+            `wav: exists=${options.wavExists}, size=${options.wavSize}`);
+        this.name = "SidplayExecutionError";
+        this.command = options.command;
+        this.exitCode = options.exitCode;
+        this.stderrFirst = first;
+        this.stderrLast = last;
+        this.wavExists = options.wavExists;
+        this.wavSize = options.wavSize;
+    }
+}
+function resolveMode(input) {
+    const envMode = (process.env.SIDPLAY_MODE || "").toLowerCase();
+    const raw = (input || envMode || "ntsc").toLowerCase();
+    return raw === "pal" ? "pal" : "ntsc";
+}
+function resolveLimitCycles(input) {
+    const fromEnv = Number(process.env.SIDPLAY_LIMIT_CYCLES);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return Math.floor(fromEnv);
+    if (typeof input === "number" && input > 0)
+        return Math.floor(input);
+    return 120000000;
+}
+function resolveBinary(input) {
+    return process.env.SIDPLAY_BINARY || process.env.SIDPLAYFP_BINARY || input || "sidplayfp";
+}
+function which(binary) {
+    const hasSep = binary.includes("/") || binary.includes("\\");
+    const pathExts = process.platform === "win32"
+        ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").map((ext) => ext.startsWith(".") ? ext : `.${ext}`)
+        : [""];
+    const tryResolve = (base) => {
+        for (const ext of pathExts) {
+            const candidate = ext ? `${base}${ext}` : base;
+            try {
+                if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+                    return candidate;
+                }
+            }
+            catch { }
+        }
+        return null;
+    };
+    if (hasSep) {
+        return tryResolve(binary);
+    }
+    const envPath = process.env.PATH || "";
+    for (const dir of envPath.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const resolved = tryResolve(path.join(dir, binary));
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+const PAL_CLOCK = 985248;
+const NTSC_CLOCK = 1022727;
+function cyclesToSeconds(cycles, mode) {
+    const clock = mode === "pal" ? PAL_CLOCK : NTSC_CLOCK;
+    return Math.max(1, Math.ceil(cycles / clock));
+}
+function buildSidplayArgs(params, seconds) {
+    const args = [];
+    if (params.mode === "pal") {
+        args.push("-vp");
+    }
+    else {
+        args.push("-vn");
+    }
+    args.push("-f44100");
+    args.push("-p16");
+    args.push(`-t${seconds}`);
+    args.push(`-w${params.wavPath}`);
+    if (typeof params.tune === "number" && Number.isFinite(params.tune)) {
+        const tuneIdx = Math.max(1, Math.floor(params.tune));
+        args.push(`-o${tuneIdx}`);
+    }
+    args.push(params.sidPath);
+    return args;
+}
+function parseWavHeader(buffer) {
+    if (buffer.length < 44)
+        throw new Error("WAV too small");
+    if (buffer.toString("ascii", 0, 4) !== "RIFF")
+        throw new Error("WAV missing RIFF header");
+    if (buffer.toString("ascii", 8, 12) !== "WAVE")
+        throw new Error("WAV missing WAVE header");
+    let offset = 12;
+    let fmt = null;
+    let dataBytes = 0;
+    while (offset + 8 <= buffer.length) {
+        const id = buffer.toString("ascii", offset, offset + 4);
+        const size = buffer.readUInt32LE(offset + 4);
+        offset += 8;
+        if (id === "fmt ") {
+            const audioFormat = buffer.readUInt16LE(offset + 0);
+            const numChannels = buffer.readUInt16LE(offset + 2);
+            const sampleRate = buffer.readUInt32LE(offset + 4);
+            const bitsPerSample = buffer.readUInt16LE(offset + 14);
+            fmt = { audioFormat, numChannels, sampleRate, bitsPerSample, dataBytes: 0 };
+        }
+        else if (id === "data") {
+            dataBytes = size;
+        }
+        offset += size;
+    }
+    if (!fmt)
+        throw new Error("WAV missing fmt chunk");
+    if (dataBytes <= 0)
+        throw new Error("WAV missing data chunk");
+    fmt.dataBytes = dataBytes;
+    return fmt;
+}
+function quoteArg(a) {
+    if (/^[A-Za-z0-9_\-\.\/]+$/.test(a))
+        return a;
+    return `'${a.replace(/'/g, "'\\''")}'`;
+}
+export async function runSidToWav(params) {
+    const mode = resolveMode(params.mode);
+    const limitCycles = resolveLimitCycles(params.limitCycles);
+    const binary = resolveBinary(params.binary);
+    if (!params.sidPath)
+        throw new Error("sidPath is required");
+    if (!params.wavPath)
+        throw new Error("wavPath is required");
+    if (!fs.existsSync(params.sidPath))
+        throw new Error(`SID not found: ${params.sidPath}`);
+    ensureParentDir(params.wavPath);
+    const full = {
+        sidPath: params.sidPath,
+        wavPath: params.wavPath,
+        mode,
+        limitCycles,
+        tune: typeof params.tune === "number" ? params.tune : undefined,
+        binary,
+    };
+    const binaryPath = which(full.binary);
+    if (!binaryPath) {
+        const installHint = `sidplayfp not found. Install via e.g. \n` +
+            `  sudo apt-get install sidplayfp\n` +
+            `  brew install sidplayfp\n` +
+            `  choco install sidplayfp\n`;
+        const msg = Buffer.from(`${full.binary} not found in PATH.\n${installHint}`);
+        throw new SidplayExecutionError({
+            message: "sidplayfp binary is not installed",
+            command: full.binary,
+            exitCode: 127,
+            stderr: msg,
+            wavExists: false,
+            wavSize: 0,
+        });
+    }
+    const seconds = cyclesToSeconds(full.limitCycles, full.mode);
+    const args = buildSidplayArgs(full, seconds);
+    const display = [binaryPath, ...args.map(quoteArg)].join(" ");
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const exitCode = await new Promise((resolve) => {
+        const child = spawn(binaryPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+        child.stdout?.on("data", (c) => stdoutChunks.push(Buffer.from(c)));
+        child.stderr?.on("data", (c) => stderrChunks.push(Buffer.from(c)));
+        child.on("error", (err) => {
+            const enoent = (err && typeof err === "object" && "code" in err && err.code === "ENOENT");
+            const hint = Buffer.from(String(err?.message || err || "spawn error"));
+            stderrChunks.push(hint);
+            resolve(enoent ? 127 : 1);
+        });
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+    const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+    const stderrBuf = Buffer.concat(stderrChunks);
+    const stderr = stderrBuf.toString("utf8");
+    const wavExists = fs.existsSync(full.wavPath);
+    const wavStat = wavExists ? fs.statSync(full.wavPath) : null;
+    const wavSize = wavStat?.size ?? 0;
+    if (exitCode !== 0) {
+        throw new SidplayExecutionError({
+            message: "sidplayfp failed (non-zero exit code)",
+            command: display,
+            exitCode,
+            stderr: stderrBuf,
+            wavExists,
+            wavSize,
+        });
+    }
+    if (!wavExists || wavSize === 0) {
+        throw new SidplayExecutionError({
+            message: "sidplayfp did not produce a WAV file",
+            command: display,
+            exitCode,
+            stderr: stderrBuf,
+            wavExists,
+            wavSize,
+        });
+    }
+    const header = fs.readFileSync(full.wavPath);
+    const info = parseWavHeader(header);
+    if (info.audioFormat !== 1 || info.sampleRate !== 44100 || info.bitsPerSample !== 16) {
+        throw new SidplayExecutionError({
+            message: `Unexpected WAV format (expected PCM 16-bit @ 44100 Hz); got format=${info.audioFormat}, bits=${info.bitsPerSample}, rate=${info.sampleRate}`,
+            command: display,
+            exitCode,
+            stderr: stderrBuf,
+            wavExists,
+            wavSize,
+        });
+    }
+    return {
+        command: display,
+        exitCode: exitCode ?? 0,
+        stdout,
+        stderr,
+        wavPath: full.wavPath,
+        wavInfo: info,
+    };
+}

package/dist/sidwave.js

@@ -0,0 +1,101 @@
+/*
+C64 Bridge - SIDWAVE Parser and Types
+Copyright (C) 2025 Christian Gleissner
+
+Licensed under the GNU General Public License v2.0 or later.
+See <https://www.gnu.org/licenses/> for details.
+*/
+import pkg from 'yaml';
+const { parse: yamlParse } = pkg;
+export function parseSidwave(input) {
+    const obj = typeof input === "string" ? yamlParse(input) : input;
+    if (!obj || typeof obj !== "object") {
+        throw new Error("Invalid SIDWAVE: not an object");
+    }
+    // Detect legacy CPG shape vs new SIDWAVE top-level
+    const legacy = !!obj.song;
+    const header = legacy
+        ? { title: obj.song?.title, tempo: obj.song?.tempo, mode: obj.song?.mode, length_bars: obj.song?.length_bars, global_fx: obj.song?.global_fx }
+        : { title: obj.title, author: obj.author, tempo: obj.tempo, mode: obj.mode, length_bars: obj, global_fx: obj.global_fx };
+    const title = header.title ?? "Untitled";
+    const tempo = normalizeTempo(header.tempo);
+    const mode = header.mode ?? "PAL";
+    const length_bars = Math.max(1, Math.floor(header.length_bars ?? inferBarsFromTimeline(obj.timeline) ?? 16));
+    const global_fx = header.global_fx ?? {};
+    const song = { title, tempo, mode, length_bars, global_fx };
+    const voices = (legacy ? obj.voices : obj.voices) ?? [];
+    if (!Array.isArray(voices) || voices.length === 0)
+        throw new Error("Invalid SIDWAVE: missing voices");
+    const normalizedVoices = voices.map((v) => normalizeVoice(v));
+    const timeline = ((legacy ? obj.timeline : obj.timeline) ?? []).map((t) => normalizeTimelineSection(t));
+    if (!Array.isArray(timeline) || timeline.length === 0)
+        throw new Error("Invalid SIDWAVE: missing timeline");
+    return { song, voices: normalizedVoices, timeline };
+}
+function inferBarsFromTimeline(t) {
+    if (!Array.isArray(t) || t.length === 0)
+        return undefined;
+    return t.reduce((sum, s) => sum + Math.max(1, Math.floor(s.bars ?? 0)), 0);
+}
+function normalizeTempo(tempo) {
+    if (!Number.isFinite(tempo))
+        return 100;
+    const t = Math.max(30, Math.min(220, Math.floor(tempo)));
+    return t;
+}
+function normalizeVoice(v) {
+    const waveform = normalizeWaveform(v.waveform ?? "pulse");
+    let pulseWidth = v.pulse_width;
+    if (typeof pulseWidth === "number") {
+        if (pulseWidth > 0 && pulseWidth <= 1) {
+            pulseWidth = Math.round(pulseWidth * 4095);
+        }
+        pulseWidth = Math.max(0, Math.min(4095, Math.floor(pulseWidth)));
+    }
+    const adsr = (v.adsr ?? [2, 2, 10, 3]).map((n) => Math.max(0, Math.min(15, Math.floor(n))));
+    return {
+        id: v.id,
+        name: v.name ?? `Voice${v.id}`,
+        waveform,
+        pulse_width: pulseWidth,
+        adsr,
+        patterns: v.patterns ?? {},
+    };
+}
+function normalizeWaveform(w) {
+    const w0 = (w || "pulse").toLowerCase();
+    if (w0 === "saw")
+        return "sawtooth";
+    if (w0 === "tri")
+        return "triangle";
+    if (w0 === "pulse" || w0 === "sawtooth" || w0 === "triangle" || w0 === "noise")
+        return w0;
+    return "pulse";
+}
+function normalizeTimelineSection(t) {
+    const bars = Math.max(1, Math.floor(t?.bars ?? 1));
+    const layers = {};
+    for (const [k, v] of Object.entries(t?.layers ?? {})) {
+        layers[k] = String(v ?? "-");
+    }
+    return { section: t.section ?? "", bars, layers };
+}
+export function noteNameToMidi(note) {
+    const m = /^([A-Ga-g])([#b]?)(-?\d+)$/.exec((note || "").trim());
+    if (!m)
+        return undefined;
+    const letter = m[1].toUpperCase();
+    const accidental = m[2];
+    const octave = Number(m[3]);
+    const base = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+    let semi = base[letter] ?? 0;
+    if (accidental === "#")
+        semi += 1;
+    if (accidental === "b")
+        semi -= 1;
+    const midi = (octave + 1) * 12 + semi;
+    return midi;
+}
+export function midiToHz(midi) {
+    return 440 * Math.pow(2, (midi - 69) / 12);
+}