picolet 0.0.1__py3-none-any.whl

picolet/__init__.py

@@ -0,0 +1,26 @@
+"""Picolet — compile Python programs to small self-contained native binaries.
+
+Public surface from the host-installed CLI:
+
+  picolet.cli         — command implementations (build, dev, init, run, test, ...)
+  picolet.testing     — AppHarness + webview/CDP drivers for autonomous testing
+                        (requires the [testing] extra: ``pip install picolet[testing]``)
+  picolet.templates   — starter-app templates discoverable via importlib.resources
+
+The ``picolet`` CLI command is exposed via the entry point declared in
+pyproject.toml; ``python -m picolet`` invokes the same main().
+
+Note: the in-binary ``import picolet`` inside a compiled MicroPython runtime
+refers to a separate set of frozen modules (the dispatcher, IPC transport,
+system event facade, etc.) that live under packages/picolet-runtime/python/
+and never ship in this wheel.
+"""
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    __version__ = _pkg_version("picolet")
+except Exception:
+    __version__ = "0.0.0-dev"
+
+__all__ = ("__version__",)

picolet/__main__.py

@@ -0,0 +1,125 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["mpremote"]
+# ///
+"""
+picolet — the Picolet framework CLI.
+
+Invocation paths:
+  uv run packages/picolet/picolet/__main__.py <args>   # zero-install
+  picolet <args>                                              # after pip install
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# When invoked via `uv run picolet/__main__.py`, the parent of the picolet
+# package directory (packages/picolet/) is not automatically on sys.path.
+# Insert it so `from picolet.cli import ...` resolves correctly in both the
+# uv-run and installed invocation paths.
+_PKG_PARENT = Path(__file__).parent.parent  # packages/picolet/
+if str(_PKG_PARENT) not in sys.path:
+    sys.path.insert(0, str(_PKG_PARENT))
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    VERSION = _pkg_version("picolet")
+except Exception:
+    VERSION = "0.0.1-dev"
+
+
+_TOP_DESCRIPTION = """\
+Picolet builds single-binary MicroPython apps with optional webview or LVGL GUI.
+Each app is scaffolded from a template, compiled to .mpy bytecode, and packed
+with a pre-built runtime into one self-contained executable.
+
+Quick start:
+  picolet init my-app --template hello-vue
+  cd my-app
+  picolet dev
+"""
+
+_TOP_EPILOG = """\
+Run `picolet <command> --help` for command-specific options and examples.
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="picolet",
+        description=_TOP_DESCRIPTION,
+        epilog=_TOP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=f"picolet {VERSION}",
+    )
+
+    subparsers = parser.add_subparsers(
+        title="subcommands",
+        dest="subcommand",
+        metavar="<command>",
+    )
+
+    # Register subcommands.
+    from picolet.cli import build_cmd, dev_cmd, init_cmd, run_cmd, test_cmd, validate_cmd
+
+    init_cmd.add_parser(subparsers)
+    validate_cmd.add_parser(subparsers)
+    build_cmd.add_parser(subparsers)
+    run_cmd.add_parser(subparsers)
+    dev_cmd.add_parser(subparsers)
+    test_cmd.add_parser(subparsers)
+
+    # 'picolet help <subcommand>' as an alias for 'picolet <subcommand> --help'.
+    help_parser = subparsers.add_parser(
+        "help",
+        help="show help for a subcommand",
+    )
+    help_parser.add_argument(
+        "topic",
+        nargs="?",
+        default=None,
+        metavar="<command>",
+        help="subcommand to show help for",
+    )
+    help_parser.set_defaults(func=_help_cmd)
+
+    return parser
+
+
+def _help_cmd(args) -> None:
+    """Handle `picolet help [<subcommand>]`."""
+    if args.topic:
+        # Re-parse with --help appended so argparse prints the subcommand help.
+        sys.argv = ["picolet", args.topic, "--help"]
+        _build_parser().parse_args()
+    else:
+        _build_parser().print_help()
+        sys.exit(0)
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.subcommand is None:
+        parser.print_help()
+        sys.exit(0)
+
+    try:
+        rc = args.func(args)
+    except NotImplementedError as exc:
+        print(f"error: not implemented: {exc}", file=sys.stderr)
+        sys.exit(1)
+    if rc is not None:
+        sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()

