learningfoundry 0.32.0__tar.gz → 0.34.0__tar.gz

{learningfoundry-0.32.0 → learningfoundry-0.34.0}/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.34.0] - 2026-04-29
+
+### Changed
+
+- **`learningfoundry build` now preserves install/build state across rebuilds.** Previously every rebuild wiped the entire output directory, including any existing `node_modules/`, `pnpm-lock.yaml`, `build/`, and `.svelte-kit/` — forcing the user to `pnpm install` after every regen. Now those four paths are moved into the fresh template copy before the swap, so iteration is install → build, then any number of `learningfoundry build` re-runs followed by just `pnpm build` (or `pnpm dev`).
+  - `src/learningfoundry/generator.py` — new `_PRESERVED_PATHS` list + `_move_preserved()` helper used by `_atomic_copy()`. Same paths are also passed to `shutil.ignore_patterns` so a stray `node_modules/` in the dev template directory never ships to user output.
+  - The "output directory exists" log message changed from `WARNING` ("will be overwritten") to `INFO` ("refreshing template files; preserving …") to reflect the new behaviour.
+
+### Added
+
+- **Smart post-build next-steps message in the CLI** based on detected dep state:
+  - `FIRST_BUILD` (no `node_modules/`) → `Next: cd dist && pnpm install && pnpm build`
+  - `CHANGED` (any declared dep missing from `node_modules/`) → `⚠️  Dependencies changed since last install. Run: cd dist && pnpm install && pnpm build`
+  - `UNCHANGED` (every declared dep present) → `Next: cd dist && pnpm build`
+- New public API: `learningfoundry.generator.check_dep_state(output_dir)` returning a `DepState` enum, used by the CLI but also callable from third-party tooling.
+
+### Added (tests)
+
+- `tests/test_generator.py::TestPreserveInstallState` — 5 cases covering preservation of `node_modules/`, `pnpm-lock.yaml`, `build/`, `.svelte-kit/`, and confirmation that template files (e.g. `curriculum.json`) still refresh on rebuild.
+- `tests/test_generator.py::TestCheckDepState` — 4 cases covering first-build, all-deps-installed, missing-dep, and malformed-`package.json` paths.
+
+### Performance
+
+- Smoke build is ~40% faster (~10s vs ~17s) because the SvelteKit template's leftover dev `node_modules/` (which a developer's local pnpm runs may create in the in-repo template) is no longer copied into every `learningfoundry build` output.
+
+## [0.33.0] - 2026-04-29
+
+### Added
+
+- **LaTeX math rendering in lesson markdown** via [KaTeX](https://katex.org/). Both inline (`$...$`) and display (`$$...$$`) syntax are supported and rendered to HTML at parse time — no runtime JS overhead per lesson view.
+  - `src/learningfoundry/sveltekit_template/package.json` — added `katex ^0.16.11` and `marked-katex-extension ^5.1.4` to dependencies
+  - `src/learningfoundry/sveltekit_template/src/lib/utils/markdown.ts` — registered `markedKatex({ throwOnError: false })` so malformed LaTeX renders the source verbatim instead of throwing
+  - `src/learningfoundry/sveltekit_template/src/app.css` — `@import 'katex/dist/katex.min.css';` so rendered formulas are styled
+
+### Added (tests)
+
+- `src/learningfoundry/sveltekit_template/src/lib/utils/markdown.test.ts` — 6 vitest cases covering blank input, headings, fenced code, inline math, display math, and graceful malformed-LaTeX handling
+- `tests/test_smoke_sveltekit.py::test_katex_styles_in_bundled_css` — regression guard asserting `.katex` rules land in the bundled CSS
+
 ## [0.32.0] - 2026-04-29
 
 ### Fixed

{learningfoundry-0.32.0 → learningfoundry-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learningfoundry
-Version: 0.32.0
+Version: 0.34.0
 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.32.0 → learningfoundry-0.34.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "learningfoundry"
-version = "0.32.0"
+version = "0.34.0"
 description = "A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application."
 readme = "README.md"
 license = "Apache-2.0"

{learningfoundry-0.32.0 → learningfoundry-0.34.0}/src/learningfoundry/__init__.py

@@ -1,4 +1,4 @@
 # Copyright 2026 Pointmatic
 # SPDX-License-Identifier: Apache-2.0
 
-__version__ = "0.32.0"
+__version__ = "0.34.0"

{learningfoundry-0.32.0 → learningfoundry-0.34.0}/src/learningfoundry/cli.py

@@ -110,6 +110,25 @@ def build(
 
     click.echo(f"Build complete → {output_dir}")
 
+    from learningfoundry.generator import DepState, check_dep_state
+
+    state = check_dep_state(output_dir)
+    if state is DepState.FIRST_BUILD:
+        click.echo("")
+        click.echo(f"Next: cd {output_dir} && pnpm install && pnpm build")
+        click.echo("  (or `pnpm dev` for a live-reloading dev server)")
+    elif state is DepState.CHANGED:
+        click.echo("")
+        click.echo(
+            "⚠️  Dependencies changed since last install "
+            "(new packages in package.json)."
+        )
+        click.echo(f"   Run: cd {output_dir} && pnpm install && pnpm build")
+    else:
+        click.echo("")
+        click.echo(f"Next: cd {output_dir} && pnpm build")
+        click.echo("  (or `pnpm dev` for a live-reloading dev server)")
+
 
 # ---------------------------------------------------------------------------
 # validate

learningfoundry-0.34.0/src/learningfoundry/generator.py

@@ -0,0 +1,193 @@
+# Copyright 2026 Pointmatic
+# SPDX-License-Identifier: Apache-2.0
+"""SvelteKit project generator — copies template and writes curriculum.json."""
+
+import dataclasses
+import json
+import logging
+import shutil
+import tempfile
+from enum import StrEnum
+from pathlib import Path
+
+from learningfoundry.exceptions import GenerationError
+from learningfoundry.resolver import ResolvedCurriculum
+
+logger = logging.getLogger("learningfoundry.generator")
+
+_TEMPLATE_DIR = Path(__file__).parent / "sveltekit_template"
+
+# Paths that represent install/build state in the generated project. These
+# are preserved across `learningfoundry build` re-runs so the user does not
+# have to `pnpm install` after every regen. Template files (package.json,
+# src/, static/, configs) are still refreshed every time.
+_PRESERVED_PATHS: tuple[str, ...] = (
+    "node_modules",
+    "pnpm-lock.yaml",
+    "build",
+    ".svelte-kit",
+)
+
+
+class DepState(StrEnum):
+    """State of installed dependencies relative to the generated package.json."""
+
+    FIRST_BUILD = "first_build"
+    """No `node_modules/` exists in the output directory."""
+
+    UNCHANGED = "unchanged"
+    """Every declared dep has a corresponding installed package."""
+
+    CHANGED = "changed"
+    """`node_modules/` exists but at least one declared dep is missing
+    (e.g. user upgraded `learningfoundry` and the template added a new dep)."""
+
+
+def generate_app(
+    resolved: ResolvedCurriculum,
+    output_dir: Path,
+    template_dir: Path | None = None,
+) -> None:
+    """Generate a SvelteKit project from a resolved curriculum.
+
+    Copies ``sveltekit_template/`` to ``output_dir`` atomically (write to a
+    temp directory, then move into place), then writes ``curriculum.json``
+    into ``output_dir/static/``.
+
+    If ``output_dir`` already exists it is replaced with a warning.
+
+    Args:
+        resolved: Fully resolved curriculum from ``resolve_curriculum()``.
+        output_dir: Destination path for the generated SvelteKit project.
+        template_dir: Override template source. Defaults to the package's
+            ``sveltekit_template/`` directory.
+
+    Raises:
+        GenerationError: If the template directory does not exist or any
+            file operation fails.
+    """
+    src = template_dir or _TEMPLATE_DIR
+
+    if not src.exists():
+        raise GenerationError(
+            f"SvelteKit template directory not found: `{src}`. "
+            "Run `learningfoundry` from the project root, or pass "
+            "`template_dir` explicitly."
+        )
+
+    if output_dir.exists():
+        logger.info(
+            "Output directory `%s` already exists; refreshing template files "
+            "(preserving node_modules/, pnpm-lock.yaml, build/, .svelte-kit/).",
+            output_dir,
+        )
+
+    _atomic_copy(src, output_dir)
+    _write_curriculum_json(resolved, output_dir)
+
+    logger.info("Generated SvelteKit project at: %s", output_dir)
+
+
+def _atomic_copy(src: Path, dst: Path) -> None:
+    """Copy src tree to dst atomically via a sibling temp directory.
+
+    If ``dst`` already exists, install/build state listed in
+    :data:`_PRESERVED_PATHS` is moved from the existing ``dst`` into the
+    fresh template copy before the swap, so users do not have to re-run
+    ``pnpm install`` after every ``learningfoundry build``.
+    """
+    parent = dst.parent
+    parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with tempfile.TemporaryDirectory(dir=parent, prefix=".lf_gen_") as tmp_str:
+            tmp = Path(tmp_str) / dst.name
+            # Never ship user-side artifacts from the template, even if a
+            # local dev environment has them (e.g. a stray node_modules/
+            # from running pnpm in the template dir during development).
+            shutil.copytree(
+                src,
+                tmp,
+                ignore=shutil.ignore_patterns(*_PRESERVED_PATHS),
+            )
+            if dst.exists():
+                _move_preserved(dst, tmp)
+                shutil.rmtree(dst)
+            tmp.rename(dst)
+    except OSError as exc:
+        raise GenerationError(
+            f"Failed to generate project at `{dst}`: {exc}"
+        ) from exc
+
+
+def _move_preserved(existing: Path, fresh: Path) -> None:
+    """Move install/build state from ``existing`` into ``fresh`` in place.
+
+    Any template-shipped placeholder at the same path inside ``fresh`` is
+    removed first so the move never collides.
+    """
+    for name in _PRESERVED_PATHS:
+        source = existing / name
+        if not source.exists() and not source.is_symlink():
+            continue
+        target = fresh / name
+        if target.exists() or target.is_symlink():
+            if target.is_dir() and not target.is_symlink():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+        shutil.move(str(source), str(target))
+
+
+def check_dep_state(output_dir: Path) -> DepState:
+    """Inspect ``output_dir`` to determine whether `pnpm install` is needed.
+
+    A dep is considered "installed" if ``node_modules/<name>/package.json``
+    exists. We do not check version ranges — that is pnpm's job. This is a
+    presence check designed to detect the common case where the generated
+    `package.json` adds a new dep (e.g. after a `learningfoundry` upgrade)
+    that is not yet in `node_modules/`.
+    """
+    node_modules = output_dir / "node_modules"
+    if not node_modules.is_dir():
+        return DepState.FIRST_BUILD
+
+    package_json = output_dir / "package.json"
+    if not package_json.is_file():
+        return DepState.FIRST_BUILD
+
+    try:
+        data = json.loads(package_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        # Malformed package.json — surface as "changed" so the user is
+        # nudged to run pnpm install (which will report the real error).
+        return DepState.CHANGED
+
+    declared: dict[str, str] = {
+        **(data.get("dependencies") or {}),
+        **(data.get("devDependencies") or {}),
+    }
+    for name in declared:
+        if not (node_modules / name / "package.json").is_file():
+            return DepState.CHANGED
+    return DepState.UNCHANGED
+
+
+def _write_curriculum_json(resolved: ResolvedCurriculum, output_dir: Path) -> None:
+    """Serialize ResolvedCurriculum to output_dir/static/curriculum.json."""
+    static_dir = output_dir / "static"
+    static_dir.mkdir(parents=True, exist_ok=True)
+
+    curriculum_json = output_dir / "static" / "curriculum.json"
+    try:
+        data = dataclasses.asdict(resolved)
+        curriculum_json.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        raise GenerationError(
+            f"Failed to write curriculum.json to `{curriculum_json}`: {exc}"
+        ) from exc
+
+    logger.debug("Wrote curriculum.json (%d bytes)", curriculum_json.stat().st_size)

{learningfoundry-0.32.0 → learningfoundry-0.34.0}/src/learningfoundry/sveltekit_template/package.json

@@ -13,8 +13,10 @@
   },
   "dependencies": {
     "@sveltejs/kit": "^2.0.0",
+    "katex": "^0.16.11",
     "lucide-svelte": "^0.468.0",
     "marked": "^18.0.0",
+    "marked-katex-extension": "^5.1.4",
     "sql.js": "^1.12.0",
     "svelte": "^5.0.0"
   },

{learningfoundry-0.32.0 → learningfoundry-0.34.0}/src/learningfoundry/sveltekit_template/src/app.css

@@ -1,4 +1,5 @@
 /* Copyright 2026 Pointmatic */
 /* SPDX-License-Identifier: Apache-2.0 */
 @import 'tailwindcss';
+@import 'katex/dist/katex.min.css';
 @plugin '@tailwindcss/typography';

learningfoundry-0.34.0/src/learningfoundry/sveltekit_template/src/lib/utils/markdown.test.ts

@@ -0,0 +1,54 @@
+// Copyright 2026 Pointmatic
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import { renderMarkdown } from './markdown.js';
+
+describe('renderMarkdown', () => {
+	it('returns empty string for null/undefined/blank input', () => {
+		expect(renderMarkdown(null)).toBe('');
+		expect(renderMarkdown(undefined)).toBe('');
+		expect(renderMarkdown('')).toBe('');
+		expect(renderMarkdown('   \n\t')).toBe('');
+	});
+
+	it('renders headings as <h1>/<h2>/<h3>', () => {
+		const html = renderMarkdown('# H1\n\n## H2\n\n### H3');
+		expect(html).toContain('<h1');
+		expect(html).toContain('<h2');
+		expect(html).toContain('<h3');
+		expect(html).toContain('H1');
+		expect(html).toContain('H2');
+		expect(html).toContain('H3');
+	});
+
+	it('renders fenced code blocks', () => {
+		const html = renderMarkdown('```python\nprint("hi")\n```');
+		expect(html).toContain('<pre');
+		expect(html).toContain('<code');
+		expect(html).toContain('print');
+	});
+
+	it('renders inline math via $...$', () => {
+		const html = renderMarkdown('Euler said $e^{i\\pi} + 1 = 0$.');
+		// KaTeX inline output wraps the formula in <span class="katex">…</span>
+		// (without the `katex-display` wrapper used for block-level math).
+		expect(html).toContain('class="katex"');
+		// The literal `$...$` delimiters should be consumed by the parser.
+		expect(html).not.toContain('$e^{i\\pi}');
+	});
+
+	it('renders display math via $$...$$', () => {
+		const md = '$$\n\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}\n$$';
+		const html = renderMarkdown(md);
+		// Display math gets the `katex-display` wrapper. KaTeX preserves the
+		// source LaTeX inside a MathML <annotation> tag for accessibility,
+		// so we don't assert that the source is absent — only that the
+		// rendered HTML structure is present.
+		expect(html).toContain('katex-display');
+		expect(html).toContain('class="katex"');
+	});
+
+	it('does not throw on malformed LaTeX (throwOnError: false)', () => {
+		expect(() => renderMarkdown('$\\unknownmacro{x}$')).not.toThrow();
+	});
+});

{learningfoundry-0.32.0 → learningfoundry-0.34.0/src/learningfoundry}/sveltekit_template/src/lib/utils/markdown.ts

@@ -1,6 +1,12 @@
 // Copyright 2026 Pointmatic
 // SPDX-License-Identifier: Apache-2.0
 import { marked } from 'marked';
+import markedKatex from 'marked-katex-extension';
+
+// Register the KaTeX extension once at module load. Supports both inline
+// `$...$` and display `$$...$$` math, rendered to HTML at parse time using
+// the KaTeX engine. Stylesheet is imported in `src/app.css`.
+marked.use(markedKatex({ throwOnError: false }));
 
 /**
  * Convert a markdown string to sanitised HTML.

learningfoundry-0.32.0/src/learningfoundry/generator.py

@@ -1,99 +0,0 @@
-# Copyright 2026 Pointmatic
-# SPDX-License-Identifier: Apache-2.0
-"""SvelteKit project generator — copies template and writes curriculum.json."""
-
-import dataclasses
-import json
-import logging
-import shutil
-import tempfile
-from pathlib import Path
-
-from learningfoundry.exceptions import GenerationError
-from learningfoundry.resolver import ResolvedCurriculum
-
-logger = logging.getLogger("learningfoundry.generator")
-
-_TEMPLATE_DIR = Path(__file__).parent / "sveltekit_template"
-
-
-def generate_app(
-    resolved: ResolvedCurriculum,
-    output_dir: Path,
-    template_dir: Path | None = None,
-) -> None:
-    """Generate a SvelteKit project from a resolved curriculum.
-
-    Copies ``sveltekit_template/`` to ``output_dir`` atomically (write to a
-    temp directory, then move into place), then writes ``curriculum.json``
-    into ``output_dir/static/``.
-
-    If ``output_dir`` already exists it is replaced with a warning.
-
-    Args:
-        resolved: Fully resolved curriculum from ``resolve_curriculum()``.
-        output_dir: Destination path for the generated SvelteKit project.
-        template_dir: Override template source. Defaults to the package's
-            ``sveltekit_template/`` directory.
-
-    Raises:
-        GenerationError: If the template directory does not exist or any
-            file operation fails.
-    """
-    src = template_dir or _TEMPLATE_DIR
-
-    if not src.exists():
-        raise GenerationError(
-            f"SvelteKit template directory not found: `{src}`. "
-            "Run `learningfoundry` from the project root, or pass "
-            "`template_dir` explicitly."
-        )
-
-    if output_dir.exists():
-        logger.warning(
-            "Output directory `%s` already exists and will be overwritten.",
-            output_dir,
-        )
-
-    _atomic_copy(src, output_dir)
-    _write_curriculum_json(resolved, output_dir)
-
-    logger.info("Generated SvelteKit project at: %s", output_dir)
-
-
-def _atomic_copy(src: Path, dst: Path) -> None:
-    """Copy src tree to dst atomically via a sibling temp directory."""
-    parent = dst.parent
-    parent.mkdir(parents=True, exist_ok=True)
-
-    try:
-        with tempfile.TemporaryDirectory(dir=parent, prefix=".lf_gen_") as tmp_str:
-            tmp = Path(tmp_str) / dst.name
-            shutil.copytree(src, tmp)
-            if dst.exists():
-                shutil.rmtree(dst)
-            tmp.rename(dst)
-    except OSError as exc:
-        raise GenerationError(
-            f"Failed to generate project at `{dst}`: {exc}"
-        ) from exc
-
-
-def _write_curriculum_json(resolved: ResolvedCurriculum, output_dir: Path) -> None:
-    """Serialize ResolvedCurriculum to output_dir/static/curriculum.json."""
-    static_dir = output_dir / "static"
-    static_dir.mkdir(parents=True, exist_ok=True)
-
-    curriculum_json = output_dir / "static" / "curriculum.json"
-    try:
-        data = dataclasses.asdict(resolved)
-        curriculum_json.write_text(
-            json.dumps(data, indent=2, ensure_ascii=False) + "\n",
-            encoding="utf-8",
-        )
-    except OSError as exc:
-        raise GenerationError(
-            f"Failed to write curriculum.json to `{curriculum_json}`: {exc}"
-        ) from exc
-
-    logger.debug("Wrote curriculum.json (%d bytes)", curriculum_json.stat().st_size)