@typecad/framework-zephyr 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/sdk/board-catalog-sync.d.ts

@@ -0,0 +1,16 @@
+import * as catalog from '@typecad/cuttlefish/board-catalog';
+export type BoardCatalogSyncReport = catalog.BoardCatalogSyncReport;
+export type BoardCatalogEnsureResult = catalog.BoardCatalogEnsureResult;
+export type BoardCatalogOverlay = catalog.BoardCatalogOverlay;
+export declare const GENERATOR_REV: number, isZephyrBase: typeof catalog.isZephyrBase, locateZephyrBaseCheap: typeof catalog.locateZephyrBaseCheap, overlayPathFor: typeof catalog.overlayPathFor, readBoardCatalogOverlayFile: typeof catalog.readBoardCatalogOverlayFile, loadBoardCatalogOverlay: typeof catalog.loadBoardCatalogOverlay, resetBoardCatalogOverlayCache: typeof catalog.resetBoardCatalogOverlayCache, isOverlayStale: typeof catalog.isOverlayStale, diffBoardCatalogs: typeof catalog.diffBoardCatalogs, boardRecordFingerprint: typeof catalog.boardRecordFingerprint, findBoardInCatalog: typeof catalog.findBoardInCatalog, activeBoardCatalog: typeof catalog.activeBoardCatalog, resetActiveBoardCatalog: typeof catalog.resetActiveBoardCatalog;
+/** Sync with the full west discovery cascade behind it (the CLI's path):
+ * falls back through spawn-based discovery when the cheap fs probes find
+ * nothing. */
+export declare function syncBoardCatalog(opts?: {
+    zephyrBase?: string;
+}): catalog.BoardCatalogSyncReport;
+/** The build-path pre-step: refresh a stale overlay before a regen
+ * (fs-only discovery — no spawns during builds). */
+export declare function ensureFreshBoardCatalog(): catalog.BoardCatalogEnsureResult;
+/** Locate a Zephyr tree by any means (spawn cascade included). */
+export declare function locateZephyrBaseFull(): string | undefined;

package/dist/sdk/board-catalog-sync.js

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// sdk/board-catalog-sync.ts — framework-side catalog orchestration.
+//
+// The catalog tooling (walker, overlay store, fs-only discovery) lives in
+// @typecad/cuttlefish/board-catalog — the create flow needs it before any
+// framework is installed. This module adds the one thing the framework owns
+// — the full spawn-based west discovery cascade for an explicit
+// `cuttlefish board sync` — and re-exports the store for the strategy's
+// import surface.
+// ----------------------------------------------------------------------------
+import path from 'node:path';
+import * as catalog from '@typecad/cuttlefish/board-catalog';
+import { discoverWest } from '../toolchain/west-discover.js';
+export const { GENERATOR_REV, isZephyrBase, locateZephyrBaseCheap, overlayPathFor, readBoardCatalogOverlayFile, loadBoardCatalogOverlay, resetBoardCatalogOverlayCache, isOverlayStale, diffBoardCatalogs, boardRecordFingerprint, findBoardInCatalog, activeBoardCatalog, resetActiveBoardCatalog, } = catalog;
+/** Sync with the full west discovery cascade behind it (the CLI's path):
+ * falls back through spawn-based discovery when the cheap fs probes find
+ * nothing. */
+export function syncBoardCatalog(opts = {}) {
+    if (opts.zephyrBase)
+        return catalog.syncBoardCatalog(opts);
+    const cheap = catalog.locateZephyrBaseCheap();
+    if (cheap)
+        return catalog.syncBoardCatalog({ zephyrBase: cheap });
+    const install = discoverWest();
+    const base = install?.zephyrBase && catalog.isZephyrBase(install.zephyrBase)
+        ? path.resolve(install.zephyrBase)
+        : undefined;
+    return catalog.syncBoardCatalog(base ? { zephyrBase: base } : {});
+}
+/** The build-path pre-step: refresh a stale overlay before a regen
+ * (fs-only discovery — no spawns during builds). */
+export function ensureFreshBoardCatalog() {
+    return catalog.ensureFreshBoardCatalog();
+}
+/** Locate a Zephyr tree by any means (spawn cascade included). */
+export function locateZephyrBaseFull() {
+    const install = discoverWest();
+    return install?.zephyrBase && catalog.isZephyrBase(install.zephyrBase)
+        ? path.resolve(install.zephyrBase)
+        : undefined;
+}

package/dist/sdk/board-data.generated.d.ts

@@ -0,0 +1,2 @@
+export { BOARD_DATA } from '@typecad/cuttlefish/api/shared';
+export type { BoardDataEntry } from '@typecad/cuttlefish/api/shared';

package/dist/sdk/board-data.generated.js

@@ -0,0 +1,4 @@
+// The board data pack lives in cuttlefish (src/create/) so the scaffolder
+// and the framework share one catalog. Re-exported here for boardgen + the
+// existing sdk imports.
+export { BOARD_DATA } from '@typecad/cuttlefish/api/shared';

