@typecad/framework-zephyr 1.0.0-alpha.10 → 1.0.0-alpha.11

package/dist/licenses.d.ts

@@ -0,0 +1,59 @@
+import { type LibraryLicenseEntry, type ReadFile, type ReadDir } from '@typecad/cuttlefish/api/shared';
+export type ZephyrLicensesOutcome = {
+    ok: true;
+    entries: LibraryLicenseEntry[];
+    needsBuild?: boolean;
+} | {
+    ok: false;
+    reason: 'west-not-found' | 'no-workspace' | 'no-dependencies';
+    message: string;
+};
+/**
+ * Injected enumeration seams so scanZephyrLicenses is unit-testable without
+ * spawning west or touching disk. The production runner (defaultRunner) wires
+ * these to discoverWest + westSpawn + fs.
+ */
+export interface ZephyrLicensesRunner {
+    /** Absolute workspace topdir, or null if cwd is not inside a west workspace. */
+    topdir: () => string | null;
+    /** west manifest projects `[{ name, abspath }]`, or null if `west list` failed. */
+    listModules: () => {
+        name: string;
+        abspath: string;
+    }[] | null;
+    /** Discovered $ZEPHYR_BASE (absolute), or undefined. */
+    zephyrBase?: string;
+    /**
+     * The build's compile_commands.json text, or null when no build exists. The
+     * project scope uses it to determine which modules the firmware actually
+     * links (a module is "linked" iff one of its sources was compiled).
+     */
+    compileCommands?: () => string | null;
+    readFile: ReadFile;
+    readdir: ReadDir;
+}
+/**
+ * Resolve the Zephyr kernel + west manifest projects to license entries.
+ *
+ * The Zephyr kernel is always included (when ZEPHYR_BASE is known) — a
+ * cuttlefish app always links it via `find_package(Zephyr)`.
+ *
+ * `all === false` (default, project scope) filters the west modules to those
+ * whose sources were compiled in the last build (via `compileCommands`). When
+ * no build is available, only the kernel is returned and `needsBuild` is set so
+ * the presenter can hint the user to build first. Never throws.
+ */
+export declare function scanZephyrLicenses(runner: ZephyrLicensesRunner, all?: boolean): ZephyrLicensesOutcome;
+/** @internal Test-only override of the default runner. Pass null to simulate west-not-found. */
+export declare function __setLicensesRunnerForTest(runner: ZephyrLicensesRunner | null | undefined): void;
+/**
+ * `cuttlefish licenses` (Zephyr) presenter. Enumerates the Zephyr kernel +
+ * west manifest projects, resolves each one's license, classifies copyleft
+ * risk, and renders a sorted table. Warns on unknown licenses; sets
+ * process.exitCode under --strict when any strong-copyleft dependency is
+ * present. Never calls process.exit().
+ *
+ * Default scope = only the modules the firmware actually links (from the last
+ * `cuttlefish build`); `--all` lists every west manifest module.
+ */
+export declare function runLicensesPresenter(strict: boolean, all: boolean): void;

package/dist/licenses.js

