jupyterlab-workshop 0.1.0__tar.gz

jupyterlab_workshop-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+scratch/
+
+# JavaScript
+node_modules/
+.yarn/
+*.bundle.*
+*.log
+*.tsbuildinfo
+.eslintcache
+.stylelintcache
+packages/*/lib/
+packages/core/coverage/
+
+# Built labextension, Node CLI bundle, schema copy and generated version file
+jupyterlab_workshop/labextension/
+jupyterlab_workshop/nodejs/
+jupyterlab_workshop/schema/
+jupyterlab_workshop/_version.py
+
+# Documentation build outputs and the assembled GitHub Pages site
+docs/_build/
+docs/reference/
+site/
+
+# Integration tests
+tests/ui-tests/test-results/
+tests/ui-tests/playwright-report/
+
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+
+# Editors and OS
+.DS_Store
+
+# Files created by running the example workshops
+examples/*/demo/
+examples/*/_workshop/
+examples/*/scratch/
+
+# Workshops downloaded through the extension
+workshops/
+
+# JupyterLite site built by `just lite`
+lite-site/
+
+# JupyterLite build state written next to a build
+.jupyterlite.doit.db

jupyterlab_workshop-0.1.0/.prettierignore

@@ -0,0 +1,15 @@
+node_modules
+**/node_modules
+**/lib
+**/package.json
+!/package.json
+jupyterlab_workshop
+eslint.config.mjs
+.venv
+scratch
+tests/ui-tests/test-results
+tests/ui-tests/playwright-report
+site
+lite-site
+docs/_build
+docs/reference

jupyterlab_workshop-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

