dbxdebug 0.2.1__tar.gz → 0.4.0__tar.gz

dbxdebug-0.4.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns: ["*"]
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]

dbxdebug-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release
+
+# release-please maintains a "Release vX.Y.Z" PR from the conventional-commit
+# history. Merging that PR updates CHANGELOG.md and the manifest, then creates
+# the vX.Y.Z tag and GitHub Release. hatch-vcs derives the package version from
+# that tag at build time. Publishing must run in this same workflow run, because
+# a tag/release created with GITHUB_TOKEN does not trigger a separate workflow.
+
+on:
+  push:
+    branches: [main]
+  # Recovery path. A tag/release created with GITHUB_TOKEN does not trigger a
+  # workflow, so a publish that fails for an environmental reason (a bad
+  # publisher/metadata pairing, a PyPI outage) cannot be retried by re-running
+  # the original run -- a re-run replays the workflow file from that commit,
+  # including whatever was broken. Dispatch this against the existing tag
+  # instead. It rebuilds from that tag and republishes; it never creates a tag.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to build and publish, e.g. v0.3.0"
+        required: true
+        type: string
+
+permissions: {}
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    if: ${{ github.event_name == 'push' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the release + tag
+      pull-requests: write # open/maintain the release PR
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  # Full CI (lint + format + pyright + test matrix + build) gates the publish.
+  # If anything here fails, the publish job below is skipped and nothing ships.
+  ci:
+    needs: release-please
+    if: ${{ !cancelled() && (needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch') }}
+    permissions:
+      contents: read
+    uses: ./.github/workflows/test.yml
+
+  publish:
+    needs: [release-please, ci]
+    if: ${{ !cancelled() && needs.ci.result == 'success' && (needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch') }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dbxdebug
+    permissions:
+      id-token: write # OIDC for PyPI Trusted Publishing
+      contents: write # upload built artifacts to the GitHub Release
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}
+          fetch-depth: 0 # Full history + tags for hatch-vcs version
+
+      - name: Install uv and set up Python
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          python-version: "3.11"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+      - name: Attach artifacts to the GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}" dist/* --clobber

dbxdebug-0.4.0/.github/workflows/test.yml

@@ -0,0 +1,75 @@
+name: Test
+
+on:
+  push:
+    branches: ["**"] # All branches, not tags
+  pull_request:
+    branches: [main]
+  workflow_call: # invoked by release.yml to gate publishing
+
+permissions:
+  contents: read
+
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+
+      - name: Install uv and set up Python
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Ruff check
+        run: uv run ruff check src/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Pyright
+        # No path argument on purpose: that makes pyright use [tool.pyright]
+        # `include` from pyproject.toml, so CI can never check fewer paths
+        # than the config claims to cover (it once skipped tests/ entirely).
+        run: uv run pyright
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+
+      - name: Install uv and set up Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Run tests
+        run: uv run pytest tests -v
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          fetch-depth: 0 # Full history for hatch-vcs
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+
+      - name: Build (packaging smoke test)
+        run: uv build

{dbxdebug-0.2.1 → dbxdebug-0.4.0}/.pre-commit-config.yaml

@@ -62,13 +62,6 @@ repos:
   #         - --allow-init-docstring=True
   #       exclude: ^(tests/|src/dbxdebug/cli\.py)
 
-  # Commitizen for commit message linting (Conventional Commits)
-  - repo: https://github.com/commitizen-tools/commitizen
-    rev: v3.29.1
-    hooks:
-      - id: commitizen
-        stages: [commit-msg]
-
   # Actionlint for GitHub Actions workflow linting
   - repo: https://github.com/rhysd/actionlint
     rev: v1.7.4

dbxdebug-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

dbxdebug-0.4.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## [0.4.0](https://github.com/lokkju/dbxdebug/compare/v0.3.0...v0.4.0) (2026-09-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **session:** DosboxSession now runs the emulator headless by default. A caller that relied on seeing the window -- to watch the guest while debugging, or to drive it by hand -- must now pass headless=False explicitly. Everything else is unaffected: the debug surface is identical headless, and screen capture was verified byte-identical between the two modes. Note also that `headless` sits mid-dataclass, so positional construction past `connect=` shifts.
+
+### Features
+
+* **session:** add DosboxSession(headless=True), on by default ([8af1f56](https://github.com/lokkju/dbxdebug/commit/8af1f56528977c2dbc4a2ddec442f4aa6f76933d)), closes [#3](https://github.com/lokkju/dbxdebug/issues/3)
+* **session:** add read_bulk, a one-call bulk memory read ([f8e228b](https://github.com/lokkju/dbxdebug/commit/f8e228b101b14e682e3b4ec98b434f1fd7e5e7c7)), closes [#9](https://github.com/lokkju/dbxdebug/issues/9)
+
+
+### Bug Fixes
+
+* **ci:** unblock publishing and add a recovery path for a failed one ([9c69a87](https://github.com/lokkju/dbxdebug/commit/9c69a87c73f30b0a249e1bd5ec3c4cc4f2af0736))
+* **gdb:** bound reads and resynchronise the packet stream ([5940242](https://github.com/lokkju/dbxdebug/commit/5940242035181668c4d35e61db56d5b2342aa620))
+* **session:** record that headless is now the default ([d649d70](https://github.com/lokkju/dbxdebug/commit/d649d705bb46261d38c30a23fc9c39bd390f7c87))
+* **video,cli:** let a GDB client be borrowed instead of reopened ([bb9d351](https://github.com/lokkju/dbxdebug/commit/bb9d35170283407f9c7fbd64f4cfd4f1d75f1d64))
+
+
+### Performance Improvements
+
+* **clients:** set TCP_NODELAY, and correct what read_bulk is now worth ([c535e3b](https://github.com/lokkju/dbxdebug/commit/c535e3bafe2799e708714e4f771046fd35a55d81))
+
+
+### Documentation
+
+* correct the hazard write-ups now that the GDB stream is fixed ([a1821aa](https://github.com/lokkju/dbxdebug/commit/a1821aa8904987afd73ad1ba97d022fee5e30213)), closes [#4](https://github.com/lokkju/dbxdebug/issues/4) [#5](https://github.com/lokkju/dbxdebug/issues/5)
+* **migration:** fix the gaps a real migration hit ([96ffaa7](https://github.com/lokkju/dbxdebug/commit/96ffaa7a901a35529e14a81828f8a36d550664d9))
+
+## [0.3.0](https://github.com/lokkju/dbxdebug/compare/v0.2.1...v0.3.0) (2026-09-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **session:** set_breakpoint(seg, off) now computes a LINEAR address via addressing.linear(seg, off) instead of packing seg:off as a far pointer. Current DOSBox-X builds decode Z0/z0 as linear (this package's GDBClient requires dosbox-x-linear-bp+ at connect), so the old packed form would silently misplace the breakpoint while gdbserver still answered OK.
+* **gdb:** read_registers()["eip"] is now documented as an offset within CS, not a linear address, matching the fixed GDB stub semantics (register 8 is EIP-within-CS in both g and G directions on stubs that advertise dosbox-x-eip-offset+). Code that combined the old eip value directly as a linear address is silently wrong against a fixed stub; call linear_pc() to get the linear program counter instead.
+* **utils:** parse_x86_address (and anything that calls it, including the `dbxdebug mem`/`cpu` CLI commands) now interprets a bare digit string with no "0x" prefix as hexadecimal instead of decimal. Callers that were relying on decimal parsing of unprefixed strings (e.g. passing "1000" and expecting 1000 rather than 4096) must add an explicit base-10 conversion before calling, or use a "0x"-prefixed or already-hex string.
+* **gdb:** GDBClient now refuses to connect to a stub that does not advertise dosbox-x-linear-bp+. Such builds split the Z0 argument as a packed far pointer, so any breakpoint above 64 KB answers OK and never fires -- silently. Pass require_capabilities=False to proceed against an old build deliberately.
+
+### Features
+
+* **addressing:** add the linear addressing module ([e73ce82](https://github.com/lokkju/dbxdebug/commit/e73ce82479a8b1883305fb4db2d33b4f0d960e7c))
+* **cli:** add session list, session reap and doctor ([8179f94](https://github.com/lokkju/dbxdebug/commit/8179f94e11aa07a536ab027dec7dbc3dd425f16c))
+* **frames:** add real-mode stack frame walking ([02c2990](https://github.com/lokkju/dbxdebug/commit/02c29909e1a492e1392d0ddecec994da8e71ea83))
+* **gdb:** add register list, linear PC, and register write to GDBClient ([fc5729e](https://github.com/lokkju/dbxdebug/commit/fc5729e6e0561310c49d1ac94a84368bb051deed))
+* **gdb:** require dosbox-x-linear-bp+ at connect ([b8cc28f](https://github.com/lokkju/dbxdebug/commit/b8cc28fb31d444a961d8850987eef2bbe0bc6d34))
+* **qmp:** wrap memdump, screendump, savestate, loadstate, system_reset and quit ([c7a97c6](https://github.com/lokkju/dbxdebug/commit/c7a97c67561f2b732cff7d62b57f994fe8d922c8))
+* **registry:** add the session registry with list and reap ([2af648d](https://github.com/lokkju/dbxdebug/commit/2af648db88c446f1563ed83ab297b22b929f278d))
+* **session:** port the DosboxSession lifecycle from a downstream consumer ([70f26d9](https://github.com/lokkju/dbxdebug/commit/70f26d948cc49f57463c9d91657a7c0f896d0372))
+* **skills:** ship the two Agent Skills from this repo ([ff01e0d](https://github.com/lokkju/dbxdebug/commit/ff01e0daad568a9de0e031b5f5ed87d56fe1638b))
+
+
+### Bug Fixes
+
+* add shifted punctuation mappings to char_to_qcode ([6a19fb4](https://github.com/lokkju/dbxdebug/commit/6a19fb47a0de76841815664eeee78b3537502f86))
+* **addressing:** validate seg:off components and clarify parse errors ([c5d67a5](https://github.com/lokkju/dbxdebug/commit/c5d67a5792392dd373860f8cf880863d20b8d2e0))
+* **cli:** report the real package version instead of a hardcoded 0.1.0 ([8100d53](https://github.com/lokkju/dbxdebug/commit/8100d53cf9c228d31d0ed3997561680c4aa18f04))
+* **frames:** correct steps_out threshold and close review gaps ([880a965](https://github.com/lokkju/dbxdebug/commit/880a965c6855a22ae6de2edbc78091a8be05e028))
+* **paths:** unify dosbox-x binary resolution between session and doctor ([0bda742](https://github.com/lokkju/dbxdebug/commit/0bda742a35e8f56f74367268612b7fd45e3c528d))
+* satisfy ruff C420 and formatting gates ([d464033](https://github.com/lokkju/dbxdebug/commit/d46403357cce148df2d424ac1df54c24fcd296c3))
+* **session:** close start()/stop() review gaps from Task 8 round 1 ([6032fcb](https://github.com/lokkju/dbxdebug/commit/6032fcb7f1414149adc8f5363c433bded29f7e86))
+* **session:** restore process-group sweep lost by round-1's kill_group pid= ([c3cd6ff](https://github.com/lokkju/dbxdebug/commit/c3cd6ff5faed880ac9d9ef94ec3db2852ce3ab73))
+* **tests:** re-scope the desync guard and close integration review gaps ([0832b6d](https://github.com/lokkju/dbxdebug/commit/0832b6d3a6026c89d03c9574b43b5c727b019b88))
+* **utils:** parse bare address digits as hex, not decimal ([b0ba5be](https://github.com/lokkju/dbxdebug/commit/b0ba5bedb5b109f4279ba2e4119ee3a4268d0fda))
+
+
+### Documentation
+
+* add CI, PyPI, and license badges to README ([cb3d2fd](https://github.com/lokkju/dbxdebug/commit/cb3d2fda3cd81c736f20dba706ef90e8e6f3e4b4))
+* document the migration path onto dbxdebug ([e868090](https://github.com/lokkju/dbxdebug/commit/e8680907b976fd8ddb3ce7c5cdf5db0301fc6d54))
+* **frames:** neutralise downstream references and drop a false claim ([cbbec5a](https://github.com/lokkju/dbxdebug/commit/cbbec5ad2b446ea50902872ad3d76a4034e604ad))
+* rewrite the README around the session lifecycle ([5cd96ce](https://github.com/lokkju/dbxdebug/commit/5cd96ce8858f8ca4244237f158f8f067d3ab5f8b))

dbxdebug-0.4.0/LICENSE

@@ -0,0 +1,151 @@
+# Polyform Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, you may continue doing so even if the licensor or
+any of its affiliates later provides a competing product.
+
+## Discontinued Products
+
+You may begin using the software to provide a product that
+competes with one the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneTM Desktop Software (http://example.com/desktop)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to anyone for any damages related to this software or this
+license, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.