package/dist/sdk/catalog-walker.d.ts

@@ -0,0 +1,90 @@
+import type { BoardDataEntry } from '@typecad/cuttlefish/api/shared';
+/** Provenance of a walked catalog — pins it to the exact tree it describes. */
+export interface BoardCatalogProvenance {
+    /** The Zephyr base directory the walk read (resolved). */
+    readonly zephyrBase: string;
+    /** VERSION file contents rendered 'MAJOR.MINOR.PATCH' (best-effort). */
+    readonly version: string;
+    /** Git HEAD of the tree when readable (best-effort; tarballs carry none). */
+    readonly gitHead?: string;
+    /** Boards-dir mtime (epoch ms) — the fallback change signal for git-less trees. */
+    readonly boardsMtimeMs: number;
+    /** ISO timestamp of the walk. */
+    readonly generatedAt: string;
+    /** Variant count, carried for quick display without loading `boards`. */
+    readonly variants: number;
+}
+/** A completed walk: records in boards/ directory order + provenance. */
+export interface BoardCatalogWalkResult {
+    readonly boards: Readonly<Record<string, BoardDataEntry>>;
+    readonly provenance: BoardCatalogProvenance;
+    readonly stats: {
+        readonly variants: number;
+        readonly withFacts: number;
+        readonly failures: number;
+    };
+}
+/** board.yml soc lookup, both formats Zephyr ships:
+ *  - legacy single-board (`board:` / top-level `socs:`): every soc listed
+ *    under the socs: block → `uniqueSocs`;
+ *  - multi-board directories (top-level `boards:` list — lyra_24_dvk,
+ *    lyra_dvk, …): each entry carries its own socs; single-soc entries map
+ *    board name → soc in `byName`. Multi-soc entries stay unmapped (their
+ *    variant yamls carry qualified identifiers).
+ *  `boardNames` lists every declared board name (the `boards:` entries and
+ *  the legacy `board:` name) — the CONFIG_BOARD_<X> stem a variant's
+ *  board.cmake guards its runner args with. */
+export interface BoardYmlSocIndex {
+    readonly byName: ReadonlyMap<string, string>;
+    readonly uniqueSocs: readonly string[];
+    readonly boardNames: readonly string[];
+}
+/** Read board.yml's board→soc index (see BoardYmlSocIndex). */
+export declare function boardYmlSocIndex(dir: string): BoardYmlSocIndex;
+/** How the caller pins runner args to ONE variant of a shared board dir. */
+export interface VariantPin {
+    /** CONFIG_BOARD stems to try in order: the board.yml entry name this
+     *  target belongs to, then the full underscored target name. */
+    readonly boardConfigs?: readonly string[];
+    /** The target's soc segment ('nrf5340'). */
+    readonly soc?: string;
+    /** Qualifier segments after the soc ('cpunet', ['a53','smp']). */
+    readonly quals?: readonly string[];
+}
+export declare function boardProbeMethods(dir: string, variant?: VariantPin): BoardDataEntry['probeMethods'];
+/** VERSION file → 'MAJOR.MINOR.PATCH' ('' when unreadable). */
+export declare function zephyrVersionOf(zephyrBase: string): string;
+/**
+ * Git HEAD of the tree, read straight off the filesystem (no git spawn —
+ * sync runs where git may be absent). Handles the plain clone (.git dir,
+ * HEAD → ref → loose ref or packed-refs) and the worktree/submodule form
+ * (.git file pointing at a gitdir). Best-effort: undefined when unreadable.
+ */
+export declare function gitHeadOf(zephyrBase: string): string | undefined;
+/** Every build target a board.yml declares, with the naming facts the
+ *  synthesizer needs (board.yml-driven dirs ship NO per-variant yamls —
+ *  nucleo_n657x0_q's sb target exists only as a board.yml entry). */
+export interface BoardYmlTarget {
+    readonly identifier: string;
+    /** The board entry name the target belongs to (CONFIG_BOARD stem). */
+    readonly boardName: string;
+    readonly soc?: string;
+    /** Variant chain segments after the soc ('sb', ['a53','smp']). */
+    readonly chain: readonly string[];
+    readonly fullName?: string;
+    readonly vendor?: string;
+}
+/**
+ * Parse board.yml into its declared build targets, both shapes:
+ * multi-board (`boards:` list) and legacy (`board:` block), with socs and
+ * (nested) variants. Variant chains accumulate through nesting levels
+ * (board/soc/v1/v2).
+ */
+export declare function boardYmlTargets(dir: string): BoardYmlTarget[];
+/**
+ * Walk `<zephyrBase>/boards` and extract one record per board variant.
+ * Reader failures degrade to the base record (identifier/name/vendor/dts +
+ * probe methods) — a board whose DTS defeats the reader still resolves, it
+ * just carries no pin facts.
+ */
+export declare function walkBoardCatalog(zephyrBase: string): BoardCatalogWalkResult;