picolet/_bridge/picolet-bridge.js

@@ -0,0 +1 @@
+"use strict";var __picolet_iife__=(()=>{var w=1,i=new Map,d=new Map;function g(t){let e=JSON.stringify(t),n=window;if(n.webkit&&n.webkit.messageHandlers&&n.webkit.messageHandlers.picolet){n.webkit.messageHandlers.picolet.postMessage(e);return}if(n.chrome&&n.chrome.webview&&typeof n.chrome.webview.postMessage=="function"){n.chrome.webview.postMessage(e);return}throw new Error("[picolet] no host postMessage channel available")}window.__picolet_recv=function(t){var n,r;let e;try{e=JSON.parse(t)}catch(o){console.warn("[picolet] malformed inbound JSON:",o);return}if(Number.isInteger(e.id)&&e.id>0&&"ok"in e){let o=i.get(e.id);if(!o){console.warn("[picolet] no pending invoke for id",e.id);return}if(i.delete(e.id),e.ok)o.resolve(e.result);else{let s=e.error,a=new Error((n=s==null?void 0:s.message)!=null?n:String(e.error));a.name=(r=s==null?void 0:s.type)!=null?r:"Error",o.reject(a)}}else if(typeof e.event=="string"){let o=d.get(e.event);if(o)for(let s of Array.from(o))try{s(e.data)}catch(a){console.error("[picolet] on() handler threw:",a)}}else console.warn("[picolet] unrecognised inbound message:",e)};window.picolet={invoke(t,e=null,n){let r=w++,o=new Promise((s,a)=>{if(i.set(r,{resolve:s,reject:a}),n!=null&&n.timeout){let u=setTimeout(()=>{i.delete(r)&&a(new Error("invoke timeout"))},n.timeout),c=i.get(r);i.set(r,{resolve:l=>{clearTimeout(u),c.resolve(l)},reject:l=>{clearTimeout(u),c.reject(l)}})}});return g({id:r,cmd:t,args:e}),o},on(t,e){return d.has(t)||d.set(t,new Set),d.get(t).add(e),function(){var r;(r=d.get(t))==null||r.delete(e)}},emit(t,e=null){g({event:t,data:e})},_drainPending(t){let e=new Error(t);for(let{reject:n}of i.values())n(e);i.clear()}};})();

picolet/_runtime_data/RUNTIME_TAG

@@ -0,0 +1 @@
+runtime-v0.0.1

picolet/_runtime_data/mbm.toml