@@ -0,0 +1,347 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-zephyr — Zephyr license scanner
+//
+// Zephyr-specific enumeration + presenter for the `cuttlefish licenses`
+// subcommand. The framework-agnostic SPDX detection engine lives in the shared
+// cuttlefish core (`@typecad/cuttlefish/api/shared`); this module owns only the
+// Zephyr pieces: discovering the west workspace, enumerating the Zephyr kernel
+// + west manifest projects (`west list`), and resolving each one's LICENSE.
+//
+// Scoping mirrors framework-arduino's `--all` distinction:
+//   - default (project scope): only the dependencies the firmware ACTUALLY
+//     links, derived from the build's `compile_commands.json` (a module is
+//     listed iff its sources were compiled). A west manifest carries every
+//     vendor HAL/library; almost none are linked by a single project, so the
+//     default filters them out. Requires a prior `cuttlefish build` — without
+//     one, only the kernel is reported with a hint to build first.
+//   - `--all`: every west manifest project (the whole workspace).
+//
+// Mirrors framework-arduino's presenter shape (runLicensesPresenter(strict,
+// all); never calls process.exit(); sets process.exitCode under --strict).
+// ---------------------------------------------------------------------------
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync } from 'node:fs';
+import * as path from 'node:path';
+import * as ui from '@typecad/cuttlefish/utils/ui';
+import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
+import { resolveLibraryLicense, RISK_RANK, riskBracket, statusMark, countByRisk, } from '@typecad/cuttlefish/api/shared';
+import { discoverWest } from './toolchain/west-discover.js';
+import { westSpawn } from './toolchain/west-spawn.js';
+// ---------------------------------------------------------------------------
+// Linked-module filtering (project scope)
+// ---------------------------------------------------------------------------
+/** Normalize a path for case-insensitive, separator-agnostic comparison. */
+function norm(p) {
+    return p.split('\\').join('/').toLowerCase();
+}
+/**
+ * Filter the west manifest to the modules whose sources were compiled in the
+ * last build. A module is "linked" iff some compiled translation unit lives
+ * under its abspath. If the build data is unparseable, no filtering is applied
+ * (degrade to listing all modules rather than reporting nothing).
+ */
+function filterLinkedModules(ccText, modules) {
+    let arr;
+    try {
+        arr = JSON.parse(ccText);
+    }
+    catch {
+        return modules;
+    }
+    if (!Array.isArray(arr))
+        return modules;
+    // One normalized blob of every compiled source path; membership is then a
+    // substring check per module (O(modules) after an O(TUs) join).
+    const blob = arr
+        .map((e) => norm(typeof e?.file === 'string' ? e.file : ''))
+        .join('\n');
+    return modules.filter((m) => blob.includes(norm(m.abspath) + '/'));
+}
+// ---------------------------------------------------------------------------
+// scanZephyrLicenses — enumerate + resolve the workspace dependency set
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the Zephyr kernel + west manifest projects to license entries.
+ *
+ * The Zephyr kernel is always included (when ZEPHYR_BASE is known) — a
+ * cuttlefish app always links it via `find_package(Zephyr)`.
+ *
+ * `all === false` (default, project scope) filters the west modules to those
+ * whose sources were compiled in the last build (via `compileCommands`). When
+ * no build is available, only the kernel is returned and `needsBuild` is set so
+ * the presenter can hint the user to build first. Never throws.
+ */
+export function scanZephyrLicenses(runner, all = false) {
+    const { readFile, readdir } = runner;
+    const entries = [];
+    // 1. The Zephyr kernel ($ZEPHYR_BASE). Apache-2.0; resolved from its LICENSE.
+    if (runner.zephyrBase) {
+        entries.push(resolveLibraryLicense({ name: 'zephyr (kernel)', installDir: runner.zephyrBase }, readFile, readdir, 
+        // Zephyr's top-level LICENSE is the authoritative source; no manifest
+        // license field to consult, and scanning its source headers is noise.
+        { subdirs: [] }));
+    }
+    // 2. west manifest projects.
+    const modules = runner.listModules();
+    if (modules === null) {
+        if (entries.length > 0)
+            return { ok: true, entries };
+        return {
+            ok: false,
+            reason: 'no-workspace',
+            message: '`west list` did not return a project list (not inside a west workspace?).',
+        };
+    }
+    // Project scope: keep only the modules the build actually linked.
+    let projectModules = modules;
+    let needsBuild = false;
+    if (!all) {
+        const cc = runner.compileCommands ? runner.compileCommands() : null;
+        if (cc === null) {
+            // No build — can't determine the linked set. Report the kernel only and
+            // flag it so the presenter prints a "build first" hint.
+            projectModules = [];
+            needsBuild = true;
+        }
+        else {
+            projectModules = filterLinkedModules(cc, modules);
+        }
+    }
+    for (const m of projectModules) {
+        // Skip the Zephyr kernel itself (already added above by name) to avoid a
+        // duplicate row when it is also a manifest project.
+        if (runner.zephyrBase && path.resolve(m.abspath) === path.resolve(runner.zephyrBase)) {
+            continue;
+        }
+        entries.push(resolveLibraryLicense({ name: m.name, installDir: m.abspath }, readFile, readdir, {
+            // Zephyr HAL modules commonly keep their LICENSE under a `zephyr/` or
+            // `src/` subdir (e.g. hal_nordic ships zephyr/LICENSE.txt). Check both
+            // alongside the root. (Source-header scanning is bounded — it only runs
+            // when no LICENSE file is found, capped at 6 files / 120 lines.)
+            subdirs: ['zephyr', 'src'],
+        }));
+    }
+    if (entries.length === 0) {
+        return {
+            ok: false,
+            reason: 'no-dependencies',
+            message: 'No Zephyr dependencies found to scan.',
+        };
+    }
+    entries.sort((a, b) => {
+        const r = RISK_RANK[a.risk] - RISK_RANK[b.risk];
+        if (r !== 0)
+            return r;
+        return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
+    });
+    return { ok: true, entries, needsBuild };
+}
+// ---------------------------------------------------------------------------
+// Default runner — wires seams to discoverWest + westSpawn + fs
+// ---------------------------------------------------------------------------
+/**
+ * Find the build's compile_commands.json under cwd. Cuttlefish's Zephyr project
+ * root is the transpile output dir (e.g. `<cwd>/src/out`), so the build dir is
+ * `<root>/build` — not necessarily `<cwd>/build`. Check the common layouts,
+ * then fall back to a bounded search (skipping node_modules/.git/dist).
+ */
+function findCompileCommandsText(readFile, readdir) {
+    const direct = [
+        path.join(process.cwd(), 'build', 'compile_commands.json'),
+        path.join(process.cwd(), 'out', 'build', 'compile_commands.json'),
+        path.join(process.cwd(), 'src', 'out', 'build', 'compile_commands.json'),
+    ];
+    for (const c of direct) {
+        const text = readFile(c);
+        if (text)
+            return text;
+    }
+    // Bounded recursive search for a build/compile_commands.json.
+    const isCc = (p) => {
+        const n = norm(p);
+        return n.endsWith('/build/compile_commands.json') || n.endsWith('\\build\\compile_commands.json');
+    };
+    let found;
+    const seen = new Set();
+    const walk = (dir, depth) => {
+        if (found || depth > 4 || seen.has(dir))
+            return;
+        seen.add(dir);
+        let entries;
+        try {
+            entries = readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e);
+            if (e === 'compile_commands.json' && isCc(full)) {
+                found = full;
+                return;
+            }
+        }
+        for (const e of entries) {
+            if (found)
+                return;
+            if (e === 'node_modules' || e === '.git' || e === 'dist' || e.startsWith('.'))
+                continue;
+            walk(path.join(dir, e), depth + 1);
+        }
+    };
+    walk(process.cwd(), 0);
+    return found ? (readFile(found) ?? null) : null;
+}
+function defaultRunner() {
+    const install = discoverWest();
+    if (!install)
+        return null;
+    const zephyrBase = install.zephyrBase;
+    // `west topdir` prints the workspace root (one path line). Returns null when
+    // cwd is not inside a west workspace (west exits non-zero).
+    const topdir = () => {
+        try {
+            const inv = westSpawn(['topdir'], { encoding: 'utf8', timeout: 15_000 });
+            const r = spawnSync(inv.command, inv.args, inv.options);
+            const out = typeof r.stdout === 'string' ? r.stdout.trim() : '';
+            return r.status === 0 && out ? out : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // `west list --format '{name}\t{abspath}'` → one project per line. Returns
+    // null on any spawn failure.
+    const listModules = () => {
+        try {
+            const inv = westSpawn(['list', '--format', '{name}\t{abspath}'], {
+                encoding: 'utf8',
+                timeout: 30_000,
+            });
+            const r = spawnSync(inv.command, inv.args, inv.options);
+            if (r.status !== 0)
+                return null;
+            const out = typeof r.stdout === 'string' ? r.stdout : '';
+            const mods = [];
+            for (const line of out.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const [name, abspath] = trimmed.split('\t');
+                if (name && abspath)
+                    mods.push({ name, abspath });
+            }
+            return mods;
+        }
+        catch {
+            return null;
+        }
+    };
+    const readFile = (p) => {
+        try {
+            return readFileSync(p, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const readdir = (d) => {
+        try {
+            return readdirSync(d);
+        }
+        catch {
+            return [];
+        }
+    };
+    return {
+        topdir,
+        listModules,
+        zephyrBase,
+        compileCommands: () => findCompileCommandsText(readFile, readdir),
+        readFile,
+        readdir,
+    };
+}
+// ---------------------------------------------------------------------------
+// CLI presenter
+// ---------------------------------------------------------------------------
+let testRunner;
+/** @internal Test-only override of the default runner. Pass null to simulate west-not-found. */
+export function __setLicensesRunnerForTest(runner) {
+    testRunner = runner;
+}
+/**
+ * `cuttlefish licenses` (Zephyr) presenter. Enumerates the Zephyr kernel +
+ * west manifest projects, resolves each one's license, classifies copyleft
+ * risk, and renders a sorted table. Warns on unknown licenses; sets
+ * process.exitCode under --strict when any strong-copyleft dependency is
+ * present. Never calls process.exit().
+ *
+ * Default scope = only the modules the firmware actually links (from the last
+ * `cuttlefish build`); `--all` lists every west manifest module.
+ */
+export function runLicensesPresenter(strict, all) {
+    ui.printHeader();
+    ui.printStep(all
+        ? 'Checking licenses for every west manifest module'
+        : 'Checking licenses for this Zephyr project (linked dependencies only)');
+    // Surface the config (informational). Best-effort: a missing/malformed config
+    // never blocks the license scan.
+    let buildTarget;
+    try {
+        buildTarget = loadCuttlefishConfig(process.cwd())?.buildTarget;
+    }
+    catch {
+        /* best-effort */
+    }
+    if (buildTarget) {
+        ui.printInfo(`Board target ... ${buildTarget}`);
+    }
+    const runner = testRunner !== undefined ? testRunner : defaultRunner();
+    if (!runner) {
+        ui.printError('west ............. NOT FOUND');
+        ui.printInfo("  → install west (pip install west) or run the typeCAD Zephyr installer.");
+        process.exitCode = 1;
+        return;
+    }
+    const result = scanZephyrLicenses(runner, all);
+    if (!result.ok) {
+        if (result.reason === 'no-workspace' || result.reason === 'no-dependencies') {
+            ui.printInfo(`(${result.message})`);
+        }
+        return;
+    }
+    // Project scope with no build: only the kernel is reported. Hint the user to
+    // build (which records which modules actually link) or use --all.
+    if (result.needsBuild) {
+        ui.printInfo('(no build found — only the Zephyr kernel is shown. Run `cuttlefish build` to scope ' +
+            'this report to the modules your firmware actually links, or use `cuttlefish licenses --all` ' +
+            'for every west module.)');
+    }
+    const counts = countByRisk(result.entries);
+    for (const e of result.entries) {
+        if (e.risk === 'unknown') {
+            ui.printWarning(`${e.name} .................. UNKNOWN`);
+        }
+        else {
+            ui.printInfo(`${e.name} .................. ${e.spdx ?? 'UNKNOWN'}${riskBracket(e.risk)}${statusMark(e.risk)}`);
+        }
+    }
+    ui.printSuccess(`${counts.permissive} permissive, ${counts['weak-copyleft']} weak copyleft, ` +
+        `${counts['strong-copyleft']} strong copyleft, ${counts.unknown} unknown`);
+    const unknowns = result.entries.filter((e) => e.risk === 'unknown');
+    if (unknowns.length > 0) {
+        ui.printWarning(`License could not be determined for ${unknowns.length} ${unknowns.length === 1 ? 'dependency' : 'dependencies'}:`);
+        for (const u of unknowns) {
+            ui.printInfo(`    ${u.name} (check LICENSE in ${u.path})`);
+        }
+    }
+    const strongCopyleft = result.entries.filter((e) => e.risk === 'strong-copyleft');
+    if (strongCopyleft.length > 0) {
+        ui.printWarning(`${strongCopyleft.length} ${strongCopyleft.length === 1 ? 'dependency carries' : 'dependencies carry'} strong-copyleft terms — review before shipping.`);
+    }
+    // --strict fails the build on any unknown OR strong-copyleft dependency.
+    if ((unknowns.length > 0 || strongCopyleft.length > 0) && strict) {
+        process.exitCode = 1;
+    }
+}

package/dist/lowering/dac.d.ts

@@ -0,0 +1,15 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the DAC device handle. Called from shimLines when the program uses the
+ * DAC (the chip must declare a `dac` entry, or nothing is emitted).
+ */
+export declare function dacInitLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Resolve a HAL dac.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerDac(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/dac.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// DAC lowering — Zephyr DAC driver via dac_channel_setup / dac_write_value
+//
+// Targets with a DAC (ESP32: 2× 8-bit channels on GPIO25/26) declare a `dac`
+// entry in the chip descriptor: the DT device node label + the pin→channel map.
+// The lowering emits a `dac_channel_setup` (lazy, on first write) + a
+// `dac_write_value` against DEVICE_DT_GET(DT_NODELABEL(<device>)).
+//
+// Targets without a DAC (nRF52840, ESP32-S3) omit `dac`; usage there lowers to a
+// comment and profileDiagnostics flags it (mirror of the ADC pin-validity gate).
+// ---------------------------------------------------------------------------
+/** Look up a DAC channel by HAL pin number. */
+function findDacChannel(chip, pin) {
+    return chip.dac?.channels.find((c) => c.pin === pin);
+}
+/**
+ * Emit the DAC device handle. Called from shimLines when the program uses the
+ * DAC (the chip must declare a `dac` entry, or nothing is emitted).
+ */
+export function dacInitLines(chip) {
+    if (!chip.dac)
+        return [];
+    return [
+        '// CUTTLEFISH_DAC_BEGIN',
+        `static const struct device* __tc_dac_dev = DEVICE_DT_GET(DT_NODELABEL(${chip.dac.device}));`,
+        '// CUTTLEFISH_DAC_END',
+    ];
+}
+/**
+ * Resolve a HAL dac.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerDac(op, chip) {
+    const o = op;
+    // No DAC on this target (e.g. nRF52840). Return a comment so the resolver
+    // reports non-undefined (the manifest validator's probe sends pin:25 on the
+    // default chip, which has no DAC). profileDiagnostics flags real misuse.
+    if (!chip.dac) {
+        return { code: `/* dac on pin ${o.pin}: no DAC on ${chip.id} */` };
+    }
+    const ch = findDacChannel(chip, o.pin);
+    if (!ch) {
+        const valid = [...chip.dac.channels].map((c) => c.pin).sort((a, b) => a - b).join(', ');
+        return {
+            code: `/* dac on pin ${o.pin}: not a DAC pin on ${chip.id} (valid: ${valid}) */`,
+        };
+    }
+    switch (op.operation) {
+        case 'dac.write': {
+            // Lazy one-time channel setup on first write (the HAL DAC surface has no
+            // begin()), then output the value. Arduino analogWrite is 0–255 against
+            // the channel's resolution; dac_write_value takes the raw code.
+            return {
+                code: [
+                    `{ static bool __tc_dac_done = false;`,
+                    `  if (!__tc_dac_done) {`,
+                    `    static const struct dac_channel_cfg __tc_dac_cfg = { .channel_id = ${ch.channel}, .resolution = ${ch.resolution} };`,
+                    `    (void)dac_channel_setup(__tc_dac_dev, &__tc_dac_cfg);`,
+                    `    __tc_dac_done = true;`,
+                    `  }`,
+                    `  (void)dac_write_value(__tc_dac_dev, ${ch.channel}, ${o.value}); }`,
+                ].join(' '),
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/fs.d.ts

@@ -0,0 +1,16 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * Emit the littlefs mount + the typed helper API the lowering calls into.
+ * Called from shimLines when the program uses the filesystem. The helpers are
+ * `static` so multiple TUs that carry the shim (guarded by the include guard)
+ * do not collide.
+ */
+export declare function fsInitLines(): string[];
+/**
+ * Resolve a HAL fs.* op to Zephyr C++.
+ * Returns `{ code }` — each op's code is the body of the HAL FS class method.
+ */
+export declare function lowerFs(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/fs.js

@@ -0,0 +1,121 @@
+// ---------------------------------------------------------------------------
+// Filesystem lowering — Zephyr FS API (littlefs on the storage partition)
+//
+// HAL `fs.*` (begin/read_text/write_text/exists/remove) maps onto Zephyr's
+// <zephyr/fs/fs.h>. A littlefs filesystem is mounted at "/lfs" on the board's
+// `storage_partition` fixed-partition (the same partition the ZMS settings
+// backend uses for preferences — a program should not use both surfaces at
+// once without dedicating separate partitions). The mount is lazy: it formats
+// + remounts on first use when the partition is unformatted.
+//
+// The HAL paths are treated as paths WITHIN the filesystem: the shim joins the
+// mount point, so fs.read_text("/data.txt") reads "/lfs/data.txt". This keeps
+// the mount point an implementation detail.
+//
+// Requires Kconfig CONFIG_FILE_SYSTEM + CONFIG_FILE_SYSTEM_LITTLEFS (+ FLASH /
+// FLASH_MAP) — emitted by the scaffold when the program uses fs.* — and the
+// storage_partition node (added by the overlay).
+// ---------------------------------------------------------------------------
+/**
+ * Emit the littlefs mount + the typed helper API the lowering calls into.
+ * Called from shimLines when the program uses the filesystem. The helpers are
+ * `static` so multiple TUs that carry the shim (guarded by the include guard)
+ * do not collide.
+ */
+export function fsInitLines() {
+    return [
+        '// CUTTLEFISH_FS_BEGIN',
+        'static struct fs_mount_t __tc_fs_mp;',
+        'static bool __tc_fs_mounted = false;',
+        '',
+        'FS_LITTLEFS_DECLARE_DEFAULT_CONFIG(__tc_fs_data);',
+        'static struct fs_mount_t __tc_fs_mp_init = {',
+        '    .type = FS_LITTLEFS,',
+        '    .fs_data = &__tc_fs_data,',
+        '    .storage_dev = (void *)FIXED_PARTITION_ID(storage_partition),',
+        '    .mnt_point = "/lfs",',
+        '};',
+        '',
+        'static void __tc_fs_ensure_mount(void) {',
+        '    if (__tc_fs_mounted) return;',
+        '    __tc_fs_mp = __tc_fs_mp_init;',
+        '    int rc = fs_mount(&__tc_fs_mp);',
+        '    if (rc == -ENODATA || rc == -EINVAL) {',
+        '        // Unformatted partition — format it for littlefs, then remount.',
+        '        (void)fs_mkfs(FS_LITTLEFS, static_cast<uintptr_t>(FIXED_PARTITION_ID(storage_partition)), NULL, 0);',
+        '        (void)fs_mount(&__tc_fs_mp);',
+        '    }',
+        '    __tc_fs_mounted = true;',
+        '}',
+        '',
+        '// Join the mount point with the user path (paths are within the FS).',
+        'static const char* __tc_fs_path(const char* p) {',
+        '    static char buf[128];',
+        '    if (!p) return "/lfs";',
+        '    const char* s = (p[0] == \'/\') ? p + 1 : p;',
+        '    (void)snprintf(buf, sizeof(buf), "/lfs/%s", s);',
+        '    return buf;',
+        '}',
+        '',
+        'static bool __tc_fs_begin(void) { __tc_fs_ensure_mount(); return true; }',
+        '',
+        'static const char* __tc_fs_read_text(const char* path) {',
+        '    __tc_fs_ensure_mount();',
+        '    static char buf[256];',
+        '    buf[0] = 0;',
+        '    struct fs_file_t f;',
+        '    fs_file_t_init(&f);',
+        '    if (fs_open(&f, __tc_fs_path(path), FS_O_READ) == 0) {',
+        '        (void)fs_read(&f, buf, sizeof(buf) - 1);',
+        '        buf[sizeof(buf) - 1] = 0;',
+        '        (void)fs_close(&f);',
+        '    }',
+        '    return buf;',
+        '}',
+        '',
+        'static void __tc_fs_write_text(const char* path, const char* content) {',
+        '    __tc_fs_ensure_mount();',
+        '    struct fs_file_t f;',
+        '    fs_file_t_init(&f);',
+        '    if (fs_open(&f, __tc_fs_path(path), FS_O_WRITE | FS_O_CREATE | FS_O_TRUNC) == 0) {',
+        '        (void)fs_write(&f, content, (content ? strlen(content) : 0));',
+        '        (void)fs_close(&f);',
+        '    }',
+        '}',
+        '',
+        'static bool __tc_fs_exists(const char* path) {',
+        '    __tc_fs_ensure_mount();',
+        '    struct fs_dirent ent;',
+        '    return fs_stat(__tc_fs_path(path), &ent) == 0;',
+        '}',
+        '',
+        'static bool __tc_fs_remove(const char* path) {',
+        '    __tc_fs_ensure_mount();',
+        '    return fs_unlink(__tc_fs_path(path)) == 0;',
+        '}',
+        '// CUTTLEFISH_FS_END',
+    ];
+}
+/**
+ * Resolve a HAL fs.* op to Zephyr C++.
+ * Returns `{ code }` — each op's code is the body of the HAL FS class method.
+ */
+export function lowerFs(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'fs.begin':
+            // No payload (the op carries only its discriminator).
+            return { code: 'return __tc_fs_begin();' };
+        case 'fs.read_text':
+            return { code: `return __tc_fs_read_text(${o.path});` };
+        case 'fs.write_text':
+            return { code: `__tc_fs_write_text(${o.path}, ${o.content});` };
+        case 'fs.exists':
+            return { code: `return __tc_fs_exists(${o.path});` };
+        case 'fs.remove':
+            return { code: `return __tc_fs_remove(${o.path});` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/hwtimer.d.ts

@@ -0,0 +1,15 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the per-instance counter device handles + frequency/callback state.
+ * Called from shimLines when the program uses hardware timers.
+ */
+export declare function hwtimerInitLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Resolve a HAL hwtimer.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerHwtimer(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};