pocket-python 0.1.0__tar.gz

pocket_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ella Inng
+
+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.

pocket_python-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: pocket-python
+Version: 0.1.0
+Summary: Auditable Python runtime assets and offline MicroPython application bundles
+Author: ellainng
+Author-email: ellainng <299958882+ellainng@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/outside-labs/pocket-python
+Project-URL: Issues, https://github.com/outside-labs/pocket-python/issues
+Description-Content-Type: text/markdown
+
+# Pocket-python
+
+Pocket-python packages explicit Python runtime assets and Shimify source
+bundles into offline MicroPython browser applications. Python runs on the
+client through WebAssembly, with a worker for execution and a service worker
+for cached reloads. No application server executes the Python code.
+
+Requires Python 3.14+ to build artifacts; the generated application must also
+be compatible with the selected MicroPython runtime. The tool has zero runtime
+dependencies and uses the MIT license. Version 0.1.0 is experimental.
+
+```sh
+python -m pip install pocket-python==0.1.0 shimify==0.2.0
+pocket-python --help
+```
+
+## Build a browser application
+
+First create a portable source bundle with
+[Shimify](https://github.com/outside-labs/shimify). Supply a MicroPython
+WebAssembly distribution containing `micropython.mjs`, `micropython.wasm` and
+its license text; use the official
+[WebAssembly port](https://github.com/micropython/micropython/tree/master/ports/webassembly)
+or the official npm package described in
+[PyScript’s offline guide](https://docs.pyscript.net/2026.7.3/user-guide/offline/).
+
+```sh
+shimify modules path/to/app.py --output build/source
+pocket-python inspect build/source
+pocket-python lock-runtime path/to/runtime --runtime-version VERSION \
+  --source-url https://example.org/upstream-runtime-release \
+  --file micropython.mjs --file micropython.wasm --license-file LICENSE \
+  --output build/runtime-lock.json
+pocket-python web build/source --runtime path/to/runtime \
+  --runtime-lock build/runtime-lock.json --output build/web --title "My Python App"
+python -m http.server 8000 --bind 127.0.0.1 --directory build/web
+```
+
+Replace VERSION and the source URL with the identity of the supplied upstream
+release. Open `http://localhost:8000`, let the app finish installing its cache,
+and wait for **Offline ready on this device** before disconnecting. Run starts
+a fresh worker; Stop terminates it, including an infinite computation. Python
+output is rendered as text. Deploy the generated directory to a static HTTPS
+server; relative URLs support deployment under a subdirectory. `file://`
+execution is unsupported.
+
+`web` writes to a new directory outside input roots. It preserves only recorded
+source/runtime files and notices and adds `POCKET-PYTHON.json` with hashes,
+runtime identity and separate source/runtime/total byte counts. Generation
+does not run application code. The published tool contains no interpreter
+binary and does not download one automatically.
+
+## Reproduce the pinned example
+
+In a checkout, the build-only helper downloads and checks the official
+MicroPython `1.29.0-6` fixture and upstream license. The committed input is a
+real Shimify 0.2 bundle with a local helper import:
+
+```sh
+uv sync --locked
+uv run python scripts/prepare_runtime.py
+uv run pocket-python inspect tests/fixtures/hello
+uv run pocket-python web tests/fixtures/hello --runtime build/runtime \
+  --runtime-lock build/runtime/runtime-lock.json --output build/demo
+python -m http.server 8000 --bind 127.0.0.1 --directory build/demo
+```
+
+The demonstrated PWA totals 578,168 uncompressed bytes, including 563,092 bytes
+of runtime assets/license and 102 bytes of application source. These measurements
+describe the tested fixture; source reduction, compressed transfer size, startup
+time and memory are separate quantities.
+
+## Development and verification
+
+```sh
+uv sync --locked --group browser-tests
+uv run python scripts/prepare_runtime.py
+POCKET_PYTHON_RUNTIME=build/runtime uv run python -m unittest discover -s tests -v
+uv run python -m playwright install chromium
+uv run --group browser-tests python scripts/browser_smoke.py
+uv build
+uv run python scripts/check_distributions.py
+```
+
+On PowerShell set `$env:POCKET_PYTHON_RUNTIME = "build/runtime"` before tests.
+Without an explicit runtime fixture path, the real-WASM test is skipped.
+Use `--channel chrome` with the browser script to test an installed Chrome.
+Playwright is a pinned build-only group; it is not a package runtime dependency.
+CI runs real-runtime tests on Linux, macOS and Windows and offline Chromium
+tests on Linux. Distribution checks verify allowlists, metadata, source parity
+and both installed wheel/source artifacts outside the checkout.
+
+## Compatibility and roadmap
+
+MicroPython provides a subset of Python and its standard library. Test every
+application against the actual selected runtime: a valid Shimify CPython source
+bundle does not establish browser compatibility. Native extensions, OS process
+APIs, resources and dynamic imports need explicit adapters or a different
+runtime profile. The initial console has no interactive stdin or DOM bridge.
+Browser cache persistence and PWA installation affordances vary by platform.
+
+The first small-runtime route is MicroPython WebAssembly. Native relocatable
+CPython assembly and subsequent bootstrap-aware trimming are planned separately;
+0.1 does not trim/rebuild CPython. Broader CPython browser compatibility through
+Pyodide and optional PyScript integration are later profiles.
+
+See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md),
+[release notes](docs/release-0.1.0.md), and the
+[GitHub Project](https://github.com/orgs/outside-labs/projects/13).
+Runtime and dependency licenses remain applicable; preserve and review their
+upstream notices before distributing generated applications.

pocket_python-0.1.0/README.md

@@ -0,0 +1,111 @@
+# Pocket-python
+
+Pocket-python packages explicit Python runtime assets and Shimify source
+bundles into offline MicroPython browser applications. Python runs on the
+client through WebAssembly, with a worker for execution and a service worker
+for cached reloads. No application server executes the Python code.
+
+Requires Python 3.14+ to build artifacts; the generated application must also
+be compatible with the selected MicroPython runtime. The tool has zero runtime
+dependencies and uses the MIT license. Version 0.1.0 is experimental.
+
+```sh
+python -m pip install pocket-python==0.1.0 shimify==0.2.0
+pocket-python --help
+```
+
+## Build a browser application
+
+First create a portable source bundle with
+[Shimify](https://github.com/outside-labs/shimify). Supply a MicroPython
+WebAssembly distribution containing `micropython.mjs`, `micropython.wasm` and
+its license text; use the official
+[WebAssembly port](https://github.com/micropython/micropython/tree/master/ports/webassembly)
+or the official npm package described in
+[PyScript’s offline guide](https://docs.pyscript.net/2026.7.3/user-guide/offline/).
+
+```sh
+shimify modules path/to/app.py --output build/source
+pocket-python inspect build/source
+pocket-python lock-runtime path/to/runtime --runtime-version VERSION \
+  --source-url https://example.org/upstream-runtime-release \
+  --file micropython.mjs --file micropython.wasm --license-file LICENSE \
+  --output build/runtime-lock.json
+pocket-python web build/source --runtime path/to/runtime \
+  --runtime-lock build/runtime-lock.json --output build/web --title "My Python App"
+python -m http.server 8000 --bind 127.0.0.1 --directory build/web
+```
+
+Replace VERSION and the source URL with the identity of the supplied upstream
+release. Open `http://localhost:8000`, let the app finish installing its cache,
+and wait for **Offline ready on this device** before disconnecting. Run starts
+a fresh worker; Stop terminates it, including an infinite computation. Python
+output is rendered as text. Deploy the generated directory to a static HTTPS
+server; relative URLs support deployment under a subdirectory. `file://`
+execution is unsupported.
+
+`web` writes to a new directory outside input roots. It preserves only recorded
+source/runtime files and notices and adds `POCKET-PYTHON.json` with hashes,
+runtime identity and separate source/runtime/total byte counts. Generation
+does not run application code. The published tool contains no interpreter
+binary and does not download one automatically.
+
+## Reproduce the pinned example
+
+In a checkout, the build-only helper downloads and checks the official
+MicroPython `1.29.0-6` fixture and upstream license. The committed input is a
+real Shimify 0.2 bundle with a local helper import:
+
+```sh
+uv sync --locked
+uv run python scripts/prepare_runtime.py
+uv run pocket-python inspect tests/fixtures/hello
+uv run pocket-python web tests/fixtures/hello --runtime build/runtime \
+  --runtime-lock build/runtime/runtime-lock.json --output build/demo
+python -m http.server 8000 --bind 127.0.0.1 --directory build/demo
+```
+
+The demonstrated PWA totals 578,168 uncompressed bytes, including 563,092 bytes
+of runtime assets/license and 102 bytes of application source. These measurements
+describe the tested fixture; source reduction, compressed transfer size, startup
+time and memory are separate quantities.
+
+## Development and verification
+
+```sh
+uv sync --locked --group browser-tests
+uv run python scripts/prepare_runtime.py
+POCKET_PYTHON_RUNTIME=build/runtime uv run python -m unittest discover -s tests -v
+uv run python -m playwright install chromium
+uv run --group browser-tests python scripts/browser_smoke.py
+uv build
+uv run python scripts/check_distributions.py
+```
+
+On PowerShell set `$env:POCKET_PYTHON_RUNTIME = "build/runtime"` before tests.
+Without an explicit runtime fixture path, the real-WASM test is skipped.
+Use `--channel chrome` with the browser script to test an installed Chrome.
+Playwright is a pinned build-only group; it is not a package runtime dependency.
+CI runs real-runtime tests on Linux, macOS and Windows and offline Chromium
+tests on Linux. Distribution checks verify allowlists, metadata, source parity
+and both installed wheel/source artifacts outside the checkout.
+
+## Compatibility and roadmap
+
+MicroPython provides a subset of Python and its standard library. Test every
+application against the actual selected runtime: a valid Shimify CPython source
+bundle does not establish browser compatibility. Native extensions, OS process
+APIs, resources and dynamic imports need explicit adapters or a different
+runtime profile. The initial console has no interactive stdin or DOM bridge.
+Browser cache persistence and PWA installation affordances vary by platform.
+
+The first small-runtime route is MicroPython WebAssembly. Native relocatable
+CPython assembly and subsequent bootstrap-aware trimming are planned separately;
+0.1 does not trim/rebuild CPython. Broader CPython browser compatibility through
+Pyodide and optional PyScript integration are later profiles.
+
+See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md),
+[release notes](docs/release-0.1.0.md), and the
+[GitHub Project](https://github.com/orgs/outside-labs/projects/13).
+Runtime and dependency licenses remain applicable; preserve and review their
+upstream notices before distributing generated applications.

pocket_python-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "pocket-python"
+version = "0.1.0"
+description = "Auditable Python runtime assets and offline MicroPython application bundles"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[[project.authors]]
+name = "ellainng"
+email = "299958882+ellainng@users.noreply.github.com"
+
+[project.scripts]
+pocket-python = "pocket_python.cli:main"
+
+[project.urls]
+Repository = "https://github.com/outside-labs/pocket-python"
+Issues = "https://github.com/outside-labs/pocket-python/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+browser-tests = ["playwright==1.64.0"]

pocket_python-0.1.0/pyproject.toml.orig

@@ -0,0 +1,33 @@
+[project]
+name = "pocket-python"
+version = "0.1.0"
+description = "Auditable Python runtime assets and offline MicroPython application bundles"
+readme = "README.md"
+authors = [{ name = "ellainng", email = "299958882+ellainng@users.noreply.github.com" }]
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.scripts]
+pocket-python = "pocket_python.cli:main"
+
+[project.urls]
+Repository = "https://github.com/outside-labs/pocket-python"
+Issues = "https://github.com/outside-labs/pocket-python/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+browser-tests = [
+    "playwright==1.64.0",
+]

pocket_python-0.1.0/src/pocket_python/__init__.py

@@ -0,0 +1,3 @@
+"""Auditable runtime assets and offline Python applications."""
+
+__version__ = "0.1.0"

pocket_python-0.1.0/src/pocket_python/__main__.py

@@ -0,0 +1,3 @@
+from pocket_python.cli import main
+
+raise SystemExit(main())

pocket_python-0.1.0/src/pocket_python/assets.py

@@ -0,0 +1,141 @@
+"""Read explicit, hashed runtime assets without loading executable code."""
+
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+import re
+from urllib.parse import urlparse
+
+
+class ArtifactError(ValueError):
+    """An unsupported, changed, or unsafe artifact input."""
+
+
+def relative_path(value: str) -> str:
+    if not isinstance(value, str):
+        raise ArtifactError("Artifact paths must be strings.")
+    path = PurePosixPath(value)
+    reserved = {"CON", "PRN", "AUX", "NUL", *(f"COM{i}" for i in range(1, 10)), *(f"LPT{i}" for i in range(1, 10))}
+    if not path.parts or path.is_absolute() or ".." in path.parts or str(path) != value:
+        raise ArtifactError(f"Unsafe artifact path: {value!r}")
+    for part in path.parts:
+        if part.split(".")[0].upper() in reserved or part.endswith((".", " ")) or any(ord(c) < 32 or c in '\\:*?"<>|#%' for c in part):
+            raise ArtifactError(f"Nonportable artifact path: {value!r}")
+    return value
+
+
+def read_asset(root: Path, name: str) -> bytes:
+    relative_path(name)
+    current = root
+    if root.is_symlink() or not root.is_dir():
+        raise ArtifactError("Asset root must be an ordinary directory.")
+    for part in PurePosixPath(name).parts:
+        current = current / part
+        if current.is_symlink():
+            raise ArtifactError(f"Symlink asset is unsupported: {name}")
+    if not current.is_file() or not current.resolve().is_relative_to(root.resolve()):
+        raise ArtifactError(f"Asset is missing or escapes its root: {name}")
+    return current.read_bytes()
+
+
+def file_record(name: str, content: bytes) -> dict:
+    return {"path": name, "sha256": hashlib.sha256(content).hexdigest(), "size_bytes": len(content)}
+
+
+def check_names(names):
+    seen = set()
+    for name in names:
+        key = relative_path(name).casefold()
+        if key in seen or any(key.startswith(other + "/") or other.startswith(key + "/") for other in seen):
+            raise ArtifactError(f"Artifact path collision: {name}")
+        seen.add(key)
+
+
+def verified_files(root: Path, records: list) -> dict[str, bytes]:
+    if not isinstance(records, list) or not records:
+        raise ArtifactError("Expected a nonempty file record list.")
+    if any(not isinstance(record, dict) or not isinstance(record.get("path"), str) for record in records):
+        raise ArtifactError("Invalid file record.")
+    check_names(record["path"] for record in records)
+    files = {}
+    for record in records:
+        digest, size = record.get("sha256"), record.get("size_bytes")
+        if not isinstance(digest, str) or not re.fullmatch(r"[0-9a-f]{64}", digest) or type(size) is not int or size < 0:
+            raise ArtifactError("Invalid file hash/size record.")
+        content = read_asset(root, record["path"])
+        if file_record(record["path"], content) != {key: record[key] for key in ["path", "sha256", "size_bytes"]}:
+            raise ArtifactError(f"Asset hash or size mismatch: {record['path']}")
+        files[record["path"]] = content
+    return files
+
+
+def json_object(content: bytes) -> dict:
+    try:
+        value = json.loads(content)
+    except (ValueError, UnicodeError) as error:
+        raise ArtifactError(f"Invalid JSON: {error}") from error
+    if not isinstance(value, dict):
+        raise ArtifactError("Expected a JSON object.")
+    return value
+
+
+def json_bytes(value: dict) -> bytes:
+    return (json.dumps(value, indent=2, sort_keys=True) + "\n").encode()
+
+
+def runtime_lock(root: str | Path, *, version: str, source_url: str, files: list[str], license_files: list[str]) -> dict:
+    if not isinstance(version, str) or not version.strip():
+        raise ArtifactError("Runtime version must be nonempty.")
+    if not isinstance(source_url, str):
+        raise ArtifactError("Runtime source must be an HTTPS URL.")
+    source = urlparse(source_url)
+    if source.scheme != "https" or not source.netloc or source.username or source.password:
+        raise ArtifactError("Runtime source must be an HTTPS URL without credentials.")
+    if not license_files:
+        raise ArtifactError("At least one runtime license file is required.")
+    names = sorted(set(files) | set(license_files))
+    check_names(names)
+    content = {name: read_asset(Path(root), name) for name in names}
+    for name in license_files:
+        if not content[name].strip():
+            raise ArtifactError(f"Empty runtime license file: {name}")
+    if not {"micropython.mjs", "micropython.wasm"} <= content.keys():
+        raise ArtifactError("MicroPython requires micropython.mjs and micropython.wasm.")
+    return {
+        "schema_version": 1,
+        "kind": "pocket-python-runtime",
+        "implementation": "micropython",
+        "version": version,
+        "source_url": source_url,
+        "entrypoint": "micropython.mjs",
+        "license_files": sorted(set(license_files)),
+        "files": [file_record(name, data) for name, data in sorted(content.items())],
+    }
+
+
+@dataclass
+class RuntimeAssets:
+    root: Path
+    lock: dict
+    files: dict[str, bytes]
+
+
+def read_runtime(root: str | Path, lock_path: str | Path) -> RuntimeAssets:
+    path = Path(lock_path)
+    if path.is_symlink():
+        raise ArtifactError("Runtime lock must not be a symlink.")
+    lock = json_object(path.read_bytes())
+    if type(lock.get("schema_version")) is not int or lock["schema_version"] != 1 or lock.get("kind") != "pocket-python-runtime":
+        raise ArtifactError("Unsupported runtime lock schema.")
+    if lock.get("implementation") != "micropython" or lock.get("entrypoint") != "micropython.mjs":
+        raise ArtifactError("Only the MicroPython WebAssembly profile is supported.")
+    root = Path(root).absolute()
+    files = verified_files(root, lock.get("files"))
+    licenses = lock.get("license_files")
+    if not isinstance(licenses, list) or not licenses or any(not isinstance(name, str) or name not in files or not files[name].strip() for name in licenses):
+        raise ArtifactError("Missing or empty locked runtime license files.")
+    expected = runtime_lock(root, version=lock.get("version"), source_url=lock.get("source_url", ""), files=list(files), license_files=licenses)
+    if lock != expected:
+        raise ArtifactError("Runtime lock differs from the supported schema.")
+    return RuntimeAssets(root, lock, files)

pocket_python-0.1.0/src/pocket_python/bundles.py

@@ -0,0 +1,81 @@
+"""Validate Shimify source-bundle snapshots without executing them."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from pocket_python.assets import ArtifactError, file_record, json_object, read_asset, verified_files
+
+
+@dataclass
+class SourceBundle:
+    root: Path
+    manifest: dict
+    files: dict[str, bytes]
+
+    def report(self) -> dict:
+        return {
+            "schema_version": 1,
+            "kind": "pocket-python-source-inspection",
+            "entrypoint": self.manifest["entrypoint"],
+            "source_modules": len(self.manifest["sources"]),
+            "source_size_bytes": sum(item["size_bytes"] for item in self.manifest["sources"]),
+            "bundle_size_bytes": sum(map(len, self.files.values())),
+            "direct_stdlib_modules": self.manifest["stdlib_modules"],
+            "runtime_closure_complete": False,
+            "browser_compatibility": "unverified; test against the selected runtime",
+        }
+
+
+def read_bundle(directory: str | Path) -> SourceBundle:
+    root = Path(directory).absolute()
+    raw = read_asset(root, "SHIMIFY-MANIFEST.json")
+    manifest = json_object(raw)
+    if type(manifest.get("schema_version")) is not int or manifest["schema_version"] != 1 or manifest.get("mode") != "modules":
+        raise ArtifactError("Expected a Shimify schema-1 modules bundle.")
+    files = verified_files(root, manifest.get("files"))
+    if any(name != "run.py" and not name.startswith(("_sources/", "LICENSES/")) for name in files):
+        raise ArtifactError("Bundle contains files outside the supported source/notices layout.")
+    entry = manifest.get("entrypoint")
+    if not isinstance(entry, str) or not entry.startswith("_sources/") or not entry.endswith(".py") or entry.count("/") != 1 or entry not in files or manifest.get("launcher") != "run.py" or "run.py" not in files:
+        raise ArtifactError("Invalid bundle entrypoint or launcher.")
+    sources = manifest.get("sources")
+    if not isinstance(sources, list) or not sources or any(not isinstance(item, dict) for item in sources):
+        raise ArtifactError("Expected source records.")
+    names, outputs = set(), set()
+    for item in sources:
+        name, output = item.get("module"), item.get("output")
+        if not isinstance(name, str) or not name or not all(part.isidentifier() for part in name.split(".")) or name in names or not isinstance(output, str) or output in outputs or output not in files:
+            raise ArtifactError("Invalid or duplicate source mapping.")
+        expected = {entry} if name == "__main__" else {"_sources/" + name.replace(".", "/") + suffix for suffix in [".py", "/__init__.py"]}
+        if output not in expected:
+            raise ArtifactError("Source mapping differs from the module layout.")
+        record = file_record(output, files[output])
+        if item.get("sha256") != record["sha256"] or type(item.get("size_bytes")) is not int or item["size_bytes"] != record["size_bytes"]:
+            raise ArtifactError("Source hash/size differs from the file record.")
+        names.add(name)
+        outputs.add(output)
+    if "__main__" not in names or outputs != {name for name in files if name.startswith("_sources/")}:
+        raise ArtifactError("Bundle has missing or unrecorded source files.")
+    stdlib = manifest.get("stdlib_modules")
+    if not isinstance(stdlib, list) or any(not isinstance(name, str) or not all(part.isidentifier() for part in name.split(".")) for name in stdlib):
+        raise ArtifactError("Invalid standard-library requirements.")
+    # Validate attribution references before copying. Hash verification covers the
+    # bytes, and required paths must also be explicitly listed in the manifest.
+    distributions = manifest.get("distributions")
+    if not isinstance(distributions, list):
+        raise ArtifactError("Invalid distribution provenance.")
+    identities = set()
+    for distribution in distributions:
+        if not isinstance(distribution, dict) or not isinstance(distribution.get("id"), str) or distribution["id"] in identities:
+            raise ArtifactError("Invalid distribution identity.")
+        identities.add(distribution["id"])
+        licenses = distribution.get("license_files")
+        metadata = distribution.get("metadata")
+        if not isinstance(licenses, list) or not licenses or any(not isinstance(path, str) or not path.startswith("LICENSES/") or path not in files or not files[path].strip() for path in licenses):
+            raise ArtifactError("Distribution license material is missing.")
+        if not isinstance(metadata, str) or not metadata.startswith("LICENSES/") or metadata not in files:
+            raise ArtifactError("Distribution metadata is missing.")
+    if any(item.get("distribution") is not None and (not isinstance(item["distribution"], str) or item["distribution"] not in identities) for item in sources):
+        raise ArtifactError("Source refers to missing distribution provenance.")
+    files["SHIMIFY-MANIFEST.json"] = raw
+    return SourceBundle(root, manifest, files)

pocket_python-0.1.0/src/pocket_python/cli.py

@@ -0,0 +1,53 @@
+"""Command-line interface for explicit runtime assets and source inspection."""
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from pocket_python import __version__
+from pocket_python.assets import ArtifactError, json_bytes, read_runtime, runtime_lock
+from pocket_python.bundles import read_bundle
+from pocket_python.web import build_web
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pocket-python", description="Audit runtime assets and assemble offline Python applications.")
+    parser.add_argument("--version", action="version", version=f"pocket-python {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    lock = commands.add_parser("lock-runtime", help="Hash an explicit MicroPython runtime asset allowlist.")
+    lock.add_argument("root", type=Path)
+    lock.add_argument("--runtime-version", required=True)
+    lock.add_argument("--source-url", required=True)
+    lock.add_argument("--file", action="append", required=True, default=[])
+    lock.add_argument("--license-file", action="append", required=True, default=[])
+    lock.add_argument("--output", type=Path, required=True)
+    inspect = commands.add_parser("inspect", help="Validate and describe a Shimify source bundle.")
+    inspect.add_argument("bundle", type=Path)
+    web = commands.add_parser("web", help="Build a local-asset MicroPython PWA in a new directory.")
+    web.add_argument("bundle", type=Path)
+    web.add_argument("--runtime", type=Path, required=True)
+    web.add_argument("--runtime-lock", type=Path, required=True)
+    web.add_argument("--output", type=Path, required=True)
+    web.add_argument("--title", default="Pocket Python")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "lock-runtime":
+            result = runtime_lock(args.root, version=args.runtime_version, source_url=args.source_url, files=args.file, license_files=args.license_file)
+            args.output.parent.mkdir(parents=True, exist_ok=True)
+            with args.output.open("xb") as stream:
+                stream.write(json_bytes(result))
+            print(f"Created {args.output.resolve()}")
+        elif args.command == "web":
+            manifest = build_web(read_bundle(args.bundle), read_runtime(args.runtime, args.runtime_lock), args.output, title=args.title)
+            print(f"Created {args.output.resolve()} ({manifest['size']['artifact_bytes']} bytes)")
+            print("Serve over HTTPS or localhost; test this application against MicroPython.")
+        else:
+            print(json.dumps(read_bundle(args.bundle).report(), indent=2, sort_keys=True))
+    except ArtifactError as error:
+        print(f"pocket-python: {error}", file=sys.stderr)
+        return 1
+    except (OSError, ValueError) as error:
+        print(f"pocket-python: {error}", file=sys.stderr)
+        return 2
+    return 0

pocket_python-0.1.0/src/pocket_python/templates.py

@@ -0,0 +1,140 @@
+"""Local-asset browser shell and MicroPython worker templates."""
+
+PAGE = '''<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="theme-color" content="#213b45">
+<link rel="manifest" href="./manifest.webmanifest">
+<link rel="icon" href="./icon.svg" type="image/svg+xml">
+<title>{title}</title>
+<style>
+:root {{ color-scheme: light dark; font: 17px/1.6 system-ui,sans-serif; }}
+body {{ max-width: 52rem; margin: 8vh auto; padding: 0 1.5rem; }}
+h1 {{ line-height: 1.2; }}
+button {{ font: inherit; padding: .35rem 1rem; margin-right: .5rem; cursor: pointer; }}
+pre {{ min-height: 10rem; padding: 1.25rem; border: 1px solid #789; border-radius: .5rem; white-space: pre-wrap; overflow-wrap: anywhere; }}
+small {{ display: block; margin-top: 1rem; }}
+</style>
+<main>
+<h1>{title}</h1>
+<p>Python runs on your device.</p>
+<p id="status" role="status">Ready</p>
+<button id="run" type="button">Run</button><button id="stop" type="button" disabled>Stop</button>
+<pre id="output" aria-label="Python output"></pre>
+<small id="offline" role="status">Preparing offline files…</small>
+</main>
+<script type="module" src="./app.js"></script>
+</html>
+'''
+
+APP = '''const output = document.querySelector("#output");
+const status = document.querySelector("#status");
+const run = document.querySelector("#run");
+const stop = document.querySelector("#stop");
+const offline = document.querySelector("#offline");
+let worker;
+function finish(message) {
+  if (worker) worker.terminate();
+  worker = undefined;
+  run.disabled = false;
+  stop.disabled = true;
+  status.textContent = message;
+}
+function start() {
+  if (worker) worker.terminate();
+  output.textContent = "";
+  status.textContent = "Running…";
+  run.disabled = true;
+  stop.disabled = false;
+  worker = new Worker(new URL("./worker.js", import.meta.url), {type: "module"});
+  worker.onmessage = ({data}) => {
+    if (data.type === "stdout" || data.type === "stderr") output.textContent += data.text;
+    if (data.type === "error") { output.textContent += "\\n" + data.text; finish("Error"); }
+    if (data.type === "done") finish("Finished");
+  };
+  worker.onerror = (event) => { output.textContent += "\\n" + event.message; finish("Error"); };
+  worker.postMessage({type: "run"});
+}
+run.addEventListener("click", start);
+stop.addEventListener("click", () => finish("Stopped"));
+async function prepareOffline() {
+  if (!("serviceWorker" in navigator)) throw new Error("Service workers require HTTPS or localhost.");
+  const registration = await navigator.serviceWorker.register(new URL("./service-worker.js", import.meta.url), {scope: "./"});
+  const installing = registration.installing || registration.waiting;
+  if (installing && installing.state !== "activated") {
+    await new Promise((resolve, reject) => {
+      function changed() {
+        if (installing.state === "activated") resolve();
+        if (installing.state === "redundant") reject(new Error("Offline installation failed."));
+      }
+      installing.addEventListener("statechange", changed);
+      changed();
+    });
+  }
+  await navigator.serviceWorker.ready;
+  offline.textContent = "Offline ready on this device";
+}
+prepareOffline().catch(error => { offline.textContent = "Offline unavailable: " + error.message; });
+start();
+'''
+
+WORKER = '''import {loadMicroPython} from "./runtime/micropython.mjs";
+let started = false;
+async function get(path) {
+  const url = new URL(path.split("/").map(encodeURIComponent).join("/"), import.meta.url);
+  const response = await fetch(url);
+  if (!response.ok) throw new Error("Could not load " + path + ": " + response.status);
+  return response;
+}
+self.onmessage = async ({data}) => {
+  if (started || data.type !== "run") return;
+  started = true;
+  const stdout = new TextDecoder();
+  const stderr = new TextDecoder();
+  try {
+    const config = await (await get("app-config.json")).json();
+    const mp = await loadMicroPython({
+      url: new URL("./runtime/micropython.wasm", import.meta.url).href,
+      linebuffer: false,
+      stdout: bytes => postMessage({type: "stdout", text: stdout.decode(bytes, {stream: true})}),
+      stderr: bytes => postMessage({type: "stderr", text: stderr.decode(bytes, {stream: true})})
+    });
+    let entry;
+    for (const source of config.sources) {
+      const bytes = new Uint8Array(await (await get(source.url)).arrayBuffer());
+      const path = "/app/" + source.path;
+      mp.FS.mkdirTree(path.slice(0, path.lastIndexOf("/")));
+      mp.FS.writeFile(path, bytes);
+      if (source.path === config.entrypoint) entry = new TextDecoder("utf-8", {fatal: true}).decode(bytes);
+    }
+    if (entry === undefined) throw new Error("Application entrypoint is missing.");
+    mp.globals.set("__file__", "/app/" + config.entrypoint);
+    mp.runPython("import sys\\nsys.path.insert(0, '/app')\\n");
+    mp.runPython(entry);
+    postMessage({type: "stdout", text: stdout.decode()});
+    postMessage({type: "stderr", text: stderr.decode()});
+    postMessage({type: "done"});
+  } catch (error) {
+    postMessage({type: "error", text: (error.type || error.name || "Error") + ": " + error.message});
+  }
+};
+'''
+
+SERVICE_WORKER = '''const FILES = __FILES__;
+const PREFIX = "pocket-python:" + self.registration.scope + ":";
+const CACHE = PREFIX + "__VERSION__";
+self.addEventListener("install", event => {
+  event.waitUntil(caches.open(CACHE).then(cache => cache.addAll(FILES.map(path => new URL(path, self.registration.scope).href))).then(() => self.skipWaiting()));
+});
+self.addEventListener("activate", event => {
+  event.waitUntil(caches.keys().then(keys => Promise.all(keys.filter(key => key.startsWith(PREFIX) && key !== CACHE).map(key => caches.delete(key)))).then(() => self.clients.claim()));
+});
+self.addEventListener("fetch", event => {
+  const url = new URL(event.request.url);
+  if (event.request.method !== "GET" || url.origin !== self.location.origin || !url.href.startsWith(self.registration.scope)) return;
+  event.respondWith(caches.open(CACHE).then(async cache => (await cache.match(event.request)) || fetch(event.request)));
+});
+'''
+
+ICON = '''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 192"><rect width="192" height="192" rx="40" fill="#213b45"/><path d="M57 49h48a30 30 0 0 1 0 60H81v34H57zM81 73v12h24a6 6 0 0 0 0-12z" fill="#f4da8b"/></svg>'''

pocket_python-0.1.0/src/pocket_python/web.py

@@ -0,0 +1,134 @@
+"""Assemble verified sources and a local MicroPython runtime as a PWA."""
+
+import hashlib
+import html
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from pocket_python import __version__
+from pocket_python.assets import ArtifactError, RuntimeAssets, check_names, file_record, json_bytes, json_object
+from pocket_python.bundles import SourceBundle
+from pocket_python.templates import APP, ICON, PAGE, SERVICE_WORKER, WORKER
+
+
+def _publish(destination: Path, files: dict[str, bytes]):
+    check_names(files)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".pocket-python-", dir=destination.parent) as temporary:
+        stage = Path(temporary)
+        for name, content in files.items():
+            path = stage / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(content)
+        destination.mkdir()
+        written, directories = [], {destination}
+        try:
+            for name in sorted(files):
+                path = destination / name
+                parents = []
+                parent = path.parent
+                while parent != destination:
+                    parents.append(parent)
+                    parent = parent.parent
+                for parent in reversed(parents):
+                    if parent not in directories:
+                        parent.mkdir()
+                        directories.add(parent)
+                os.link(stage / name, path)
+                written.append(path)
+        except BaseException:
+            for path in reversed(written):
+                path.unlink(missing_ok=True)
+            for path in sorted(directories, key=lambda p: len(p.parts), reverse=True):
+                try:
+                    path.rmdir()
+                except OSError:
+                    pass
+            raise
+
+
+def build_web(bundle: SourceBundle, runtime: RuntimeAssets, output: str | Path, *, title: str = "Pocket Python") -> dict:
+    if json_object(bundle.files["SHIMIFY-MANIFEST.json"]) != bundle.manifest:
+        raise ArtifactError("Source manifest snapshot changed after validation.")
+    for records, snapshot, extra in [
+        (bundle.manifest["files"], bundle.files, {"SHIMIFY-MANIFEST.json"}),
+        (runtime.lock["files"], runtime.files, set()),
+    ]:
+        if set(snapshot) != {record["path"] for record in records} | extra:
+            raise ArtifactError("Snapshot files changed after validation.")
+        for record in records:
+            if file_record(record["path"], snapshot[record["path"]]) != {key: record[key] for key in ["path", "sha256", "size_bytes"]}:
+                raise ArtifactError("Snapshot hash or size changed after validation.")
+    requested = Path(output).absolute()
+    if requested.exists() or requested.is_symlink():
+        raise ArtifactError("Output already exists; choose a new directory.")
+    destination = requested.resolve()
+    for root in [bundle.root.resolve(), runtime.root.resolve()]:
+        if destination.is_relative_to(root) or root.is_relative_to(destination):
+            raise ArtifactError("Output overlaps an input root.")
+    if not isinstance(title, str) or not title.strip():
+        raise ArtifactError("Application title must be nonempty.")
+    sources = []
+    for source in bundle.manifest["sources"]:
+        name = source["output"]
+        try:
+            bundle.files[name].decode("utf-8")
+        except UnicodeError as error:
+            raise ArtifactError("The MicroPython profile requires UTF-8 application sources.") from error
+        sources.append({"path": name.removeprefix("_sources/"), "url": "application/" + name})
+    files = {"application/" + name: data for name, data in bundle.files.items()}
+    files.update({"runtime/" + name: data for name, data in runtime.files.items()})
+    files["runtime-lock.json"] = json_bytes(runtime.lock)
+    files["index.html"] = PAGE.format(title=html.escape(title, quote=True)).encode()
+    files["app.js"] = APP.encode()
+    files["worker.js"] = WORKER.encode()
+    files["icon.svg"] = ICON.encode()
+    files["app-config.json"] = json_bytes({"entrypoint": bundle.manifest["entrypoint"].removeprefix("_sources/"), "sources": sorted(sources, key=lambda s: s["path"])})
+    files["manifest.webmanifest"] = json_bytes({
+        "name": title, "short_name": title[:24], "id": "./", "start_url": "./", "scope": "./",
+        "display": "standalone", "theme_color": "#213b45", "background_color": "#213b45",
+        "icons": [{"src": "./icon.svg", "sizes": "any", "type": "image/svg+xml", "purpose": "any maskable"}],
+    })
+    records = [file_record(name, content) for name, content in sorted(files.items())]
+    cache_version = hashlib.sha256(json_bytes({"files": records})).hexdigest()
+    precache = ["./", *sorted(files), "service-worker.js", "POCKET-PYTHON.json"]
+    files["service-worker.js"] = SERVICE_WORKER.replace("__FILES__", json.dumps(precache)).replace("__VERSION__", cache_version).encode()
+    manifest = {
+        "schema_version": 1,
+        "kind": "pocket-python-web",
+        "pocket_python_version": __version__,
+        "title": title,
+        "entrypoint": "index.html",
+        "runtime": {key: runtime.lock[key] for key in ["implementation", "version", "source_url", "license_files"]},
+        "source_bundle": "application/SHIMIFY-MANIFEST.json",
+        "runtime_lock": "runtime-lock.json",
+        "cache_version": cache_version,
+        "size": {
+            "application_source_bytes": bundle.report()["source_size_bytes"],
+            "source_bundle_bytes": sum(map(len, bundle.files.values())),
+            "runtime_asset_bytes": sum(map(len, runtime.files.values())),
+            "artifact_bytes": 0,
+        },
+        "files": [file_record(name, content) for name, content in sorted(files.items())],
+        "direct_stdlib_modules": bundle.manifest["stdlib_modules"],
+        "limitations": [
+            "MicroPython compatibility must be tested for this application; CPython syntax and stdlib APIs may differ.",
+            "Supplied runtime assets are preserved, not automatically rebuilt or trimmed.",
+            "Offline use requires initial installation over HTTPS/localhost and retained browser cache.",
+            "License material is preserved; redistribution compliance is not certified.",
+        ],
+    }
+    # The manifest excludes its own file hash, but its total byte count includes
+    # itself. Iterate until the decimal length of the total is stable.
+    payload_size = sum(map(len, files.values()))
+    while True:
+        content = json_bytes(manifest)
+        total = payload_size + len(content)
+        if manifest["size"]["artifact_bytes"] == total:
+            break
+        manifest["size"]["artifact_bytes"] = total
+    files["POCKET-PYTHON.json"] = content
+    _publish(destination, files)
+    return manifest