@@ -0,0 +1,71 @@
+# micropython-branch-manager (mbm)
+# Install: pip install micropython-branch-manager
+#          or: uv tool install micropython-branch-manager
+# Usage:   mbm --help
+
+[[submodules]]
+path = "micropython"
+integration_branch = "integration"
+
+# --- Base set inherited from pydfu-win ---
+
+[[submodules.branches]]
+name = "pr/lib-pyusb-windows"
+pr_url = "https://github.com/andrewleech/micropython/pull/38"
+pr_number = 38
+title = "lib/micropython-lib: Update pyusb with Windows support."
+
+[[submodules.branches]]
+name = "pr/mkrules-exe-fix"
+pr_url = "https://github.com/andrewleech/micropython/pull/39"
+pr_number = 39
+title = "py/mkrules.mk: Allow PROG to be set on the command line for .exe targets."
+
+[[submodules.branches]]
+name = "pr/mkrules-frozen-str"
+pr_url = "https://github.com/andrewleech/micropython/pull/40"
+pr_number = 40
+title = "py/mkrules.mk: Make MICROPY_MODULE_FROZEN_STR conditional on compiler."
+
+[[submodules.branches]]
+name = "pr/gc-add-heap"
+pr_url = "https://github.com/andrewleech/micropython/pull/41"
+pr_number = 41
+title = "py/modgc: Add gc.add_heap() function for runtime heap expansion."
+
+[[submodules.branches]]
+name = "pr/ports-windows-ffi"
+pr_url = "https://github.com/andrewleech/micropython/pull/42"
+pr_number = 42
+title = "ports/windows: Add FFI module support with libffi."
+
+[[submodules.branches]]
+name = "pr/unix-windows-romfs"
+pr_url = "https://github.com/andrewleech/micropython/pull/43"
+pr_number = 43
+title = "ports/unix,windows: Add embedded romfs support with auto-mount."
+
+[[submodules.branches]]
+name = "pr/ports-windows-variant-overrides"
+pr_url = "https://github.com/andrewleech/micropython/pull/44"
+pr_number = 44
+title = "ports/windows: Allow variant override of common config defines."
+
+[[submodules.branches]]
+name = "manifest_c_module"
+pr_url = "https://github.com/micropython/micropython/pull/18229"
+pr_number = 18229
+title = "py: Add c_module() manifest function for user C modules."
+
+[[submodules.branches]]
+name = "pr/windows-extra-src-c"
+pr_url = "https://github.com/andrewleech/micropython/pull/PLACEHOLDER"
+pr_number = 0
+title = "ports/windows: Add EXTRA_SRC_C hook for variant-supplied source files."
+
+# --- Renderer-specific PRs added here as they're written ---
+# - picolet webview bridge bootstrap
+# - LVGL binding integration
+# - picolet IPC C module
+# - picolet window C module
+# - macOS port (when added)

picolet/_runtime_data/sbom/runtime.toml

