oc-box 0.1.23__tar.gz

oc_box-0.1.23/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: Package and source checks
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        python: ['3.10', '3.13']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Unit and documentation coverage checks
+        run: |
+          python -B -m unittest discover -s tests -v
+          python tools/build_docs.py --check
+          git diff --check
+      - name: Build Python distributions
+        run: |
+          python -m venv "$RUNNER_TEMP/build"
+          "$RUNNER_TEMP/build/bin/python" -m pip install build twine
+          "$RUNNER_TEMP/build/bin/python" -m build
+          "$RUNNER_TEMP/build/bin/python" -m twine check dist/*
+          python tools/check_package.py dist

oc_box-0.1.23/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: Build and publish Python package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish to PyPI after checks (false builds only)
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.10'
+      - name: Create isolated build tools
+        run: |
+          python -m venv "$RUNNER_TEMP/oc-box-build"
+          "$RUNNER_TEMP/oc-box-build/bin/python" -m pip install build twine
+      - name: Validate source and release version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python -m compileall -q oc_box.py bootstrap.py sync_config.py terminal_ui.py status_report.py workspace_identity.py installation.py updater.py version_info.py
+          python tools/build_docs.py --check
+          python - <<'PY'
+          import os
+          from version_info import get_version_info, VERSION_SERIES
+          build = get_version_info('.')
+          expected = f"v{VERSION_SERIES}.{build['commit_count']}"
+          assert not build['dirty'], 'Publish only a clean source commit'
+          if os.environ.get('RELEASE_TAG'):
+              assert os.environ['RELEASE_TAG'] == expected, f'Release tag must be {expected}'
+          print('Publishing/building', expected, 'from', build['commit'])
+          PY
+      - name: Run source regression tests
+        run: python -B -m unittest discover -s tests -v
+      - name: Build wheel and source distribution
+        run: |
+          "$RUNNER_TEMP/oc-box-build/bin/python" -m build
+          "$RUNNER_TEMP/oc-box-build/bin/python" -m twine check dist/*
+      - name: Verify isolated package installation and resources
+        run: python tools/check_package.py dist
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    if: github.event_name == 'release' || inputs.publish
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/oc-box/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-distributions
+          path: dist
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1

oc_box-0.1.23/AGENTS.md

@@ -0,0 +1,110 @@
+# oc-box development
+
+Run development commands from the repository root. Keep public documentation
+portable: use example project paths and synthetic session IDs, not local data.
+
+## Architecture
+
+- `oc_box.py`: external rootless-Podman launcher and workspace lifecycle.
+- `bootstrap.py`: baseline tools installed inside the container.
+- `sync_config.py`: container-only config refresh with dependency-cache reuse.
+- `terminal_ui.py`: native TUI relay and startup loading indicator.
+- `status_report.py`: read-only host resource and storage reporting.
+- `version_info.py`: commit-derived version and author/license information.
+- `workspace_identity.py`: generic Linux VFS directory identity, capability-based
+  persistent handles and strict fallback; shared by lifecycle/status checks.
+- `install.py`: copies the launcher to `~/.local/share/oc-box` and creates
+  `~/.local/bin/oc-box`.
+- `installation.py`: staged immutable installed copies and launcher activation.
+- `updater.py` / `install.sh`: public GitHub upgrades and one-line bootstrap.
+- `pyproject.toml` / `setup.py`: Python distributions with an isolated `oc_box`
+  namespace, resources, public versions, and source metadata.
+- `.github/workflows/publish.yml`: selected PyPI releases via Trusted Publishing.
+- `tests/`: stdlib unit tests and bounded offline mainline integration fixtures.
+- `docs/cli.md`: canonical command reference; `tools/build_docs.py` generates
+  the committed man/Texinfo/Info manuals from it.
+
+OpenCode itself and its integrations run natively inside the container. Preserve
+MCPs, formatters, language servers, and plugins. Do not return to replacing
+built-in tools or disabling integrations for containment. Keep mainline OpenCode
+unmodified. Live sessions persist in a private named volume, and host-side
+history is synchronized with supported CLI export/import commands on exit.
+
+## Git workflow
+
+Commit completed changes after reviewing the diff and running the relevant
+checks. The user explicitly requests automatic commits for work in this
+repository. Stage intended source files explicitly; sandbox-generated empty
+placeholder dotfiles are not project source. The user authorizes automatic
+pushes of reviewed commits to an explicitly configured upstream, provided the
+hosting service permits this AI-assisted project. Do not create a remote or
+push to a service with incompatible policies. Do not store credentials in Git
+URLs, config, source files, or command-line arguments.
+
+The public upstream is `https://github.com/groopcd/oc-box.git`. Use only the
+explicit `PERSONAL_GITHUB_TOKEN` for publication. Inherited `GITHUB_TOKEN` and
+`GH_TOKEN` belong to a separate Microsoft/Copilot account and must not be used
+for repository management or pushes. Give publishing subprocesses an isolated
+GitHub CLI config and set their local `GH_TOKEN` from `PERSONAL_GITHUB_TOKEN`,
+without modifying the parent environment. Verify `gh api user` reports
+`groopcd` before publishing. Pass Git credential helpers per command rather
+than storing tokens or changing global authentication settings.
+
+Version `0.1.N+gHASH` is derived from the full Git history; every commit advances
+N automatically. The installer embeds the source identity in its private
+`build-info.json`. Original project code/documentation is GPL-3.0-or-later;
+retain LICENSE and NOTICE when distributing/installing it.
+PyPI uses the public `0.1.N` version; retain the full `+gHASH` identity in package
+resources. Python-package installations upgrade through pipx/uv/pip, never the
+GitHub self-updater. Preserve the normal curl/GitHub update path in parallel.
+
+Update `docs/cli.md` when command-line behavior changes, then regenerate with
+`python3 tools/build_docs.py` (requires GNU makeinfo). Prebuilt manuals ship in
+the repository; installing oc-box must not require documentation build tools.
+
+## Checks
+
+```bash
+python3 -B -m unittest discover -s tests -v
+python3 -B tests/smoke_mainline.py
+```
+
+The smoke test uses temporary databases and offline fixture services, with
+bounded timeouts. It does not verify actual Podman isolation. Live Podman
+verification must run on the host, outside another container/sandbox.
+
+A host-terminal Tumbleweed container/OpenCode launch has succeeded. Full live
+MCP, formatter, language-server, and stop/resume verification is still pending;
+the automated integration checks use offline fixtures.
+
+The host-terminal warm-start test is now effectively instant after retaining
+the container-generated plugin SDK manifest, lockfiles, and dependency cache.
+
+Host-session import and mapped NPU access have been exercised on Tumbleweed.
+A native warm plugin-initialization probe completed in under one second.
+New mounts use `:z`, and cold plugin resolution is timed before opening the TUI.
+
+Container launches give Build mode allow-all OpenCode permissions through a
+generated private config/plugin. Keep Plan/subagent rules and plain host
+OpenCode permissions unchanged.
+
+Do not treat a lost marker or changed filesystem device/inode as permission to
+create a replacement workspace. Look up registered canonical paths, direct the
+host operator to explicit `repair`, and never overwrite another workspace's
+marker. Device-number changes may be accepted only against a recorded matching
+filesystem ID, persistent directory handle, and inode; never infer a baseline
+from an old device number and unchanged inode alone. Upgrade legacy records
+under the workspace lock only after verification or explicit repair.
+Use the common VFS APIs without filesystem-name branches. Do not promise
+physical identity on unsupported drivers or replace it with a copyable marker.
+Plain stale-workspace purge preserves project files, host history, and
+private archive-origin evidence under `retired/`; keep that recovery path tested.
+
+`terminal` is maintenance-only: no host credential/pass_env forwarding, no
+OpenCode/auth/config refresh, startup profiles, or persistent shell history.
+Keep its environment allowlisted and preserve the original container run state.
+
+Updates fetch the fixed public HTTPS upstream anonymously with sanitized Git
+configuration/environment. Never reuse publishing/provider credentials for
+downloads. Keep automatic updating opt-in, preserve running release copies,
+workspaces and source checkouts, and do not self-update from inside a container.

oc_box-0.1.23/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing
+
+Use the full Git history: the release identity is `0.1.N+gHASH`, with the commit
+count as N. Changes should keep mainline OpenCode unmodified and preserve MCPs,
+formatters, language servers, plugins, and the host/container storage boundary.
+
+## Checks
+
+Python 3.10+ and stdlib are sufficient for unit tests. The mainline smoke test
+also needs Git and OpenCode (integration checked with 1.19.5):
+
+```sh
+python3 -B -m unittest discover -s tests -v
+python3 -B tests/smoke_mainline.py
+python3 -B tools/build_docs.py --check
+git diff --check
+```
+
+Tests use isolated temporary app data. Mainline model/MCP/LSP/formatter fixtures
+are local and bounded. These checks do not replace live host-side Podman tests.
+Do not run host lifecycle tests from inside the project's running container.
+
+## Manuals
+
+Edit `docs/cli.md` when command-line behavior changes. Generate committed man,
+Texinfo, and Info files with GNU makeinfo installed:
+
+```sh
+python3 -B tools/build_docs.py
+```
+
+End-user installation copies prebuilt manuals and must not require build tools.
+Optional man/Info rendering checks run when groff and GNU info are available.
+Info output is byte-reproducible with the same makeinfo version. Different
+Texinfo releases may change their banner, wrapping, typography, and tag offsets;
+tests verify matching navigation across versions rather than requiring identical
+binary output from every distribution's documentation toolchain.
+
+## Source and release hygiene
+
+- Stage intended files explicitly. Never commit auth files, tokens, private keys,
+  session databases/exports, registry metadata, caches, or sandbox placeholders.
+- Review Git history as well as the working tree before a first public push.
+  With Gitleaks installed, run `gitleaks git --log-opts=--all --redact .` and
+  `gitleaks dir --redact .`. Scan reports belong outside the repository.
+- Shell calls should use argument arrays. Forward credentials through the
+  process environment, never command-line arguments or credential-bearing URLs.
+- Add regression tests for boundary changes, import compatibility, lifecycle
+  preservation, and actual command behavior rather than implementation mirrors.
+- Keep examples portable and use synthetic session IDs.
+- Disclose AI assistance honestly. Check each hosting service's policy before
+  publication; a GPL license does not override a service's content rules.
+
+Original contributions are licensed GPL-3.0-or-later. Retain LICENSE and NOTICE.
+
+## Python packages and PyPI releases
+
+The wheel contains a namespaced `oc_box` package, runtime helper scripts,
+prebuilt manuals, license/notice, and immutable source metadata. It has no
+third-party runtime Python dependencies. GitHub source/curl installations stay
+supported in parallel. Do not make a pip-managed launcher install through the
+GitHub self-updater or write a global wrapper as an installation side effect.
+
+Build in isolation (uv uses an ephemeral environment; no project/system pip
+install is needed):
+
+```sh
+uv run --no-project --with build --with twine python -m build
+uv run --no-project --with twine python -m twine check dist/*
+python3 tools/check_package.py dist
+```
+
+The last check installs only the wheel into a temporary virtual environment,
+tests CLI commands/resources, and ensures package upgrades do not invoke the
+GitHub installer. Standard build produces the wheel from the sdist to verify
+that it works without Git. Do not publish a dirty working tree.
+
+PyPI rejects local `+gHASH` version suffixes: the distribution version is
+`0.1.N` from full-history commit count, and packaged `build-info.json` keeps
+`0.1.N+gHASH` plus the full commit. Each selected release needs a unique version;
+ordinary commits remain on GitHub without requiring a PyPI upload.
+
+Trusted Publisher configuration in PyPI must match:
+
+- Project: `oc-box` (pending publisher until its first successful publication).
+- GitHub owner/repository: `groopcd/oc-box`.
+- Workflow filename: `publish.yml`.
+- GitHub environment: `pypi`.
+
+No long-lived PyPI upload token belongs in GitHub or this repository. Only the
+publish job receives `id-token: write`, and it downloads already-tested artifacts
+rather than executing package build code with publishing credentials. GitHub
+Actions are pinned by commit. The user must create/own the PyPI account and
+configure the matching publisher; pending publishers do not reserve names.
+
+First run the workflow with its `publish` input false to verify a build-only
+run. A published GitHub release named `v0.1.N` (matching that commit's count)
+builds, validates, and publishes to PyPI. Alternatively manually dispatch
+`publish.yml` on a reviewed commit with `publish` true. Environment protection
+rules may require owner approval. Do not publish from untrusted pull requests.
+The repository's CI builds/verifies packages on Python 3.10 and 3.13; the full
+mainline smoke fixture remains part of local verification with OpenCode.