learningfoundry 0.79.1__tar.gz → 0.79.2__tar.gz

{learningfoundry-0.79.1 → learningfoundry-0.79.2}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.79.2] - 2026-06-02
+
+Fix sql.js browser-ESM init failure in the SvelteKit template's dev-server preview path. Module and lesson routes were returning 500 in `learningfoundry preview` because `(await import('sql.js')).default` was `undefined` in the browser. Diagnosed in `docs/specs/bug-sql-js-browser-esm-spec.md`; fixed via Story J.y.
+
+### Fixed
+
+- **`vite.config.ts` — `optimizeDeps.exclude` scoped to test mode only.** The exclude was added by Story J.w as a belt-and-braces safety net (J.w's actual fix was the `vi.mock('@pointmatic/quizazz', …)`), but in dev/prod mode it disables Vite's CJS→ESM dep pre-bundling for `sql.js`. Without that pre-bundling layer, the dev-server browser receives `sql.js@1.13+`'s raw UMD `dist/sql-wasm-browser.js`, whose CJS/AMD export branches don't run in pure browser ESM — so `.default` is `undefined` and `initSqlJsFn(...)` throws `TypeError: initSqlJsFn is not a function`. The exclude is now gated on `process.env.VITEST` so vitest 4.x still skips the dep-optimizer (preserving the J.w WASM-magic-header fix) while dev/prod regain CJS-interop.
+- **`src/lib/db/database.ts` — typed `CjsEsmInteropError` backstop.** The dynamic `import('sql.js')` site now reads `.default` defensively and throws a named `CjsEsmInteropError` instead of an opaque `TypeError` when the initializer is missing. So the *next* sql.js drift surfaces a self-describing error in the dev-server console rather than the previous unactionable shape.
+
+### Verified
+
+- `pnpm exec vitest run` → 278 passed (was 277; +1 new contract test for the CJS/ESM interop guard).
+- `pnpm exec svelte-check` → 0 errors, 0 warnings.
+- `pnpm exec vite build` → succeeds (confirms the gated `optimizeDeps.exclude` doesn't break prod build; the J.w comment's "covers both prod build" framing was incorrect).
+- Manual: dev-server `/{moduleId}/{lessonId}` route renders without 500 in the d802-deep-learning consumer (verification scheduled with the consumer team — captured as a `[ ]` follow-up).
+
 ## [0.79.1] - 2026-05-22
 
 Fix five pre-existing `svelte-check` and `vitest` failures uncovered after the J.v post-assessment work landed (Story J.w). All five are type-only or test-only — no runtime behaviour changes.

{learningfoundry-0.79.1 → learningfoundry-0.79.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learningfoundry
-Version: 0.79.1
+Version: 0.79.2
 Summary: A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application.
 Project-URL: Homepage, https://github.com/pointmatic/learningfoundry
 Project-URL: Repository, https://github.com/pointmatic/learningfoundry

learningfoundry-0.79.2/docs/specs/nbfoundry/README.md

@@ -0,0 +1,100 @@
+# nbfoundry
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+
+Marimo-based notebook framework for ML/DS work. One notebook source compiles into two
+artifacts: a standalone runnable application and an `ExerciseBlock`-compatible artifact
+that drops into a learningfoundry curriculum.
+
+For the why, see [`docs/specs/concept.md`](docs/specs/concept.md). For the what, see
+[`docs/specs/features.md`](docs/specs/features.md). For the how, see
+[`docs/specs/tech-spec.md`](docs/specs/tech-spec.md).
+
+## Installation
+
+`nbfoundry` targets Python 3.12.13 with the pinned Pyve + micromamba environment defined
+in [`src/nbfoundry/templates/environment.yml`](src/nbfoundry/templates/environment.yml).
+That one shared file ships as package data, gets copied into every scaffolded project by
+`nbfoundry init`, and is the same spec the standalone artifact emitter falls back to.
+
+### Apple Silicon quickstart
+
+The pinned stack defaults to Apple Silicon with Metal/MPS acceleration across PyTorch,
+TensorFlow (via `tensorflow-metal`), and the bundled Keras 3 namespace from TF 2.16+.
+It also ships the wider cross-project stack (HuggingFace `transformers` / `datasets` /
+`peft`, Optuna, the plotly/seaborn/pyarrow utility set, dev tooling, and the
+Pointmatic-internal `ml-datarefinery` package).
+
+To verify the stack on a clean Apple Silicon machine, copy the shared env file and
+`scripts/metal_smoke.py` into a fresh directory and let pyve build a micromamba-backed
+env from the spec:
+
+```bash
+mkdir nbfoundry-test && cd nbfoundry-test
+mkdir scripts
+cp <path-to-nbfoundry-root>/src/nbfoundry/templates/environment.yml .
+cp <path-to-nbfoundry-root>/scripts/metal_smoke.py scripts/
+pyve init --backend micromamba
+pyve run python scripts/metal_smoke.py
+```
+
+`pyve init --backend micromamba` reads the local `environment.yml` and provisions the
+runtime env from it. The smoke script exercises PyTorch / TensorFlow / Keras against the
+MPS device and then imports every other package added in Phase F (HuggingFace, Optuna,
+plotly, seaborn, etc.) to assert basic availability — it doesn't import `nbfoundry`
+itself, so no `pip install -e .` step is required for the verify.
+
+Successful output ends with `all frameworks ran on MPS ✓`. If any framework or import
+fails, the script reports which one and why (no MPS device, plugin not installed,
+package missing from the env, etc.).
+
+#### Cross-platform users (CUDA / CPU-only)
+
+The shared `environment.yml` ships comment-delimited swap blocks for the framework
+sections:
+
+- **PyTorch CUDA:** drop the `pytorch` conda-forge line and add to the `pip:` block
+  `--extra-index-url https://download.pytorch.org/whl/cu126` + `torch` (or `.../cu128`
+  for CUDA 12.8).
+- **TensorFlow CPU-only or Linux+CUDA:** replace the `tensorflow-macos` /
+  `tensorflow-metal` pip lines with `tensorflow>=2.16` (CPU-only) or
+  `tensorflow[and-cuda]>=2.16` (Linux + CUDA).
+
+Both swap blocks are documented inline in the env file at the framework section.
+
+### Development setup (Pyve two-env)
+
+```bash
+pyve init
+pyve run pip install -e .
+pyve testenv init
+pyve testenv install -r requirements-dev.txt
+```
+
+## Usage
+
+The CLI surface (`nbfoundry init`, `compile`, `compile-exercise`, `validate`) lands
+across Phase D. See [`docs/specs/stories.md`](docs/specs/stories.md) for the
+implementation roadmap.
+
+## Releasing to PyPI
+
+Releases ship through [`.github/workflows/publish.yml`](.github/workflows/publish.yml),
+which is triggered by pushing a `v*` tag. The workflow builds an sdist + wheel with
+`hatch build` and publishes via PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC, no long-lived API tokens).
+
+One-time PyPI setup: register `nbfoundry` on PyPI and add a pending trusted publisher
+under the project's *Publishing* settings — owner `pointmatic`, repository `nbfoundry`,
+workflow `publish.yml`, environment `pypi`.
+
+Per-release procedure:
+
+1. Land the version-bump story on `main` (package version in `src/nbfoundry/_version.py`
+   and a matching `CHANGELOG.md` entry).
+2. Tag the commit with the matching `v<version>` (e.g. `git tag v0.29.0 && git push origin v0.29.0`).
+3. The workflow verifies the tag matches `hatch version`, builds the distributions, and
+   publishes to PyPI under the `pypi` GitHub environment.
+
+The workflow refuses to publish if the tag and `hatch version` disagree, so the only way
+to ship a release is to tag the same commit that owns the version bump.