@@ -0,0 +1,288 @@
+# packages/picolet-runtime/sbom/runtime.toml
+#
+# Hand-curated component declarations for every native dependency that
+# ships inside a built picolet runtime.  This is the authoritative source
+# for components not discoverable from Python package metadata (C
+# libraries, vendored DLLs, submodule-pinned bindings).
+#
+# Schema
+# ------
+# Each entry in the [[component]] array MUST have:
+#   name        string   human-readable component name
+#   version     string   version string (SemVer, git SHA, or "picolet-authored")
+#   licence     string   SPDX expression (or LicenseRef-* for non-SPDX)
+#   source_url  string   canonical source / homepage URL
+#   link_type   string   "static" | "dynamic" | "build-time-only"
+#
+# Optional keys:
+#   variants    list     inclusion filter — entry applies only to listed variants
+#               omit     entry applies to all variants
+#   targets     list     inclusion filter — entry applies only to listed targets
+#               omit     entry applies to all targets
+#   purl        string   package URL (pkg:type/namespace/name@version)
+#   notes       string   free-text; citations, caveats, PR lists, etc.
+#
+# link_type meanings:
+#   static          object code is part of the runtime binary
+#   dynamic         loaded at runtime; binary carries no copy
+#   build-time-only used only during the build; absent from the shipped artifact
+#
+# Supported variants:  cli | webview | lvgl
+# Supported targets:   linux-x64 | windows-x64 | macos-x64 | macos-arm64
+
+# ---------------------------------------------------------------------------
+# Universal components — present in every runtime artifact
+# ---------------------------------------------------------------------------
+
+[[component]]
+name        = "MicroPython"
+version     = "1.24.0"
+licence     = "MIT"
+source_url  = "https://github.com/micropython/micropython"
+link_type   = "static"
+purl        = "pkg:github/micropython/micropython@1.24.0"
+notes       = "Integration PRs are MicroPython-derived patches sharing the MicroPython MIT licence; the generator injects the full PR list from mbm.toml automatically."
+
+[[component]]
+name        = "libffi"
+version     = "3.4.6"
+licence     = "MIT"
+source_url  = "https://github.com/libffi/libffi"
+link_type   = "static"
+purl        = "pkg:github/libffi/libffi@3.4.6"
+notes       = "Statically linked into all runtime variants to support ctypes / ffi module."
+
+# ---------------------------------------------------------------------------
+# LVGL-specific components (variants = ["lvgl"])
+# ---------------------------------------------------------------------------
+
+[[component]]
+name        = "lv_binding_micropython"
+version     = "4a569cd"
+licence     = "MIT"
+source_url  = "https://github.com/lvgl/lv_binding_micropython"
+link_type   = "static"
+variants    = ["lvgl"]
+purl        = "pkg:github/lvgl/lv_binding_micropython@4a569cd"
+notes       = "MicroPython binding for LVGL; git SHA pinned via submodule."
+
+[[component]]
+name        = "LVGL"
+version     = "9.x"
+licence     = "MIT"
+source_url  = "https://github.com/lvgl/lvgl"
+link_type   = "static"
+variants    = ["lvgl"]
+purl        = "pkg:github/lvgl/lvgl@9.x"
+notes       = "Pulled in as a nested submodule of lv_binding_micropython."
+
+# SDL2 — dynamic on Linux (system package) and Windows (upstream MinGW release); dynamic via brew on macOS.
+
+[[component]]
+name        = "SDL2"
+version     = "2.0.20"
+licence     = "Zlib"
+source_url  = "https://www.libsdl.org/"
+link_type   = "dynamic"
+variants    = ["lvgl"]
+targets     = ["linux-x64"]
+purl        = "pkg:github/libsdl-org/SDL@release-2.0.20"
+notes       = "System-provided SDL2 on Ubuntu 22.04; loaded dynamically via dlopen at runtime."
+
+[[component]]
+name        = "SDL2"
+version     = "2.30.10"
+licence     = "Zlib"
+source_url  = "https://www.libsdl.org/"
+link_type   = "dynamic"
+variants    = ["lvgl"]
+targets     = ["windows-x64"]
+purl        = "pkg:github/libsdl-org/SDL@release-2.30.10"
+notes       = "Official upstream MinGW devel release (SDL2-devel-2.30.10-mingw.tar.gz). SDL2.dll redistributed alongside the runtime binary. Linked via libSDL2.dll.a import library at build time. The NFR-3 ceiling for windows-x64/lvgl is relaxed to 3 MiB to accommodate the unstripped DLL; a future pass targeting < 2 MiB via custom from-source build (-ffunction-sections + --gc-sections) is on the roadmap."
+
+[[component]]
+name        = "SDL2"
+version     = "2.x.x (brew)"
+licence     = "Zlib"
+source_url  = "https://www.libsdl.org/"
+link_type   = "dynamic"
+variants    = ["lvgl"]
+targets     = ["macos-x64", "macos-arm64"]
+notes       = "Installed via 'brew install sdl2'. SDL2 Cocoa backend provides the macOS window and event loop. Headers resolved from brew --prefix sdl2; dylib loaded dynamically at runtime. NFR-MAC-4 accepts dynamic SDL2 on macOS (equivalent to system libSDL2.so on Linux)."
+
+# ---------------------------------------------------------------------------
+# WebView components (variants = ["webview"])
+# ---------------------------------------------------------------------------
+
+[[component]]
+name        = "WebKitGTK"
+version     = "4.1"
+licence     = "LGPL-2.1-or-later"
+source_url  = "https://webkitgtk.org/"
+link_type   = "dynamic"
+variants    = ["webview"]
+targets     = ["linux-x64"]
+purl        = "pkg:deb/ubuntu/libwebkit2gtk-4.1-0"
+notes       = "LGPL-2.1-or-later; loaded dynamically — the Picolet runtime binary does not statically incorporate any LGPL object code. Relinking is possible by replacing the system WebKitGTK package. NFR-5 is satisfied."
+
+[[component]]
+name        = "WebKit.framework (Apple system framework)"
+version     = "bundled-with-macos"
+licence     = "LicenseRef-Apple-System-Framework"
+source_url  = "https://developer.apple.com/documentation/webkit"
+link_type   = "dynamic"
+variants    = ["webview"]
+targets     = ["macos-x64", "macos-arm64"]
+notes       = "Apple system framework; not redistributed. Reached via -framework WebKit at link time; all ObjC calls go through objc_msgSend (libobjc.A.dylib) at runtime — no static ObjC++ object code is incorporated. Redistribution permitted under the Apple Developer Programme licence."
+
+[[component]]
+name        = "Cocoa / AppKit (Apple system framework)"
+version     = "bundled-with-macos"
+licence     = "LicenseRef-Apple-System-Framework"
+source_url  = "https://developer.apple.com/documentation/appkit"
+link_type   = "dynamic"
+variants    = ["webview"]
+targets     = ["macos-x64", "macos-arm64"]
+notes       = "Apple system framework; not redistributed. Linked as -framework Cocoa for NSApplication, NSWindow, NSView. All calls go through objc_msgSend at runtime. Redistribution permitted under the Apple Developer Programme licence."
+
+[[component]]
+name        = "Foundation (Apple system framework)"
+version     = "bundled-with-macos"
+licence     = "LicenseRef-Apple-System-Framework"
+source_url  = "https://developer.apple.com/documentation/foundation"
+link_type   = "dynamic"
+variants    = ["webview"]
+targets     = ["macos-x64", "macos-arm64"]
+notes       = "Apple system framework; not redistributed. Linked as -framework Foundation for NSString, NSData, NSURL, NSDictionary helpers used in picolet_webview_mac.c. Redistribution permitted under the Apple Developer Programme licence."
+
+[[component]]
+name        = "Microsoft.Web.WebView2"
+version     = "1.0.2210.55"
+licence     = "LicenseRef-MS-WebView2-Fixed"
+source_url  = "https://aka.ms/webview2"
+link_type   = "dynamic"
+variants    = ["webview"]
+targets     = ["windows-x64"]
+purl        = "pkg:nuget/Microsoft.Web.WebView2@1.0.2210.55"
+notes       = "Redistributable under Microsoft's fixed-terms licence; not an OSI-approved SPDX identifier. Governing licence: https://www.nuget.org/packages/Microsoft.Web.WebView2/1.0.2210.55/License"
+
+[[component]]
+name        = "WebView2Loader.dll"
+version     = "1.0.2210.55"
+licence     = "LicenseRef-MS-WebView2-Fixed"
+source_url  = "https://aka.ms/webview2"
+link_type   = "dynamic"
+variants    = ["webview"]
+targets     = ["windows-x64"]
+purl        = "pkg:nuget/Microsoft.Web.WebView2@1.0.2210.55#WebView2Loader.dll"
+notes       = "Loader DLL bundled inside the app romfs at picolet/WebView2Loader.dll; extracted to %LOCALAPPDATA%\\picolet\\<pid>\\ at runtime. Governing licence: https://www.nuget.org/packages/Microsoft.Web.WebView2/1.0.2210.55/License"
+
+[[component]]
+name        = "WebView2_min.h (derived)"
+version     = "picolet-authored"
+licence     = "MIT"
+source_url  = "https://github.com/andrewleech/picolet"
+link_type   = "build-time-only"
+variants    = ["webview"]
+targets     = ["windows-x64"]
+notes       = "Picolet-authored minimal header derived from the public Microsoft WebView2 C API; used only at build time. NFR-6: all Picolet-authored code is MIT."
+
+# ---------------------------------------------------------------------------
+# pydfu example — libusb-1.0 (loaded at runtime; platform-specific)
+# ---------------------------------------------------------------------------
+
+[[component]]
+name        = "libusb-1.0"
+version     = "1.0.27"
+licence     = "LGPL-2.1-or-later"
+source_url  = "https://github.com/libusb/libusb"
+link_type   = "dynamic"
+targets     = ["linux-x64"]
+purl        = "pkg:deb/ubuntu/libusb-1.0-0@1.0.27-1"
+notes       = "LGPL-2.1-or-later; loaded dynamically via ffi.open('libusb-1.0.so.0') at runtime by the pydfu example app. Version tracks the Ubuntu package libusb-1.0-0 (2:1.0.27-1), not the libusb API series. The Picolet runtime binary does not statically incorporate any LGPL object code. Relinking is possible by replacing the system libusb-1.0-0 package. NFR-5 is satisfied."
+
+[[component]]
+name        = "libusb-1.0 (macOS dylib)"
+version     = "1.0.27"
+licence     = "LGPL-2.1-or-later"
+source_url  = "https://github.com/libusb/libusb"
+link_type   = "dynamic"
+targets     = ["macos-x64", "macos-arm64"]
+purl        = "pkg:brew/libusb@1.0.27"
+notes       = "LGPL-2.1-or-later; loaded dynamically via ffi.open('libusb-1.0.dylib') at runtime by the pydfu example app (FR-EX-MAC-2). Installed via 'brew install libusb'. On x64 the dylib resolves from /usr/local/lib; on arm64 from /opt/homebrew/lib. The Picolet runtime binary does not statically incorporate any LGPL object code. NFR-MAC-8 is satisfied."
+
+[[component]]
+name        = "libusb-1.0 (Windows DLL)"
+version     = "1.0.26"
+licence     = "LGPL-2.1-or-later"
+source_url  = "https://github.com/libusb/libusb"
+link_type   = "dynamic"
+targets     = ["windows-x64"]
+purl        = "pkg:github/libusb/libusb@v1.0.26"
+notes       = "LGPL-2.1-or-later; vendored Windows x64 DLL bundled in the pydfu example romfs at /rom/src/_usb/libusb-1.0.dll. Loaded dynamically via ffi.open() at runtime; the Picolet runtime binary contains no LGPL object code. LGPL-2.1-or-later compliance: dynamic linkage only; users can replace the DLL with their own build. DLL sourced from the pydfu-win submodule (nickel-org/libusb-package build pipeline). NFR-5 is satisfied."
+
+# ---------------------------------------------------------------------------
+# pydfu example fonts — bundled in romfs/ui/fonts/ (PH19)
+# ---------------------------------------------------------------------------
+
+[[component]]
+name        = "Monaspace Neon"
+version     = "1.101"
+licence     = "OFL-1.1"
+source_url  = "https://github.com/githubnext/monaspace"
+link_type   = "static"
+purl        = "pkg:github/githubnext/monaspace@v1.101"
+notes       = "OFL-1.1 (SIL Open Font Licence). Used as display/monospace font in the pydfu example UI (square-tech variant of the Monaspace family; industrial-aesthetic replacement for JetBrains Mono per NFR-EX-AESTHETIC). Woff2 files bundled in romfs at /rom/ui/fonts/MonaspaceNeon-Regular.woff2 and /rom/ui/fonts/MonaspaceNeon-Bold.woff2 (sourced from githubnext/monaspace v1.101)."
+
+[[component]]
+name        = "IBM Plex Sans"
+version     = "6.4.0"
+licence     = "OFL-1.1"
+source_url  = "https://github.com/IBM/plex"
+link_type   = "static"
+purl        = "pkg:github/IBM/plex@v6.4.0"
+notes       = "OFL-1.1 (SIL Open Font Licence). Used as body font in the pydfu example UI. Latin subset woff2 files (Regular + SemiBold) bundled in romfs at /rom/ui/fonts/. Sourced from @fontsource/ibm-plex-sans npm package."
+
+# ---------------------------------------------------------------------------
+# notes example fonts — bundled in romfs/ui/fonts/ (PH20)
+# ---------------------------------------------------------------------------
+
+[[component]]
+name        = "Source Serif 4"
+version     = "4.005"
+licence     = "OFL-1.1"
+source_url  = "https://github.com/adobe-fonts/source-serif"
+link_type   = "static"
+purl        = "pkg:github/adobe-fonts/source-serif@4.005R"
+notes       = "OFL-1.1 (SIL Open Font Licence). Used as display/heading font in the notes example UI. Variable woff2 files (Roman + Italic, weight range 200-900) bundled in romfs at /rom/ui/fonts/. Renamed from canonical axis-tag filenames to avoid Vite bracket-character issues (O4 in PH20 plan)."
+
+[[component]]
+name        = "Source Sans 3"
+version     = "3.052"
+licence     = "OFL-1.1"
+source_url  = "https://github.com/adobe-fonts/source-sans"
+link_type   = "static"
+purl        = "pkg:github/adobe-fonts/source-sans@3.052R"
+notes       = "OFL-1.1 (SIL Open Font Licence). Used as body/UI font in the notes example UI. Variable woff2 (Upright, weight range 200-900) bundled in romfs at /rom/ui/fonts/source-sans-3.woff2."
+
+# ---------------------------------------------------------------------------
+# dashboard example fonts — bundled in romfs/ui/fonts/ (PH22)
+# ---------------------------------------------------------------------------
+
+[[component]]
+name        = "Antonio"
+version     = "22"
+licence     = "OFL-1.1"
+source_url  = "https://fonts.google.com/specimen/Antonio"
+link_type   = "static"
+purl        = "pkg:generic/google-fonts/Antonio@v22"
+notes       = "OFL-1.1 (SIL Open Font Licence). Used as condensed display font in the dashboard example UI (OFL fallback for GT America Condensed per spec aesthetic). Variable font: a single latin-subset woff2 covers the full weight axis; Antonio-Bold.woff2 is byte-identical to Antonio-Regular.woff2 (Google Fonts serves one file for all weights). Both files bundled in romfs at /rom/ui/fonts/. Downloaded from fonts.gstatic.com."
+
+[[component]]
+name        = "DM Sans"
+version     = "17"
+licence     = "OFL-1.1"
+source_url  = "https://fonts.google.com/specimen/DM+Sans"
+link_type   = "static"
+purl        = "pkg:generic/google-fonts/DM+Sans@v17"
+notes       = "OFL-1.1 (SIL Open Font Licence). Used as body/label font in the dashboard example UI (OFL fallback for GT Walsheim per spec aesthetic). Variable font: a single latin-subset woff2 covers the full weight axis; DMSans-Medium.woff2 is byte-identical to DMSans-Regular.woff2 (Google Fonts serves one file for all weights). Both files bundled in romfs at /rom/ui/fonts/. Downloaded from fonts.gstatic.com."