jupyterlab_workshop-0.1.0/.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Read the Docs build. The project itself is not installed (that would need
+# Node.js to build the extension); only the docs dependency group is synced
+# with uv, matching `just docs`.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --only-group docs --no-install-project
+    - uv run --no-sync sphinx-build -W --keep-going -b html docs $READTHEDOCS_OUTPUT/html

jupyterlab_workshop-0.1.0/.yarnrc.yml

@@ -0,0 +1,2 @@
+nodeLinker: node-modules
+enableScripts: false

jupyterlab_workshop-0.1.0/AGENTS.md

@@ -0,0 +1,204 @@
+# Agent guidance for jupyterlab-workshop
+
+## Project
+
+jupyterlab-workshop is a JupyterLab extension for running guided,
+interactive workshops inside JupyterLab. Workshop instructions are shown in
+a side panel and contain clickable actions that drive the live JupyterLab
+session: terminals, the file browser, the editor, notebooks, kernels and
+layout. Workshops can verify learner progress, gate pages on that progress,
+and include forms and quizzes. The concept comes from the Educates Training
+Platform (educates.dev), re-imagined so that a single workshop runs wherever
+JupyterLab runs, without Kubernetes or containers. See README.md for the
+project goals.
+
+A workshop is a directory containing a `workshop.yaml` manifest and
+MyST-flavoured Markdown pages. The format is text based and git friendly.
+
+The repository is a monorepo with three main parts:
+
+- `packages/core/` is `@jupyterlab-workshop/core`, pure TypeScript with no
+  JupyterLab dependencies: workshop format parsing, action definitions,
+  variable substitution, lint rules and JSON schemas. Keep it free of
+  JupyterLab imports so the CLI and other tooling can reuse it under Node.
+
+- `packages/labextension/` is `@jupyterlab-workshop/labextension`, the
+  JupyterLab frontend extension: instructions panel, renderer, action
+  implementations, verify engine, trust manager, loader and state.
+
+- `jupyterlab_workshop/` is the Python package: the
+  `jupyter_server` extension (platform detection, fetching, script
+  verifies, checkpoints) and the `jupyter workshop` CLI.
+
+README.md is the long description shown on PyPI, so it stays short and
+user facing and links to the documentation site; development setup and
+workflow belong in CONTRIBUTING.md, and the full documentation is under
+`docs/` and published on Read the Docs.
+
+Example workshops live in `examples/` and double as test fixtures. Tests
+live in `tests/` (Python and Galata UI tests) and alongside the source in
+`packages/core/`. See TESTING.md for where tests are, how to run them, and
+conventions for adding new ones.
+
+The scratch/ directory is not part of the git repo. It holds temporary
+working files, such as reference material given to an agent or plans an
+agent is asked to generate. Its contents come and go, so never reference
+scratch/ files by name from code or documentation that will be committed.
+
+## Tooling: always use uv and jlpm
+
+All Python environment and package management in this project is done with
+[uv](https://docs.astral.sh/uv/). Never use the Python venv module, bare
+pip, or python -m build directly.
+
+- Run commands in the project environment: `uv run <command>`
+  (e.g. `uv run pytest`, `uv run jupyter lab`)
+
+- Run a Python interpreter: `uv run python`
+
+- Build sdist and wheel: `uv build`
+
+- Add or remove dependencies (updates pyproject.toml): `uv add <package>`,
+  `uv remove <package>`
+
+- Sync the environment from pyproject.toml: `uv sync`
+
+All JavaScript and TypeScript package management is done with `jlpm`, the
+pinned Yarn that ships with JupyterLab. Never use npm or a system yarn
+directly, and never commit a lockfile produced by them. jlpm is installed
+into the project environment with JupyterLab, so run it as `uv run jlpm`.
+
+- Install workspace dependencies: `uv run jlpm install`
+
+- Add a dependency to one workspace package: run `uv run jlpm add <package>`
+  from inside that package's directory (for example `packages/core`)
+
+- Build all packages: `uv run jlpm build`
+
+## Common tasks: use the Justfile
+
+The Justfile defines targets for the common development tasks, wrapping
+the correct uv and jlpm invocations (including details like linking the
+labextension into JupyterLab in development mode and running the Galata
+tests against a live server). Prefer these targets over synthesizing the
+underlying commands yourself; run `just --list` to see everything.
+
+- `just install` sets up the development environment: syncs the Python
+  environment, installs JavaScript dependencies and links the extension
+  into JupyterLab in development mode.
+
+- `just build` builds the TypeScript packages and the labextension bundle.
+  `just watch` rebuilds on change; run it alongside `just lab`.
+
+- `just lab` starts JupyterLab from the repository root with the extension
+  loaded, so the example workshops are reachable through the contents API.
+
+- `just test` runs the fast test suites: the Jest tests for `packages/core`
+  and the pytest suite for the Python package. Extra arguments pass
+  through to pytest, so a specific file or test is
+  `just test tests/python/test_fetch.py` or `just test -k pattern`.
+
+- `just test-core` runs only the Jest tests; `just test-python` runs only
+  pytest; `just test-ui` runs the Galata browser tests against a real
+  JupyterLab (slow; run before finishing frontend work, not on every edit).
+
+- `just lint` checks TypeScript with eslint and prettier and Python with
+  the ruff linter and formatter; `just format` reformats and applies
+  auto-fixes in both.
+
+- `just typecheck` runs tsc for the TypeScript packages and mypy for
+  Python.
+
+- `just docs` builds the documentation with Sphinx into `docs/_build/html`
+  (the pages are MyST Markdown under `docs/`, and the manifest reference is
+  generated from the JSON schema on every build); `just docs-serve` rebuilds
+  on change; `just docs-clean` clears a stale build after structural changes
+  such as renamed or removed pages.
+
+- `just pages` assembles the GitHub Pages site into `site/`: the landing
+  page from `github-pages/`, the JSON schemas under `schemas/v1alpha1/`,
+  and the example workshop as a JupyterLite site under `demo/`.
+
+- `just clean` removes build outputs only. `just distclean` also removes
+  `node_modules`, `.venv`, caches, built docs and sites, and files left
+  by running the examples, returning the tree to a fresh checkout; run
+  `just install` afterwards.
+
+## Style
+
+- Do not use emdashes in any files in this project. Rephrase with commas,
+  parentheses, colons, or separate sentences instead.
+
+- In bulleted lists where items run to multiple lines, put a blank
+  line between the bullets: in docstrings, markdown files, and any
+  other prose. This is about the raw file being readable, not the
+  rendered form, which can look fine either way. Be consistent within
+  a list: if one item needs the spacing, space every item in that
+  list, never a mix.
+
+- Python code must always use type hints. Add them to all function
+  and method signatures (parameters and return types), and to attributes
+  and variables where the type is not obvious from the assignment. When
+  adding or modifying code that lacks type hints, add them.
+
+- TypeScript code must be explicitly typed at its boundaries: every
+  exported function, method, class member and module-level constant has
+  an explicit type or return type. Never use `any`; use `unknown` and
+  narrow it. Do not disable strict compiler options.
+
+- Use vertical white space liberally inside function and method bodies,
+  in both Python and TypeScript. Write code in paragraphs: group the
+  statements that together perform one step, and separate each group
+  from the next with a blank line. Natural paragraph boundaries include
+  setup versus the main work versus the result, before and after a
+  conditional or loop, and around a with or try block. Do not cram a body
+  into one contiguous blob, and equally do not put a blank line between
+  every single statement; the blank lines should mark where one thought
+  ends and the next begins.
+
+- Where it helps the reader, start a paragraph of code with a short
+  comment saying what that step does or why it is needed. Prefer one
+  comment per logical block over line-by-line commentary, and skip the
+  comment entirely when the code already says it plainly.
+
+- Put a blank line between such a block comment and the code below it:
+  the comment introduces the paragraph rather than sitting flush against
+  its first line.
+
+- Put a blank line between a function or method docstring and the first
+  line of code in the body.
+
+- Every function, method or property that is part of the public API must
+  have a docstring (Python) or a TSDoc comment (TypeScript) saying what it
+  does. The exceptions are cases that are truly trivial and obvious, such
+  as an accessor property named for the attribute it returns, and dunder
+  methods implementing standard protocols.
+
+- Every directive, action type or option added to the workshop format must
+  be reflected in the JSON schema, the lint rules and the format
+  documentation in the same change.
+
+- Verify JupyterLab API names against the installed version's TypeScript
+  definitions (under `node_modules/@jupyterlab/*/lib/`) before using them.
+  Use only public tokens and APIs.
+
+## Git
+
+- Git commit messages must never include a co-authored-by agent message or
+  any similar agent attribution trailer.
+
+- An AI agent must never commit changes on its own initiative. Finish the
+  piece of work, summarize it, and wait to be told to commit. Permission to
+  commit applies only to the work it was given for; it does not carry
+  forward to later steps of a multi-step plan, each of which needs its own
+  review and its own instruction to commit. Uncommitted changes are how the
+  review happens: once work is committed it can no longer be reviewed as
+  the pending diff, so committing early makes review harder, not easier.
+
+- When merging a feature branch back to main and pushing to the remote,
+  do not treat the work as landed until the CI workflow on GitHub has run
+  against the pushed merge and passed. Check the run (for example with
+  `gh run list --branch main` and `gh run watch`), and only once it is
+  green report that the changes are on the remote and clean up the feature
+  branch. If CI fails, leave the feature branch in place, report the
+  failure, and wait for instructions rather than deleting anything.

jupyterlab_workshop-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

jupyterlab_workshop-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Development setup and workflow for jupyterlab-workshop. The user-facing
+documentation is under `docs/` and published at
+<https://jupyterlab-workshop.readthedocs.io/>; this file is about working
+on the project itself.
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/), [just](https://just.systems/),
+Node.js and git.
+
+```
+just install
+just lab
+```
+
+`just install` creates the Python environment, installs the JavaScript
+workspace, builds the extension and links it into JupyterLab in
+development mode. `just lab` starts JupyterLab with the repository root
+as its root directory, which is where the example workshops live. Open
+the Workshop panel in the right sidebar (the `panelSide` setting, or
+dragging the tab, moves it to the left).
+
+To rebuild while editing the TypeScript, run `just watch` in a second
+terminal and refresh the browser after each rebuild. `just --list` shows
+every task.
+
+## Layout
+
+- `packages/core/` is `@jupyterlab-workshop/core`, pure TypeScript with no
+  JupyterLab dependencies: the workshop format, actions, variables, lint
+  rules and JSON schemas.
+
+- `packages/labextension/` is `@jupyterlab-workshop/labextension`, the
+  JupyterLab frontend extension.
+
+- `jupyterlab_workshop/` is the Python package: the `jupyter_server`
+  extension and the `jupyter workshop` command line.
+
+- `examples/` holds the example workshops, which double as test fixtures.
+
+- `docs/` is the Sphinx documentation and `github-pages/` the landing page
+  of the project site.
+
+## Checks and tests
+
+```
+just lint
+just typecheck
+just test
+```
+
+`just test` runs the Jest tests for `packages/core` and the pytest suite.
+`just test-ui` runs the Galata browser tests against a real JupyterLab,
+`just selftest` runs every action of the example workshops in JupyterLab,
+and `just selftest-lite` does the same in a JupyterLite build. See
+TESTING.md for where the tests live and how to add more.
+
+Python is managed with uv and JavaScript with `jlpm`, the Yarn that ships
+with JupyterLab, run as `uv run jlpm`. Do not use pip, npm or a system
+yarn directly. AGENTS.md records the coding conventions the project
+follows.
+
+## Documentation and the project site
+
+`just docs` builds the documentation into `docs/_build/html`, and
+`just docs-serve` rebuilds it on change. The manifest reference page is
+generated from the JSON schema on every build.
+
+`just pages` assembles the GitHub Pages site into `site/`: the landing
+page, the JSON schemas and the example workshop built as a JupyterLite
+site under `demo/`. Building the JupyterLite terminal needs `node`, `npm`
+and `micromamba` on the path; pass `--no-terminal` to leave it out.
+
+## Releases
+
+The version is read from the root `package.json` by the Python build, so
+bump it there and in the two workspace `package.json` files together.
+Releases are made by pushing a tag that is the bare version string, such
+as `0.1.0`, with no `v` prefix. The release workflow refuses to build if
+the tag does not match the version in `package.json`, then builds the
+wheel and sdist, attaches them to a GitHub release and publishes to PyPI.

jupyterlab_workshop-0.1.0/Justfile

@@ -0,0 +1,121 @@
+# Development tasks for jupyterlab-workshop.
+#
+# Python is managed with uv, JavaScript with jlpm (the Yarn that ships with
+# JupyterLab, installed into the project environment). Run `just --list`
+# to see the available targets.
+
+set positional-arguments
+
+# List the available targets.
+default:
+    @just --list
+
+# Set up the development environment and link the extension into JupyterLab.
+install:
+    uv sync --no-install-project
+    uv run --no-sync jlpm install
+    uv run --no-sync jlpm build
+    uv sync
+    uv run jupyter labextension develop . --overwrite
+    uv run jupyter server extension enable jupyterlab_workshop
+
+# Build the TypeScript packages and the labextension bundle.
+build:
+    uv run jlpm build
+
+# Rebuild the TypeScript packages and labextension on change (run alongside `just lab`).
+watch:
+    uv run jlpm watch
+
+# Start JupyterLab from the repository root with the extension loaded.
+lab *args:
+    uv run jupyter lab --notebook-dir=. "$@"
+
+# Run the fast test suites: Jest for packages/core and pytest for the Python package.
+test *args:
+    uv run jlpm test
+    uv run pytest "$@"
+
+# Run only the Jest tests for packages/core.
+test-core *args:
+    uv run jlpm test "$@"
+
+# Run only the pytest suite for the Python package.
+test-python *args:
+    uv run pytest "$@"
+
+# Run the Galata browser tests against a real JupyterLab on port 8890 (slow).
+test-ui *args:
+    cd tests/ui-tests && uv run jlpm install && JUPYTER_PORT=8890 uv run jlpm playwright test "$@"
+
+# Check TypeScript with eslint and prettier, and Python with ruff.
+lint:
+    uv run jlpm lint:check
+    uv run ruff check .
+    uv run ruff format --check .
+
+# Reformat and apply auto-fixes for TypeScript and Python.
+format:
+    uv run jlpm lint
+    uv run ruff check --fix .
+    uv run ruff format .
+
+# Type check the TypeScript packages with tsc and the Python package with mypy.
+typecheck:
+    uv run jlpm typecheck
+    uv run mypy
+
+# Build the documentation with Sphinx into docs/_build/html (generates the manifest reference first).
+docs:
+    uv run sphinx-build -W --keep-going -b html docs docs/_build/html
+
+# Serve the documentation with live reload.
+docs-serve:
+    uv run sphinx-autobuild docs docs/_build/html
+
+# Clear generated documentation outputs.
+docs-clean:
+    rm -rf docs/_build docs/reference
+
+# Assemble the GitHub Pages site into site/: landing page, JSON schemas and the JupyterLite demo.
+pages *args:
+    rm -rf site
+    mkdir -p site/schemas/v1alpha1
+    cp github-pages/index.html site/index.html
+    touch site/.nojekyll
+    cp packages/core/src/schema/workshop.schema.json packages/core/src/schema/registry.schema.json site/schemas/v1alpha1/
+    uv run jupyter workshop lite examples/hello-jupyterlab --out site/demo "$@"
+
+# Self-test a workshop directory in a real JupyterLab (default: every example).
+selftest *args:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ "$#" -eq 0 ]; then set -- examples/git-basics examples/hello-jupyterlab examples/workshop-authoring; fi
+    for dir in "$@"; do uv run jupyter workshop test "$dir"; done
+
+# Self-test a workshop in a static JupyterLite build (default: hello-jupyterlab).
+selftest-lite *args:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ "$#" -eq 0 ]; then set -- examples/hello-jupyterlab; fi
+    for dir in "$@"; do uv run jupyter workshop test "$dir" --lite; done
+
+# Build a JupyterLite site with the example workshop into lite-site/ and serve it.
+lite *args:
+    uv run jupyter workshop lite examples/hello-jupyterlab --out lite-site --serve "$@"
+
+# Remove build outputs (compiled TypeScript, the labextension bundle, lint caches).
+clean:
+    uv run jlpm clean
+    uv run jlpm clean:lintcache
+
+# Return to a fresh checkout: also removes node_modules, .venv, caches, built docs and sites.
+distclean:
+    rm -rf packages/core/lib packages/labextension/lib packages/*/tsconfig.tsbuildinfo
+    rm -rf jupyterlab_workshop/labextension jupyterlab_workshop/nodejs jupyterlab_workshop/schema
+    rm -rf .eslintcache .stylelintcache packages/core/coverage
+    rm -rf node_modules packages/*/node_modules tests/ui-tests/node_modules .venv
+    rm -rf site docs/_build docs/reference build dist lite-site .jupyterlite.doit.db .coverage htmlcov
+    rm -rf tests/ui-tests/test-results tests/ui-tests/playwright-report
+    rm -rf examples/*/_workshop examples/*/scratch examples/*/demo workshops
+    find . -type d \( -name __pycache__ -o -name .ipynb_checkpoints -o -name '*.egg-info' -o -name .yarn -o -name .mypy_cache -o -name .ruff_cache -o -name .pytest_cache \) -prune -exec rm -rf {} +