moonlit 0.1.0__tar.gz

moonlit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.idea/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+
+# zensical docs site build output
+site/
+.zensical/

moonlit-0.1.0/CLAUDE.md

@@ -0,0 +1,169 @@
+# CLAUDE.md
+
+Operating notes for future Claude instances working in this repo.
+
+**For design contracts, read `specs/`** — the foundational specifications that drive implementation. Start with `specs/README.md`, then `specs/00-architecture.md` for the system view, then the component specs. `specs/CROSS_CUTTING_DECISIONS.md` is binding when any spec disagrees with it.
+
+`IMPLEMENTATION_PLAN.md` (in the repo root) captures the original design rationale and is preserved for context, but the specs in `specs/` are the canonical contract.
+
+This file captures rules and conventions that aren't obvious from the code or the specs.
+
+## What this project is
+
+**moonlit** is a CLI that builds self-contained Python zipapps (PEP 441) — analogous to LinkedIn's [shiv](https://github.com/linkedin/shiv), but built on **uv** instead of pip and aware of **uv workspaces**.
+
+A produced `.pyz` bundles the application + all dependencies. On first run, it extracts site-packages to a per-build cache directory and invokes the configured entry point. Subsequent runs hit the cache.
+
+## Architecture (two halves, hard boundary)
+
+There are two distinct codebases in `src/moonlit/`, and they have **different rules**:
+
+### Build-time code (`cli.py`, `builder.py`, `resolver.py`, `workspace.py`, `hashing.py`, `errors.py`)
+- Runs as the user's `moonlit` CLI on their dev machine.
+- May depend on third-party packages (currently just `click`).
+- Shells out to `uv` via `subprocess` — there is no Python API for uv. The shell-out is in `resolver.py`; do not call `subprocess.run(["uv", ...])` from anywhere else.
+
+### Bootstrap code (`src/moonlit/_bootstrap/`)
+- Gets copied verbatim into every `.pyz` produced.
+- Runs **before** the bundled site-packages is on `sys.path`.
+- **Must be stdlib-only.** No `click`, no anything-else. If you need a third-party feature, reimplement enough of it on stdlib or rethink the design.
+- No relative imports outside the `_bootstrap` package.
+- Compatible with the *target* Python the user will run the .pyz with — currently the project pins `requires-python >=3.13` and the bootstrap can assume that.
+
+If you find yourself adding a dep to `_bootstrap`, stop. That's a design break, not a tweak.
+
+## The build pipeline at a glance
+
+`cli.build` → `builder.build(BuildConfig)`:
+
+1. `workspace.detect(project_root)` — parse `[tool.uv.workspace]`.
+2. Pick target package (workspace member via `--package`, or the project itself).
+3. `uv export --frozen --no-dev --no-emit-workspace --format requirements-txt [--package <name>]` → requirements file.
+4. `uv pip install --target <staging>/site-packages --no-deps -r <reqs> --python <sys.executable>`.
+5. `uv build --wheel [--package <name>] --out-dir <tmp>/dist`.
+6. `uv pip install --target <staging>/site-packages --no-deps --reinstall-package <name> <wheel>`.
+7. Resolve `-c` (console script) by reading `*.dist-info/entry_points.txt` from staging.
+8. `hashing.compute_build_id(staging)` — sorted SHA-256.
+9. `builder.create_archive` — write shebang prefix → ZipFile → site-packages → `_bootstrap/` → generated `__main__.py` → `env.json`.
+10. POSIX `chmod 0o755`; Windows no-op.
+
+The bootstrap `__main__.py` template is just:
+```python
+import sys
+from _bootstrap import bootstrap
+sys.exit(bootstrap())
+```
+
+## Development practices
+
+**Test-driven development.** The specs in `specs/` already enumerate falsifiable invariants, and many name explicit test files (e.g. `tests/unit/test_bootstrap_stdlib_only.py`, `tests/unit/test_builder_preflight.py::test_parent_missing_exits_7`). Workflow per change:
+
+1. Pick the spec invariant or named test ID you're implementing.
+2. Write the failing test first. Run it. Confirm it fails for the expected reason.
+3. Make it pass with the smallest change that works.
+4. Refactor with the test green.
+5. Commit the test and production code together.
+
+Don't write production code without a failing test. Don't write speculative tests for behavior the specs don't require. When a critique surfaces a missing edge case, add the test first, then fix.
+
+**Stepdown rule — modules read like a book.** Every module is laid out top-to-bottom in order of decreasing abstraction. A reader doing `from moonlit.builder import build` and scrolling top-to-bottom should understand what `build` does without ever scrolling backward.
+
+- Module docstring at the top.
+- Public API immediately below — the names another module would import.
+- The highest-level function defined first; the functions it calls appear below, in the order they're called.
+- Private helpers at the bottom.
+
+If you find yourself jumping up the file to understand a downstream function, the module is in the wrong order — reorder before merging. Same rule applies inside `_bootstrap/`: `bootstrap()` at the top of `__init__.py`; the helpers it dispatches to follow in call order across `environment.py`, `extract.py`, `runner.py`.
+
+**Clean-code defaults** (beyond the system prompt's guidance):
+
+- Small functions, one job each. If a function does two things, split it.
+- Names describe intent, not implementation: `compute_build_id`, not `do_sha256`. `materialize`, not `do_extract_step`.
+- Guard clauses over deep nesting. Return early on the error path; keep the happy path unindented.
+- Pure functions wherever possible — especially in `hashing.py`, `workspace.py`, and `_bootstrap/extract.py`. Pure functions test trivially and don't need fixtures.
+- Errors are part of the design, not afterthoughts. Every `MoonlitError` subclass has a stable `exit_code`; raise the right one as early as the spec's preflight order allows (CLI spec §4 is authoritative).
+- No dead code, no commented-out blocks, no `_unused` variables left as breadcrumbs. If it's not called, delete it.
+- Side effects live at the boundary (CLI layer, `resolver.py` subprocess calls, file I/O). Pure logic in the middle.
+
+## Invariants — don't break these
+
+- **Build-id determinism**: `hashing.compute_build_id` hashes sorted relative paths (forward-slash, regardless of platform) interleaved with file content, separated by `\0`. Cache correctness depends on this being deterministic across runs of the same staging dir.
+- **`env.json` is not part of the build_id input**. Compute the id first, then write env.json.
+- **Shebang prefix goes before the zip header**, not as a zip entry. This is what makes `.pyz` files Unix-executable. `zipapp` and `zipfile` both tolerate a leading `#!...\n` line.
+- **`--no-deps` on every `uv pip install`** in the build pipeline. The lockfile is the single source of truth for resolution; we do not want uv re-resolving and disagreeing with `uv.lock`.
+- **`--reinstall-package <name>`** in step 6 — defensive against future changes to `uv export` semantics.
+- **Cache root on Windows is `%LOCALAPPDATA%\moonlit`**, not `~/.moonlit`. Roaming profiles must not bloat.
+- **`os.replace()` for atomic rename** — works on both POSIX and Windows since Python 3.3. Don't use `os.rename()` (Windows fails if the target exists).
+- **Locking is `O_CREAT|O_EXCL` sentinels**, not `fcntl` (POSIX-only) or `msvcrt.locking` (Windows byte-range, different semantics). Documented limitation: stale lock on crash, recovered via `MOONLIT_FORCE_EXTRACT=1`.
+
+## Environment variables (runtime, read by bootstrap)
+
+- `MOONLIT_ROOT` — override cache root.
+- `MOONLIT_FORCE_EXTRACT` — re-extract even if cache exists.
+- `MOONLIT_ENTRY_POINT` — override the entry point baked into env.json.
+
+When adding new env vars, prefix with `MOONLIT_` and document them in this section.
+
+## Error handling conventions
+
+- All user-facing failures raise a subclass of `MoonlitError` (in `errors.py`), each with a stable `exit_code` attribute.
+- Top-level CLI catches `MoonlitError` → prints message, exits with the class's exit code.
+- `KeyboardInterrupt` → exit 130, no traceback.
+- Tracebacks are only shown with `--verbose`.
+- Exit-code map lives in `IMPLEMENTATION_PLAN.md`. Don't reuse codes for unrelated conditions.
+
+## Testing
+
+- `tests/unit/` — pure-Python unit tests, no real subprocess calls. Mock `subprocess.run` in resolver tests.
+- `tests/e2e/` — runs the real `moonlit build` against a fixture workspace. Slower, hits real `uv`. Skip if `uv` isn't on PATH (don't fail).
+- The bootstrap is tested by building a fixture .pyz and running it as a subprocess, then asserting on stdout/exit code.
+
+## Documentation
+
+Project docs are built with **[zensical](https://zensical.org)** — the modern static-site generator from the Material for MkDocs team (Rust + Python core, differential builds, configured via `zensical.toml`).
+
+- Markdown source lives under `docs/`. Configuration lives in `zensical.toml` at the repo root.
+- Add zensical as a dev/docs dependency: `uv add --group docs zensical`. Build with `uv run zensical build`; local preview with `uv run zensical serve`.
+- **Do not introduce MkDocs, Sphinx, Read the Docs Sphinx theme, or any other docs framework.** Zensical is the chosen tool; switching is not in scope.
+
+## Common commands
+
+```powershell
+# Run the CLI from source during development
+uv run moonlit build --help
+
+# Build moonlit's own wheel
+uv build --wheel
+
+# Run tests
+uv run pytest
+
+# Build the docs site (zensical)
+uv run zensical build
+uv run zensical serve   # local preview at http://127.0.0.1:8000
+
+# Build a .pyz from a workspace member (the canonical demo)
+cd C:\tmp\moonlit-demo
+uv lock
+uv run moonlit build --package shouter -e shouter.cli:main -o shouter.pyz
+python .\shouter.pyz
+```
+
+## Out of scope (don't implement without asking)
+
+The following are intentionally deferred from the MVP. If a task touches one of these, surface it before doing the work:
+
+- `--reproducible` builds (zeroed mtimes, sorted entries, `SOURCE_DATE_EPOCH`)
+- `--compile-pyc`
+- `--no-modify` hash verification at runtime
+- `--preamble` script
+- `--extend-pythonpath` for subprocesses
+- `--site-packages` extra-dirs flag
+- `moonlit info <pyz>` subcommand
+- `--windows-exe` launcher (distlib-style native .exe wrapping)
+- Real `fcntl.flock` / `msvcrt.LK_NBLCK` locking (replacement for the sentinel approach)
+- Cross-interpreter builds (`--python-version` / `--platform` pass-through to uv)
+
+## Platform note
+
+Primary dev environment is **Windows 11**. PowerShell syntax for any commands surfaced to the user. Code paths that touch the filesystem, locking, or paths must be tested mentally on both Windows and POSIX before being committed.

moonlit-0.1.0/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,262 @@
+# moonlit — uv-powered zipapp builder (MVP)
+
+## Context
+
+The repo is a clean slate (just a stub `pyproject.toml` for `moonlit`, `requires-python >=3.13`, no deps, no source). The goal is a CLI tool that builds fully self-contained Python zipapps per PEP 441 — like LinkedIn's **shiv**, but using **uv** for dependency resolution/installation and supporting **uv workspaces** as a first-class concept.
+
+User decisions locked in:
+- CLI command: `moonlit` (e.g. `moonlit build -e pkg.cli:main -o app.pyz`)
+- Scope: **MVP only** — build pipeline + runtime bootstrap. Defer `--reproducible`, `--compile-pyc`, `--no-modify` hash verification, `--preamble`, `--extend-pythonpath`, the `info` subcommand.
+- Workspace UX: `moonlit build --package <member>` mirroring `uv`'s own flag.
+
+Constraint: the user is on Windows 11. Cross-platform locking and the `.pyz` vs `.exe` question both have to be answered, even if the answer is "defer the Windows launcher."
+
+## Approach
+
+A two-piece tool:
+
+1. **Build-time** (`moonlit` CLI): shell out to `uv` to resolve deps for the target package against `uv.lock`, install into a staging dir, build the target's own wheel and install it too, then assemble a `.pyz` via stdlib `zipapp`/`zipfile` semantics.
+2. **Run-time** (`_bootstrap` package baked into every .pyz): on first execution, extract site-packages to a per-build cache dir under `%LOCALAPPDATA%\moonlit` (Win) or `~/.moonlit` (POSIX), set up `sys.path` via `site.addsitedir`, then import + invoke the entry point. Subsequent runs reuse the cache.
+
+The bootstrap is **stdlib-only** — it runs before the staged site-packages is on `sys.path`, so it cannot depend on third-party code (including click).
+
+## Package layout
+
+```
+src/moonlit/
+├── __init__.py            # __version__
+├── __main__.py            # `python -m moonlit` -> cli.main
+├── cli.py                 # click command group + `build` subcommand
+├── builder.py             # zipapp assembly, shebang prefix, env.json, __main__ template
+├── resolver.py            # subprocess wrapper around uv (export, build, pip install --target)
+├── workspace.py           # parse [tool.uv.workspace], validate --package
+├── hashing.py             # sorted SHA-256 over (relpath, content) -> build_id
+├── errors.py              # MoonlitError hierarchy
+├── _templates/
+│   └── main_py.tmpl       # source for generated __main__.py inside the .pyz
+└── _bootstrap/            # SHIPPED INSIDE THE .PYZ — stdlib-only
+    ├── __init__.py        # bootstrap() entry
+    ├── environment.py     # parse env.json (dataclass)
+    ├── extract.py         # cache-dir resolution, atomic extract
+    ├── locking.py         # cross-platform file lock
+    └── runner.py          # sys.path setup + entry-point invocation
+
+tests/
+├── unit/                  # workspace, hashing, resolver (mock subprocess), builder
+└── e2e/fixtures/          # tiny demo workspace for the smoke test
+```
+
+CLI lib choice: **click** (`>=8.1`). Justified by the planned growth of the CLI surface (info subcommand, more flags) — argparse would just get refactored away.
+
+## CLI surface (MVP)
+
+```
+moonlit build [PROJECT]                # positional, default = cwd
+  -e, --entry-point TEXT               # "pkg.module:callable"
+  -c, --console-script TEXT            # mutually exclusive with -e; resolved post-stage
+  -o, --output-file PATH    [required]
+  -p, --python TEXT                    # shebang; default "/usr/bin/env python3"
+      --package TEXT                   # workspace member; required iff project is a workspace
+      --no-dev                         # default ON
+      --force                          # overwrite OUTPUT
+  -q/-v
+```
+
+Rules:
+- `-e` xor `-c` is required (exit 2 otherwise).
+- `--package` is **required** when `[tool.uv.workspace]` exists, **forbidden** when it doesn't (mirrors uv).
+- `-c` resolution happens after Step 6 of the build pipeline by reading `*.dist-info/entry_points.txt` from the staging dir.
+
+## Build pipeline
+
+Driven from `cli.build` calling `builder.build(BuildConfig)`:
+
+1. **Workspace detection** (`workspace.detect(project_root)`). Parse `pyproject.toml` with `tomllib`. Expand `members` globs, apply `exclude`, return `Workspace(root, members)` or `None`. Validate `--package`.
+2. **Pick target package.** Workspace + `--package foo` → `members["foo"]`. Else → project root, name read from `[project].name`.
+3. **`uv export`** (`resolver.export`):
+   ```
+   uv export --frozen --no-dev --no-emit-workspace --format requirements-txt
+             [--package <name>] --output-file <tmp>/requirements.txt
+   ```
+   Run from project root. `--no-emit-workspace` strips `-e file://` self-refs.
+4. **Stage third-party deps** (`resolver.pip_install_target`):
+   ```
+   uv pip install --target <staging>/site-packages --no-deps
+                  --requirement <tmp>/requirements.txt
+                  --python <sys.executable>
+   ```
+   `--no-deps` because the lockfile is already complete. `--python <sys.executable>` works around uv's "needs a venv" quirk.
+5. **Build target wheel** (`resolver.build_wheel`):
+   ```
+   uv build --wheel [--package <name>] --out-dir <tmp>/dist
+   ```
+6. **Install target wheel into staging:**
+   ```
+   uv pip install --target <staging>/site-packages --no-deps
+                  --reinstall-package <name> <tmp>/dist/<wheel>
+   ```
+   `--reinstall-package` is cheap insurance against future `uv export` semantics changes.
+7. **Resolve `-c`** if used. Walk `*.dist-info/entry_points.txt`, parse with `configparser`, look up `[console_scripts][name]`. Convert to `module:function`. If missing, error with the discovered list.
+8. **Compute build_id** (see "Build ID" below).
+9. **Assemble zipapp** (`builder.create_archive`):
+   1. Open output as `ZipFile(path, "w", ZIP_DEFLATED)`.
+   2. **Before** opening the zip, write `b"#!" + python.encode() + b"\n"` directly to the file (zipapp tolerates a prefix — same trick shiv uses).
+   3. Walk `staging/site-packages/`, write each file with arcname relative to staging.
+   4. Copy the `_bootstrap/` package from the installed `moonlit` location via `importlib.resources.files("moonlit") / "_bootstrap"`.
+   5. Render `__main__.py` from the template:
+      ```python
+      import sys
+      from _bootstrap import bootstrap
+      sys.exit(bootstrap())
+      ```
+   6. Write `env.json` at zip root.
+10. **Finalize.** POSIX: `os.chmod(output, 0o755)`. Windows: no-op. Tempdir cleanup.
+
+### Why `uv pip install --target`, not `uv add`
+
+`uv add` is project-management: it mutates `[project.dependencies]` in `pyproject.toml`, updates `uv.lock`, and installs into the project's `.venv`. We need the opposite — a stateless "install these wheels into this staging dir, don't touch anything else." `uv pip install --target` is the right primitive. The "pip" in the name is the surface (pip-compatible flags); the implementation is native uv (Rust resolver/installer, no pip shell-out). `uv sync` and `uv tool install` are similarly project- or user-scoped and have no `--target`.
+
+## Bootstrap runtime
+
+`_bootstrap/__init__.py::bootstrap()`, stdlib-only:
+
+1. Locate the running zipapp via `os.path.abspath(sys.argv[0])`.
+2. Read `env.json` via `zipfile.ZipFile(archive).read("env.json")`, hydrate `Environment`.
+3. Resolve cache root: `MOONLIT_ROOT` env var, else `%LOCALAPPDATA%\moonlit` (Win) / `~/.moonlit` (POSIX).
+4. `site_dir = cache_root / f"{name}_{build_id}" / "site-packages"`.
+5. Skip extraction if `site_dir` exists and `MOONLIT_FORCE_EXTRACT` is unset.
+6. Otherwise: acquire lock → re-check (TOCTOU) → extract to `cache_root / f".{name}_{build_id}.tmp.{pid}"` → `os.replace()` to final path (atomic on POSIX and Windows since Python 3.3) → release lock.
+7. `site.addsitedir(str(site_dir))` — handles `.pth` files correctly.
+8. Resolve entry point: `MOONLIT_ENTRY_POINT` env var overrides `env.entry_point`. Split on `:`, `importlib.import_module`, `getattr` walking dots.
+9. Invoke; return `0` if `None`, else `int(result)`.
+
+**Cross-platform locking** (`_bootstrap/locking.py`): use `os.open(..., O_CREAT | O_EXCL | O_RDWR)` on a `.lock` sentinel file with a polling retry loop (50ms, 60s timeout). Portable, no `fcntl`/`msvcrt` divergence. Trade-off: stale lock on crashed extraction; recovered manually or via `MOONLIT_FORCE_EXTRACT=1`. A real `flock`/`msvcrt.LK_NBLCK` implementation is a v0.2 follow-up — document the limitation in README.
+
+Env vars honored: `MOONLIT_ROOT`, `MOONLIT_FORCE_EXTRACT`, `MOONLIT_ENTRY_POINT`.
+
+## env.json schema
+
+```json
+{
+  "schema_version": 1,
+  "name": "myapp",
+  "build_id": "<64hex>",
+  "entry_point": "myapp.cli:main",
+  "built_at": "2026-05-08T15:23:01Z",
+  "moonlit_version": "0.1.0",
+  "python_shebang": "/usr/bin/env python3"
+}
+```
+
+Bootstrap reads `name`, `build_id`, `entry_point`. Rest is for human inspection / future `info` subcommand.
+
+## Build ID
+
+`hashing.compute_build_id(staging_root)`:
+
+```python
+h = hashlib.sha256()
+for relpath in sorted(all_files_under(staging_root)):
+    h.update(relpath.encode("utf-8")); h.update(b"\0")
+    h.update((staging_root / relpath).read_bytes()); h.update(b"\0")
+return h.hexdigest()
+```
+
+Forward-slash relpaths regardless of platform. Computed before `env.json` is written, so env.json contents don't feed into the id.
+
+## Windows considerations
+
+**MVP outputs `.pyz` only.** Run via `python app.pyz` or `py app.pyz`. The shebang is harmless on Windows.
+
+**Deferred to v0.2:** a `--windows-exe` flag that prepends a distlib launcher .exe to the zipapp to produce a native-runnable `app.exe`. Document this gap in README so users aren't surprised.
+
+Cache root on Windows is `%LOCALAPPDATA%\moonlit` (not `~/.moonlit`) to avoid bloating roaming profiles.
+
+## Error cases (MVP)
+
+| Condition | Class | Exit |
+|---|---|---|
+| `uv` not on PATH | `UvNotFoundError` | 3 |
+| `uv.lock` missing | `NoLockfileError` | 4 |
+| `--package` set, no `[tool.uv.workspace]` | `NotAWorkspaceError` | 5 |
+| `--package foo` not a member | `UnknownPackageError` | 5 |
+| Entry-point string unparseable | `BadEntryPointError` | 6 |
+| `-c name` not in any installed dist | `ConsoleScriptNotFoundError` | 6 |
+| Output exists, no `--force` | `OutputExistsError` | 7 |
+
+`KeyboardInterrupt` → exit 130, no traceback. Tracebacks only with `--verbose`.
+
+## Critical files to create
+
+- `pyproject.toml` (extend: add `click>=8.1`, `[project.scripts] moonlit = "moonlit.cli:main"`, build-system, `[tool.hatch.build.targets.wheel] packages = ["src/moonlit"]` or equivalent)
+- `src/moonlit/cli.py`
+- `src/moonlit/builder.py`
+- `src/moonlit/resolver.py`
+- `src/moonlit/workspace.py`
+- `src/moonlit/hashing.py`
+- `src/moonlit/errors.py`
+- `src/moonlit/_templates/main_py.tmpl`
+- `src/moonlit/_bootstrap/__init__.py`
+- `src/moonlit/_bootstrap/environment.py`
+- `src/moonlit/_bootstrap/extract.py`
+- `src/moonlit/_bootstrap/locking.py`
+- `src/moonlit/_bootstrap/runner.py`
+
+Reuse from stdlib (no new deps for these): `tomllib`, `zipfile`, `zipapp`, `site`, `importlib.resources`, `importlib.import_module`, `configparser` (for entry_points.txt), `hashlib`, `subprocess`, `tempfile`.
+
+## Documentation
+
+Docs are built with **[zensical](https://zensical.org)** — the modern static-site generator from the Material for MkDocs team. Rust + Python core, differential builds, configured via `zensical.toml`. Requires Python ≥3.10 (well within the project's `requires-python >=3.13`).
+
+- Markdown source lives under `docs/`; site config in `zensical.toml` at the repo root.
+- Install via a `docs` dependency group: `uv add --group docs zensical`. The group keeps it out of the runtime install closure for the `moonlit` package itself.
+- Build / preview: `uv run zensical build`, `uv run zensical serve`.
+- Initial docs scope (MVP-aligned): `index.md` (intro + install), `getting-started.md` (single-package and workspace examples mirroring the verification commands below), `cli-reference.md` (auto or hand-written from `moonlit build --help`), `runtime.md` (env vars, cache layout). Defer the full reference site until v0.2.
+- **Do not introduce MkDocs, Sphinx, or any other docs framework** — zensical is the chosen tool.
+
+## Verification (end-to-end)
+
+Create demo workspace at `C:\tmp\moonlit-demo\`:
+
+```
+moonlit-demo/
+├── pyproject.toml        # [tool.uv.workspace] members = ["packages/*"]
+├── uv.lock
+└── packages/
+    ├── greeter/  (name="greeter", deps=["click>=8.1"], cli:main prints "hello from greeter")
+    └── shouter/  (name="shouter", deps=["greeter"], [tool.uv.sources] greeter={workspace=true};
+                   cli:main imports greeter and uppercases its output)
+```
+
+PowerShell smoke test:
+
+```powershell
+cd C:\tmp\moonlit-demo
+uv lock
+uv run moonlit build --package shouter -e shouter.cli:main -o shouter.pyz
+python .\shouter.pyz                                  # expect "HELLO FROM GREETER"
+$env:MOONLIT_FORCE_EXTRACT="1"; python .\shouter.pyz  # re-extracts; same output
+ls $env:LOCALAPPDATA\moonlit                          # confirm cache dir
+python .\shouter.pyz                                  # cache hit; near-instant
+Remove-Item Env:MOONLIT_FORCE_EXTRACT
+```
+
+Negative paths to spot-check:
+- `moonlit build --package nonexistent` → exit 5
+- `moonlit build` (no `-e`/`-c`) → exit 2
+- Build twice without `--force` → exit 7
+- Delete `uv.lock` and rebuild → exit 4
+
+Unit tests cover: workspace parsing/validation, build_id determinism, resolver subprocess argv assembly (mocked), `-c` resolution against synthetic `entry_points.txt`.
+
+## Open risks
+
+- **uv `--target` without active venv**: passing `--python <sys.executable>` should work, but uv's behavior here has been a moving target — verify on first implementation pass. If it breaks, fall back to creating a throwaway venv in the tempdir.
+- **Build interpreter == run interpreter**: native-extension wheels are tagged for a specific Python. MVP documents "build on the same major.minor as you run." Cross-interpreter builds (`--python-version`/`--platform` pass-through to uv) deferred to v0.3.
+- **Lock file robustness**: `O_CREAT|O_EXCL` sentinels leak on crash. Acceptable for MVP; real `flock`/`LK_NBLCK` is v0.2.
+- **Workspace root that itself has `[project]`**: uv allows it. The `--package` validator should accept the root's name. Add a unit test.
+- **`.pth` files in staged deps**: `site.addsitedir` handles them, but absolute-path `.pth` files from editable installs would point outside the staging dir. Going through wheel install (Step 6) avoids this; verify with a test that `uv export --no-emit-workspace` truly excludes editable workspace members from the requirements file.
+
+## Follow-ups (post-MVP, explicitly out of scope)
+
+`--reproducible` (zeroed mtimes, sorted entries, `SOURCE_DATE_EPOCH`) · `--compile-pyc` · `--no-modify` hash verification · `--preamble` · `--extend-pythonpath` · `--site-packages` (extra dirs to bundle) · `moonlit info <pyz>` subcommand · `--windows-exe` launcher · real `flock`/`msvcrt` locking · cross-interpreter builds.

moonlit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phil Harrison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moonlit-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: moonlit
+Version: 0.1.0
+Summary: uv-powered Python zipapp builder.
+Project-URL: Homepage, https://github.com/OpenAfterHours/moonlit
+Project-URL: Documentation, https://openafterhours.github.io/moonlit/
+Project-URL: Repository, https://github.com/OpenAfterHours/moonlit
+Project-URL: Issues, https://github.com/OpenAfterHours/moonlit/issues
+Author: Phil Harrison
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bundler,packaging,pep441,pyz,shiv,uv,zipapp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Archiving :: Packaging
+Requires-Python: >=3.13
+Requires-Dist: click>=8.1
+Description-Content-Type: text/markdown
+
+# moonlit
+
+`moonlit` is a CLI that bundles a uv-managed Python project (and optionally a uv workspace) into a single self-contained zipapp per [PEP 441](https://peps.python.org/pep-0441/). The produced `.pyz` ships every transitive dependency from `uv.lock`; on the end user's machine it extracts to a per-build cache on first run, then dispatches the configured entry point.
+
+It is similar to LinkedIn's [shiv](https://github.com/linkedin/shiv), with two differences:
+
+- **Built on `uv`, not `pip`.** Resolution is done by `uv export --frozen` against `uv.lock`; staging is done by `uv pip install --target` (no virtualenv); the target's wheel is built by `uv build --wheel`.
+- **uv workspaces are first-class.** `--package <member>` selects a workspace target; transitive workspace deps are bundled automatically via `uv build --all-packages`.
+
+## Status
+
+Pre-release (0.x). API and CLI surface are stabilizing toward 1.0; the produced `.pyz` runtime contract is pinned by the design specs under [`specs/`](specs/).
+
+## Install
+
+`moonlit` is not yet on PyPI. From source:
+
+```sh
+git clone <repo> moonlit
+cd moonlit
+uv sync
+uv run moonlit --help
+```
+
+## Quick start
+
+In a uv-managed project (`pyproject.toml` + `uv.lock`):
+
+```sh
+uv run moonlit build -e myapp.cli:main -o myapp.pyz
+python ./myapp.pyz
+```
+
+In a uv workspace:
+
+```sh
+uv run moonlit build --package shouter -e shouter.cli:main -o shouter.pyz
+python ./shouter.pyz
+```
+
+The produced `.pyz` is self-contained: `uv.lock`'s entire dependency closure is bundled, plus the target's own wheel. On first run it extracts `site-packages/` to a per-build cache (`%LOCALAPPDATA%\moonlit` on Windows, `~/.moonlit` on POSIX); subsequent runs hit the cache directly without unpacking.
+
+## How it works
+
+The `moonlit build` pipeline runs ten ordered steps:
+
+1. **Workspace detection.** Parse `[tool.uv.workspace]` from `pyproject.toml`; expand `members` globs; apply `exclude`; PEP 503 normalize.
+2. **Target selection.** Workspace + `--package <name>` → matched member; non-workspace → project root.
+3. **`uv export`** writes a frozen requirements file from `uv.lock`.
+4. **`uv pip install --target`** stages the third-party closure under a temp `site-packages/` (no venv).
+5. **`uv build --wheel`** (or `--all-packages` for workspaces) builds the target's wheel.
+6. Each produced wheel is installed into the same `site-packages/`.
+7. If `-c <script>` was used, the entry point is resolved from staged `*.dist-info/entry_points.txt`.
+8. **`build_id`** is computed: a sorted SHA-256 over every file in `site-packages/` (excluding `__pycache__`/`.pyc`).
+9. **Archive assembly:** shebang prefix, then a `ZIP_DEFLATED` archive containing `site-packages/`, the stdlib-only `_bootstrap/` package, the rendered `__main__.py`, and `env.json`.
+10. **Atomic finalize:** temp-then-rename to the output path; POSIX `chmod 0o755`.
+
+At runtime, the `_bootstrap` package reads `env.json`, derives a cache key from `(name, build_id)`, takes either the lock-free fast path (cache hit) or the locked slow path (extract under `O_CREAT|O_EXCL` sentinel, atomic-replace into the cache via `os.rename` + `os.replace`), then calls `site.addsitedir()` and invokes the entry point.
+
+## Documentation
+
+| | |
+|---|---|
+| [`docs/index.md`](docs/index.md) | Overview and at-a-glance example. |
+| [`docs/getting-started.md`](docs/getting-started.md) | Walkthroughs for single-package projects and uv workspaces. |
+| [`docs/cli-reference.md`](docs/cli-reference.md) | Every flag, every exit code, preflight order, stdout/stderr semantics. |
+| [`docs/runtime.md`](docs/runtime.md) | What runs inside the `.pyz`: cache layout, env vars, runtime exit codes, stale-lock recovery. |
+
+The docs are built with [zensical](https://zensical.org):
+
+```sh
+uv sync --group docs
+uv run zensical serve   # http://127.0.0.1:8000
+```
+
+## Project layout
+
+```
+src/moonlit/
+├── cli.py              # Click frontend
+├── builder.py          # 10-step build pipeline orchestrator
+├── resolver.py         # the only module that calls `uv` subprocesses
+├── workspace.py        # parses [tool.uv.workspace]
+├── hashing.py          # deterministic build_id
+├── errors.py           # MoonlitError hierarchy with stable exit codes
+├── _templates/main_py.tmpl
+└── _bootstrap/         # SHIPPED INSIDE EVERY .pyz — stdlib-only
+    ├── __init__.py     # bootstrap() orchestrator
+    ├── environment.py  # env.json validation
+    ├── extract.py      # D4 atomic-replace, D14 fast path
+    ├── locking.py      # O_CREAT|O_EXCL sentinel lock
+    ├── runner.py       # site.addsitedir, entry-point resolution
+    └── errors.py
+
+specs/                  # Foundational design contracts (start here for hacking)
+tests/
+├── unit/               # 451 unit tests
+└── e2e/                # 25 contract tests via subprocess
+```
+
+## Status of features
+
+| Feature | State |
+|---|---|
+| Build single-package projects | done |
+| Build uv workspaces with transitive deps | done |
+| `--entry-point` (`-e`) and `--console-script` (`-c`) | done |
+| Atomic `.pyz` output (temp-then-rename) | done |
+| First-run extraction + cache-hit fast path | done |
+| Cross-platform caching (`%LOCALAPPDATA%`, `~/.moonlit`) | done |
+| `MOONLIT_ROOT`, `MOONLIT_FORCE_EXTRACT`, `MOONLIT_ENTRY_POINT`, `MOONLIT_DEBUG` | done |
+| `--reproducible` builds (zeroed mtimes, sorted entries) | deferred to v0.2 |
+| `--compile-pyc` | deferred to v0.2 |
+| `--no-modify` integrity verification | deferred to v0.2 |
+| `--windows-exe` native launcher | deferred to v0.2 |
+| Real `flock`/`msvcrt` locking | deferred to v0.2 |
+| `moonlit info <pyz>` subcommand | deferred to v0.2 |
+
+## Contributing
+
+Read [`CLAUDE.md`](CLAUDE.md) for development conventions and [`specs/`](specs/) for the design contracts (start with `specs/README.md`, then `specs/00-architecture.md`).
+
+```sh
+uv run pytest                       # 476 tests, ~10s with e2e
+uv run pytest tests/unit            # unit only, <2s
+uv run ruff format --check .        # format check (CI gate)
+uv run ruff check .                 # lints (CI gate)
+uv run zensical build --strict      # docs build (CI gate)
+```
+
+The e2e suite (`tests/e2e/`) shells out to real `uv` and produces real `.pyz` files; it skips automatically if `uv` is not on `PATH`.
+
+CI runs all four gates on every pull request via [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+## License
+
+[MIT](LICENSE).