picolet/cli/RUNTIME_TAG

@@ -0,0 +1 @@
+runtime-v0.1.0

picolet/cli/_paths.py

@@ -0,0 +1,144 @@
+"""
+Shared path / project-resolution helpers for the picolet CLI.
+
+Used by run_cmd, dev_cmd, and build_cmd. Plain str constants only —
+no enum, since the framework is intended to be self-hostable on
+MicroPython.
+"""
+from __future__ import annotations
+
+import stat
+import sys
+import tomllib
+from pathlib import Path
+
+from picolet.cli._targets import host_target, target_exe_suffix
+from picolet.cli.validator import validate_toml
+
+
+# Directory components that should never be watched or scanned for source
+# freshness — build outputs, caches, compiled artifacts.
+_IGNORE_DIRS = frozenset({"target", ".picolet-cache", "__pycache__", "node_modules", "dist"})
+_IGNORE_SUFFIXES = frozenset({".pyc", ".mpy"})
+
+
+def find_picolet_toml(start: Path) -> Path | None:
+    """Walk up from ``start`` looking for ``picolet.toml``.
+
+    Returns the located path, or ``None`` when the filesystem root is reached
+    without finding one.  The walk is iterative to avoid stack-depth issues
+    on pathological paths (and to keep the implementation MicroPython-safe
+    by avoiding deep recursion).
+    """
+    current = start
+    while True:
+        candidate = current / "picolet.toml"
+        if candidate.is_file():
+            return candidate
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def resolve_app(args) -> tuple[Path, dict, str, Path]:
+    """Validate picolet.toml and resolve the binary path.
+
+    Returns ``(toml_path, data, target, binary_path)``. Exits 1 on any
+    validation error.
+    """
+    toml_path = find_picolet_toml(Path.cwd())
+    if toml_path is None:
+        print(
+            "error: picolet.toml not found in current directory or any ancestor",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    _all_results = validate_toml(toml_path)
+    _hard_errors = [e for e in _all_results if e.level != "warn"]
+    for e in _all_results:
+        if e.level == "warn":
+            print(str(e), file=sys.stderr)
+    if _hard_errors:
+        for e in _hard_errors:
+            print(str(e), file=sys.stderr)
+        sys.exit(1)
+
+    with open(toml_path, "rb") as fh:
+        data = tomllib.load(fh)
+
+    target = args.target if args.target else host_target()
+    app_name: str = data["app"]["name"]
+    app_root: Path = toml_path.parent
+
+    binary_path = app_root / "target" / target / (app_name + target_exe_suffix(target))
+
+    return toml_path, data, target, binary_path
+
+
+def should_ignore(path: Path) -> bool:
+    """Return True if path is in a watch-ignored location."""
+    for part in path.parts:
+        if part in _IGNORE_DIRS or part.startswith("."):
+            return True
+    return path.suffix in _IGNORE_SUFFIXES
+
+
+def collect_watch_paths(app_root: Path, data: dict) -> list[Path]:
+    """Return the list of paths/dirs to watch (may not all exist)."""
+    src_dir = app_root / Path(data["app"]["entry"]).parent
+    paths = [app_root / "picolet.toml", src_dir]
+
+    ui = data.get("ui", {})
+    if ui:
+        ui_root = ui.get("root")
+        if ui_root:
+            paths.append(app_root / ui_root)
+        else:
+            fallback = app_root / "ui"
+            if fallback.is_dir():
+                paths.append(fallback)
+
+    return paths
+
+
+def sources_newer_than(
+    toml_path: Path, data: dict, binary: Path
+) -> bool:
+    """Return True if any watched source is newer than the binary."""
+    binary_mtime = binary.stat().st_mtime
+    watch_paths = collect_watch_paths(toml_path.parent, data)
+    for _path, mtime, _size in iter_watched_files(watch_paths):
+        if mtime > binary_mtime:
+            return True
+    return False
+
+
+def iter_watched_files(watch_paths):
+    """Yield ``(path, mtime, size)`` for each watched non-ignored regular file.
+
+    Single ``stat()`` per file via ``stat.S_ISREG`` — no separate
+    ``is_file()`` pass.
+    """
+    for watch_path in watch_paths:
+        if should_ignore(watch_path):
+            continue
+        try:
+            st = watch_path.stat()
+        except OSError:
+            continue
+        if stat.S_ISREG(st.st_mode):
+            yield watch_path, st.st_mtime, st.st_size
+            continue
+        if not stat.S_ISDIR(st.st_mode):
+            continue
+        for f in watch_path.rglob("*"):
+            if should_ignore(f):
+                continue
+            try:
+                fst = f.stat()
+            except OSError:
+                continue
+            if stat.S_ISREG(fst.st_mode):
+                yield f, fst.st_mtime, fst.st_size